ya-agent-sdk 0.41.1

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

Ya Agent SDK

Yet Another Agent SDK

Yet Another Agent SDK for building AI agents with Pydantic AI. Used at my homelab for research and prototyping.

Key Features

• Environment-based Architecture: Protocol-based design for file operations, shell access, and resources. Built-in LocalEnvironment and SandboxEnvironment, 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
• Tool Search: Dynamic tool discovery for large tool libraries -- agents find and load only the tools they need, reducing context bloat by 85%+ while maintaining accuracy across hundreds of tools
• 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
• Event System: Lifecycle and sideband events for execution tracking, with streaming support for real-time monitoring
• Media Upload: Pluggable media upload (S3, custom backends) with automatic binary-to-URL conversion for images and videos
• Message Bus: Inter-agent communication with subscriber-based delivery, supporting multimodal content and user steering
• 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 ya-agent-sdk[all]
uv add ya-agent-sdk[all]

# Or install individual extras as needed
pip install ya-agent-sdk[docker]       # Docker sandbox support
pip install ya-agent-sdk[web]          # Web tools (tavily, firecrawl, markitdown)
pip install ya-agent-sdk[document]     # Document processing (pymupdf, markitdown)
pip install ya-agent-sdk[s3]           # S3 media upload (boto3)
pip install ya-agent-sdk[tool-search]  # Semantic tool search (fastembed)

Project Structure

This repository contains:

• ya_agent_sdk/ - Core SDK with environment abstraction, toolsets, and session management
• yaacli/ - 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 ya_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 YAACLI CLI

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

# Run directly with uvx (no installation needed)
uvx yaacli

# Or install globally
uv tool install yaacli
pip install yaacli

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
• Events - Lifecycle events, sideband events, event correlation, custom events
• Toolset Architecture - Create tools, use hooks, handle errors, extend Toolset
• Tool Search - Dynamic tool discovery with keyword and embedding search strategies
• Subagent System - Hierarchical agents, builtin presets, markdown configuration
• Skills System - Markdown-based skills, hot reload, pre-scan hooks
• Message Bus - Inter-agent communication, multimodal messages, user steering
• Media Upload - S3 media upload, custom backends, history filter integration
• 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.