pai-agent-sdk 0.16.0

Application framework for building AI agents with Pydantic AI - environment abstractions, session management, and hierarchical agent patterns

PAI Agent SDK

PAI is for Paintress or Pydantic AI

Application framework for building AI agents with Pydantic AI. Used to build the next-generation agent system of YouWare.

Key Features

• Environment-based Architecture: Protocol-based design for file operations, shell access, and resources. Built-in LocalEnvironment and DockerEnvironment, easily extensible for custom backends (SSH, S3, cloud VMs, etc.)
• Fully Typed: Complete type annotations validated with pyright (standard mode). Enjoy full IDE autocompletion and catch errors before runtime
• Resumable Sessions: Export and restore AgentContext state for multi-turn conversations across restarts
• Hierarchical Agents: Subagent system with task delegation, tool inheritance, and markdown-based configuration
• Skills System: Markdown-based instruction files with hot reload and progressive loading
• Human-in-the-Loop: Built-in approval workflows for sensitive tool operations
• Toolset Architecture: Extensible tool system with pre/post hooks for logging, validation, and error handling
• Resumable Resources: Export and restore resource states (like browser sessions) across process restarts
• Browser Automation: Docker-based headless Chrome sandbox for safe browser automation
• Streaming Support: Real-time streaming of agent responses and tool executions

Installation

# Recommended: install with all optional dependencies
pip install pai-agent-sdk[all]
uv add pai-agent-sdk[all]

# Or install individual extras as needed
pip install pai-agent-sdk[docker]    # Docker sandbox support
pip install pai-agent-sdk[web]       # Web tools (tavily, firecrawl, markitdown)
pip install pai-agent-sdk[document]  # Document processing (pymupdf, markitdown)

Project Structure

This repository contains:

• pai_agent_sdk/ - Core SDK with environment abstraction, toolsets, and session management
• paintress_cli/ - Reference CLI implementation with TUI for interactive agent sessions
• examples/ - Code examples demonstrating SDK features
• docs/ - Documentation for SDK architecture and APIs

Quick Start

Using the SDK

from pai_agent_sdk.agents import create_agent, stream_agent

# create_agent returns AgentRuntime (not a context manager)
runtime = create_agent("openai:gpt-4o")

# stream_agent manages runtime lifecycle automatically
async with stream_agent(runtime, "Hello") as streamer:
    async for event in streamer:
        print(event)

Using Paintress CLI

For a ready-to-use terminal interface, try paintress-cli - a TUI reference implementation built on top of pai-agent-sdk:

# Run directly with uvx (no installation needed)
uvx paintress-cli

# Or install globally
uv tool install paintress-cli
pip install paintress-cli

Features:

• Rich terminal UI with syntax highlighting and streaming output
• Built-in tool approval workflows (human-in-the-loop)
• Session management with conversation history
• Browser automation support via Docker sandbox
• MCP (Model Context Protocol) server integration

Examples

Check out the examples/ directory:

Example	Description
general.py	Complete pattern with streaming, HITL approval, and session persistence
deepresearch.py	Autonomous research agent with web search and content extraction
browser_use.py	Browser automation with Docker-based headless Chrome sandbox

For Agent Users

If you're using an AI agent (e.g., Claude, Cursor) that supports skills:

• Clone this repo: The SKILL.md file in the repository root provides comprehensive guidance for agents
• Download release package: Get the latest SKILL.zip from the Releases page (automatically built during each release)

Configuration

Copy examples/.env.example to examples/.env and configure your API keys.

Documentation

• AgentContext & Sessions - Session state, resumable sessions, extending context
• Streaming & Hooks - Real-time streaming, lifecycle hooks, event handling
• Toolset Architecture - Create tools, use hooks, handle errors, extend Toolset
• Subagent System - Hierarchical agents, builtin presets, markdown configuration
• Message Bus - Inter-agent communication, user steering during execution
• Skills System - Markdown-based skills, hot reload, pre-scan hooks
• Custom Environments - Environment lifecycle, resource management
• Resumable Resources - Export and restore resource states across restarts
• Model Configuration - Provider setup, gateway mode
• Logging Configuration - Configure SDK logging levels

Development

See CONTRIBUTING.md for development setup and guidelines.