agent-builder

分类: 工具与效率 | 上传者: Wh1isper | 下载: 0 | 版本: v1.0（最新）

使用 ya-agent-sdk 和 Pydantic AI 构建 AI 代理。涵盖通过 create_agent() 创建代理、工具集配置、使用 ResumableState 的会话持久性、子代理层次结构和浏览器自动化。在创建代理应用程序、配置自定义工具、管理多轮会话、设置分层代理或实施 HITL 审批流程时使用。

更新日志: Source: GitHub https://github.com/Wh1isper/ya-agent-sdk

目录结构

当前层级: tree/main/

📁 .github/
- 📁 actions/
  - 📁 setup-python-env/
    
    📄 action.yml 1.1 KB
- 📁 workflows/
  - 📄 cli-tests.yml 778 B
  - 📄 main.yml 1.8 KB
  - 📄 on-release-main.yml 1.6 KB
  - 📄 validate-codecov-config.yml 352 B
📁 .vscode/
- 📄 settings.json 77 B
📁 docs/
- 📄 context.md 10.9 KB
- 📄 environment.md 7.8 KB
- 📄 events.md 12.7 KB
- 📄 logging.md 3.2 KB
- 📄 media.md 8.1 KB
- 📄 message-bus.md 9.0 KB
- 📄 model.md 5.7 KB
- 📄 README.md 2.2 KB
- 📄 resumable-resources.md 7.1 KB
- 📄 skills.md 12.8 KB
- 📄 streaming.md 12.3 KB
- 📄 subagent.md 12.4 KB
- 📄 tool-proxy.md 6.7 KB
- 📄 tool-search.md 11.3 KB
- 📄 toolset.md 7.1 KB
📁 examples/
- 📁 prompts/
  - 📄 browser_use.md 2.4 KB
  - 📄 deepresearch.md 9.3 KB
  - 📄 general.md 3.5 KB
- 📄 .env.example 3.1 KB
- 📄 __init__.py 262 B
- 📄 browser_use.py 9.1 KB
- 📄 deepresearch.py 11.9 KB
- 📄 general.py 13.0 KB
📁 scripts/
- 📄 sync-skills.sh 573 B
📁 tests/
- 📁 agents/
  - 📄 __init__.py 31 B
  - 📄 test_compact.py 18.6 KB
  - 📄 test_guards.py 3.9 KB
  - 📄 test_stream_cancel.py 7.2 KB
  - 📄 test_streamer.py 8.0 KB
- 📁 environment/
  - 📄 __init__.py 36 B
  - 📄 test_composite.py 24.7 KB
  - 📄 test_local.py 23.4 KB
  - 📄 test_sandbox.py 17.9 KB
  - 📄 test_virtual_file_operator.py 14.2 KB
- 📁 filters/
  - 📄 __init__.py 0 B
  - 📄 test_auto_load_files.py 6.7 KB
  - 📄 test_bus_message.py 14.6 KB
  - 📄 test_capability.py 7.2 KB
  - 📄 test_environment_instructions.py 5.7 KB
  - 📄 test_handoff.py 13.3 KB
  - 📄 test_image.py 26.0 KB
  - 📄 test_media_upload.py 9.5 KB
  - 📄 test_model_switch.py 4.0 KB
  - 📄 test_runtime_instructions.py 5.8 KB
  - 📄 test_system_prompt.py 5.3 KB
  - 📄 test_tool_args.py 6.9 KB
- 📁 sandbox/
  - 📁 browser/
    
    📄 __init__.py 0 B
    
    📄 test_browser_sandbox.py 3.1 KB
  - 📄 __init__.py 0 B
- 📁 subagents/
  - 📄 __init__.py 34 B
  - 📄 conftest.py 1015 B
  - 📄 test_config.py 6.2 KB
  - 📄 test_factory.py 23.3 KB
  - 📄 test_init.py 12.1 KB
  - 📄 test_unified.py 27.6 KB
