ni.agentkit 0.3.1__py3-none-any.whl

agentkit/docs/TestReport.md

@@ -0,0 +1,80 @@
+# AgentKit 示例测试报告
+
+> 测试时间：2026-04-12  
+> 测试环境：macOS (Apple Silicon)  
+> 模型：Ollama `qwen3.5:cloud`  
+> AgentKit 版本：v0.3.1  
+> Thinking 模式：开启（默认）  
+> LLM 调用模式：非流式（默认）  
+> 缓存：开启（默认）
+
+---
+
+## 测试结果
+
+| # | 示例 | 文件 | 耗时 | 状态 | 说明 |
+|---|------|------|-----:|:----:|------|
+| 1 | 基础对话 | `01_basic_chat.py` | 27.7s | ✅ | 正确回答量子计算定义 |
+| 2 | 工具调用 | `02_tool_calling.py` | 21.8s | ✅ | add=42 / multiply=21 / weather=晴25°C |
+| 3 | Skill 使用 | `03_skill_usage.py` | 42.8s | ✅ | 深圳阵雨→带伞 / 成都阴→厚外套 / 广州晴→防晒 |
+| 4 | 多 Agent 协作 | `04_multi_agent.py` | 116.6s | ✅ | as_tool 委派成功；Handoff 偶发返回 None |
+| 5 | 安全护栏 | `05_guardrail.py` | 12.9s | ✅ | 敏感词拦截 ✅ / read_file 放行 ✅ / delete_file 拒绝 ✅ |
+| 6 | 编排 Agent | `06_orchestration.py` | 195.6s | ✅ | Sequential 流水线 + Parallel 并行 + Loop 循环 |
+| 7 | 同步/异步/流式 | `07_sync_async_stream.py` | 50.0s | ✅ | run_sync 4.3s / run 2.1s / 并发×3 4.5s / 流式 8.3s |
+| 8 | 记忆系统 | `08_memory.py` | 144.2s | ✅ | 咖啡→拿铁→牛奶过敏→燕麦拿铁（4 轮完美记忆） |
+| | **合计** | | **611.6s** | **8/8** | |
+
+## 耗时分析
+
+- **单次 LLM 调用**（含 thinking）：约 5-15 秒
+- **最快示例**：05 安全护栏（12.9s）——护栏拦截不经过 LLM
+- **最慢示例**：06 编排 Agent（195.6s）——3 组编排模式，每组含多个 Agent 串行/并行调用
+- **多轮示例耗时** ≈ LLM 调用次数 × 单次调用耗时
+
+## 各示例 LLM 调用次数估算
+
+| # | 示例 | LLM 调用次数 | 说明 |
+|---|------|:-----------:|------|
+| 1 | 基础对话 | 1 | 单次对话 |
+| 2 | 工具调用 | 6 | 3 个查询 × 2 轮（调工具 + 生成回复） |
+| 3 | Skill 使用 | 9 | 3 个查询 × 3 轮（load_skill + 调工具 + 回复） |
+| 4 | 多 Agent 协作 | ~8 | 模式 A（经理+研究员）+ 模式 B（分诊+2 专家） |
+| 5 | 安全护栏 | 3 | 1 次被拦截 + 2 次正常执行（含工具调用） |
+| 6 | 编排 Agent | ~12 | Sequential(3) + Parallel(3) + Loop(~6) |
+| 7 | 同步/异步/流式 | ~7 | 同步(1) + 异步(1) + 并发(3) + 流式(2) |
+| 8 | 记忆系统 | ~10 | 无记忆(2) + 有记忆(4 轮 × 2 调用) |
+
+## 已知问题
+
+| 问题 | 严重程度 | 说明 |
+|------|:--------:|------|
+| 示例 04 Handoff 偶发返回 None | 低 | cloud 模型对 `transfer_to_xxx` 工具的理解偶发异常，非框架 bug |
+| 示例 06 Loop 部分输出较简短 | 低 | 小模型在迭代优化场景下生成质量有限 |
+
+## 配置说明
+
+本次测试使用以下默认配置：
+
+```python
+Agent(
+    model="ollama/qwen3.5:cloud",
+    enable_cache=True,           # LLM 响应缓存（默认开启）
+    cache_ttl=300,               # 缓存有效期 300 秒
+    memory_async_write=True,     # 记忆异步写入（示例 08 为 False）
+)
+```
+
+OllamaAdapter 配置：
+- **Thinking 模式**：开启（默认 `think=True`）
+- **调用模式**：非流式（`stream=False`）
+- **超时**：300 秒
+
+## 运行方式
+
+```bash
+# 运行单个示例
+python examples/ollama/01_basic_chat.py
+
+# 运行全部示例
+for f in examples/ollama/0*.py; do python "$f"; done
+```

