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.

Release files for pai-agent-sdk 0.16.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pai-agent-sdk 0.16.1
File	Size	Uploaded
pai_agent_sdk-0.16.1.tar.gz	703.0 kB	Feb 5, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for pai-agent-sdk 0.16.1
File	Interpreter	ABI	Platform	Reset
pai_agent_sdk-0.16.1-py3-none-any.whl 243.2 kB Feb 5, 2026	Python 3	none	any	Details

Total release size: 946.2 kB

Release files / pai_agent_sdk-0.16.1.tar.gz

Download URL	pai_agent_sdk-0.16.1.tar.gz
Size	703.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`6ba9f39fc88ec2bf49df7c95c3155ed4e7b93af08e0bb2d7908489705ef6e983`
BLAKE2b-256 checksum How to use checksums	`adec536ad48b0346fdbe227f14ff32a691aeceb6d5e6eeb684786dee552a5fd6`
Upload date	Feb 5, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.6.2`

Release files / pai_agent_sdk-0.16.1-py3-none-any.whl

Download URL	pai_agent_sdk-0.16.1-py3-none-any.whl
Size	243.2 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`a1b3472ee9b0ba6520e2803837ca58c61efa825592cdaf7844141f454aeba1ca`
BLAKE2b-256 checksum How to use checksums	`b13a79e1a180b5b926ca2d80ea794676c44cec1634907aac4691cc633793c69c`
Upload date	Feb 5, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.6.2`