- 📁 toolsets/
  - 📁 browser_use/
    
    📁 test_fixtures/
    
    📁 navigation/
    
    📄 page1.html 394 B
    
    📄 page2.html 336 B
    
    📄 basic.html 682 B
    
    📄 delayed_requests.html 2.6 KB
    
    📄 dialogs.html 881 B
    
    📄 dynamic.html 1.4 KB
    
    📄 forms.html 2.8 KB
    
    📄 interactive.html 1.1 KB
    
    📄 long_page.html 1.1 KB
    
    📄 conftest.py 1.9 KB
    
    📄 test_browser_use_config.py 6.6 KB
    
    📄 test_browser_use_dialog.py 3.1 KB
    
    📄 test_browser_use_form.py 15.4 KB
    
    📄 test_browser_use_interaction.py 8.3 KB
    
    📄 test_browser_use_navigation.py 9.8 KB
    
    📄 test_browser_use_query.py 4.4 KB
    
    📄 test_browser_use_state.py 7.5 KB
    
    📄 test_browser_use_tools.py 1.0 KB
    
    📄 test_browser_use_toolset.py 9.7 KB
    
    📄 test_browser_use_validation.py 8.1 KB
    
    📄 test_browser_use_wait.py 9.0 KB
  - 📁 core/
    
    📁 content/
    
    📄 __init__.py 30 B
    
    📄 test_url_helper.py 6.9 KB
    
    📁 context/
    
    📄 __init__.py 31 B
    
    📄 test_handoff.py 4.2 KB
    
    📁 document/
    
    📄 __init__.py 41 B
    
    📄 dummy.docx 19.1 KB
    
    📄 dummy.pdf 13.0 KB
    
    📄 dummy.pptx 61.2 KB
    
    📄 dummy.xlsx 9.1 KB
    
    📄 test_document.py 9.0 KB
    
    📁 enhance/
    
    📄 __init__.py 33 B
    
    📄 test_thinking.py 3.5 KB
    
    📄 test_todo.py 11.4 KB
    
    📁 filesystem/
    
    📄 __init__.py 36 B
    
    📄 test_edit.py 17.8 KB
    
    📄 test_file_change_events.py 14.7 KB
    
    📄 test_gitignore.py 7.4 KB
    
    📄 test_glob.py 15.5 KB
    
    📄 test_grep.py 20.4 KB
    
    📄 test_ls.py 6.4 KB
    
    📄 test_mkdir.py 5.9 KB
    
    📄 test_move_copy.py 10.8 KB
    
    📄 test_view.py 17.7 KB
    
    📄 test_write.py 4.5 KB
    
    📁 shell/
    
    📄 __init__.py 31 B
    
    📄 test_shell.py 6.1 KB
    
    📁 subagent/
    
    📄 __init__.py 34 B
    
    📄 test_factory.py 20.9 KB
    
    📄 test_tools.py 8.2 KB
    
    📁 web/
    
    📄 __init__.py 55 B
    
    📄 test_download.py 3.7 KB
    
    📄 test_fetch.py 6.5 KB
    
    📄 test_http_client.py 5.7 KB
    
    📄 test_scrape.py 3.8 KB
    
    📄 test_search.py 9.7 KB
    
    📄 __init__.py 31 B
    
    📄 test_base.py 19.7 KB
  - 📁 skills/
    
    📄 __init__.py 32 B
    
    📄 test_config.py 7.1 KB
    
    📄 test_toolset.py 10.3 KB
  - 📄 __init__.py 0 B
  - 📄 conftest.py 519 B
  - 📄 test_instruction.py 8.9 KB
  - 📄 test_skills.py 8.3 KB
  - 📄 test_tool_proxy.py 24.0 KB
  - 📄 test_tool_search.py 46.0 KB