agentkit/examples/ollama/01_basic_chat.py

@@ -0,0 +1,34 @@
+"""
+示例 1：最简 Agent — 纯对话（Ollama 本地版）
+
+运行前请确保 Ollama 已启动：
+  ollama serve
+  ollama pull qwen3.5:cloud
+
+运行：
+  python examples/ollama/01_basic_chat.py
+"""
+import sys, os
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "..", ".."))
+
+from agentkit import Agent, Runner
+
+# 创建最简 Agent —— 使用本地 Ollama 模型
+agent = Agent(
+    name="assistant",
+    instructions="你是一个有帮助的中文助手。回答尽量简洁。",
+    model="ollama/qwen3.5:cloud",      # 本地 Ollama 模型，无需 API Key
+)
+
+# 同步运行
+result = Runner.run_sync(agent, input="什么是量子计算？请用一句话解释。")
+
+if result.success:
+    print(f"✅ 回复: {result.final_output}")
+else:
+    print(f"❌ 错误: {result.error}")
+
+# 查看事件流
+print("\n📋 事件流:")
+for event in result.events:
+    print(f"  [{event.type}] {str(event.data)[:80]}")

agentkit/examples/ollama/02_tool_calling.py

@@ -0,0 +1,70 @@
+"""
+示例 2：带工具的 Agent — Function Calling（Ollama 本地版）
+
+演示 @function_tool 装饰器 + 本地 Ollama 的 Function Calling 能力。
+
+运行前请确保 Ollama 已启动：
+  ollama serve
+  ollama pull qwen3.5:cloud
+
+运行：
+  python examples/ollama/02_tool_calling.py
+"""
+import sys, os
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "..", ".."))
+
+from agentkit import Agent, Runner, function_tool
+
+
+# ===== 定义工具 =====
+
+@function_tool
+def add(a: int, b: int) -> str:
+    """两个数字相加"""
+    return str(a + b)
+
+@function_tool
+def multiply(a: int, b: int) -> str:
+    """两个数字相乘"""
+    return str(a * b)
+
+@function_tool
+def get_weather(city: str) -> str:
+    """获取指定城市的天气信息"""
+    weather_data = {
+        "北京": "晴，25°C",
+        "上海": "多云，22°C",
+        "深圳": "阵雨，28°C",
+    }
+    return weather_data.get(city, f"{city}：暂无数据")
+
+
+# ===== 创建 Agent =====
+
+agent = Agent(
+    name="smart-assistant",
+    instructions="你是一个全能助手。可以做数学计算和查天气。根据用户需求选择合适的工具。回答简洁。",
+    model="ollama/qwen3.5:cloud",
+    tools=[add, multiply, get_weather],
+)
+
+
+# ===== 运行测试 =====
+
+queries = [
+    "请计算 15 + 27 的结果",
+    "3 乘以 7 等于多少？",
+    "北京今天天气如何？",
+]
+
+for q in queries:
+    print(f"\n用户: {q}")
+    result = Runner.run_sync(agent, input=q)
+    if result.success:
+        print(f"助手: {result.final_output}")
+    else:
+        print(f"❌ 错误: {result.error}")
+
+    for event in result.events:
+        if event.type == "tool_result":
+            print(f"  🔧 工具调用: {event.data}")

agentkit/examples/ollama/03_skill_usage.py

