Python SDK

The Python wrapper is async-first, easy to drop into services and notebooks, and maps cleanly onto the runtime event stream.

Install

uv

uv add autohand-sdk

pip

pip install autohand-sdk

Stream a prompt

`AutohandSDK` works best inside an async context manager so startup and teardown stay tidy.

Python

import asyncio
from autohand_sdk import AutohandSDK

async def main():
    async with AutohandSDK(cwd='.', model='fantail2') as sdk:
        async for event in sdk.stream_prompt('Explain what src/index.ts is responsible for.'):
            if event['type'] == 'message_update':
                print(event.get('delta', ''), end='')
            elif event['type'] == 'tool_start':
                print('\nRunning', event.get('tool_name') or event.get('toolName'))

asyncio.run(main())

Respond to permission requests

Python

async with AutohandSDK(cwd='.', permission_mode='interactive') as sdk:
    async for event in sdk.stream_prompt('Run the test suite and summarize failures.'):
        if event['type'] == 'permission_request':
            await sdk.respond_to_permission(
                event['request_id'],
                decision='allow',
                allowed=event.get('tool') != 'run_command',
            )
            continue

        if event['type'] == 'message_update':
            print(event.get('delta', ''), end='')

Parse typed events

Raw events are dictionaries, but you can upgrade known ones into typed models when you want stricter handling.

Python

from autohand_sdk import parse_sdk_event

async with AutohandSDK(cwd='.') as sdk:
    async for raw_event in sdk.stream_prompt('Hello'):
        event = parse_sdk_event(raw_event)
        if not isinstance(event, dict) and event.type == 'message_update':
            print(event.delta or '', end='')

Activate skills

The Python wrapper can point at installed skills or local `SKILL.md` files.

Python

sdk = AutohandSDK(
    cwd='.',
    skill_refs=[
        'typescript',
        './skills/my-custom/SKILL.md',
        {'name': 'api', 'path': '/absolute/path/to/SKILL.md'},
    ],
    copy_skill_files=False,
)

Configuration notes

  • `startup_check=True` is useful when you want fast feedback if the CLI process does not come up cleanly.
  • Known camelCase fields are mirrored with snake_case aliases on incoming event dictionaries.
  • Provider configuration still lives in the CLI config file for the CLI-backed Python SDK.

Next steps

  • Open [Handle approvals and user input](/docs/agent-sdk/io/approvals.html) for the full review loop.
  • Open [Python API](/docs/agent-sdk/python-api.html) for reference details.