Computer Agents Python SDK

Official Python SDK for Computer Agents, the Agentic Compute Platform.

Computer Agents gives AI agents the things a real teammate needs to finish work: persistent cloud computers, files, project plans, tasks, memory, skills, scheduled work, and deployable resources. Use this SDK from Python scripts, services, notebooks, backend jobs, and internal tools to start agents, stream their work, manage projects and computers, deploy resources, store data, and monitor usage.

What You Can Build

• Agentic product workspaces with projects, releases, tickets, reviewers, comments, and task-linked threads.
• Persistent cloud computers where agents can browse, code, run CLIs, install packages, edit files, and keep state across sessions.
• Hosted products and internal tools with Web Apps, Functions, Databases, Auth, Agent Runtimes, and Secrets.
• Automated research and operations with threads, schedules, triggers, skills, and reusable custom agents.
• Python control planes for your own apps, CI jobs, data workflows, research systems, and backend automation.

Install

pip install computer-agents

Python 3.9 or newer is required.

Authenticate

Create an API key in Computer Agents, then set:

export COMPUTER_AGENTS_API_KEY="ca_..."

from computer_agents import ComputerAgentsClient

client = ComputerAgentsClient()

You can also pass the key directly:

client = ComputerAgentsClient(api_key="ca_...")

Cloud and Appliance Base URLs

Set base_url per client to target a local appliance or another Computer Agents deployment:

client = ComputerAgentsClient(
    api_key="ca_...",
    base_url="https://appliance.example.com",
)

You can alternatively configure a process-wide default:

export COMPUTER_AGENTS_BASE_URL="https://appliance.example.com"

An origin and an already-versioned URL are both accepted, so https://appliance.example.com and https://appliance.example.com/v1 resolve to the same API. The setting applies to regular requests, event streams, downloads, and multipart uploads. The older COMPUTER_AGENTS_API_URL environment variable remains supported.

For direct HTTP calls, append the canonical /v1 API prefix:

curl https://appliance.example.com/v1/agents \
  -H "Authorization: Bearer $COMPUTER_AGENTS_API_KEY"

Quick Start

Run a task and stream the agent's work:

from computer_agents import ComputerAgentsClient

client = ComputerAgentsClient()

result = client.run(
    "Create a small FastAPI service and explain how to run it.",
    on_event=lambda event: print(event["type"]),
)

print(result.content)
print(result.thread_id)

Core Concepts

All 43 tenant-facing platform service groups—including prompts, knowledge, guardrails, evaluations, Tests, assurance, fine-tuning, optimization campaigns and candidates, Metronomes, Batches, Security Agents, evidence review, organization administration, and billing/inference endpoints—are available as first-class SDK managers. See the API and SDK capability map.

Persistent Computers and Threads

Create a computer, start a thread inside it, and continue later with the same files and state:

computer = client.computers.create(
    name="product-build-computer",
    internet_access=True,
)

thread = client.threads.create(environment_id=computer["id"])

client.threads.send_message(
    thread["id"],
    content="Create a Python API with a health route.",
    on_event=lambda event: print(event["type"]),
)

client.threads.send_message(
    thread["id"],
    content="Now add authentication and tests.",
)

logs = client.threads.get_logs(thread["id"])
diffs = client.threads.get_diffs(thread["id"])

Thread methods include create, list, get, send_message, cancel, resume, copy, search, get_messages, get_logs, get_status, get_diffs, list_steps, download_step_file, fork_from_step, revert_to_step, set_feedback, report_issue, and permission request approval/denial.

Projects and Tasks

Use projects when agents need the same context a human team would need: the goal, current release, backlog, comments, dependencies, resources, and review policy.

project = client.projects.create(
    "Customer Portal",
    description="Build and deploy an authenticated customer portal.",
)

release = client.tasks.create_release(
    project["id"],
    "v0.1 MVP",
    description="Ship the first production-ready customer workflow.",
    success_criteria=[
        "Customers can sign in and update account settings.",
        "The release passes its linked test and assurance gates.",
    ],
)

task = client.tasks.create(
    "Deploy login and account settings",
    project_id=project["id"],
    release_id=release["id"],
    status="todo",
    priority="high",
)

client.tasks.create_comment(
    task["id"],
    body="Include password reset and session validation.",
)

client.tasks.run_thread(
    task["id"],
    environment_id=computer["id"],
)

For an autonomous project, submit one strict delivery contract and let the control plane create the standard graph and bindings atomically:

planned = client.projects.put_delivery_plan(
    project["id"],
    contract,
    idempotency_key=f"mission-control-{project['id']}-delivery-v1",
)
delivery_plan = client.projects.provision_delivery_plan(project["id"])

print(delivery_plan["graph"]["nodes"])
print(delivery_plan["bindings"])

The provisioned optimization job starts in planned; queue it only after the bound build, Test, and baseline Evaluation dependencies pass:

optimization_job_id = delivery_plan["bindings"].get("optimizationJobId")
if optimization_job_id:
    client.fine_tuning.queue_job(
        optimization_job_id,
        source="project_delivery_graph",
    )

Tests, Evaluations, and Optimization

Use client.tests for engineering verification. Test Plans are immutable by version, execute in a selected Computer Agents environment, and return case-level results plus a server-fingerprinted terminal evidence envelope.

test_plan = client.tests.create(
    name="Customer Portal release gate",
    project_id=project["id"],
    target_type="project",
    definition={
        "cases": [
            {
                "id": "unit",
                "name": "Unit tests",
                "kind": "command",
                "command": "pytest",
            },
            {
                "id": "health",
                "name": "Deployed health contract",
                "kind": "contract",
                "request": {"method": "GET", "path": "/api/health"},
                "assertions": [{"kind": "status", "equals": 200}],
            },
        ]
    },
)