@@ -0,0 +1,86 @@
+"""
+示例 3：带 Skill 的 Agent — 领域知识包（Ollama 本地版）
+
+演示 Skill 三级加载和 Skill + Tool 协作。
+
+运行前请确保 Ollama 已启动：
+  ollama serve
+  ollama pull qwen3.5:cloud
+
+运行：
+  python examples/ollama/03_skill_usage.py
+"""
+import sys, os
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "..", ".."))
+
+from agentkit import Agent, Runner, Skill, SkillFrontmatter, function_tool
+
+
+# ===== 定义工具 =====
+
+@function_tool
+def get_weather(city: str) -> str:
+    """获取指定城市的天气信息"""
+    weather_data = {
+        "北京": "晴，25°C",
+        "上海": "多云，22°C",
+        "深圳": "阵雨，28°C",
+        "广州": "晴，30°C",
+        "成都": "阴，18°C",
+    }
+    return weather_data.get(city, f"{city}：暂无数据")
+
+
+# ===== 定义 Skill =====
+
+weather_skill = Skill(
+    frontmatter=SkillFrontmatter(
+        name="weather-analysis",
+        description="天气分析技能，查询天气并给出穿衣建议",
+    ),
+    instructions="""## 天气分析步骤
+
+1. 使用 get_weather 工具查询用户指定城市的天气
+2. 根据天气情况给出穿衣建议：
+   - 温度 > 30°C：建议穿短袖、注意防晒
+   - 温度 20-30°C：建议穿薄外套
+   - 温度 < 20°C：建议穿厚外套
+3. 如果有雨，额外提醒带伞
+4. 用简洁的中文回复用户""",
+)
+
+
+# ===== 创建带 Skill 的 Agent =====
+
+agent = Agent(
+    name="skill-agent",
+    instructions="你是一个智能助手，可以使用专业技能来完成任务。",
+    model="ollama/qwen3.5:cloud",
+    skills=[weather_skill],
+    tools=[get_weather],
+)
+
+
+# ===== 运行测试 =====
+
+queries = [
+    "深圳今天适合穿什么衣服？",
+    "成都现在冷不冷？需要穿什么？",
+    "广州今天出门要注意什么？",
+]
+
+for q in queries:
+    print(f"\n用户: {q}")
+    result = Runner.run_sync(agent, input=q)
+    if result.success:
+        print(f"助手: {result.final_output}")
+    else:
+        print(f"❌ 错误: {result.error}")
+
+    for event in result.events:
+        if event.type == "tool_result":
+            tool_name = event.data.get("tool", "")
+            if tool_name == "load_skill":
+                print(f"  📚 加载了 Skill: {event.data.get('result', {}).get('skill_name', '')}")
+            else:
+                print(f"  🔧 工具调用: {event.data}")

agentkit/examples/ollama/04_multi_agent.py

@@ -0,0 +1,84 @@
+"""
+示例 4：多 Agent 协作 — Handoff 与 as_tool（Ollama 本地版）
+
+演示两种 Agent 协作模式。
+
+运行前请确保 Ollama 已启动：
+  ollama serve
+  ollama pull qwen3.5:cloud
+
+运行：
+  python examples/ollama/04_multi_agent.py
+"""
+import sys, os
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "..", ".."))
+
+from agentkit import Agent, Runner
+
+
+# ============================================================
+# 模式 A：as_tool（委派）
+# ============================================================
+
+print("=" * 50)
+print("  模式 A：as_tool（委派）")
+print("=" * 50)
+
+researcher = Agent(
+    name="researcher",
+    instructions="你是一个研究助手。收到问题后，给出简短的研究结论（不超过 3 句话）。",
+    model="ollama/qwen3.5:cloud",
+)
+
+manager = Agent(
+    name="manager",
+    instructions="你是项目经理。需要研究信息时调用 research 工具。综合研究结果给出你的建议。",
+    model="ollama/qwen3.5:cloud",
+    tools=[
+        researcher.as_tool("research", "调用研究助手获取研究信息"),
+    ],
+)
+
+result = Runner.run_sync(manager, input="帮我调研 Python 异步编程的最佳实践")
+if result.success:
+    print(f"\n✅ 回复: {result.final_output}")
+else:
+    print(f"\n❌ 错误: {result.error}")
+
+for event in result.events:
+    if event.type == "tool_result":
+        print(f"  🔧 研究员返回: {str(event.data)[:100]}")
+
+
+# ============================================================
+# 模式 B：Handoff（转介）
+# ============================================================
+
+print(f"\n{'=' * 50}")
+print("  模式 B：Handoff（转介）")
+print("=" * 50)
+
+billing_agent = Agent(
+    name="billing",
+    instructions="你是账单专家。处理所有账单相关的问题，给出专业的解答。",
+    model="ollama/qwen3.5:cloud",
+)
+
+tech_agent = Agent(
+    name="tech",
+    instructions="你是技术支持专家。处理所有技术相关的问题。",
+    model="ollama/qwen3.5:cloud",
+)
+
+triage_agent = Agent(
+    name="triage",
+    instructions="你是客服分诊员。根据用户问题类型，转交给合适的专家：账单问题转给 billing，技术问题转给 tech。",
+    model="ollama/qwen3.5:cloud",
+    handoffs=[billing_agent, tech_agent],
+)
+
+result = Runner.run_sync(triage_agent, input="我的账单金额好像不对，比上个月多了很多")
+if result.success:
+    print(f"\n✅ 最终由 [{result.last_agent}] 处理: {result.final_output}")
+else:
+    print(f"\n❌ 错误: {result.error}")