- 📄 conftest.py 4.1 KB
- 📄 test_bus.py 17.9 KB
- 📄 test_config.py 1.7 KB
- 📄 test_context.py 58.9 KB
- 📄 test_events.py 14.3 KB
- 📄 test_hello.py 34 B
- 📄 test_image_compress.py 14.7 KB
- 📄 test_mcp.py 4.4 KB
- 📄 test_media.py 10.1 KB
- 📄 test_model_wrapper.py 8.6 KB
- 📄 test_note.py 4.5 KB
- 📄 test_presets.py 34.3 KB
- 📄 test_subagent_wrapper.py 3.0 KB
- 📄 test_task_manager.py 8.3 KB
- 📄 test_utils.py 5.9 KB
📁 ya_agent_sdk/
- 📁 agents/
  - 📁 models/
    
    📄 __init__.py 992 B
    
    📄 gateway.py 4.7 KB
    
    📄 utils.py 2.8 KB
  - 📁 prompts/
    
    📄 audio_understanding.md 1.9 KB
    
    📄 compact.md 5.6 KB
    
    📄 image_understanding.md 1.7 KB
    
    📄 main.md 252 B
    
    📄 video_understanding.md 2.3 KB
  - 📄 __init__.py 0 B
  - 📄 audio_understanding.py 10.0 KB
  - 📄 compact.py 25.6 KB
  - 📄 guards.py 1.8 KB
  - 📄 image_understanding.py 9.9 KB
  - 📄 main.py 54.0 KB
  - 📄 video_understanding.py 9.5 KB
- 📁 context/
  - 📄 __init__.py 1.7 KB
  - 📄 agent.py 69.2 KB
  - 📄 bus.py 13.8 KB
  - 📄 note.py 2.6 KB
  - 📄 tasks.py 9.5 KB
- 📁 environment/
  - 📄 __init__.py 1.1 KB
  - 📄 composite.py 21.5 KB
  - 📄 local.py 42.1 KB
  - 📄 sandbox.py 18.5 KB
- 📁 filters/
  - 📄 __init__.py 998 B
  - 📄 auto_load_files.py 3.1 KB
  - 📄 bus_message.py 4.3 KB
  - 📄 capability.py 7.2 KB
  - 📄 environment_instructions.py 4.2 KB
  - 📄 handoff.py 7.6 KB
  - 📄 image.py 17.9 KB
  - 📄 media_upload.py 5.6 KB
  - 📄 model_switch.py 1.8 KB
  - 📄 runtime_instructions.py 3.9 KB
  - 📄 system_prompt.py 3.5 KB
  - 📄 tool_args.py 2.1 KB
- 📁 sandbox/
  - 📁 browser/
    
    📄 __init__.py 162 B
    
    📄 base.py 1.6 KB
    
    📄 docker_.py 7.2 KB
  - 📄 __init__.py 0 B
- 📁 stream/
  - 📄 __init__.py 0 B
- 📁 subagents/
  - 📁 presets/
    
    📄 code-reviewer.md 3.0 KB
    
    📄 debugger.md 2.6 KB
    
    📄 executor.md 2.2 KB
    
    📄 explorer.md 2.5 KB
    
    📄 searcher.md 3.1 KB
  - 📄 __init__.py 10.1 KB
  - 📄 builder.py 6.1 KB
  - 📄 config.py 5.9 KB
  - 📄 factory.py 6.3 KB
