---
title: "Python API Reference Code Agent SDK"
source: https://docs.autohand.ai/agent-sdk/python-api
---

# Python API Reference

Complete API reference for the Autohand SDK Python. The SDK spawns the Autohand CLI as a subprocess and communicates over JSON-RPC.

## Installation

## AutohandSDK

Main async API for controlling the Autohand CLI.

#### Constructor

Common args: `cwd`, `cli_path`, `debug`, `timeout`, `model`, `provider`, `api_key`, `permission_mode`, `skills`, etc.

#### Lifecycle

Also supports async context manager: `async with AutohandSDK(...) as sdk:`

#### Prompting

#### Control Methods

#### Information Methods

## CLI Runtime Control

The current Python SDK exposes the v1.0.4 control surface on both `Agent` and `AutohandSDK`.

-   **Lifecycle:** `reset`, `create_browser_handoff`, `attach_browser_handoff`, `attach_latest_browser_handoff`.
-   **Auto-mode:** `start_automode`, `get_automode_status`, `pause_automode`, `resume_automode`, `cancel_automode`, `get_automode_log`.
-   **Approvals and sessions:** `acknowledge_permission`, `respond_to_directory_access`, `acknowledge_directory_access`, `decide_changes`, `get_history`, `get_session`, `attach_session`.
-   **Integrations:** `set_yolo`, `set_yolo_compat`, `set_vscode_mcp_tools`, `respond_to_mcp_invocation`, `get_learning_recommendations`, `update_learned_skills`, `generate_skill`, `get_tools_registry`, `set_context_compact`.

Read [Control the Autohand CLI from every SDK](concepts/cli-runtime-control.html) for behavior, safety contracts, aliases, and the cross-language name map.

## Events

Events are dictionaries. Common types:

-   `agent_start` - Agent started a session
-   `message_update` - Streaming assistant text delta
-   `tool_start` - Tool execution started
-   `tool_end` - Tool execution completed
-   `permission_request` - Runtime pause for approval
-   `automode_iteration`, `automode_complete`, and `automode_error` - Auto-mode lifecycle
-   `error` - Transport, runtime, or execution failure

Common fields have both camelCase and snake\_case aliases: `sessionId/session_id`, `toolName/tool_name`, etc.

See [Hooks and events](concepts/hooks-and-events.html) for the complete normalized event contract.

## Types

### SDKConfig

## Exceptions

-   `TransportNotStartedError` - request attempted before start()
-   `RequestTimeoutError` - no JSON-RPC response before timeout
-   `RPCError` - CLI returned a JSON-RPC error response (has `code` and `data`)

## See Also

-   [Python SDK Overview](python.html)
-   [CLI Quick Start](../guides/cli-quick-start.html)