Metadata-Version: 2.4
Name: ya-agent-sdk
Version: 0.58.9
Summary: Application framework for building AI agents with Pydantic AI - environment abstractions, session management, and hierarchical agent patterns
Project-URL: Repository, https://github.com/wh1isper/ya-mono
Author-email: wh1isper <jizhongsheng957@gmail.com>
Keywords: python
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: <3.14,>=3.11
Requires-Dist: anyio>=4.12.0
Requires-Dist: cdp-use<2.0.0,>=1.4.4
Requires-Dist: httpx>=0.28.1
Requires-Dist: jinja2>=3.0.0
Requires-Dist: pathspec>=0.12.0
Requires-Dist: pillow>=10.0.0
Requires-Dist: pydantic-ai-slim>=1.79.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: pydantic>=2.12.5
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: tenacity>=9.0.0
Requires-Dist: typing-extensions>=4.15.0
Requires-Dist: y-agent-environment==0.9.0
Provides-Extra: all
Requires-Dist: boto3>=1.34; extra == 'all'
Requires-Dist: docker>=7.0.0; extra == 'all'
Requires-Dist: fastembed>=0.6; extra == 'all'
Requires-Dist: firecrawl-py>=4.0.0; extra == 'all'
Requires-Dist: markitdown[docx,pdf,pptx,xls,xlsx]>=0.1.5; extra == 'all'
Requires-Dist: numpy>=2.0; extra == 'all'
Requires-Dist: pydantic-ai; extra == 'all'
Requires-Dist: pymupdf-layout>=1.26.6; extra == 'all'
Requires-Dist: pymupdf4llm>=0.2.8; extra == 'all'
Requires-Dist: pymupdf>=1.26.6; extra == 'all'
Requires-Dist: python-dotenv; extra == 'all'
Requires-Dist: tavily-python>=0.7.0; extra == 'all'
Provides-Extra: docker
Requires-Dist: docker>=7.0.0; extra == 'docker'
Provides-Extra: document
Requires-Dist: markitdown[docx,pdf,pptx,xls,xlsx]>=0.1.5; extra == 'document'
Requires-Dist: pymupdf-layout>=1.26.6; extra == 'document'
Requires-Dist: pymupdf4llm>=0.2.8; extra == 'document'
Requires-Dist: pymupdf>=1.26.6; extra == 'document'
Provides-Extra: examples
Requires-Dist: pydantic-ai; extra == 'examples'
Requires-Dist: python-dotenv; extra == 'examples'
Provides-Extra: s3
Requires-Dist: boto3>=1.34; extra == 's3'
Provides-Extra: tool-search
Requires-Dist: fastembed>=0.6; extra == 'tool-search'
Requires-Dist: numpy>=2.0; extra == 'tool-search'
Provides-Extra: web
Requires-Dist: firecrawl-py>=4.0.0; extra == 'web'
Requires-Dist: markitdown[docx,pdf,pptx,xls,xlsx]>=0.1.5; extra == 'web'
Requires-Dist: tavily-python>=0.7.0; extra == 'web'
Description-Content-Type: text/markdown

# Ya Agent SDK

> Yet Another Agent SDK

[![Release](https://img.shields.io/github/v/release/wh1isper/ya-mono)](https://github.com/wh1isper/ya-mono/releases)
[![Build status](https://img.shields.io/github/actions/workflow/status/wh1isper/ya-mono/main.yml?branch=main)](https://github.com/wh1isper/ya-mono/actions/workflows/main.yml?query=branch%3Amain)
[![codecov](https://codecov.io/gh/wh1isper/ya-mono/branch/main/graph/badge.svg)](https://codecov.io/gh/wh1isper/ya-mono)
[![Commit activity](https://img.shields.io/github/commit-activity/m/wh1isper/ya-mono)](https://github.com/wh1isper/ya-mono/commits/main)
[![License](https://img.shields.io/github/license/wh1isper/ya-mono)](https://github.com/wh1isper/ya-mono/blob/main/LICENSE)

Yet Another Agent SDK for building AI agents with [Pydantic AI](https://ai.pydantic.dev/).

## 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

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

Selective extras:

```bash
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`](.env.example) to `packages/ya-agent-sdk/.env`.
For the runnable example scripts, copy [`examples/.env.example`](../../examples/.env.example) to `examples/.env`.

```python
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)
```

## 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 `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`](https://github.com/wh1isper/ya-mono) workspace.

- CLI package: [`packages/yaacli`](https://github.com/wh1isper/ya-mono/tree/main/packages/yaacli)
- Examples: [`examples/`](https://github.com/wh1isper/ya-mono/tree/main/examples)
- Skill source: [`skills/agent-builder/`](https://github.com/wh1isper/ya-mono/tree/main/skills/agent-builder)
- agent-builder skill: [`skills/agent-builder/SKILL.md`](https://github.com/wh1isper/ya-mono/tree/main/skills/agent-builder/SKILL.md)

## Examples

| Example | Description |
| --- | --- |
| [`general.py`](https://github.com/wh1isper/ya-mono/tree/main/examples/general.py) | Production pattern with streaming, HITL approval, and session persistence |
| [`deepresearch.py`](https://github.com/wh1isper/ya-mono/tree/main/examples/deepresearch.py) | Autonomous research agent with web search and content extraction |
| [`browser_use.py`](https://github.com/wh1isper/ya-mono/tree/main/examples/browser_use.py) | Browser automation with Docker-based headless Chrome sandbox |

## Reference Files

- [AgentContext & Sessions](https://github.com/wh1isper/ya-mono/tree/main/skills/agent-builder/context.md)
- [Streaming & Hooks](https://github.com/wh1isper/ya-mono/tree/main/skills/agent-builder/streaming.md)
- [Events](https://github.com/wh1isper/ya-mono/tree/main/skills/agent-builder/events.md)
- [Toolset Architecture](https://github.com/wh1isper/ya-mono/tree/main/skills/agent-builder/toolset.md)
- [Tool Search](https://github.com/wh1isper/ya-mono/tree/main/skills/agent-builder/tool-search.md)
- [Subagent System](https://github.com/wh1isper/ya-mono/tree/main/skills/agent-builder/subagent.md)
- [Skills System](https://github.com/wh1isper/ya-mono/tree/main/skills/agent-builder/skills.md)
- [Message Bus](https://github.com/wh1isper/ya-mono/tree/main/skills/agent-builder/message-bus.md)
- [Media Upload](https://github.com/wh1isper/ya-mono/tree/main/skills/agent-builder/media.md)
- [Custom Environments](https://github.com/wh1isper/ya-mono/tree/main/skills/agent-builder/environment.md)
- [Resumable Resources](https://github.com/wh1isper/ya-mono/tree/main/skills/agent-builder/resumable-resources.md)
- [Model Configuration](https://github.com/wh1isper/ya-mono/tree/main/skills/agent-builder/model.md)
- [Logging Configuration](https://github.com/wh1isper/ya-mono/tree/main/skills/agent-builder/logging.md)
- [Tool Proxy](https://github.com/wh1isper/ya-mono/tree/main/skills/agent-builder/tool-proxy.md)

## Development

```bash
git clone git@github.com:YOUR_NAME/ya-mono.git
cd ya-mono
uv sync --all-packages
```

Workspace commands live at the repository root. See the [contributing guide](https://github.com/wh1isper/ya-mono/tree/main/CONTRIBUTING.md).