- 📁 toolsets/
  - 📁 browser_use/
    
    📁 tools/
    
    📄 __init__.py 2.6 KB
    
    📄 _types.py 4.0 KB
    
    📄 dialog.py 5.3 KB
    
    📄 form.py 13.8 KB
    
    📄 interaction.py 14.3 KB
    
    📄 navigation.py 11.7 KB
    
    📄 query.py 9.0 KB
    
    📄 state.py 10.9 KB
    
    📄 validation.py 8.7 KB
    
    📄 wait.py 14.2 KB
    
    📄 __init__.py 134 B
    
    📄 _config.py 1.3 KB
    
    📄 _session.py 1020 B
    
    📄 _tools.py 3.5 KB
    
    📄 toolset.py 11.2 KB
  - 📁 core/
    
    📁 content/
    
    📁 prompts/
    
    📄 load_media_url.md 973 B
    
    📄 __init__.py 399 B
    
    📄 _url_helper.py 5.9 KB
    
    📄 load_media_url.py 7.8 KB
    
    📁 context/
    
    📁 prompts/
    
    📄 handoff.md 2.9 KB
    
    📄 __init__.py 342 B
    
    📄 handoff.py 4.9 KB
    
    📁 document/
    
    📁 prompts/
    
    📄 office.md 319 B
    
    📄 pdf.md 385 B
    
    📄 __init__.py 763 B
    
    📄 office.py 8.5 KB
    
    📄 pdf.py 9.6 KB
    
    📁 enhance/
    
    📁 prompts/
    
    📄 note.md 822 B
    
    📄 task_manager.md 1.6 KB
    
    📄 thinking.md 686 B
    
    📄 to_do_read.md 253 B
    
    📄 to_do_write.md 554 B
    
    📄 __init__.py 1.3 KB
    
    📄 note.py 2.2 KB
    
    📄 task.py 10.3 KB
    
    📄 thinking.py 1.3 KB
    
    📄 todo.py 4.9 KB
    
    📁 filesystem/
    
    📁 prompts/
    
    📄 copy.md 321 B
    
    📄 edit.md 440 B
    
    📄 glob.md 850 B
    
    📄 grep.md 492 B
    
    📄 ls.md 298 B
    
    📄 mkdir.md 338 B
    
    📄 move.md 284 B
    
    📄 multi_edit.md 456 B
    
    📄 view.md 407 B
    
    📄 write.md 386 B
    
    📄 __init__.py 1.6 KB
    
    📄 _gitignore.py 3.6 KB
    
    📄 _types.py 4.9 KB
    
    📄 _utils.py 599 B
    
    📄 edit.py 10.6 KB
    
    📄 glob.py 6.3 KB
    
    📄 grep.py 9.4 KB
    
    📄 ls.py 3.5 KB
    
    📄 mkdir.py 3.3 KB
    
    📄 move_copy.py 6.5 KB
    
    📄 view.py 23.4 KB
    
    📄 write.py 3.0 KB
    
    📁 multimodal/
    
    📄 __init__.py 581 B
    
    📄 audio.py 2.4 KB
    
    📄 image.py 2.4 KB
    
    📄 video.py 2.4 KB
    
    📁 shell/
    
    📁 prompts/
    
    📄 shell.md 693 B
    
    📄 __init__.py 257 B
    
    📄 shell.py 4.9 KB
    
    📁 subagent/
    
    📄 __init__.py 2.2 KB
    
    📄 factory.py 13.1 KB
    
    📄 tools.py 4.6 KB
    
    📄 unified.py 11.1 KB
    
    📁 web/
    
    📁 prompts/
    
    📄 download.md 409 B
    
    📄 fetch.md 460 B
    
    📄 scrape.md 407 B
    
    📄 search.md 239 B
    
    📄 search_image.md 538 B
    
    📄 search_stock_image.md 484 B
    
    📄 __init__.py 1.2 KB
    
    📄 _http_client.py 7.2 KB
    
    📄 download.py 4.8 KB
    
    📄 fetch.py 8.1 KB
    
    📄 scrape.py 3.6 KB
    
    📄 search.py 11.5 KB
    
    📄 __init__.py 384 B
    
    📄 base.py 27.8 KB
  - 📁 skills/
    
    📄 __init__.py 1.2 KB
    
    📄 config.py 5.9 KB
    
    📄 toolset.py 14.4 KB
  - 📁 tool_proxy/
    
    📁 prompts/
    
    📄 tool_proxy.md 855 B
    
    📄 __init__.py 859 B
    
    📄 toolset.py 27.9 KB
  - 📁 tool_search/
    
    📁 prompts/
    
    📄 tool_search.md 241 B
    
    📁 strategies/
    
    📄 __init__.py 1.9 KB
    
    📄 embedding.py 6.8 KB
    
    📄 keyword.py 3.6 KB
    
    📄 __init__.py 2.7 KB
    
    📄 metadata.py 4.1 KB
    
    📄 toolset.py 23.5 KB
  - 📄 __init__.py 1.2 KB
  - 📄 base.py 8.7 KB
