agent-os-base

agent-base

agent-base 是一个用于快速搭建智能体项目脚手架的 Python 库，核心目标是：

• 通过 CLI 一键创建智能体工程目录
• 自动生成 .env、agent.py、技能目录、本地函数目录、MCP 工具集目录
• 基于 google-adk 统一加载模型、Skills、本地函数工具、远端 MCP 工具

---

项目结构

核心代码位于 src/agent_base：

• main.py：CLI 入口，解析命令并分发到 Operator
• operator.py：脚手架生成与文件落地逻辑
• agent_config.py：配置数据模型（Pydantic）
• adk_agent.py：智能体运行时封装，负责动态加载工具与技能
• observability/tracing.py：OpenTelemetry Trace 初始化
• templates/*.template：新建智能体时使用的代码和环境变量模板

---

依赖与版本

pyproject.toml 中定义：

• Python: >=3.10
• 核心依赖：
  • google-adk[extensions]>=1.27.0
  • pydantic_yaml>=1.6.0
• 命令行入口：
  • agent-base = agent_base.main:main

---

CLI 功能说明

1) 创建智能体

agent-base -an <agent_name> create-agent \
  -ad "<description>" \
  -ai "<instruction>" \
  -mdu "<model_base_url>" \
  -mdn "<model_name>" \
  -mdk "<model_api_key>" \
  -mdt 0.0 \
  -teh "<trace_endpoint_host>"

执行后会在当前目录下生成：

./<agent_name>/
  ├── .env
  ├── __init__.py
  ├── agent.py
  ├── skills/
  ├── local-functions/
  │   └── function_toolset.py
  └── mcp-toolsets/

2) 创建 MCP 工具集配置

agent-base -an <agent_name> create-mcp-toolset \
  -mpn "<mcp_name>" \
  -mpu "<mcp_url>" \
  -mpst "SSE|StreamableHTTP" \
  -mpat "<optional_token>"

会在 ./<agent_name>/mcp-toolsets/ 下生成对应 JSON 配置文件。

3) 预留命令（尚未实现）

• create-skill
• create-local-function-tool

当前在 operator.py 中仍是占位实现（pass 或空函数体）。

---

运行时加载机制（ADKAgent）

ADKAgent 初始化时会把三类能力合并到 tools：

1. 本地函数工具
   扫描 ./<agent_name>/local-functions/*.py，通过动态 import 抽取顶层函数并注册。

2. Skills
   扫描 ./<agent_name>/skills/*，使用 google.adk.skills.load_skill_from_dir 加载后封装为 SkillToolset。

3. 远端 MCP 工具
   扫描 ./<agent_name>/mcp-toolsets/*.json，按 server_type 构建：

   • SSE -> SseServerParams
   • StreamableHTTP -> StreamableHTTPServerParams

---

Trace 能力

当提供 TRACE_ENDPOINT_HOST 时，会调用 setup_tracing(endpoint_host, experiment_id)：

• 使用 OTLP HTTP exporter 上报到 ${endpoint_host}/v1/traces
• 额外写入 header：x-mlflow-experiment-id

experiment_id 在示例中由当前时间戳（毫秒）生成。

---

示例代码分析（tests/test_agent）

你本地示例目录中的 tests/test_agent/agent.py 展示了最小可运行初始化流程：

1. 读取 .env（dotenv）
2. 初始化 tracing（可选）
3. 组装 AgentConfig + ModelProvider
4. 构造 root_agent = ADKAgent(...)

示例技能中包含：

• skills/calculator：通过 scripts/calculate.py 提供加减乘除脚本工具
• skills/comment-news：给出“先搜新闻，再客观评价”的技能流程
• skills/tavily-search：封装 Tavily CLI 的检索能力（含安装与命令范式）

---

当前实现特点与注意事项

已具备

• 模板化创建智能体工程
• 统一配置模型参数与工具加载
• 可加载本地函数 + Skills + MCP toolsets

需要注意

• operator.py 使用 os.system 进行目录与文件创建，后续可考虑改为 pathlib/shutil 提高可维护性与安全性。
• create-skill、create-local-function-tool 还未完成。
• 示例 .env 中出现了真实样式的 API Key，建议立即替换并避免提交到版本库（应使用环境注入或密钥管理）。

---

快速开始（建议流程）

1. 安装依赖并安装本包（开发模式）
2. 通过 agent-base ... create-agent 生成智能体目录
3. 在 skills/ 与 local-functions/ 中补充能力
4. 根据需要添加 mcp-toolsets/*.json
5. 在生成的 agent.py 中实例化并运行智能体

如需扩展，建议优先补齐 create-skill 与 create-local-function-tool 的自动化生成能力，这样项目可以形成完整的“从 0 到可运行”脚手架闭环。