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.
Files changed (32) hide show
  1. voyoagent-0.1.0/.gitignore +25 -0
  2. voyoagent-0.1.0/PKG-INFO +235 -0
  3. voyoagent-0.1.0/README.md +215 -0
  4. voyoagent-0.1.0/pyproject.toml +57 -0
  5. voyoagent-0.1.0/voyoagent/__init__.py +72 -0
  6. voyoagent-0.1.0/voyoagent/agent.py +89 -0
  7. voyoagent-0.1.0/voyoagent/agent_base.py +94 -0
  8. voyoagent-0.1.0/voyoagent/agent_chat.py +88 -0
  9. voyoagent-0.1.0/voyoagent/agent_context.py +16 -0
  10. voyoagent-0.1.0/voyoagent/agent_hook.py +27 -0
  11. voyoagent-0.1.0/voyoagent/agent_mcp.py +301 -0
  12. voyoagent-0.1.0/voyoagent/agent_skill.py +181 -0
  13. voyoagent-0.1.0/voyoagent/constants.py +10 -0
  14. voyoagent-0.1.0/voyoagent/env.py +23 -0
  15. voyoagent-0.1.0/voyoagent/functional/logger_event_handler.py +10 -0
  16. voyoagent-0.1.0/voyoagent/llm.py +44 -0
  17. voyoagent-0.1.0/voyoagent/log.py +5 -0
  18. voyoagent-0.1.0/voyoagent/prompt.py +46 -0
  19. voyoagent-0.1.0/voyoagent/prompts/soul.md +0 -0
  20. voyoagent-0.1.0/voyoagent/prompts/system.md +21 -0
  21. voyoagent-0.1.0/voyoagent/tools/__init__.py +13 -0
  22. voyoagent-0.1.0/voyoagent/tools/file_tool.py +129 -0
  23. voyoagent-0.1.0/voyoagent/tools/load_skill.py +59 -0
  24. voyoagent-0.1.0/voyoagent/tools/shell_tool.py +40 -0
  25. voyoagent-0.1.0/voyoagent/tools/tool.py +91 -0
  26. voyoagent-0.1.0/voyoagent/tools/tool_types.py +43 -0
  27. voyoagent-0.1.0/voyoagent/tools/weather_tool.py +19 -0
  28. voyoagent-0.1.0/voyoagent/utils/common_utils.py +98 -0
  29. voyoagent-0.1.0/voyoagent/utils/exception.py +11 -0
  30. voyoagent-0.1.0/voyoagent/utils/llm_utils.py +24 -0
  31. voyoagent-0.1.0/voyoagent/utils/subject.py +42 -0
  32. 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
@@ -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
+