- 📄 __init__.py 782 B
- 📄 _config.py 1.7 KB
- 📄 _logger.py 5.8 KB
- 📄 events.py 16.1 KB
- 📄 mcp.py 3.9 KB
- 📄 media.py 9.7 KB
- 📄 presets.py 60.1 KB
- 📄 usage.py 1.8 KB
- 📄 utils.py 11.2 KB
📁 yaacli/
- 📁 spec/
  - 📄 00-overview.md 4.5 KB
  - 📄 01-event-system.md 6.0 KB
  - 📄 02-configuration.md 15.9 KB
  - 📄 03-tui-environment.md 17.9 KB
  - 📄 04-steering.md 16.8 KB
  - 📄 05-browser-integration.md 12.0 KB
  - 📄 06-ui-layout.md 19.7 KB
  - 📄 07-logging.md 4.4 KB
  - 📄 08-hitl.md 9.3 KB
- 📁 tests/
  - 📄 conftest.py 1.7 KB
  - 📄 test_app_integration.py 21.3 KB
  - 📄 test_background.py 21.3 KB
  - 📄 test_browser.py 4.3 KB
  - 📄 test_commands.py 6.9 KB
  - 📄 test_config.py 15.9 KB
  - 📄 test_display.py 26.0 KB
  - 📄 test_environment.py 4.1 KB
  - 📄 test_events_hooks.py 3.0 KB
  - 📄 test_guards.py 7.1 KB
  - 📄 test_hitl.py 8.6 KB
  - 📄 test_logging.py 6.8 KB
  - 📄 test_mcp.py 5.0 KB
  - 📄 test_processes.py 14.4 KB
  - 📄 test_runtime.py 6.2 KB
  - 📄 test_session.py 9.5 KB
  - 📄 test_state.py 9.6 KB
  - 📄 test_streaming.py 11.5 KB
  - 📄 test_toolsets.py 10.6 KB
  - 📄 test_usage.py 6.2 KB
  - 📄 test_worktree.py 8.5 KB
