Skip to main content

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.2.0) in anything you don't want to fix on upgrade day, and read the CHANGELOG before bumping.

Program the Argus 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

Update the desktop app alongside SDK 0.2.0 to use the shared history and confirmation policy. If upgrading from 0.1.x, use confirmation_mode="manual" when your callback must approve every gated action. client.chats() now includes ordinary app-created conversations too; review scripts that delete listed chats.

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

Each tool call yields two events — finished=False then finished=True — carrying the same id and the same summary. If you render a component per step, key it on event.id: tools run in parallel and the same tool repeats within a run, so name does not identify a call.

Shared conversations

Ordinary app and SDK chats appear in the same history and search. List them with client.chats() and resume either kind with client.session(id=...). Wait for the current run to finish before continuing from the other client. Closing a session preserves its conversation; delete() removes it from both clients. ephemeral=True still opts into automatic deletion.

Attended vs unattended

The SDK uses the same runtime approval policy as the app. Handlers declare which requests the client can answer; registering one does not force Manual Mode.

  • No on_question: the agent is not offered ask_user.
  • on_confirm: receives only confirmations required by the current policy. Without a handler, a required approval returns “no answer”, never “user declined”.
  • confirmation_mode="auto": ordinary actions proceed; dangerous actions require approval.
  • confirmation_mode="manual": ask before every gated action.
  • confirmation_mode="approve_all": explicitly approve all gates, including dangerous actions, inside the runtime. This is also what CLI --auto-approve selects.

Omit confirmation_mode to follow the app's live Auto/Manual setting. Explicit modes apply to this client's runs and sessions without changing the app's settings.

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, confirmation_mode="manual") 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()

The CLI accepts the same deadline with cosmon run "..." --timeout 1800. Values must be positive and finite; omitting it keeps the 600-second default. Expiry requests server-side cancellation and raises CosmonTimeoutError. Native CAD work already dispatched can outlive that request; inspect its state before retrying.

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 "mesh and solve" --agent abaqus --timeout 1800   # 30-minute client deadline
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/

Metadata

Release files for cosmon-agent-sdk 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cosmon-agent-sdk 0.2.0
File Size Uploaded Provenance Actions
cosmon_agent_sdk-0.2.0.tar.gz 59.7 kB With provenance Details for cosmon_agent_sdk-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for cosmon-agent-sdk 0.2.0
File Interpreter ABI Platform Actions
cosmon_agent_sdk-0.2.0-py3-none-any.whl Python 3 none any Details for cosmon_agent_sdk-0.2.0-py3-none-any.whl

Total release size: 91.9 kB

Release files / cosmon_agent_sdk-0.2.0.tar.gz

Download URL cosmon_agent_sdk-0.2.0.tar.gz
Size 59.7 kB
Tags Source
SHA-256 checksum
How to use checksums
5a0ad28f4c9c0768c8197e052c878b9c84996f62fbc5a4e346492792bfc5aac9
BLAKE2b-256 checksum
How to use checksums
8ca2889b5f3cae284db4a9a5bb92c02462eb7327db2ac61bd1a8bf15f69c8123
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

Release files / cosmon_agent_sdk-0.2.0-py3-none-any.whl

Download URL cosmon_agent_sdk-0.2.0-py3-none-any.whl
Size 32.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5fbf7a390d988e20e7078c9056698819d7f44b511e29d67bed740f730ca82048
BLAKE2b-256 checksum
How to use checksums
17d2204aec93f13b6d6ef7b5022d21afa232c6cbd51897afea3570a47585f87d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

Security for cosmon-agent-sdk 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for cosmon_agent_sdk-0.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page