Metadata-Version: 2.4
Name: agent-os-base
Version: 0.1.3
Summary: 基础智能体构建库
Author-email: fubo <fb_linux@163.com>
License: MIT
Project-URL: Homepage, https://codeup.aliyun.com/64650c96168f0a5963451dec/agi-next/agent-base/blob/master/README.md
Project-URL: Repository, https://codeup.aliyun.com/64650c96168f0a5963451dec/agi-next/agent-base.git
Keywords: agent
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: google-adk[extensions]>=1.27.0
Requires-Dist: pydantic_yaml>=1.6.0
Requires-Dist: aiomysql
Requires-Dist: ag_ui_adk
Provides-Extra: test
Requires-Dist: pytest>=6.0; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Dynamic: license-file

# 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) 创建智能体

```bash
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>"
```

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

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

### 2) 创建 MCP 工具集配置

```bash
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 到可运行”脚手架闭环。
