Python SDK

The Python SDK (qosm-mcp-client) lets you call published Qosm agents from Python applications using the MCP protocol.

Install

pip install qosm-mcp-client

Credentials

Credentials are resolved in order:

1. Explicit constructor arguments
2. Environment variables (QOSM_BASE_URL, QOSM_TOKEN)
3. .env file

# .env
QOSM_BASE_URL=https://your-qosm-host.com
QOSM_TOKEN=your_personal_access_token

Quick start

from qosm import QosmClient

client = QosmClient()  # resolves from env/.env

# List your projects
projects = client.get_projects()

# Typecheck code
check = client.qosm_check("let x = 1;", "@alice/my-project")

# Run an agent
run = client.qosm_run("@alice/my-agent")

Bound project API (recommended)

The bound API gives you a project-scoped client with direct function calls:

from qosm import QosmClient

client = QosmClient()
q = client.project("@alice/my-project")

# Call functions directly
result = q.add(1, 2)
summary = q.summarize(text="Hello world")

Async API

from qosm import AsyncQosmClient

client = AsyncQosmClient()

projects = await client.get_projects()
result = await client.qosm_run("@alice/my-agent")

Stub generation (typed)

Generate Python stubs for static typing:

qosm-stubgen @alice/my-project > my_project.pyi

This creates type stubs so your IDE can autocomplete function names and parameters.

Available methods

| Method | Description | |--------|-------------| | get_projects() | List all projects | | get_project_context(address) | Get project code and capabilities | | qosm_check(code, address) | Typecheck code | | qosm_run(address) | Execute a published agent | | get_project_functions(address) | List functions in a project | | call_function(address, name, args) | Call a specific function |

Error handling

from qosm import QosmClient, ToolError

client = QosmClient()

try:
    result = client.qosm_run("@alice/my-agent")
except ToolError as e:
    print(f"Execution failed: {e}")

Error types: AuthenticationError, ToolError, ProtocolError, ServerError.