Cosmon Agent SDK (Python)

⚠️ Alpha. This SDK is an early release: the API surface is still moving and breaking changes will ship in minor versions while we're on 0.x. Pin an exact version (cosmon-agent-sdk==0.1.1) in anything you don't want to fix on upgrade day, and read the CHANGELOG before bumping.

Program the Nexus agent in your installed, signed-in Cosmon app — drive SolidWorks, Abaqus, COMSOL, Fluent, Ansys Mechanical and more from your own Python. Your code brings the caller; the installed app brings the capability (your login, your credits, the CAD software on your machine). Your code never holds a key.

Under the hood the SDK is a small MCP client: it discovers the running app, connects to the local MCP server it exposes, and drives the agent through one run tool.

Install

pip install cosmon-agent-sdk

Then: open Cosmon, sign in, and turn on Settings → Developer access.

Check it's working:

cosmon doctor

Quickstart

client.run() returns a Run; get the agent's final answer with .text():

from cosmon_agent_sdk import Client

with Client() as client:
    answer = client.run("What's the max von Mises in bracket.sldprt?", agent="solidworks").text()
    print(answer)

Or iterate the run to stream it — it yields typed ToolCall / TextChunk events (.text() and iterating are the two ways to consume a run; pick one):

import sys
from cosmon_agent_sdk import Client, TextChunk, ToolCall

with Client() as client:
    for event in client.run("Run a static study on bracket.sldprt", 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

Attended vs unattended

Interactivity is set when you build the client, by whether you supply handlers:

• Unattended (default) — no handlers. The agent is never offered ask_user (it proceeds on its own) and confirmations are auto-resolved (approve safe, decline dangerous). .text() just runs to completion. This is the headless path; put any decisions the agent might otherwise ask about in the prompt.
• Interactive — supply on_question and/or on_confirm. The app forwards the agent's ask_user / confirm_action to your handlers (over MCP elicitation) while .text() runs to completion. There's no event loop to drive — your handlers are called as needed, so .text() never stalls waiting for an answer.

from cosmon_agent_sdk import Client, Question, Confirmation

def answer(question: Question) -> str:
    return question.options[0] if question.options else "10mm seed size"

def approve(confirmation: Confirmation) -> bool:
    return True  # your policy here

with Client(on_question=answer, on_confirm=approve) as client:
    print(client.run("Mesh the model and submit the job", agent="abaqus").text())

Long runs

The agent can work for many minutes (mesh, solve, post-process). The client sets a generous default timeout (10 minutes) and you can raise it:

with Client(timeout=1800) as client:   # 30 minutes
    client.run("Run a mesh-convergence study on bracket.sldprt", agent="solidworks").text()

Async

AsyncClient is the async twin (for pipelines, FastAPI, etc.) — same surface, awaited:

import asyncio
from cosmon_agent_sdk import AsyncClient

async def main() -> None:
    async with AsyncClient() as client:
        print(await client.run("what can you do?", agent="nexus").text())

asyncio.run(main())

Client/AsyncClient and Run/AsyncRun are the sync/async pairs.

Command line

cosmon doctor                                  # check the connection, step by step
cosmon run "mesh and solve" --agent abaqus                  # stream the work (steps to stderr)
cosmon run "what can you do?" --agent nexus -q              # -q: print just the final answer

The CLI is headless (it can't answer ask_user); --auto-approve additionally approves confirmation requests, including dangerous ones.

Notes

• Discovery: the app writes a mcp-gateway.json descriptor while Developer access is on; the SDK reads it automatically. Override with the COSMON_SDK_DESCRIPTOR environment variable.
• Errors: connecting / starting a run can raise CosmonConnectionError, CosmonAuthError, CosmonTimeoutError, CosmonProtocolError; a run that fails while running raises CosmonRunError from .text().
• Docs: https://docs.cosmon.com/