- 📁 yaacli/
  - 📁 app/
    
    📄 __init__.py 900 B
    
    📄 commands.py 3.9 KB
    
    📄 state.py 5.9 KB
    
    📄 tui.py 116.7 KB
  - 📁 hitl/
    
    📄 __init__.py 977 B
    
    📄 approval.py 6.0 KB
    
    📄 ui.py 6.0 KB
  - 📁 rendering/
    
    📁 tool_panels/
    
    📄 __init__.py 669 B
    
    📄 base.py 5.2 KB
    
    📄 edit_panel.py 7.2 KB
    
    📄 task_panel.py 3.6 KB
    
    📄 thinking_panel.py 1.3 KB
    
    📄 todo_panel.py 4.2 KB
    
    📄 __init__.py 1.2 KB
    
    📄 event_renderer.py 17.3 KB
    
    📄 renderer.py 3.4 KB
    
    📄 tool_message.py 4.2 KB
    
    📄 tracker.py 2.3 KB
    
    📄 types.py 1.4 KB
  - 📁 skills/
    
    📁 cli-config/
    
    📁 references/
    
    📄 presets.md 2.3 KB
    
    📄 SKILL.md 4.2 KB
    
    📁 skill-creator/
    
    📁 references/
    
    📄 output-patterns.md 1.8 KB
    
    📄 workflows.md 819 B
    
    📁 scripts/
    
    📄 init_skill.py 10.6 KB
    
    📄 package_skill.py 3.2 KB
    
    📄 quick_validate.py 3.4 KB
    
    📄 LICENSE.txt 11.1 KB
    
    📄 SKILL.md 17.4 KB
    
    📄 __init__.py 2.6 KB
  - 📁 streaming/
    
    📄 __init__.py 1.5 KB
    
    📄 event_handler.py 4.3 KB
    
    📄 subagent_tracker.py 5.1 KB
    
    📄 text_streamer.py 5.4 KB
  - 📁 templates/
    
    📄 config.toml 3.4 KB
    
    📄 env.example 2.1 KB
    
    📄 mcp.json 20 B
    
    📄 system_prompt.md 4.3 KB
    
    📄 tools.toml 189 B
  - 📁 toolsets/
    
    📄 __init__.py 361 B
    
    📄 background.py 10.5 KB
    
    📄 process.py 8.8 KB
  - 📄 __init__.py 1021 B
  - 📄 background.py 7.6 KB
  - 📄 browser.py 5.2 KB
  - 📄 cli.py 23.9 KB
  - 📄 config.py 22.4 KB
  - 📄 display.py 1.1 KB
  - 📄 environment.py 3.1 KB
  - 📄 events.py 2.1 KB
  - 📄 guards.py 4.5 KB
  - 📄 hooks.py 1.8 KB
  - 📄 logging.py 9.5 KB
  - 📄 mcp.py 6.4 KB
  - 📄 perf.py 2.8 KB
  - 📄 processes.py 14.1 KB
  - 📄 runtime.py 15.2 KB
  - 📄 session.py 1.5 KB
  - 📄 usage.py 4.9 KB
- 📄 LICENSE 1.5 KB
- 📄 pyproject.toml 1.3 KB
- 📄 README.md 642 B
📄 .env.example 2.8 KB
📄 .gitattributes 73 B
📄 .gitignore 2.1 KB
📄 .pre-commit-config.yaml 931 B
📄 .python-version 5 B
📄 AGENTS.md 12.0 KB
📄 CLAUDE.md 9 B
📄 codecov.yaml 235 B
📄 CONTRIBUTING.md 3.2 KB
📄 FUNDING.yml 19 B
📄 LICENSE 1.5 KB
📄 Makefile 2.5 KB
📄 pyproject.toml 4.8 KB
📄 pytest.ini 64 B
📄 README.md 6.9 KB
📄 SKILL.md 9.6 KB
📄 uv.lock 545.5 KB

SKILL.md

---
name: agent-builder
description: Build AI agents using ya-agent-sdk with Pydantic AI. Covers agent creation via create_agent(), toolset configuration, session persistence with ResumableState, subagent hierarchies, and browser automation. Use when creating agent applications, configuring custom tools, managing multi-turn sessions, setting up hierarchical agents, or implementing HITL approval flows.
---

# Building Agents with ya-agent-sdk

Build production-ready AI agents with Pydantic AI.

## Quick Start

```python
from ya_agent_sdk.agents import create_agent

async with create_agent("openai:gpt-4o") as runtime:
    result = await runtime.agent.run("Hello", deps=runtime.ctx)
    print(result.output)
```

With tools and streaming:

```python
from ya_agent_sdk.agents import create_agent, stream_agent
from ya_agent_sdk.toolsets.core.filesystem import tools as fs_tools
from ya_agent_sdk.toolsets.core.shell import tools as shell_tools

async with create_agent(
    model="anthropic:claude-sonnet-4",
    system_prompt="You are a coding assistant.",
    tools=[*fs_tools, *shell_tools],
) as runtime:
    async with stream_agent(runtime.agent, "List files", runtime.ctx) as stream:
        async for event in stream:
            # Handle streaming events
            pass
```

## Installation

```bash
pip install ya-agent-sdk[all]
# Or selective: pip install ya-agent-sdk[docker,web,document]
```