test_run = client.tests.run(
    test_plan["id"],
    environment_id=computer["id"],
    project_id=project["id"],
    task_id=task["id"],
    release_id=release["id"],
    commit_sha="0123456789abcdef",
    trigger_type="mission_control",
)

evidence = client.tests.get_run(test_run["id"])
print(evidence["status"], evidence["evidence"])

assurance_policy = client.assurance.create_policy(
    name="Customer Portal release assurance",
    project_id=project["id"],
    definition={
        "testGates": [
            {
                "id": "engineering",
                "testPlanId": test_plan["id"],
                "versionId": test_plan["publishedVersionId"],
                "requireCommitSha": True,
            }
        ],
        "approval": {"mode": "manual"},
    },
)

assurance_run = client.assurance.run(
    assurance_policy["id"],
    project_id=project["id"],
    release_id=release["id"],
    commit_sha="0123456789abcdef",
    evidence_references={"testRunIds": [test_run["id"]]},
)

if assurance_run["status"] == "blocked":
    client.assurance.approve(
        assurance_run["id"],
        assurance_run["evidence"]["fingerprint"],
    )

Tests answer whether software and workflows work. client.evaluations measures behavioral quality on versioned datasets, while client.fine_tuning performs a bounded optimization job from Evaluation evidence. client.assurance verifies the actual terminal evidence, pins it to versioned release gates, and emits one fingerprinted decision.

Deployable Server Resources

Computer Agents resources let humans and agents ship software from the same workspace where the work is planned and built.

Create and Deploy a Function

Upload source code from a computer, create the Function, deploy it, then invoke it.

client.files.upload_file(
    computer["id"],
    path="functions/hello-world",
    filename="index.mjs",
    content="""
export default async function handler(request) {
  return Response.json({ message: 'Hello from Computer Agents Functions' });
}
""",
    content_type="text/javascript",
)

fn = client.functions.create(
    name="hello-world",
    source_type="computer",
    source_environment_id=computer["id"],
    source_path="functions/hello-world",
    runtime="nodejs22",
    auth_mode="public",
)

client.functions.deploy(fn["id"])

response = client.functions.invoke(
    fn["id"],
    method="GET",
    path="/",
)

print(response)

Resource managers support create, list, get, update, delete, deploy, list_deployments, rollback_deployment, invoke, get_analytics, get_logs, list_bindings, upsert_binding, delete_binding, file operations, and secret operations. Auth resources also support list_users, create_user, sign_up, and sign_in.

Databases and Secrets

Use databases for app state and structured output. Use Secrets for credentials that functions, web apps, and agents can read at runtime.

import os

db = client.databases.create(name="crm-data")

leads = client.databases.create_collection(
    db["id"],
    name="leads",
)

client.databases.create_document(
    db["id"],
    leads["id"],
    data={
        "company": "Acme",
        "stage": "qualified",
        "owner": "agent",
    },
)

vault = client.secrets.create(name="production-secrets")

client.secrets.create_secret(
    vault["id"],
    name="SENDGRID_API_KEY",
    value=os.environ["SENDGRID_API_KEY"],
)

client.functions.upsert_binding(
    fn["id"],
    "database",
    target_id=db["id"],
    alias="appDatabase",
)

client.functions.upsert_binding(
    fn["id"],
    "secrets",
    target_id=vault["id"],
    alias="productionSecrets",
)

Server-side runtime helpers for deployed Node Functions and server-rendered Web Apps are available from the JavaScript SDK:

import { getSecretValue } from 'computer-agents/runtime/server';

Use this Python SDK to create, bind, deploy, invoke, monitor, and operate those resources from Python services and automation.

Schedules, Triggers, and Orchestrations

automation_agent = client.agents.list()[0]

client.schedules.create(
    "Daily competitor brief",
    automation_agent["id"],
    automation_agent["name"],
    "Research competitors and write a concise Markdown brief.",
    "recurring",
    environment_id=computer["id"],
    cron_expression="0 9 * * *",
)

client.triggers.create(
    "New lead enrichment",
    computer["id"],
    "webhook",
    "lead.created",
    {
        "type": "send_message",
        "message": "Enrich the new lead and update the CRM database.",
    },
    agent_id=automation_agent["id"],
)

client.orchestrations.create(
    "Research and build landing page",
    computer["id"],
    "sequential",
    [
        {
            "agentId": automation_agent["id"],
            "name": "Research market",
            "instructions": "Research the market and summarize the findings.",
        },
        {
            "agentId": automation_agent["id"],
            "name": "Build landing page",
            "instructions": "Use the research to write and deploy a landing page.",
        },
    ],
)

Agents and Models

models = client.agents.list_models()
model = next(entry["id"] for entry in models["models"] if not entry.get("locked"))

agent = client.agents.create(
    name="Senior Product Engineer",
    model=model,
    instructions="Build carefully, test changes, and explain tradeoffs.",
    reasoning_effort="high",
)

Computer Agents supports built-in models from Anthropic, OpenAI, Gemini, DeepSeek, Kimi, and connected external models on supported plans. Use client.agents.list_models() to read the current catalog instead of hard-coding model availability.

Budget and Usage

budget = client.budget.get_status()
can_run = client.budget.can_execute()
usage = client.billing.get_stats(days=30)

print({
    "budget": budget,
    "can_run": can_run,
    "usage": usage,
})

Context Manager

with ComputerAgentsClient(api_key="ca_...") as client:
    result = client.run("Hello world")
    print(result.content)

SDK Surface

Links

• Website
• Documentation
• API Reference
• PyPI
• GitHub

License

MIT