> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cosmon.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Install the SDK, connect to your running Nexus app, and run your first agent in Python.

## Prerequisites

<Steps>
  <Step title="Install and sign in to Nexus">
    Open the Nexus app and sign in. The SDK drives this running app, so it must
    be open while your code runs.
  </Step>

  <Step title="Turn on Developer access">
    In **Settings → Developer access**, enable it. This starts the local MCP
    server the SDK connects to and writes a per-user descriptor the SDK discovers
    automatically.
  </Step>

  <Step title="Install the SDK">
    ```bash theme={null}
    pip install cosmon-agent-sdk
    ```

    Requires Python 3.10+.
  </Step>

  <Step title="Check the connection">
    ```bash theme={null}
    cosmon doctor
    ```

    This confirms the app is reachable, you're signed in, and the agent runtime
    is ready. A healthy check looks like this:

    ```text theme={null}
    Cosmon Agent SDK — connection check

      descriptor (default): ~/Library/Application Support/nexus/mcp-gateway.json
      ✓ reached the app
      ✓ signed in (you@company.com)
      ✓ agent runtime ready
      ✓ tool server ready
          agents: nexus, solidworks, abaqus, fluent, ansys_mechanical, comsol
          model:  claude-sonnet-5

    Ready. Try:  cosmon run "what can you do?"
    ```

    Any line marked `✗` tells you what to fix — re-check that the app is open,
    you're signed in, and Developer access is on.
  </Step>
</Steps>

## Your first run

```python theme={null}
from cosmon_agent_sdk import Client

with Client() as client:
    answer = client.run(
        "What is the peak von Mises stress in bracket.sldprt?",
        agent="solidworks",
    ).text()
    print(answer)
```

`Client()` discovers the running app and connects — no endpoint or key to
configure. `client.run(...)` starts an agent run and returns a **`Run`**;
`.text()` drives it to completion and returns the run's transcript — the
answer plus each tool step as a `▶` line. Add `live=True` to watch it print
while you wait.

The printed transcript looks like this — the `▶` lines are the tool steps the
agent took, and the prose is its answer:

```text theme={null}
▶ Open bracket.sldprt

▶ Run static structural study

The peak von Mises stress is 187.4 MPa, at the inner fillet of the mounting
lug. With the yield strength of the assigned material (AISI 1020, ~350 MPa),
that's a safety factor of ~1.9.
```

## Streaming the work as it happens

Instead of `.text()`, **iterate** the run to see it live. It yields typed events —
`ToolCall` (a tool-call boundary) and `TextChunk` (the answer, as it streams):

```python theme={null}
import sys
from cosmon_agent_sdk import Client, TextChunk, ToolCall

with Client() as client:
    for event in client.run("Open bracket.sldprt and summarize the part", agent="solidworks"):
        if isinstance(event, TextChunk):
            print(event.text, end="", flush=True)          # answer, token by token
        elif isinstance(event, ToolCall) and not event.finished:
            print(f"[{event.summary}]", file=sys.stderr)    # tool steps
```

<Note>
  Iterate **or** call `.text()` — a run is single-use. The `TextChunk`s reconstruct
  the same answer `.text()` returns; iterating just lets you render it (and the tool
  steps) as it arrives.
</Note>

## Picking an agent

Pass `agent=` to target a platform: `"solidworks"`, `"abaqus"`, `"fluent"`,
`"ansys_mechanical"`, `"comsol"`, … Omit it to use the default agent. Run
`cosmon doctor` to see which agents your app exposes.

## Next steps

<CardGroup cols={2}>
  <Card title="Guide" icon="book-open" href="/sdk/guide">
    Attended vs unattended, answering the agent with handlers, and batch runs.
  </Card>

  <Card title="Examples" icon="list-check" href="/sdk/examples/one-shot-run">
    Runnable scripts for every capability — copy, run, adapt.
  </Card>

  <Card title="Python reference" icon="code" href="/sdk/python-reference">
    The full API surface, async client, streaming, and errors.
  </Card>

  <Card title="Command line" icon="terminal" href="/sdk/cli">
    The `cosmon` CLI — `doctor`, `run`, and `chats` from the shell.
  </Card>
</CardGroup>