Metadata-Version: 2.4
Name: computer-agents
Version: 2.6.2
Summary: Official Python SDK for the Computer Agents Agentic Compute Platform API. Build with threads, computers, agents, resources, and databases.
Project-URL: Homepage, https://computer-agents.com
Project-URL: Documentation, https://computer-agents.com/documentation
Project-URL: Repository, https://github.com/computer-agents/computer-agents-sdk-python
Project-URL: Issues, https://github.com/computer-agents/computer-agents-sdk-python/issues
Project-URL: Changelog, https://github.com/computer-agents/computer-agents-sdk-python/blob/main/CHANGELOG.md
Author: Computer Agents
License-Expression: MIT
License-File: LICENSE
Keywords: agentic-compute-platform,agents,ai,api,automation,cloud,code-generation,computer-agents,mcp,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: httpx>=0.25.0
Provides-Extra: dev
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: respx>=0.21.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Description-Content-Type: text/markdown

# Computer Agents Python SDK

[![PyPI version](https://img.shields.io/pypi/v/computer-agents.svg)](https://pypi.org/project/computer-agents/)
[![Python versions](https://img.shields.io/pypi/pyversions/computer-agents.svg)](https://pypi.org/project/computer-agents/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

The official Python SDK for the [Computer Agents](https://computer-agents.com) Cloud API. Build against the Agentic Compute Platform with threads, computers, resources, databases, skills, and agents.

## Installation

```bash
pip install computer-agents
```

## Quick Start

```python
from computer_agents import ComputerAgentsClient

client = ComputerAgentsClient(api_key="ca_your_api_key")

# Execute a task
result = client.run(
    "Create a REST API with Flask",
    computer_id="env_xxx",
    on_event=lambda e: print(e["type"]),
)

print(result.content)
print(f"Thread ID: {result.thread_id}")
```

## Multi-Turn Conversations

```python
# Create a thread for persistent conversation
thread = client.threads.create(environment_id="env_xxx")

# First message
result = client.threads.send_message(
    thread["id"],
    content="Create a Python web server",
    on_event=lambda e: print(e),
)

# Follow-up (continues same session)
result2 = client.threads.send_message(
    thread["id"],
    content="Add authentication to the server",
)
```

## Computers

```python
# Create a custom computer
computer = client.computers.create(
    name="data-science",
    internet_access=True,
    runtimes={"python": "3.12"},
)

# Install packages
client.computers.install_packages(computer["id"], "python", ["pandas", "numpy"])

# Add MCP servers
client.computers.update(
    computer["id"],
    mcp_servers=[{
        "type": "stdio",
        "name": "filesystem",
        "command": "npx",
        "args": ["@modelcontextprotocol/server-filesystem", "/workspace"],
    }],
)
```

## Supported Models

| Model | ID | Use Case |
|-------|-----|----------|
| Claude 4.7 Opus | `claude-opus-4-7` | Latest Anthropic flagship, hardest coding and reasoning tasks |
| Claude 4.6 Opus | `claude-opus-4-6` | Most capable, complex tasks |
| Claude 4.5 Sonnet | `claude-sonnet-4-5` | Balanced Claude option |
| Claude 4.5 Haiku | `claude-haiku-4-5` | Fast, efficient |
| GPT-5.5 Pro | `gpt-5.5-pro` | Highest-accuracy OpenAI model for the hardest professional and agentic work |
| GPT-5.5 | `gpt-5.5` | OpenAI frontier model for coding, professional work, and long-context agents |
| GPT-5.4 | `gpt-5.4` | OpenAI flagship for advanced coding and planning |
| GPT-5.4 mini | `gpt-5.4-mini` | Fast OpenAI coding, subagents, and computer use |
| GPT-5.4 nano | `gpt-5.4-nano` | Lightweight OpenAI model for simple, high-volume workflows |
| Gemini 3 Flash | `gemini-3-flash` | Low-latency general workflows |
| Gemini 3.1 Flash | `gemini-3-1-flash` | Alias tier that currently routes through the Gemini 3 Flash runtime |
| Gemini 3.1 Pro | `gemini-3-1-pro` | Broader reasoning and research tasks |
| DeepSeek V4 Pro | `deepseek-v4-pro` | DeepSeek flagship for agentic coding and long-context reasoning |
| DeepSeek V4 Flash | `deepseek-v4-flash` | Fast, efficient DeepSeek model for agent execution |
| Kimi K2.6 | `kimi-k2.6` | Moonshot flagship via Cloudflare Workers AI for long-horizon coding and tool use |

Built-in system agents default to DeepSeek V4 Pro, while the Developer system agent defaults to Kimi K2.6.

## Thread Feedback and Permissions

```python
summary = client.threads.set_feedback(thread["id"], "up")

client.threads.report_issue(
    thread["id"],
    report_type="bug",
    message="The thread missed the requested test run.",
)

requests = client.threads.list_permission_requests(thread["id"])
if requests:
    client.threads.approve_permission_request(thread["id"], requests[0]["requestId"])
```

## Tasks

```python
task = client.tasks.create(
    "Add login audit logs",
    project_id="proj_xxx",
    status="todo",
    priority="high",
)

client.tasks.create_comment(
    task["id"],
    body="Include success and failure cases.",
)

started = client.tasks.start_thread(
    task["id"],
    environment_id="env_xxx",
)

result = client.tasks.run_thread(
    task["id"],
    environment_id="env_xxx",
    message="Implement the ticket and summarize changed files.",
)
```

## Computer Change History

```python
history = client.computers.list_changes(
    computer["id"],
    limit=25,
    project_id="proj_123",
    operation=["created", "modified"],
)

latest = history["data"][0]
latest_file = latest["files"][0]

diff = client.computers.get_change_diff(
    computer["id"],
    latest["id"],
    path=latest_file["path"],
)

file_state = client.computers.get_change_file(
    computer["id"],
    latest["id"],
    path=latest_file["path"],
)

fork = client.computers.fork_from_change(
    computer["id"],
    latest["id"],
    name="history-branch",
)
```

## Agents

```python
# Create a custom agent
agent = client.agents.create(
    name="Code Reviewer",
    model="claude-sonnet-4-5",
    instructions="You are a thorough code reviewer.",
    enabled_skills=["web_search"],
)

# Use the agent
thread = client.threads.create(
    computer_id="env_xxx",
    agent_id=agent["id"],
)
```

## Files

```python
# Upload a file
client.files.upload_file(
    "env_xxx",
    filename="app.py",
    content='print("hello")',
    path="src",
)

# Download a file
content = client.files.get_file("env_xxx", "src/app.py")

# Download a folder as a zip archive
zip_bytes = client.files.download_directory("env_xxx", "src")

# List files
files = client.files.list_files("env_xxx")
```

## Git Operations

```python
diff = client.git.diff("env_xxx")
client.git.commit("env_xxx", message="Update feature")
client.git.push("env_xxx")
```

## Schedules

```python
schedule = client.schedules.create(
    name="Daily Report",
    agent_id="agent_xxx",
    agent_name="Reporter",
    task="Generate daily report",
    schedule_type="recurring",
    cron_expression="0 9 * * *",
)
```

## Resources

```python
resource = client.resources.create(
    name="crm-web",
    kind="web_app",
    auth_mode="public",
)

client.resources.deploy(resource["id"])
analytics = client.resources.get_analytics(resource["id"])
```

## Databases

```python
database = client.databases.create(name="crm-data")

client.databases.create_collection(database["id"], name="leads")
client.databases.create_document(
    database["id"],
    "leads",
    data={"company": "Acme", "stage": "new"},
)
```

## Skills

```python
skills = client.skills.list()
print([skill["name"] for skill in skills])
```

## Configuration

The API key can be provided via:

1. Constructor argument: `ComputerAgentsClient(api_key="ca_...")`
2. Environment variable: `COMPUTER_AGENTS_API_KEY`

```python
# Custom base URL and timeout
client = ComputerAgentsClient(
    api_key="ca_...",
    base_url="https://custom-api.example.com",
    timeout=120.0,
    debug=True,
)
```

## Context Manager

```python
with ComputerAgentsClient(api_key="ca_...") as client:
    result = client.run("Hello world", computer_id="env_xxx")
    print(result.content)
# Client is automatically closed
```

## API Resources

| Resource | Description |
|----------|-------------|
| `client.threads` | Conversation management with SSE streaming |
| `client.environments` / `client.computers` | Computer configuration and lifecycle |
| `client.agents` | Agent configuration (model, instructions, skills) |
| `client.resources` | Web apps, functions, auth modules, runtimes, and secret vaults |
| `client.web_apps` / `client.functions` / `client.auth` / `client.runtimes` / `client.secrets` | Product-shaped server resource managers |
| `client.databases` | Managed database surfaces |
| `client.skills` | Custom ACP skills |
| `client.files` | File management in computer workspaces |
| `client.tasks` | Planning tasks, comments, releases, sprints, and task-linked threads |
| `client.schedules` | Scheduled task management |
| `client.triggers` | Event-driven triggers |
| `client.orchestrations` | Agent-to-agent orchestration |
| `client.budget` | Budget and usage tracking |
| `client.billing` | Billing records and statistics |
| `client.git` | Git operations on computer workspaces |
| `client.notifications` | In-app notifications and push token registration |

## Requirements

- Python >= 3.9
- httpx >= 0.25.0

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.

## License

MIT - see [LICENSE](LICENSE) for details.
