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

pip install autohand-sdk
 
uv add autohand-sdk

AutohandSDK

Main async API for controlling the Autohand CLI.

Constructor

AutohandSDK(config: SDKConfig | None = None, **kwargs)

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

Lifecycle

await sdk.start()
await sdk.stop()
await sdk.close()

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

Prompting

async for event in sdk.stream_prompt(message: str, **kwargs):
    ...
await sdk.prompt(message: str, **kwargs)

Control Methods

await sdk.abort(reason="User cancelled")
await sdk.respond_to_permission(request_id, decision="allow", allowed=True, remember=False)
await sdk.set_model("fantail2")
await sdk.set_agent("code-reviewer")
await sdk.set_temperature(0.2)

Information Methods

state = await sdk.get_state()
messages = await sdk.get_messages(limit=20)
models = await sdk.get_models()
agents = await sdk.get_agents()
account = await sdk.get_account_info()
await sdk.save_session()

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 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 for the complete normalized event contract.

Types

SDKConfig

@dataclass
class SDKConfig:
    cwd: str = "."
    cli_path: str | None = None
    debug: bool = False
    timeout: int = 300000
    model: str | None = None
    provider: str | None = None
    api_key: str | None = None
    permission_mode: str | None = None
    skills: list[str] | None = None

Exceptions

from autohand_sdk import RPCError, RequestTimeoutError, TransportNotStartedError
  • 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