## Core Concepts

| Concept           | Purpose                                        | Reference                                                  |
| ----------------- | ---------------------------------------------- | ---------------------------------------------------------- |
| AgentContext      | Session state, model config, tool config       | [docs/context.md](docs/context.md)                         |
| Streaming & Hooks | Real-time events, lifecycle hooks              | [docs/streaming.md](docs/streaming.md)                     |
| Events            | Lifecycle and sideband event types             | [docs/events.md](docs/events.md)                           |
| Toolset           | Tool management with hooks and HITL            | [docs/toolset.md](docs/toolset.md)                         |
| Subagent          | Hierarchical agent delegation                  | [docs/subagent.md](docs/subagent.md)                       |
| Environment       | File/shell operations, resource lifecycle      | [docs/environment.md](docs/environment.md)                 |
| Resources         | Resumable resource state export/restore        | [docs/resumable-resources.md](docs/resumable-resources.md) |
| Model             | Provider configuration, gateway mode           | [docs/model.md](docs/model.md)                             |
| Skills            | Markdown-based instruction files               | [docs/skills.md](docs/skills.md)                           |
| Message Bus       | Inter-agent communication, user steering       | [docs/message-bus.md](docs/message-bus.md)                 |
| Logging           | Configurable logging with module-level control | [docs/logging.md](docs/logging.md)                         |

## Task Guide

### Creating Custom Tools

Inherit from `BaseTool`:

```python
from ya_agent_sdk.toolsets.core.base import BaseTool
from pydantic_ai import RunContext
from ya_agent_sdk.context import AgentContext

class MyTool(BaseTool):
    name = "my_tool"
    description = "Does something useful"

    async def call(self, ctx: RunContext[AgentContext], arg: str) -> str:
        return f"Result: {arg}"
```

Full guide: [docs/toolset.md](docs/toolset.md)

### Session Persistence

Export and restore state across restarts:

```python
# Export
state = ctx.export_state()
with open("session.json", "w") as f:
    f.write(state.model_dump_json())

# Restore
from ya_agent_sdk.context import ResumableState
state = ResumableState.model_validate_json(open("session.json").read())

async with create_agent("openai:gpt-4o", state=state) as runtime:
    # Session restored with history and context
    ...
```

Full guide: [docs/context.md](docs/context.md)

### Human-in-the-Loop (HITL)

Require approval for dangerous tools:

```python
async with create_agent(
    model="anthropic:claude-sonnet-4",
    tools=[*fs_tools, *shell_tools],
    need_user_approve_tools=["shell", "edit"],  # These require approval
) as runtime:
    ...
```

Full guide: [docs/toolset.md](docs/toolset.md)

### Subagents

Delegate specialized tasks to child agents:

```python
from ya_agent_sdk.subagents import SubagentConfig

config = SubagentConfig(
    name="researcher",
    description="Research specialist for web searches",
    system_prompt="You are a research specialist...",
    tools=["search_with_tavily", "visit_webpage"],
)

async with create_agent(
    "anthropic:claude-sonnet-4",
    tools=[SearchTool, VisitTool, ViewTool],
    subagent_configs=[config],
    include_builtin_subagents=True,  # debugger, explorer, code-reviewer, searcher
) as runtime:
    ...
```

Full guide: [docs/subagent.md](docs/subagent.md)

### Browser Automation

Use DockerBrowserSandbox for headless Chrome:

```python
from ya_agent_sdk.sandbox.browser.docker_ import DockerBrowserSandbox
from ya_agent_sdk.toolsets.browser_use import BrowserUseToolset

# See examples/browser_use.py for complete implementation
```

Full example: [examples/browser_use.py](examples/browser_use.py)

### Streaming Events

Handle real-time events with lifecycle hooks:

