voyoagent 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- voyoagent-0.1.0/.gitignore +25 -0
- voyoagent-0.1.0/PKG-INFO +235 -0
- voyoagent-0.1.0/README.md +215 -0
- voyoagent-0.1.0/pyproject.toml +57 -0
- voyoagent-0.1.0/voyoagent/__init__.py +72 -0
- voyoagent-0.1.0/voyoagent/agent.py +89 -0
- voyoagent-0.1.0/voyoagent/agent_base.py +94 -0
- voyoagent-0.1.0/voyoagent/agent_chat.py +88 -0
- voyoagent-0.1.0/voyoagent/agent_context.py +16 -0
- voyoagent-0.1.0/voyoagent/agent_hook.py +27 -0
- voyoagent-0.1.0/voyoagent/agent_mcp.py +301 -0
- voyoagent-0.1.0/voyoagent/agent_skill.py +181 -0
- voyoagent-0.1.0/voyoagent/constants.py +10 -0
- voyoagent-0.1.0/voyoagent/env.py +23 -0
- voyoagent-0.1.0/voyoagent/functional/logger_event_handler.py +10 -0
- voyoagent-0.1.0/voyoagent/llm.py +44 -0
- voyoagent-0.1.0/voyoagent/log.py +5 -0
- voyoagent-0.1.0/voyoagent/prompt.py +46 -0
- voyoagent-0.1.0/voyoagent/prompts/soul.md +0 -0
- voyoagent-0.1.0/voyoagent/prompts/system.md +21 -0
- voyoagent-0.1.0/voyoagent/tools/__init__.py +13 -0
- voyoagent-0.1.0/voyoagent/tools/file_tool.py +129 -0
- voyoagent-0.1.0/voyoagent/tools/load_skill.py +59 -0
- voyoagent-0.1.0/voyoagent/tools/shell_tool.py +40 -0
- voyoagent-0.1.0/voyoagent/tools/tool.py +91 -0
- voyoagent-0.1.0/voyoagent/tools/tool_types.py +43 -0
- voyoagent-0.1.0/voyoagent/tools/weather_tool.py +19 -0
- voyoagent-0.1.0/voyoagent/utils/common_utils.py +98 -0
- voyoagent-0.1.0/voyoagent/utils/exception.py +11 -0
- voyoagent-0.1.0/voyoagent/utils/llm_utils.py +24 -0
- voyoagent-0.1.0/voyoagent/utils/subject.py +42 -0
- voyoagent-0.1.0/voyoagent/yo_agent.py +51 -0
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
# 凭证与本地配置
|
|
2
|
+
.env
|
|
3
|
+
.mcp.json
|
|
4
|
+
.claude/settings*.json
|
|
5
|
+
|
|
6
|
+
# Python
|
|
7
|
+
__pycache__/
|
|
8
|
+
*.py[cod]
|
|
9
|
+
.venv/
|
|
10
|
+
.pytest_cache/
|
|
11
|
+
*.egg-info/
|
|
12
|
+
dist/
|
|
13
|
+
build/
|
|
14
|
+
|
|
15
|
+
# 运行产物
|
|
16
|
+
logs/
|
|
17
|
+
runtime/
|
|
18
|
+
|
|
19
|
+
# 前端
|
|
20
|
+
frontend/node_modules/
|
|
21
|
+
frontend/dist/
|
|
22
|
+
|
|
23
|
+
# OS
|
|
24
|
+
.DS_Store
|
|
25
|
+
Thumbs.db
|
voyoagent-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,235 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: voyoagent
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: 基于 OpenAI Responses API 的极简异步 Agent 框架:流式事件、工具注册、Skill 加载、MCP 接入、提示词 fragment 与生命周期钩子
|
|
5
|
+
Author: zhantewei
|
|
6
|
+
Keywords: agent,asyncio,llm,mcp,openai,skill
|
|
7
|
+
Classifier: Development Status :: 4 - Beta
|
|
8
|
+
Classifier: Intended Audience :: Developers
|
|
9
|
+
Classifier: Operating System :: OS Independent
|
|
10
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
11
|
+
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
|
|
12
|
+
Requires-Python: >=3.13
|
|
13
|
+
Requires-Dist: aiofiles>=25.1.0
|
|
14
|
+
Requires-Dist: mcp>=2.3.0
|
|
15
|
+
Requires-Dist: pydantic-settings>=2.16.1
|
|
16
|
+
Requires-Dist: pydantic>=2.0
|
|
17
|
+
Requires-Dist: python-dotenv>=1.0.0
|
|
18
|
+
Requires-Dist: voyolib>=0.4.0
|
|
19
|
+
Description-Content-Type: text/markdown
|
|
20
|
+
|
|
21
|
+
# voyoagent
|
|
22
|
+
|
|
23
|
+
基于 OpenAI Responses API 的极简异步 Agent 框架:流式事件输出、工具注册、Skill 渐进加载、MCP 接入、提示词 fragment 与生命周期钩子。核心是基类 `Voyo_Agent`,`await agent.run("...")` 即完成一次多轮工具调用对话,全过程经 `agent_event` 以 dataclass 事件推送;`Yo_Agent` 是预置内置工具的高阶封装。
|
|
24
|
+
|
|
25
|
+
## 特性
|
|
26
|
+
|
|
27
|
+
- **流式事件**:思考流 / 正文流 / 工具调用 / 工具结果 / 错误,全部以 dataclass 事件从单一订阅点推送
|
|
28
|
+
- **工具**:`(schema, handler)` 二元组注册,async handler,参数由模型 JSON 给出、返回字符串回传
|
|
29
|
+
- **Skill**:扫描目录登记技能(SKILL.md frontmatter),模型经 `load_skill` 工具按需读取全文
|
|
30
|
+
- **MCP**:stdio 子进程与 streamable http 两种接入,后台连接,`loading → ready/error` 状态机
|
|
31
|
+
- **提示词**:system + 动态 fragment(按 id 增删改)+ soul 三段拼接
|
|
32
|
+
- **钩子**:`on_agent_init` / `on_user_input` / `on_dialog_end`,回调支持同步与 async
|
|
33
|
+
|
|
34
|
+
## 安装
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
uv add voyoagent
|
|
38
|
+
# 或
|
|
39
|
+
pip install voyoagent
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
依赖 `voyolib`(提供 `voyo.model.OpenAiResponsesClient` 与工具函数)。
|
|
43
|
+
|
|
44
|
+
## 快速开始(Voyo_Agent)
|
|
45
|
+
|
|
46
|
+
```python
|
|
47
|
+
import asyncio
|
|
48
|
+
from datetime import datetime
|
|
49
|
+
|
|
50
|
+
from voyoagent import Voyo_Agent
|
|
51
|
+
from voyoagent.agent_base import ThinkingDeltaEvent, TextDeltaEvent, DoneEvent
|
|
52
|
+
from voyoagent.tools.tool_types import ToolDef
|
|
53
|
+
|
|
54
|
+
GET_TIME_TOOL: ToolDef = {
|
|
55
|
+
"type": "function",
|
|
56
|
+
"name": "get_time",
|
|
57
|
+
"description": "获取当前时间",
|
|
58
|
+
"parameters": {"type": "object", "properties": {}},
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
async def get_time() -> str:
|
|
62
|
+
return datetime.now().isoformat()
|
|
63
|
+
|
|
64
|
+
agent = Voyo_Agent(
|
|
65
|
+
model="gpt-5.2",
|
|
66
|
+
base_url="https://api.example.com/v1",
|
|
67
|
+
api_key="sk-...",
|
|
68
|
+
effort="high", # 思考力度: none/low/medium/high
|
|
69
|
+
)
|
|
70
|
+
agent.registry_tool((GET_TIME_TOOL, get_time))
|
|
71
|
+
|
|
72
|
+
def on_event(event):
|
|
73
|
+
if isinstance(event, ThinkingDeltaEvent):
|
|
74
|
+
print(event.content, end="")
|
|
75
|
+
elif isinstance(event, TextDeltaEvent):
|
|
76
|
+
print(event.content, end="")
|
|
77
|
+
elif isinstance(event, DoneEvent):
|
|
78
|
+
print(f"\n=== 最终回答 ===\n{event.content}")
|
|
79
|
+
|
|
80
|
+
agent.agent_event.subscribe(on_event)
|
|
81
|
+
|
|
82
|
+
async def main():
|
|
83
|
+
await agent.init() # 注册 MCP 管理工具、登记技能,触发 on_agent_init 钩子
|
|
84
|
+
await agent.run("现在几点了?")
|
|
85
|
+
await agent.close() # 断开全部 MCP server
|
|
86
|
+
|
|
87
|
+
asyncio.run(main())
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
## Voyo_Agent 能力总览
|
|
91
|
+
|
|
92
|
+
`Voyo_Agent` 由四个能力层 mixin(AgentChat / AgentTool / Agent_MCP / Agent_Skill)加三个横切组件(AgentPrompt / Agent_Hook / agent_event)组成:
|
|
93
|
+
|
|
94
|
+
| 组成 | 职责 | 关键接口 |
|
|
95
|
+
| --- | --- | --- |
|
|
96
|
+
| AgentChat | 模型对话、多轮循环、history 维护 | `run()` / `achat()` / `history` |
|
|
97
|
+
| AgentTool | 工具注册、schema 下发、调用执行 | `registry_tool()` / `unregistry_tool()` |
|
|
98
|
+
| Agent_MCP | MCP server 接入与状态机 | `registry_mcp()` / `list_mcp()` / `close()` |
|
|
99
|
+
| Agent_Skill | 技能登记与按需加载 | `registry_skill()` / `list_skill()` |
|
|
100
|
+
| AgentPrompt | system + fragment + soul 拼接 | `append_fragment_prompt()` / `replace_fragment_prompt()` |
|
|
101
|
+
| Agent_Hook | 生命周期钩子 | `on_agent_init` / `on_user_input` / `on_dialog_end` |
|
|
102
|
+
| agent_event | 事件流推送 | `subscribe()` |
|
|
103
|
+
|
|
104
|
+
生命周期三个入口:
|
|
105
|
+
|
|
106
|
+
- **`init()`**:注册 MCP 管理工具(`mcp_list` / `mcp_remove` / `mcp_reload`)→ 登记 `skill_dirs` 技能 → 触发 `on_agent_init`
|
|
107
|
+
- **`run(content)`**:触发 `on_user_input` → 模型响应 → 工具调用 → 结果回传,循环至无待回传调用或达到 `MAX_TURNS` → 触发 `on_dialog_end` → 推送 `DoneEvent`
|
|
108
|
+
- **`close()`**:断开全部 MCP server,销毁前调用一次
|
|
109
|
+
|
|
110
|
+
构造参数:`model` / `base_url` / `api_key` / `effort` / `system_prompt_path` / `soul_prompt_path` / `skill_dirs`。对话全程可读 `agent.history`(reasoning 内容随轮写回,供下一轮上下文使用)。
|
|
111
|
+
|
|
112
|
+
以下各节展开这些能力。
|
|
113
|
+
|
|
114
|
+
## 自定义工具
|
|
115
|
+
|
|
116
|
+
```python
|
|
117
|
+
from voyoagent.tools.tool_types import ToolDef
|
|
118
|
+
|
|
119
|
+
GET_TIME_TOOL: ToolDef = {
|
|
120
|
+
"type": "function",
|
|
121
|
+
"name": "get_time",
|
|
122
|
+
"description": "获取当前时间",
|
|
123
|
+
"parameters": {
|
|
124
|
+
"type": "object",
|
|
125
|
+
"properties": {"timezone": {"type": "string", "description": "时区,可选"}},
|
|
126
|
+
},
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
async def get_time(timezone: str = None) -> str:
|
|
130
|
+
return datetime.now().isoformat()
|
|
131
|
+
|
|
132
|
+
agent.registry_tool((GET_TIME_TOOL, get_time))
|
|
133
|
+
agent.unregistry_tool("get_time") # 注销
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
handler 入参来自模型给出的 JSON(无参数时可不带),返回值序列化后作为 `function_call_output` 回传;handler 抛异常时错误文本回传给模型并推送 `ToolErrorEvent`。同名工具重复注册抛 `YoAgentException`。
|
|
137
|
+
|
|
138
|
+
## Skill
|
|
139
|
+
|
|
140
|
+
技能即一个含 `SKILL.md` 的目录,frontmatter 提供元数据:
|
|
141
|
+
|
|
142
|
+
```markdown
|
|
143
|
+
---
|
|
144
|
+
name: weather-report
|
|
145
|
+
description: 查询并生成城市天气报告
|
|
146
|
+
---
|
|
147
|
+
(操作指南正文,模型经 load_skill 读取)
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
```python
|
|
151
|
+
# 构造时传入
|
|
152
|
+
agent = Voyo_Agent(skill_dirs=["./skills"])
|
|
153
|
+
|
|
154
|
+
# 运行期增删查
|
|
155
|
+
await agent.registry_skill("./more-skills") # 目录自身含 SKILL.md 按单技能,否则扫描一级子目录
|
|
156
|
+
await agent.unregistry_skill("./more-skills")
|
|
157
|
+
agent.list_skill() # [{name, description, readed, skill_dir}, ...]
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
登记后技能集合以 fragment 注入系统提示词,模型按需调用 `load_skill` 读取全文,`readed` 标记已读状态。
|
|
161
|
+
|
|
162
|
+
## MCP
|
|
163
|
+
|
|
164
|
+
```python
|
|
165
|
+
# stdio 子进程接入(npx 首次安装耗时,状态停在 loading)
|
|
166
|
+
await agent.registry_mcp("fetch", command="npx", args=["-y", "@modelcontextprotocol/server-fetch"])
|
|
167
|
+
|
|
168
|
+
# streamable http 接入
|
|
169
|
+
await agent.registry_mcp("remote", url="https://example.com/mcp")
|
|
170
|
+
|
|
171
|
+
agent.list_mcp() # [{name, state: loading|ready|error, error, tools, command, args, url}, ...]
|
|
172
|
+
await agent.reload_mcp("fetch") # 原参数重连(ready 刷新工具表,error 重试)
|
|
173
|
+
await agent.remove_mcp("fetch") # 断开并注销其全部工具
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
连接在后台任务中进行,`registry_mcp` 立即返回;失败落 `error` 状态、通过 `list_mcp()['error']` 查看原因。server 工具以 `mcp__<server>__<工具名>` 注册。`init()` 已把 `mcp_list` / `mcp_reload` / `mcp_remove` 注册为模型工具,agent 可自主查看与管理 MCP server。
|
|
177
|
+
|
|
178
|
+
## 事件流
|
|
179
|
+
|
|
180
|
+
`agent.agent_event.subscribe(handler)` 订阅,`handler` 收到全部事件 dataclass:
|
|
181
|
+
|
|
182
|
+
| 事件 | 字段 | 时机 |
|
|
183
|
+
| --- | --- | --- |
|
|
184
|
+
| `RunStartEvent` | - | `run()` 开始 |
|
|
185
|
+
| `ThinkingStartEvent` / `ThinkingDeltaEvent` / `ThinkingEndEvent` | `content`(delta) | 思考流 |
|
|
186
|
+
| `TextStartEvent` / `TextDeltaEvent` | `content`(delta) | 正文流 |
|
|
187
|
+
| `ToolCallEvent` | `call_id` / `name` / `arguments` | 工具调用前 |
|
|
188
|
+
| `ToolResultEvent` / `ToolErrorEvent` | `call_id` / `name` / `result` 或 `error` | 工具返回后 |
|
|
189
|
+
| `ResponseCompletedEvent` | - | 一轮模型响应流结束 |
|
|
190
|
+
| `TurnEndEvent` | - | 一轮工具结果回传完成 |
|
|
191
|
+
| `DoneEvent` | `content` | `run()` 结束,最终全文 |
|
|
192
|
+
| `ErrorEvent` | `content` | 错误 |
|
|
193
|
+
|
|
194
|
+
事件类型汇总为 `AgentEventType`;thinking 流结束时框架把 reasoning 内容写回 history,供下一轮上下文使用。
|
|
195
|
+
|
|
196
|
+
## 生命周期钩子
|
|
197
|
+
|
|
198
|
+
```python
|
|
199
|
+
agent.agent_hook.on_agent_init.subscribe(my_init) # init() 尾部触发一次
|
|
200
|
+
agent.agent_hook.on_user_input.subscribe(my_hook) # 每次 run() 入口,参数: 用户输入 str
|
|
201
|
+
agent.agent_hook.on_dialog_end.subscribe(my_hook) # 每次 run() 结束
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
回调支持同步函数或 async 函数。
|
|
205
|
+
|
|
206
|
+
## 提示词体系
|
|
207
|
+
|
|
208
|
+
最终 system 提示词 = `system.md` + 动态 fragment 区 + `soul.md`:
|
|
209
|
+
|
|
210
|
+
```python
|
|
211
|
+
agent.agent_prompt.append_fragment_prompt("rules", "额外规则文本")
|
|
212
|
+
agent.agent_prompt.replace_fragment_prompt("rules", "新文本") # 按 id 替换,id 不存在返回 False
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
默认提示词文件随包内置(`voyoagent/prompts/`),构造时用 `system_prompt_path` / `soul_prompt_path` 覆盖。
|
|
216
|
+
|
|
217
|
+
## Yo_Agent:高阶封装
|
|
218
|
+
|
|
219
|
+
`Yo_Agent` 继承 `Voyo_Agent`,预置常用能力,构造即可投入使用:
|
|
220
|
+
|
|
221
|
+
- **内置工具**(构造即注册,`auto_registry_tool=False` 可关闭):`read_file` / `write_file` / `replace_file` / `list_dir` / `run_shell` / `get_weather`
|
|
222
|
+
- **fragment 自动注入**:当前时间(每轮 `run()` 刷新)与操作系统平台
|
|
223
|
+
|
|
224
|
+
```python
|
|
225
|
+
from voyoagent import Yo_Agent
|
|
226
|
+
|
|
227
|
+
agent = Yo_Agent(
|
|
228
|
+
model="gpt-5.2",
|
|
229
|
+
base_url="https://api.example.com/v1",
|
|
230
|
+
api_key="sk-...",
|
|
231
|
+
skill_dirs=["./skills"],
|
|
232
|
+
)
|
|
233
|
+
```
|
|
234
|
+
|
|
235
|
+
构造参数与 `Voyo_Agent` 一致,额外多 `auto_registry_tool`;事件、Skill、MCP、钩子、提示词等接口全部继承自 `Voyo_Agent`。
|
|
@@ -0,0 +1,215 @@
|
|
|
1
|
+
# voyoagent
|
|
2
|
+
|
|
3
|
+
基于 OpenAI Responses API 的极简异步 Agent 框架:流式事件输出、工具注册、Skill 渐进加载、MCP 接入、提示词 fragment 与生命周期钩子。核心是基类 `Voyo_Agent`,`await agent.run("...")` 即完成一次多轮工具调用对话,全过程经 `agent_event` 以 dataclass 事件推送;`Yo_Agent` 是预置内置工具的高阶封装。
|
|
4
|
+
|
|
5
|
+
## 特性
|
|
6
|
+
|
|
7
|
+
- **流式事件**:思考流 / 正文流 / 工具调用 / 工具结果 / 错误,全部以 dataclass 事件从单一订阅点推送
|
|
8
|
+
- **工具**:`(schema, handler)` 二元组注册,async handler,参数由模型 JSON 给出、返回字符串回传
|
|
9
|
+
- **Skill**:扫描目录登记技能(SKILL.md frontmatter),模型经 `load_skill` 工具按需读取全文
|
|
10
|
+
- **MCP**:stdio 子进程与 streamable http 两种接入,后台连接,`loading → ready/error` 状态机
|
|
11
|
+
- **提示词**:system + 动态 fragment(按 id 增删改)+ soul 三段拼接
|
|
12
|
+
- **钩子**:`on_agent_init` / `on_user_input` / `on_dialog_end`,回调支持同步与 async
|
|
13
|
+
|
|
14
|
+
## 安装
|
|
15
|
+
|
|
16
|
+
```bash
|
|
17
|
+
uv add voyoagent
|
|
18
|
+
# 或
|
|
19
|
+
pip install voyoagent
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
依赖 `voyolib`(提供 `voyo.model.OpenAiResponsesClient` 与工具函数)。
|
|
23
|
+
|
|
24
|
+
## 快速开始(Voyo_Agent)
|
|
25
|
+
|
|
26
|
+
```python
|
|
27
|
+
import asyncio
|
|
28
|
+
from datetime import datetime
|
|
29
|
+
|
|
30
|
+
from voyoagent import Voyo_Agent
|
|
31
|
+
from voyoagent.agent_base import ThinkingDeltaEvent, TextDeltaEvent, DoneEvent
|
|
32
|
+
from voyoagent.tools.tool_types import ToolDef
|
|
33
|
+
|
|
34
|
+
GET_TIME_TOOL: ToolDef = {
|
|
35
|
+
"type": "function",
|
|
36
|
+
"name": "get_time",
|
|
37
|
+
"description": "获取当前时间",
|
|
38
|
+
"parameters": {"type": "object", "properties": {}},
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
async def get_time() -> str:
|
|
42
|
+
return datetime.now().isoformat()
|
|
43
|
+
|
|
44
|
+
agent = Voyo_Agent(
|
|
45
|
+
model="gpt-5.2",
|
|
46
|
+
base_url="https://api.example.com/v1",
|
|
47
|
+
api_key="sk-...",
|
|
48
|
+
effort="high", # 思考力度: none/low/medium/high
|
|
49
|
+
)
|
|
50
|
+
agent.registry_tool((GET_TIME_TOOL, get_time))
|
|
51
|
+
|
|
52
|
+
def on_event(event):
|
|
53
|
+
if isinstance(event, ThinkingDeltaEvent):
|
|
54
|
+
print(event.content, end="")
|
|
55
|
+
elif isinstance(event, TextDeltaEvent):
|
|
56
|
+
print(event.content, end="")
|
|
57
|
+
elif isinstance(event, DoneEvent):
|
|
58
|
+
print(f"\n=== 最终回答 ===\n{event.content}")
|
|
59
|
+
|
|
60
|
+
agent.agent_event.subscribe(on_event)
|
|
61
|
+
|
|
62
|
+
async def main():
|
|
63
|
+
await agent.init() # 注册 MCP 管理工具、登记技能,触发 on_agent_init 钩子
|
|
64
|
+
await agent.run("现在几点了?")
|
|
65
|
+
await agent.close() # 断开全部 MCP server
|
|
66
|
+
|
|
67
|
+
asyncio.run(main())
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
## Voyo_Agent 能力总览
|
|
71
|
+
|
|
72
|
+
`Voyo_Agent` 由四个能力层 mixin(AgentChat / AgentTool / Agent_MCP / Agent_Skill)加三个横切组件(AgentPrompt / Agent_Hook / agent_event)组成:
|
|
73
|
+
|
|
74
|
+
| 组成 | 职责 | 关键接口 |
|
|
75
|
+
| --- | --- | --- |
|
|
76
|
+
| AgentChat | 模型对话、多轮循环、history 维护 | `run()` / `achat()` / `history` |
|
|
77
|
+
| AgentTool | 工具注册、schema 下发、调用执行 | `registry_tool()` / `unregistry_tool()` |
|
|
78
|
+
| Agent_MCP | MCP server 接入与状态机 | `registry_mcp()` / `list_mcp()` / `close()` |
|
|
79
|
+
| Agent_Skill | 技能登记与按需加载 | `registry_skill()` / `list_skill()` |
|
|
80
|
+
| AgentPrompt | system + fragment + soul 拼接 | `append_fragment_prompt()` / `replace_fragment_prompt()` |
|
|
81
|
+
| Agent_Hook | 生命周期钩子 | `on_agent_init` / `on_user_input` / `on_dialog_end` |
|
|
82
|
+
| agent_event | 事件流推送 | `subscribe()` |
|
|
83
|
+
|
|
84
|
+
生命周期三个入口:
|
|
85
|
+
|
|
86
|
+
- **`init()`**:注册 MCP 管理工具(`mcp_list` / `mcp_remove` / `mcp_reload`)→ 登记 `skill_dirs` 技能 → 触发 `on_agent_init`
|
|
87
|
+
- **`run(content)`**:触发 `on_user_input` → 模型响应 → 工具调用 → 结果回传,循环至无待回传调用或达到 `MAX_TURNS` → 触发 `on_dialog_end` → 推送 `DoneEvent`
|
|
88
|
+
- **`close()`**:断开全部 MCP server,销毁前调用一次
|
|
89
|
+
|
|
90
|
+
构造参数:`model` / `base_url` / `api_key` / `effort` / `system_prompt_path` / `soul_prompt_path` / `skill_dirs`。对话全程可读 `agent.history`(reasoning 内容随轮写回,供下一轮上下文使用)。
|
|
91
|
+
|
|
92
|
+
以下各节展开这些能力。
|
|
93
|
+
|
|
94
|
+
## 自定义工具
|
|
95
|
+
|
|
96
|
+
```python
|
|
97
|
+
from voyoagent.tools.tool_types import ToolDef
|
|
98
|
+
|
|
99
|
+
GET_TIME_TOOL: ToolDef = {
|
|
100
|
+
"type": "function",
|
|
101
|
+
"name": "get_time",
|
|
102
|
+
"description": "获取当前时间",
|
|
103
|
+
"parameters": {
|
|
104
|
+
"type": "object",
|
|
105
|
+
"properties": {"timezone": {"type": "string", "description": "时区,可选"}},
|
|
106
|
+
},
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
async def get_time(timezone: str = None) -> str:
|
|
110
|
+
return datetime.now().isoformat()
|
|
111
|
+
|
|
112
|
+
agent.registry_tool((GET_TIME_TOOL, get_time))
|
|
113
|
+
agent.unregistry_tool("get_time") # 注销
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
handler 入参来自模型给出的 JSON(无参数时可不带),返回值序列化后作为 `function_call_output` 回传;handler 抛异常时错误文本回传给模型并推送 `ToolErrorEvent`。同名工具重复注册抛 `YoAgentException`。
|
|
117
|
+
|
|
118
|
+
## Skill
|
|
119
|
+
|
|
120
|
+
技能即一个含 `SKILL.md` 的目录,frontmatter 提供元数据:
|
|
121
|
+
|
|
122
|
+
```markdown
|
|
123
|
+
---
|
|
124
|
+
name: weather-report
|
|
125
|
+
description: 查询并生成城市天气报告
|
|
126
|
+
---
|
|
127
|
+
(操作指南正文,模型经 load_skill 读取)
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
```python
|
|
131
|
+
# 构造时传入
|
|
132
|
+
agent = Voyo_Agent(skill_dirs=["./skills"])
|
|
133
|
+
|
|
134
|
+
# 运行期增删查
|
|
135
|
+
await agent.registry_skill("./more-skills") # 目录自身含 SKILL.md 按单技能,否则扫描一级子目录
|
|
136
|
+
await agent.unregistry_skill("./more-skills")
|
|
137
|
+
agent.list_skill() # [{name, description, readed, skill_dir}, ...]
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
登记后技能集合以 fragment 注入系统提示词,模型按需调用 `load_skill` 读取全文,`readed` 标记已读状态。
|
|
141
|
+
|
|
142
|
+
## MCP
|
|
143
|
+
|
|
144
|
+
```python
|
|
145
|
+
# stdio 子进程接入(npx 首次安装耗时,状态停在 loading)
|
|
146
|
+
await agent.registry_mcp("fetch", command="npx", args=["-y", "@modelcontextprotocol/server-fetch"])
|
|
147
|
+
|
|
148
|
+
# streamable http 接入
|
|
149
|
+
await agent.registry_mcp("remote", url="https://example.com/mcp")
|
|
150
|
+
|
|
151
|
+
agent.list_mcp() # [{name, state: loading|ready|error, error, tools, command, args, url}, ...]
|
|
152
|
+
await agent.reload_mcp("fetch") # 原参数重连(ready 刷新工具表,error 重试)
|
|
153
|
+
await agent.remove_mcp("fetch") # 断开并注销其全部工具
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
连接在后台任务中进行,`registry_mcp` 立即返回;失败落 `error` 状态、通过 `list_mcp()['error']` 查看原因。server 工具以 `mcp__<server>__<工具名>` 注册。`init()` 已把 `mcp_list` / `mcp_reload` / `mcp_remove` 注册为模型工具,agent 可自主查看与管理 MCP server。
|
|
157
|
+
|
|
158
|
+
## 事件流
|
|
159
|
+
|
|
160
|
+
`agent.agent_event.subscribe(handler)` 订阅,`handler` 收到全部事件 dataclass:
|
|
161
|
+
|
|
162
|
+
| 事件 | 字段 | 时机 |
|
|
163
|
+
| --- | --- | --- |
|
|
164
|
+
| `RunStartEvent` | - | `run()` 开始 |
|
|
165
|
+
| `ThinkingStartEvent` / `ThinkingDeltaEvent` / `ThinkingEndEvent` | `content`(delta) | 思考流 |
|
|
166
|
+
| `TextStartEvent` / `TextDeltaEvent` | `content`(delta) | 正文流 |
|
|
167
|
+
| `ToolCallEvent` | `call_id` / `name` / `arguments` | 工具调用前 |
|
|
168
|
+
| `ToolResultEvent` / `ToolErrorEvent` | `call_id` / `name` / `result` 或 `error` | 工具返回后 |
|
|
169
|
+
| `ResponseCompletedEvent` | - | 一轮模型响应流结束 |
|
|
170
|
+
| `TurnEndEvent` | - | 一轮工具结果回传完成 |
|
|
171
|
+
| `DoneEvent` | `content` | `run()` 结束,最终全文 |
|
|
172
|
+
| `ErrorEvent` | `content` | 错误 |
|
|
173
|
+
|
|
174
|
+
事件类型汇总为 `AgentEventType`;thinking 流结束时框架把 reasoning 内容写回 history,供下一轮上下文使用。
|
|
175
|
+
|
|
176
|
+
## 生命周期钩子
|
|
177
|
+
|
|
178
|
+
```python
|
|
179
|
+
agent.agent_hook.on_agent_init.subscribe(my_init) # init() 尾部触发一次
|
|
180
|
+
agent.agent_hook.on_user_input.subscribe(my_hook) # 每次 run() 入口,参数: 用户输入 str
|
|
181
|
+
agent.agent_hook.on_dialog_end.subscribe(my_hook) # 每次 run() 结束
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
回调支持同步函数或 async 函数。
|
|
185
|
+
|
|
186
|
+
## 提示词体系
|
|
187
|
+
|
|
188
|
+
最终 system 提示词 = `system.md` + 动态 fragment 区 + `soul.md`:
|
|
189
|
+
|
|
190
|
+
```python
|
|
191
|
+
agent.agent_prompt.append_fragment_prompt("rules", "额外规则文本")
|
|
192
|
+
agent.agent_prompt.replace_fragment_prompt("rules", "新文本") # 按 id 替换,id 不存在返回 False
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
默认提示词文件随包内置(`voyoagent/prompts/`),构造时用 `system_prompt_path` / `soul_prompt_path` 覆盖。
|
|
196
|
+
|
|
197
|
+
## Yo_Agent:高阶封装
|
|
198
|
+
|
|
199
|
+
`Yo_Agent` 继承 `Voyo_Agent`,预置常用能力,构造即可投入使用:
|
|
200
|
+
|
|
201
|
+
- **内置工具**(构造即注册,`auto_registry_tool=False` 可关闭):`read_file` / `write_file` / `replace_file` / `list_dir` / `run_shell` / `get_weather`
|
|
202
|
+
- **fragment 自动注入**:当前时间(每轮 `run()` 刷新)与操作系统平台
|
|
203
|
+
|
|
204
|
+
```python
|
|
205
|
+
from voyoagent import Yo_Agent
|
|
206
|
+
|
|
207
|
+
agent = Yo_Agent(
|
|
208
|
+
model="gpt-5.2",
|
|
209
|
+
base_url="https://api.example.com/v1",
|
|
210
|
+
api_key="sk-...",
|
|
211
|
+
skill_dirs=["./skills"],
|
|
212
|
+
)
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
构造参数与 `Voyo_Agent` 一致,额外多 `auto_registry_tool`;事件、Skill、MCP、钩子、提示词等接口全部继承自 `Voyo_Agent`。
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "voyoagent"
|
|
3
|
+
dynamic = ["version"]
|
|
4
|
+
description = "基于 OpenAI Responses API 的极简异步 Agent 框架:流式事件、工具注册、Skill 加载、MCP 接入、提示词 fragment 与生命周期钩子"
|
|
5
|
+
readme = "README.md"
|
|
6
|
+
requires-python = ">=3.13"
|
|
7
|
+
authors = [{ name = "zhantewei" }]
|
|
8
|
+
keywords = ["agent", "llm", "mcp", "skill", "openai", "asyncio"]
|
|
9
|
+
classifiers = [
|
|
10
|
+
"Development Status :: 4 - Beta",
|
|
11
|
+
"Intended Audience :: Developers",
|
|
12
|
+
"Operating System :: OS Independent",
|
|
13
|
+
"Programming Language :: Python :: 3.13",
|
|
14
|
+
"Topic :: Scientific/Engineering :: Artificial Intelligence",
|
|
15
|
+
]
|
|
16
|
+
dependencies = [
|
|
17
|
+
"aiofiles>=25.1.0",
|
|
18
|
+
"mcp>=2.3.0",
|
|
19
|
+
"python-dotenv>=1.0.0",
|
|
20
|
+
"pydantic>=2.0",
|
|
21
|
+
"pydantic-settings>=2.16.1",
|
|
22
|
+
"voyolib>=0.4.0",
|
|
23
|
+
]
|
|
24
|
+
|
|
25
|
+
[dependency-groups]
|
|
26
|
+
# 仓库本地开发用:管理平台 server/、tests_server/、tests_skill/ 与 main.py 示例的依赖,
|
|
27
|
+
# 不进入 voyoagent 发布包
|
|
28
|
+
dev = [
|
|
29
|
+
"asgi-lifespan>=2.1.0",
|
|
30
|
+
"deepagents>=0.7.28",
|
|
31
|
+
"fastapi>=0.156.4",
|
|
32
|
+
"httpx>=0.28.1",
|
|
33
|
+
"langchain-anthropic>=1.7.6",
|
|
34
|
+
"pytest>=9.2.0",
|
|
35
|
+
"pytest-asyncio>=1.4.1",
|
|
36
|
+
"uvicorn[standard]>=0.54.0",
|
|
37
|
+
]
|
|
38
|
+
|
|
39
|
+
[build-system]
|
|
40
|
+
requires = ["hatchling"]
|
|
41
|
+
build-backend = "hatchling.build"
|
|
42
|
+
|
|
43
|
+
[tool.hatch.version]
|
|
44
|
+
path = "voyoagent/__init__.py"
|
|
45
|
+
|
|
46
|
+
[tool.hatch.build.targets.wheel]
|
|
47
|
+
packages = ["voyoagent"]
|
|
48
|
+
# test.py 是仓库内手动联调脚本(读 .env、sys.path hack),不随包发布
|
|
49
|
+
exclude = ["voyoagent/test.py"]
|
|
50
|
+
|
|
51
|
+
[tool.hatch.build.targets.sdist]
|
|
52
|
+
# 只带包源码与 README,排除 server/ frontend/ tests_server/ tests_skill/ main.py 等
|
|
53
|
+
include = ["/voyoagent", "/README.md"]
|
|
54
|
+
exclude = ["voyoagent/test.py"]
|
|
55
|
+
|
|
56
|
+
[tool.pytest.ini_options]
|
|
57
|
+
asyncio_mode = "auto"
|
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
__version__ = "0.1.0"
|
|
2
|
+
|
|
3
|
+
from voyoagent.agent import Voyo_Agent
|
|
4
|
+
from voyoagent.yo_agent import Yo_Agent, BUILTIN_TOOLS
|
|
5
|
+
from voyoagent.prompt import AgentPrompt
|
|
6
|
+
from voyoagent.agent_hook import Agent_Hook
|
|
7
|
+
from voyoagent.agent_base import (
|
|
8
|
+
AgentEvent,
|
|
9
|
+
AgentEventType,
|
|
10
|
+
RunStartEvent,
|
|
11
|
+
ThinkingStartEvent,
|
|
12
|
+
ThinkingDeltaEvent,
|
|
13
|
+
ThinkingEndEvent,
|
|
14
|
+
TextStartEvent,
|
|
15
|
+
TextDeltaEvent,
|
|
16
|
+
ToolCallEvent,
|
|
17
|
+
ToolResultEvent,
|
|
18
|
+
ToolErrorEvent,
|
|
19
|
+
ResponseCompletedEvent,
|
|
20
|
+
TurnEndEvent,
|
|
21
|
+
DoneEvent,
|
|
22
|
+
ErrorEvent,
|
|
23
|
+
)
|
|
24
|
+
from voyoagent.tools import (
|
|
25
|
+
AgentTool,
|
|
26
|
+
LOAD_SKILL_TOOL,
|
|
27
|
+
WEATHER_TOOL_ENTRY,
|
|
28
|
+
READ_FILE_ENTRY,
|
|
29
|
+
WRITE_FILE_ENTRY,
|
|
30
|
+
REPLACE_FILE_ENTRY,
|
|
31
|
+
LIST_DIR_ENTRY,
|
|
32
|
+
RUN_SHELL_ENTRY,
|
|
33
|
+
)
|
|
34
|
+
from voyoagent.tools.tool_types import ToolDef, ToolHandler, ToolEntry
|
|
35
|
+
from voyoagent.utils.exception import YoAgentCode, YoAgentException
|
|
36
|
+
|
|
37
|
+
__all__ = [
|
|
38
|
+
"__version__",
|
|
39
|
+
"Voyo_Agent",
|
|
40
|
+
"Yo_Agent",
|
|
41
|
+
"BUILTIN_TOOLS",
|
|
42
|
+
"AgentPrompt",
|
|
43
|
+
"Agent_Hook",
|
|
44
|
+
"AgentEvent",
|
|
45
|
+
"AgentEventType",
|
|
46
|
+
"RunStartEvent",
|
|
47
|
+
"ThinkingStartEvent",
|
|
48
|
+
"ThinkingDeltaEvent",
|
|
49
|
+
"ThinkingEndEvent",
|
|
50
|
+
"TextStartEvent",
|
|
51
|
+
"TextDeltaEvent",
|
|
52
|
+
"ToolCallEvent",
|
|
53
|
+
"ToolResultEvent",
|
|
54
|
+
"ToolErrorEvent",
|
|
55
|
+
"ResponseCompletedEvent",
|
|
56
|
+
"TurnEndEvent",
|
|
57
|
+
"DoneEvent",
|
|
58
|
+
"ErrorEvent",
|
|
59
|
+
"AgentTool",
|
|
60
|
+
"LOAD_SKILL_TOOL",
|
|
61
|
+
"WEATHER_TOOL_ENTRY",
|
|
62
|
+
"READ_FILE_ENTRY",
|
|
63
|
+
"WRITE_FILE_ENTRY",
|
|
64
|
+
"REPLACE_FILE_ENTRY",
|
|
65
|
+
"LIST_DIR_ENTRY",
|
|
66
|
+
"RUN_SHELL_ENTRY",
|
|
67
|
+
"ToolDef",
|
|
68
|
+
"ToolHandler",
|
|
69
|
+
"ToolEntry",
|
|
70
|
+
"YoAgentCode",
|
|
71
|
+
"YoAgentException",
|
|
72
|
+
]
|
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
from voyo.model import OpenAiResponsesClient,ModelUsage,ThinkingEffort
|
|
2
|
+
from voyo.model.types import OpenAiResponsesMsg,ResponsesFunctionCallOutputItem,ResponsesFunctionCallItem
|
|
3
|
+
|
|
4
|
+
|
|
5
|
+
from voyo.utils.json import JSON
|
|
6
|
+
from typing import TypedDict,Literal,AsyncIterator
|
|
7
|
+
import sys
|
|
8
|
+
from voyoagent.constants import Constants
|
|
9
|
+
|
|
10
|
+
from voyoagent.agent_base import AgentEvent,RunStartEvent,TurnEndEvent,DoneEvent
|
|
11
|
+
from voyoagent.agent_chat import AgentChat
|
|
12
|
+
from voyoagent.agent_hook import Agent_Hook
|
|
13
|
+
from voyoagent.functional.logger_event_handler import logger_event_handler
|
|
14
|
+
from voyoagent.prompt import AgentPrompt
|
|
15
|
+
from voyoagent.constants import root_dir
|
|
16
|
+
from voyoagent.agent_mcp import Agent_MCP
|
|
17
|
+
from voyoagent.agent_skill import Agent_Skill
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
class Voyo_Agent(AgentChat, Agent_MCP, Agent_Skill):
|
|
21
|
+
history: list[OpenAiResponsesMsg]
|
|
22
|
+
model:str
|
|
23
|
+
effort: ThinkingEffort
|
|
24
|
+
next_call_tools:list[ResponsesFunctionCallOutputItem|ResponsesFunctionCallItem]
|
|
25
|
+
agent_prompt: AgentPrompt
|
|
26
|
+
|
|
27
|
+
def __init__(
|
|
28
|
+
self,
|
|
29
|
+
model:str=None,
|
|
30
|
+
base_url:str="",
|
|
31
|
+
api_key:str="",
|
|
32
|
+
effort:ThinkingEffort="none",
|
|
33
|
+
system_prompt_path:str="",
|
|
34
|
+
soul_prompt_path:str="",
|
|
35
|
+
skill_dirs:list[str]|None=None
|
|
36
|
+
):
|
|
37
|
+
self.client= OpenAiResponsesClient(
|
|
38
|
+
base_url=base_url,
|
|
39
|
+
api_key=api_key
|
|
40
|
+
)
|
|
41
|
+
|
|
42
|
+
system_prompt_path=system_prompt_path if system_prompt_path else str(root_dir / "prompts" / "system.md")
|
|
43
|
+
soul_prompt_path=soul_prompt_path if soul_prompt_path else str(root_dir / "prompts" / "soul.md")
|
|
44
|
+
|
|
45
|
+
super().__init__(AgentEvent())
|
|
46
|
+
self.model=model
|
|
47
|
+
self.effort=effort
|
|
48
|
+
self.history=[]
|
|
49
|
+
self.next_call_tools=[]
|
|
50
|
+
self.skill_dirs=skill_dirs if skill_dirs else []
|
|
51
|
+
self.agent_prompt = AgentPrompt(
|
|
52
|
+
system_prompt_path=system_prompt_path,
|
|
53
|
+
soul_prompt_path=soul_prompt_path
|
|
54
|
+
)
|
|
55
|
+
|
|
56
|
+
logger_event_handler(self.agent_event)
|
|
57
|
+
|
|
58
|
+
async def init(self):
|
|
59
|
+
#先触发钩子,订阅方注入的 fragment 能进入随后的统一提示词
|
|
60
|
+
self.registry_mcp_base_tools()
|
|
61
|
+
if self.skill_dirs:
|
|
62
|
+
await self.registry_skill(self.skill_dirs)
|
|
63
|
+
await self.agent_hook.emit_agent_init()
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
async def run(self,content:str):
|
|
67
|
+
await self.agent_hook.emit_user_input(content)
|
|
68
|
+
self.agent_event.write(RunStartEvent())
|
|
69
|
+
await self.achat(content)
|
|
70
|
+
for _ in range(Constants.MAX_TURNS):
|
|
71
|
+
if not self.next_call_tools: break
|
|
72
|
+
self.history.extend(self.next_call_tools)
|
|
73
|
+
self.next_call_tools=[]
|
|
74
|
+
await self.achat()
|
|
75
|
+
self.agent_event.write(TurnEndEvent())
|
|
76
|
+
await self.agent_hook.emit_dialog_end()
|
|
77
|
+
self.agent_event.write(DoneEvent(self._final_text()))
|
|
78
|
+
|
|
79
|
+
def _final_text(self)->str:
|
|
80
|
+
#最终回答取最后一条 assistant 文本消息
|
|
81
|
+
for msg in reversed(self.history):
|
|
82
|
+
if msg.get("role")=="assistant" and isinstance(msg.get("content"),str):
|
|
83
|
+
return msg["content"]
|
|
84
|
+
return ""
|
|
85
|
+
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
|
|
89
|
+
|