agentkit/examples/ollama/05_guardrail.py

@@ -0,0 +1,101 @@
+"""
+示例 5：安全护栏 — Guardrail 与权限控制（Ollama 本地版）
+
+演示输入护栏、输出护栏和权限控制。
+
+运行前请确保 Ollama 已启动：
+  ollama serve
+  ollama pull qwen3.5:cloud
+
+运行：
+  python examples/ollama/05_guardrail.py
+"""
+import sys, os
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "..", ".."))
+
+from agentkit import (
+    Agent, Runner, function_tool,
+    input_guardrail, output_guardrail, GuardrailResult,
+    PermissionPolicy,
+)
+
+
+# ===== 定义工具 =====
+
+@function_tool
+def read_file(filename: str) -> str:
+    """读取文件内容"""
+    return f"[模拟] 文件 {filename} 的内容：Hello World"
+
+@function_tool
+def delete_file(filename: str) -> str:
+    """删除文件"""
+    return f"[模拟] 已删除文件 {filename}"
+
+
+# ===== 定义护栏 =====
+
+@input_guardrail
+async def block_sensitive_words(ctx):
+    """检查输入是否包含敏感词"""
+    sensitive = ["密码", "身份证", "银行卡号", "社保号"]
+    for word in sensitive:
+        if word in ctx.input:
+            return GuardrailResult(triggered=True, reason=f"包含敏感词: {word}")
+    return GuardrailResult(triggered=False)
+
+@output_guardrail
+async def check_output_safety(ctx, output):
+    """检查输出是否安全"""
+    dangerous_words = ["删除成功", "已格式化"]
+    output_str = str(output)
+    for word in dangerous_words:
+        if word in output_str:
+            return GuardrailResult(triggered=True, reason=f"输出包含危险内容: {word}")
+    return GuardrailResult(triggered=False)
+
+
+# ===== 创建带安全护栏的 Agent =====
+
+agent = Agent(
+    name="safe-agent",
+    instructions="你是一个安全的助手。可以帮用户读取文件，但不能删除文件。",
+    model="ollama/qwen3.5:cloud",
+    tools=[read_file, delete_file],
+    input_guardrails=[block_sensitive_words],
+    output_guardrails=[check_output_safety],
+    permission_policy=PermissionPolicy(
+        mode="ask",
+        allowed_tools={"read_file"},
+    ),
+)
+
+
+# ===== 运行测试 =====
+
+print("=" * 50)
+print("  测试输入护栏")
+print("=" * 50)
+
+# 测试 1：敏感请求 → 被拦截
+result = Runner.run_sync(agent, input="请告诉我管理员的密码")
+print(f"\n请求: '请告诉我管理员的密码'")
+print(f"结果: {'🛡️ 已拦截 — ' + result.error if result.error else result.final_output}")
+
+# 测试 2：正常请求 → 通过
+result = Runner.run_sync(agent, input="请读取 config.txt 文件")
+print(f"\n请求: '请读取 config.txt 文件'")
+print(f"结果: {result.final_output if result.success else '❌ ' + str(result.error)}")
+
+print(f"\n{'=' * 50}")
+print("  测试权限控制")
+print("=" * 50)
+
+# 测试 3：尝试调用未授权的工具
+result = Runner.run_sync(agent, input="请删除 temp.txt 文件")
+print(f"\n请求: '请删除 temp.txt 文件'")
+print(f"结果: {result.final_output if result.success else '🔒 ' + str(result.error)}")
+
+for event in result.events:
+    if event.type == "permission_denied":
+        print(f"  🔒 权限拒绝: {event.data}")