```python
from ya_agent_sdk.agents import stream_agent
from ya_agent_sdk.stream import AgentStartContext, AgentCompleteContext

async def on_start(ctx: AgentStartContext):
    print(f"Agent started with prompt: {ctx.user_prompt}")

async def on_complete(ctx: AgentCompleteContext):
    print(f"Agent completed in {ctx.duration_ms}ms")

async with stream_agent(
    runtime.agent, "Hello", runtime.ctx,
    on_agent_start=on_start,
    on_agent_complete=on_complete,
) as stream:
    async for event in stream:
        pass
```

Full guide: [docs/streaming.md](docs/streaming.md)

### Message Bus

Inter-agent communication and user steering:

```python
# Send message from external code
await ctx.bus.send("user", "Please focus on security issues")

# Agent can read messages via bus tools
```

Full guide: [docs/message-bus.md](docs/message-bus.md)

## Complete Examples

| Example                                              | Description                                              |
| ---------------------------------------------------- | -------------------------------------------------------- |
| [examples/general.py](examples/general.py)           | Production pattern: streaming, HITL, session persistence |
| [examples/deepresearch.py](examples/deepresearch.py) | Autonomous research agent with web tools                 |
| [examples/browser_use.py](examples/browser_use.py)   | Browser automation with Docker sandbox                   |

## Configuration Reference

### Model Strings

```python
# Native pydantic-ai format
"openai:gpt-4o"
"anthropic:claude-sonnet-4"
"gemini:gemini-1.5-pro"

# Gateway mode (via proxy)
"mygateway@openai:gpt-4o"
# Requires: MYGATEWAY_API_KEY, MYGATEWAY_BASE_URL
```

### Environment Variables

Check examples/.env.example for all available environment variables

| Variable                                     | Purpose              |
| -------------------------------------------- | -------------------- |
| `TAVILY_API_KEY`                             | Web search           |
| `FIRECRAWL_API_KEY`                          | Web scraping         |
| `GOOGLE_SEARCH_API_KEY` + `GOOGLE_SEARCH_CX` | Google Custom Search |

### ModelConfig

```python
from ya_agent_sdk.context import ModelConfig, ModelCapability

ModelConfig(
    context_window=200_000,
    capabilities={ModelCapability.vision},
)
```

### ToolConfig

```python
from ya_agent_sdk.context import ToolConfig

ToolConfig(
    tavily_api_key="...",
    firecrawl_api_key="...",
    google_search_api_key="...",
    google_search_cx="...",
)
```

## Builtin Tools

Import from `ya_agent_sdk.toolsets.core.*`:

| Module       | Tools                                                                 |
| ------------ | --------------------------------------------------------------------- |
| `filesystem` | view, edit, multi_edit, write, ls, glob, grep                         |
| `shell`      | shell (command execution)                                             |
| `web`        | search_with_tavily, search_with_google, visit_webpage, save_web_files |
| `document`   | pdf_convert, office_to_markdown                                       |
| `content`    | validate_json                                                         |
| `context`    | thinking, summarize, to_do_read, to_do_write                          |
| `enhance`    | screenshot                                                            |
| `multimodal` | view (images, video, audio)                                           |

## Builtin Subagents

Available via `include_builtin_subagents=True`:

| Name          | Purpose               | Required Tools       |
| ------------- | --------------------- | -------------------- |
| debugger      | Root cause analysis   | glob, grep, view, ls |
| explorer      | Codebase navigation   | glob, grep, view, ls |
| code-reviewer | Code quality analysis | glob, grep, view, ls |
| searcher      | Web research          | search               |

## Troubleshooting

**Missing API key errors**: Set required environment variables or pass via `ToolConfig`.

**Tool not available**: Check `tool.is_available()` or set `skip_unavailable=True` in Toolset.

**Session restore fails**: Ensure message history and ResumableState are both saved/restored.

**Docker sandbox issues**: Ensure Docker daemon is running and user has Docker permissions.

登录后下载/点赞/收藏 ❤ 7 | ★ 0

agent-builder

目录结构

SKILL.md

举报内容

提示