Autohand Code Agent SDK for Python

Build AI agents with Autohand Code. Clean public APIs, provider-agnostic backends, and an ecosystem dashboard.

Note: This SDK is designed to work with the Autohand Code CLI. While the SDK can be used standalone, we recommend installing the CLI for the best experience.

Installation

pip install autohand-agents

Prerequisites:

• Python 3.10+
• Autohand Code CLI (recommended for full functionality)

Quick Start

from autohand_agents import Agent, Runner

agent = Agent(name="Assistant", instructions="You are a helpful assistant")
result = Runner.run_sync(agent, "Write a haiku about coding.")
print(result.final_output)

Basic Usage: query()

query() is an async function for querying AI agents. It returns an AsyncIterator of response messages.

import asyncio
from autohand_agents import query

async def main():
    async for message in query("What is 2 + 2?"):
        print(message)

asyncio.run(main())

Using Tools

The SDK provides 40+ built-in tools for filesystem access, shell commands, git operations, and more.

import os
from autohand_agents import Agent, Runner, Tool

os.environ["AUTOHAND_PROVIDER"] = "openrouter"
os.environ["AUTOHAND_API_KEY"] = "your-api-key-here"

agent = Agent(
    name="Code Explorer",
    instructions="You are a software engineering assistant. Read code, understand it, and answer questions.",
    tools=[Tool.READ_FILE, Tool.BASH],
    max_turns=15,
)

result = Runner.run_sync(agent, "What does the auth module in src/auth.py do?")
print(result.final_output)

Streaming Responses

For long-running agents, you want to see progress in real-time:

import asyncio
from autohand_agents import Agent, Runner

agent = Agent(
    name="Explorer",
    instructions="Explore the codebase and report your findings.",
    tools=[Tool.FIND, Tool.GLOB, Tool.READ_FILE],
)

async def main():
    async for chunk in Runner.run_stream(agent, "Find all Python test files"):
        print(chunk)

asyncio.run(main())

Configuration

Configure providers and models via environment variables:

export AUTOHAND_PROVIDER=openrouter
export AUTOHAND_API_KEY=sk-or-v1-...
export AUTOHAND_MODEL=your-model-name-here

Available Tools

The SDK provides 40+ built-in tools organized by category:

Category	Tools
Filesystem	read_file, write_file, edit_file, apply_patch, find, glob, search_in_files
Commands	bash
Git	git_status, git_diff, git_log, git_commit, git_add, git_reset, git_push, git_pull, git_fetch, git_checkout, git_switch, git_branch, git_merge, git_rebase, git_stash, git_apply_patch, git_worktree_list, git_worktree_add
Web	web_search
Notebook	notebook_read, notebook_edit
Dependencies	read_package_manifest, add_dependency, remove_dependency
Formatters	format_file, format_directory, list_formatters, check_formatting
Linters	lint_file, lint_directory, list_linters

Providers

The SDK is provider-agnostic and supports multiple LLM backends:

Provider	Notes
OpenRouter	Primary/default, 200+ models
OpenAI	Direct OpenAI API
Ollama	Local models
Azure	Enterprise Azure OpenAI
LlamaCpp	Local LLaMA.cpp server
MLX	Apple Silicon local runtime
LLMGateway	Internal gateway proxy

Types

See src/autohand_agents/types.py for complete type definitions:

• Agent - Agent configuration with instructions, tools, and model settings
• AgentOptions - Runtime options for agent execution
• Tool - Tool definitions and permissions
• Session - Conversation state management
• RunnerResult - Execution results with outputs and metadata

Examples

See examples/ for comprehensive examples:

• 01-hello-agent.py - Basic agent usage
• 02-streaming-query.py - Streaming responses
• 03-code-reviewer-agent.py - Code review workflow
• 04-bash-command.py - Shell command execution
• 05-file-editor-agent.py - File editing
• 06-patch-application.py - Git patch workflow
• And many more...

Documentation

• Guides - Detailed tutorials on agent patterns, provider configuration, streaming, and more
• Reference - API reference for Agent, Runner, Tools, Types, and Config
• Examples - 26+ working examples covering common use cases
• Autohand Code CLI - The companion CLI for Autohand Code

Development

If you're contributing to this project:

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run tests with coverage
pytest --cov=autohand_agents

For development with the Autohand Code CLI, see the CLI repository.

Docker

Run the SDK in an isolated Docker environment:

# Build the Docker image
docker build -t autohand-agents .

# Run tests in Docker
docker run --rm autohand-agents

# Run a specific example
docker run --rm -e AUTOHAND_API_KEY=your-key autohand-agents python examples/01-hello-agent.py

Or use Docker Compose for easier development:

# Run tests
docker-compose --profile dev up

# Run an example
docker-compose --profile example up

# Interactive shell
docker-compose --profile shell run --rm shell

License

Apache License 2.0