agentkit/examples/ollama/06_orchestration.py

@@ -0,0 +1,123 @@
+"""
+示例 6：编排 Agent — 顺序执行、并行执行、循环执行（Ollama 本地版）
+
+演示三种编排模式。
+
+运行前请确保 Ollama 已启动：
+  ollama serve
+  ollama pull qwen3.5:cloud
+
+运行：
+  python examples/ollama/06_orchestration.py
+"""
+import sys, os
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "..", ".."))
+
+from agentkit import Agent, Runner, SequentialAgent, ParallelAgent, LoopAgent
+
+
+MODEL = "ollama/qwen3.5:cloud"
+
+
+# ============================================================
+# 模式 A：顺序执行 — 报告生成流水线
+# ============================================================
+
+print("=" * 50)
+print("  SequentialAgent — 报告生成流水线")
+print("=" * 50)
+
+pipeline = SequentialAgent(
+    name="report-pipeline",
+    sub_agents=[
+        Agent(
+            name="extractor",
+            instructions="你是数据提取专家。从用户输入中提取所有关键数据点，以列表形式输出。",
+            model=MODEL,
+        ),
+        Agent(
+            name="analyzer",
+            instructions="你是数据分析专家。分析上文提取的数据点，找出趋势和规律，给出 2-3 条洞察。",
+            model=MODEL,
+        ),
+        Agent(
+            name="reporter",
+            instructions="你是报告撰写专家。将上文的分析结果写成一段简洁的中文报告（不超过 100 字）。",
+            model=MODEL,
+        ),
+    ],
+)
+
+result = Runner.run_sync(pipeline, input="今年Q1销售额1000万，Q2增长到1500万，Q3下降到1200万，Q4预计1800万")
+print(f"\n输入: 今年Q1销售额1000万...")
+for event in result.events:
+    if event.type == "final_output":
+        print(f"  [{event.agent}] {str(event.data)[:120]}")
+
+
+# ============================================================
+# 模式 B：并行执行 — 多维度分析
+# ============================================================
+
+print(f"\n{'=' * 50}")
+print("  ParallelAgent — 多维度并行分析")
+print("=" * 50)
+
+parallel = ParallelAgent(
+    name="multi-analysis",
+    sub_agents=[
+        Agent(
+            name="financial",
+            instructions="你是财务分析师。用一句话分析给定数据的财务状况。",
+            model=MODEL,
+        ),
+        Agent(
+            name="market",
+            instructions="你是市场分析师。用一句话分析给定数据反映的市场趋势。",
+            model=MODEL,
+        ),
+        Agent(
+            name="risk",
+            instructions="你是风险分析师。用一句话分析给定数据中的潜在风险。",
+            model=MODEL,
+        ),
+    ],
+)
+
+result = Runner.run_sync(parallel, input="公司年收入 5 亿，同比增长 20%，但负债率从 30% 升至 45%")
+print(f"\n输入: 公司年收入 5 亿...")
+for event in result.events:
+    if event.type == "final_output":
+        print(f"  [{event.agent}] {str(event.data)[:120]}")
+
+
+# ============================================================
+# 模式 C：循环执行 — 迭代优化
+# ============================================================
+
+print(f"\n{'=' * 50}")
+print("  LoopAgent — 迭代优化循环")
+print("=" * 50)
+
+loop = LoopAgent(
+    name="improvement-loop",
+    max_iterations=3,
+    sub_agents=[
+        Agent(
+            name="writer",
+            instructions="你是一个文案写手。根据用户需求或上轮反馈，写一句广告语。只输出广告语本身。",
+            model=MODEL,
+        ),
+        Agent(
+            name="critic",
+            instructions="你是一个文案评审。评估上面的广告语，如果已经很好则只输出'通过'，否则给出简短的改进建议。",
+            model=MODEL,
+        ),
+    ],
+)
+
+result = Runner.run_sync(loop, input="为一款AI编程助手写一句吸引开发者的广告语")
+print(f"\n输入: 为一款AI编程助手写广告语")
+for event in result.events:
+    if event.type == "final_output":
+        print(f"  [{event.agent}] {str(event.data)[:120]}")