ya-agent-sdk 0.72.2

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.

Key Features

• Environment-based architecture for file operations, shell access, and resources
• Fully typed SDK validated with pyright
• Resumable sessions with state export and restore
• Hierarchical agents with subagent delegation
• Tool search for large tool libraries
• Skills system with hot reload and progressive loading
• Human-in-the-loop approval workflows
• Event system and streaming support
• Message bus for agent coordination and user steering
• Browser automation with Docker sandbox support

Installation

pip install ya-agent-sdk[all]
uv add ya-agent-sdk[all]

Selective extras:

pip install ya-agent-sdk[docker]
pip install ya-agent-sdk[web]
pip install ya-agent-sdk[document]
pip install ya-agent-sdk[s3]
pip install ya-agent-sdk[tool-search]

Quick Start

For workspace development, copy packages/ya-agent-sdk/.env.example to packages/ya-agent-sdk/.env. For the runnable example scripts, copy examples/.env.example to examples/.env.

from ya_agent_sdk.agents import create_agent, stream_agent

runtime = create_agent("openai:gpt-4o")

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

Shell Command Review

Configure shell command review on AgentContext.security.shell_review to run a small reviewer model before shell execution:

from ya_agent_sdk.agents import create_agent, stream_agent
from ya_agent_sdk.context import SecurityConfig, ShellReviewConfig

runtime = create_agent(
    "gateway@openai-responses:gpt-5.5",
    extra_context_kwargs={
        "security": SecurityConfig(
            shell_review=ShellReviewConfig(
                enabled=True,
                model="gateway@openai-responses:gpt-5.4-mini",
                model_settings="openai_responses_low",
                on_needs_approval="defer",
                risk_threshold="high",
            )
        )
    },
)

async with stream_agent(runtime, "Run the test suite") as streamer:
    async for event in streamer:
        print(event)

model is required when shell review is enabled. model_settings accepts SDK preset names or an inline settings dictionary. on_needs_approval supports defer for HITL-capable runtimes and deny for autopilot runtimes. risk_threshold defaults to high and controls when the configured action triggers.

Model Preset Tips

For Anthropic models, anthropic now resolves to adaptive thinking by default.

• Use anthropic for the default adaptive preset.
• Use anthropic_adaptive_xhigh for Claude Opus 4.7 long-horizon coding and agentic workloads.
• Use openai_responses_xhigh for GPT-5.5 hard asynchronous agentic tasks and evals.
• Use anthropic_off when you want thinking disabled.
• Use anthropic_400k or claude_400k for a 400K context window between claude_200k and claude_1m.

Repository Context

This package lives in the ya-mono workspace.

• CLI package: packages/yaacli
• Examples: examples/
• Skill source: skills/agent-builder/
• agent-builder skill: skills/agent-builder/SKILL.md

Examples

Example	Description
general.py	Production 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

Reference Files

• AgentContext & Sessions
• Streaming & Hooks
• Events
• Toolset Architecture
• Tool Search
• Subagent System
• Skills System
• Message Bus
• Media Upload
• Custom Environments
• Resumable Resources
• Model Configuration
• Logging Configuration
• Tool Proxy

Development

git clone [e-mail]:YOUR_NAME/ya-mono.git
cd ya-mono
uv sync --all-packages

Workspace commands live at the repository root. See the contributing guide.