> ## 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.

# Agent SDK

> Program Nexus from Python — describe an engineering task and the agent plans and runs it across your CAD and simulation tools.

<Warning>
  **Alpha release.** The SDK's API surface is still moving — breaking changes
  will ship in minor versions while it's on `0.x`. Pin an exact version
  (`cosmon-agent-sdk==0.1.1`) in pipelines you don't want to fix on upgrade day.
</Warning>

The Cosmon Agent SDK lets you drive the Nexus agent from your own Python code.
You describe an engineering outcome — *"run a static structural study on this
bracket and report the peak stress"* — and the agent reasons about the model,
plans the operations, drives the CAD/CAE software, recovers from errors, and
reports back. Anything an engineer can do in the Nexus app, your code can script,
batch, and embed.

It works the way the [Claude Agent SDK](https://docs.claude.com/en/api/agent-sdk/overview)
exposes Claude Code: your code talks to the Nexus app already installed and
signed in on the machine, not to a cloud API. Under the hood the SDK is a small
[MCP](https://modelcontextprotocol.io) client — it connects to the local MCP
server the app exposes and drives the agent through a single `run` tool.

## Why it's different from a CAD/CAE API

The usual way to automate engineering software is each vendor's scripting API —
the SolidWorks API, Abaqus Python, PyAnsys, COMSOL's model API. Those are
**imperative**: you script every operation, one tool at a time, and the script
breaks the moment a model isn't quite what you assumed.

The Nexus SDK is **goal-level and agentic**:

<CardGroup cols={2}>
  <Card title="Outcomes, not operations" icon="bullseye">
    Describe the result. The agent plans the steps, adapts to the actual model,
    and handles the edge cases — instead of replaying a brittle macro.
  </Card>

  <Card title="One surface, every platform" icon="layer-group">
    The same SDK drives SolidWorks, Abaqus, Ansys, COMSOL, and Fluent — not a
    different API per vendor.
  </Card>

  <Card title="The same agent as the app" icon="equals">
    No capability gap: anything Nexus can do interactively, your code can trigger.
  </Card>

  <Card title="Autonomy you dial" icon="sliders">
    From unattended batches to interactive runs where your code answers the
    agent's questions and approves its actions — set by the handlers you pass.
  </Card>
</CardGroup>

## The connection model

Four pieces are involved: **your code** (the SDK), the **Nexus app** running the
agent, the **LLM** it reasons with, and the **CAD/CAE software** on
your machine. Everything but the model runs locally — including your login and
billing, which stay inside the app.

```mermaid theme={null}
flowchart LR
    subgraph machine["Your machine"]
        direction LR
        SDK["Your code<br/>(Agent SDK)"]
        APP["Nexus app<br/>agent + your login"]
        CAD["CAD/CAE software"]
    end
    LLM["LLM<br/>(cloud model)"]

    SDK <-->|"run · streamed answer"| APP
    APP <-->|"drives"| CAD
    APP <-->|"reasons"| LLM
```

### The agent loop

A `run` isn't a single call to the model — the agent works in a loop, driving
your CAD/CAE software one step at a time and adapting to what it finds, exactly
as it does in the app. The SDK streams each step back to you as it happens:

```mermaid theme={null}
sequenceDiagram
    participant You as Your code (SDK)
    participant App as Nexus app (agent)
    participant CAD as CAD/CAE software

    You->>App: run("mesh & solve")
    loop each step
        App->>CAD: drive a tool
        CAD-->>App: result
        App-->>You: stream the step
    end
    App-->>You: final answer
```

* **Your code never holds an API key.** Authentication and billing stay in the
  installed app. The SDK discovers the running app on `localhost` and rides it.
* **It acts on the machine it runs on.** Like the app, the SDK drives the CAD/CAE
  software installed locally — that's the whole point.
* **SDK runs stay out of the app's UI.** A scripted run executes exactly like a
  chat, but it doesn't appear in the app's conversation list — your script owns
  it. Use a [`session`](/sdk/guide#multi-turn-sessions) to keep context across
  turns; conversations persist and are resumable until you delete them (or mark
  a run [`ephemeral`](/sdk/guide#multi-turn-sessions)). The
  [Guide](/sdk/guide#multi-turn-sessions) walks through both.

<Note>
  The SDK requires the Nexus app to be **running, signed in, with Developer access
  turned on** (Settings → Developer access). It connects only over loopback and
  authenticates with a per-launch token the app writes locally — nothing is
  exposed off the machine.
</Note>

## What you can ask for

A prompt you'd type into the Nexus app is a prompt you can send from the SDK —
same agent, same capabilities. So the question *"what can the SolidWorks agent
do?"* has the same answer whether you drive it by chat or by code. The
capability guides list what each platform handles, each with a library of
**example prompts** you can lift straight into `client.run(...)`:

<CardGroup cols={2}>
  <Card title="Geometry creation" icon="cube" href="/cad/geometry-creation">
    Sketches, features, assemblies, part families — from a description.
  </Card>

  <Card title="Drafting & DFX" icon="pen-ruler" href="/cad/drafting">
    Drawings, GD\&T, BOMs, and design-for-X checks.
  </Card>

  <Card title="Simulation preprocessing" icon="gauge" href="/cae/preprocessing">
    Cleanup, mesh, materials, and boundary conditions.
  </Card>

  <Card title="Postprocessing" icon="chart-line" href="/cae/postprocessing">
    Extract results, compare studies, and report.
  </Card>
</CardGroup>

```python theme={null}
# Any of those example prompts works verbatim through the SDK:
client.run(
    "Create a rectangular base plate 120x80x6mm with four M6 counterbored "
    "holes 10mm from each corner, and set the material to Aluminium 6061-T6.",
    agent="solidworks",
).text()
```

See [Supported Software](/getting-started/supported-software) for the full
platform and version list.

## When to use it

<CardGroup cols={2}>
  <Card title="Batch automation" icon="layer-group">
    Run the same study across dozens of parts, unattended.
  </Card>

  <Card title="Pipelines & CI" icon="arrows-spin">
    Trigger an analysis from a build step or a data pipeline.
  </Card>

  <Card title="Custom tooling" icon="screwdriver-wrench">
    Wire Nexus into an internal app, notebook, or web service.
  </Card>

  <Card title="Reproducible runs" icon="repeat">
    Capture a workflow as code you can re-run and version.
  </Card>
</CardGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="bolt" href="/sdk/quickstart">
    Install, enable Developer access, and run your first agent in Python.
  </Card>

  <Card title="Guide" icon="book-open" href="/sdk/guide">
    Stream the run, answer the agent with handlers, and run unattended batches.
  </Card>

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

  <Card title="Python reference" icon="code" href="/sdk/python-reference">
    Clients, runs, interaction handlers, streaming, and errors.
  </Card>

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