ya-agent-sdk 0.74.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.

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

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]
pip install ya-agent-sdk[oauth]

OAuth-backed Codex

Use your ChatGPT/Codex subscription through ya-oauth:

uv run --package ya-oauth ya-oauth login codex

Then select the OAuth model string:

from ya_agent_sdk.agents import create_agent

runtime = create_agent("oauth@codex:gpt-5.5")

The SDK passes stable session and thread headers into the OAuth provider. YA Claw sets the provider session header from the session ID and the provider thread header from the run ID.

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

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.