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.