# Agent Integration

This guide covers patterns for running AI agents and automation systems on Chaser with durable environments, MCP tools, and team governance.

## Durable agent workspace

Give an agent its own persistent workspace:

```bash
chaser workspaces create --session-type sandbox --name agent-home --json
```

The agent uses the MCP `terminal` tool to run commands. Chaser auto-provisions a sandbox session and reuses it on subsequent calls:

```bash
curl -sS "$CHASER_API_URL/v1/mcp" \
  -H "Authorization: Bearer $CHASER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0", "id": 1,
    "method": "tools/call",
    "params": {
      "name": "terminal",
      "arguments": {
        "workspace": "agent-home",
        "command": "git status && ls -la /workspace"
      }
    }
  }' | jq
```

The response includes `session_id` and `workspace_id` for follow-up calls that want to target the same runtime.

## Service accounts for agents

Create a dedicated service account with minimal permissions:

```bash
# Create the service account
chaser --account "Acme Engineering" accounts service-accounts create \
  --name ci-agent --json

# Create a scoped API key
chaser --account "Acme Engineering" accounts service-accounts keys create \
  <service_account_id> \
  --name ci-agent-key \
  --scope sessions.read \
  --scope sessions.write \
  --scope workspaces.read \
  --scope workspaces.write \
  --scope exec.write \
  --scope files.read \
  --scope files.write \
  --json
```

Service account keys can use MCP for compute and workspace automation, including `terminal`, `browser`, session lifecycle tools, and workspace management. They cannot access assistant configuration or vault tools.

## MCP tool surface for agents

The recommended tools for agent integration:

| Tool | Purpose |
|------|---------|
| `terminal` | Shell commands and structured file operations in sandboxes |
| `browser` | Browser automation via `chrome-devtools-mcp` |
| `chaser_list_sessions` | List sessions in the active account |
| `chaser_get_session` | Get session details |
| `chaser_create_sandbox_session` | Explicit sandbox creation |
| `chaser_create_browser_session` | Explicit browser creation |
| `chaser_terminate_session` | Terminate a session |
| `chaser_exec_sandbox` | Run a command in a sandbox |
| `chaser_self_test_sandbox` | Runtime diagnostic |
| `chaser_get_sandbox_forward_url` | Get a port forwarding URL |
| `chaser_list_workspaces` | List workspaces |
| `chaser_get_workspace` | Get workspace details |
| `chaser_set_workspace_name` | Rename a workspace |
| `chaser_delete_workspace` | Delete a workspace |

Most agents should start with `terminal` and `browser` and only use the lower-level tools when they need explicit lifecycle control.

## Human + agent coexistence

- The workspace is the shared state boundary -- both humans and agents see the same files
- Organization members can inspect account-scoped workspaces via the dashboard, CLI, or API
- Lifecycle webhooks and audit events make agent actions visible to operators
- `POST /v1/sessions/{id}/self-test` lets operators verify the sandbox runtime when an agent reports issues

## Ephemeral agent execution

When the agent task is stateless and isolation matters more than continuity:

```bash
curl -sS "$CHASER_API_URL/v1/mcp" \
  -H "Authorization: Bearer $CHASER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0", "id": 1,
    "method": "tools/call",
    "params": {
      "name": "terminal",
      "arguments": {
        "ephemeral": true,
        "command": "python3 -c \"print(2+2)\""
      }
    }
  }' | jq
```

## Related

- [MCP Integration](/docs/developer-tools/mcp-integration) -- full MCP reference
- [Accounts & Teams](/docs/platform/accounts-teams) -- service accounts and roles
- [Audit](/docs/platform/audit) -- event tracking for governance