ni.agentkit 0.3.1__py3-none-any.whl

agentkit/examples/ollama/07_sync_async_stream.py

@@ -0,0 +1,180 @@
+"""
+示例：三种运行方式对比 — 同步 / 异步 / 流式（Ollama 本地版）
+
+演示 Runner 的三种运行方式在同一个 Agent 上的用法差异。
+
+运行前请确保 Ollama 已启动：
+  ollama serve
+  ollama pull qwen3.5:cloud
+
+运行：
+  python examples/ollama/07_sync_async_stream.py
+"""
+import asyncio
+import sys
+import os
+import time
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "..", ".."))
+
+from agentkit import Agent, Runner, function_tool
+
+
+# ===== 定义一个简单工具 =====
+
+@function_tool
+def get_weather(city: str) -> str:
+    """获取指定城市的天气信息"""
+    return {"北京": "晴，25°C", "上海": "多云，22°C"}.get(city, f"{city}：暂无数据")
+
+
+# ===== 创建 Agent（三种方式共用同一个） =====
+
+agent = Agent(
+    name="assistant",
+    instructions="你是一个简洁的中文助手。回答尽量简短。",
+    model="ollama/qwen3.5:cloud",
+    tools=[get_weather],
+)
+
+
+# ============================================================
+# 方式 1：同步运行 — Runner.run_sync()
+# 最简单，一行搞定。适合脚本和快速测试。
+# ============================================================
+
+def demo_sync():
+    print("=" * 50)
+    print("  方式 1：同步运行 — Runner.run_sync()")
+    print("=" * 50)
+
+    start = time.time()
+    result = Runner.run_sync(agent, input="北京今天天气如何？")
+    elapsed = time.time() - start
+
+    if result.success:
+        print(f"  ✅ 回复: {result.final_output}")
+    else:
+        print(f"  ❌ 错误: {result.error}")
+    print(f"  ⏱️ 耗时: {elapsed:.1f}s")
+
+
+# ============================================================
+# 方式 2：异步运行 — await Runner.run()
+# 推荐用于 Web 服务、并发任务等生产场景。
+# ============================================================
+
+async def demo_async():
+    print(f"\n{'=' * 50}")
+    print("  方式 2：异步运行 — await Runner.run()")
+    print("=" * 50)
+
+    start = time.time()
+    result = await Runner.run(agent, input="上海今天天气如何？")
+    elapsed = time.time() - start
+
+    if result.success:
+        print(f"  ✅ 回复: {result.final_output}")
+    else:
+        print(f"  ❌ 错误: {result.error}")
+    print(f"  ⏱️ 耗时: {elapsed:.1f}s")
+
+
+# ============================================================
+# 方式 2b：异步并发 — 同时运行多个 Agent
+# 这是异步的核心优势：多个 LLM 调用可以并发执行。
+# ============================================================
+
+async def demo_async_concurrent():
+    print(f"\n{'=' * 50}")
+    print("  方式 2b：异步并发 — 同时运行多个请求")
+    print("=" * 50)
+
+    queries = [
+        "1+1等于几？只回答数字",
+        "北京今天天气如何？",
+        "用一句话解释什么是 Python",
+    ]
+
+    start = time.time()
+
+    # asyncio.gather 并发执行 3 个请求
+    results = await asyncio.gather(*[
+        Runner.run(agent, input=q) for q in queries
+    ])
+
+    elapsed = time.time() - start
+
+    for q, r in zip(queries, results):
+        status = f"✅ {r.final_output}" if r.success else f"❌ {r.error}"
+        print(f"  [{q[:15]:15s}] → {status}")
+
+    print(f"  ⏱️ 3 个请求并发总耗时: {elapsed:.1f}s（如果串行需要约 3 倍时间）")
+
+
+# ============================================================
+# 方式 3：流式运行 — async for event in Runner.run_streamed()
+# 实时获取每一个事件，适合聊天界面、进度展示。
+# ============================================================
+
+async def demo_stream():
+    print(f"\n{'=' * 50}")
+    print("  方式 3：流式运行 — Runner.run_streamed()")
+    print("=" * 50)
+
+    print("  📡 实时事件流:")
+
+    start = time.time()
+    async for event in Runner.run_streamed(agent, input="北京今天天气如何？"):
+        elapsed = time.time() - start
+        # 每个事件实时打印
+        if event.type == "llm_response":
+            has_tools = "有工具调用" if event.data.has_tool_calls else "纯文本"
+            print(f"  [{elapsed:5.1f}s] 🤖 LLM 响应 ({has_tools})")
+        elif event.type == "tool_result":
+            tool_name = event.data.get("tool", "?")
+            tool_result = event.data.get("result", "")
+            print(f"  [{elapsed:5.1f}s] 🔧 工具 {tool_name} → {tool_result}")
+        elif event.type == "final_output":
+            print(f"  [{elapsed:5.1f}s] ✅ 最终输出: {event.data}")
+        else:
+            print(f"  [{elapsed:5.1f}s] 📋 {event.type}: {str(event.data)[:60]}")
+
+
+# ============================================================
+# 主入口
+# ============================================================
+
+def run_all():
+    """先同步跑一个，再 asyncio.run 跑异步的"""
+
+    print("🚀 AgentKit — 三种运行方式对比\n")
+
+    # 方式 1：同步（必须在 asyncio.run 之外调用）
+    demo_sync()
+
+    # 方式 2、2b、3：异步（在同一个事件循环中运行）
+    async def async_demos():
+        await demo_async()
+        await demo_async_concurrent()
+        await demo_stream()
+
+    asyncio.run(async_demos())
+
+    print(f"\n{'=' * 50}")
+    print("  全部演示完成 🎉")
+    print("=" * 50)
+    print("""
+📝 总结：
+  run_sync()      — 最简单，一行代码，适合脚本和测试
+  await run()     — 异步核心，可并发执行多个请求
+  run_streamed()  — 实时事件流，适合聊天 UI 和进度展示
+
+⚠️ 注意：run_sync() 内部调用 asyncio.run()，因此不能在
+   已有事件循环中使用。如果你的代码已经是 async 的，
+   请直接用 await Runner.run()。
+""")
+
+
+if __name__ == "__main__":
+    run_all()

agentkit/examples/ollama/08_memory.py

@@ -0,0 +1,201 @@
+"""
+示例 8：记忆系统 — 让 Agent 拥有跨会话长期记忆（Ollama 本地版）
+
+演示三种记忆用法：
+  A. 无记忆（默认）— 每次对话互相独立
+  B. SimpleMemory（内置）— 轻量内存记忆，无需外部依赖，适合开发测试
+  C. Mem0Provider（生产级）— 基于向量数据库的长期记忆（需安装 mem0ai + qdrant）
+
+运行前请确保 Ollama 已启动：
+  ollama serve
+  ollama pull qwen3.5:cloud
+
+运行：
+  python examples/ollama/08_memory.py
+"""
+import asyncio
+import sys
+import os
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "..", ".."))
+
+from agentkit import Agent, Runner, BaseMemoryProvider, Memory
+
+
+MODEL = "ollama/qwen3.5:cloud"
+
+
+# ============================================================
+# SimpleMemory：轻量内存记忆实现（无需外部依赖）
+#
+# 适合开发和测试。进程退出后记忆丢失。
+# 生产环境请使用 Mem0Provider（见示例 C）。
+# ============================================================
+
+class SimpleMemory(BaseMemoryProvider):
+    """最简单的内存记忆实现——基于关键词匹配"""
+
+    def __init__(self):
+        self._store: list[Memory] = []
+        self._counter = 0
+
+    async def add(self, content, *, user_id=None, agent_id=None, metadata=None):
+        self._counter += 1
+        m = Memory(id=str(self._counter), content=content)
+        self._store.append(m)
+        print(f"    💾 记忆已存储: {content[:60]}...")
+        return [m]
+
+    async def search(self, query, *, user_id=None, agent_id=None, limit=10):
+        # 简单的关键词重叠匹配（生产环境应该用向量相似度搜索）
+        query_words = set(query)
+        scored = []
+        for m in self._store:
+            overlap = len(query_words & set(m.content))
+            if overlap > 0:
+                scored.append((overlap, m))
+        scored.sort(reverse=True, key=lambda x: x[0])
+        results = [m for _, m in scored[:limit]]
+        if results:
+            print(f"    🔍 检索到 {len(results)} 条相关记忆")
+        return results
+
+    async def get_all(self, *, user_id=None, agent_id=None):
+        return list(self._store)
+
+    async def delete(self, memory_id):
+        self._store = [m for m in self._store if m.id != memory_id]
+        return True
+
+
+# ============================================================
+# 演示 A：无记忆（默认）
+# ============================================================
+
+async def demo_no_memory():
+    print("=" * 55)
+    print("  A. 无记忆（默认）— 每次对话独立")
+    print("=" * 55)
+
+    agent = Agent(
+        name="forgetful",
+        instructions="你是一个简洁的助手。回答尽量简短。",
+        model=MODEL,
+    )
+
+    # 第一次告诉它信息
+    result = await Runner.run(agent, input="我叫小明，我喜欢喝咖啡")
+    print(f"  对话1: {result.final_output}")
+
+    # 第二次问它——它不会记得
+    result = await Runner.run(agent, input="我叫什么名字？我喜欢喝什么？")
+    print(f"  对话2: {result.final_output}")
+    print("  📝 无记忆 → Agent 不记得之前的对话\n")
+
+
+# ============================================================
+# 演示 B：使用 SimpleMemory
+# ============================================================
+
+async def demo_simple_memory():
+    print("=" * 55)
+    print("  B. SimpleMemory — 轻量内存记忆")
+    print("=" * 55)
+
+    memory = SimpleMemory()
+
+    agent = Agent(
+        name="remembering",
+        instructions="你是一个贴心的个人助手。根据相关记忆来个性化回答。回答简洁。",
+        model=MODEL,
+        memory=memory,
+        memory_async_write=False,   # 多轮串行对话需要即时读取记忆
+    )
+
+    # 第一次对话：告诉它偏好
+    print("\n  第1轮对话:")
+    result = await Runner.run(agent, input="我叫小明，我喜欢喝咖啡，讨厌喝茶", user_id="user_001")
+    print(f"  助手: {result.final_output}")
+
+    # 第二次对话：它应该记住
+    print("\n  第2轮对话:")
+    result = await Runner.run(agent, input="帮我推荐一杯饮料吧", user_id="user_001")
+    print(f"  助手: {result.final_output}")
+
+    # 第三次对话：继续积累记忆
+    print("\n  第3轮对话:")
+    result = await Runner.run(agent, input="对了，我对牛奶过敏", user_id="user_001")
+    print(f"  助手: {result.final_output}")
+
+    # 第四次对话：看看它记住了多少
+    print("\n  第4轮对话:")
+    result = await Runner.run(agent, input="再给我推荐一杯饮料，要考虑我的情况", user_id="user_001")
+    print(f"  助手: {result.final_output}")
+
+    # 查看存储的所有记忆
+    all_memories = await memory.get_all()
+    print(f"\n  📋 记忆库中共 {len(all_memories)} 条记忆")
+
+
+# ============================================================
+# 演示 C：Mem0 说明（仅展示配置方式）
+# ============================================================
+
+def demo_mem0_info():
+    print(f"\n{'=' * 55}")
+    print("  C. Mem0Provider — 生产级长期记忆（配置说明）")
+    print("=" * 55)
+
+    print("""
+  Mem0 提供向量数据库驱动的语义记忆，支持跨会话持久化。
+
+  安装：
+    pip install mem0ai
+    docker run -p 6333:6333 qdrant/qdrant    # 启动向量数据库
+
+  使用：
+    from agentkit.memory.mem0_provider import Mem0Provider
+
+    memory = Mem0Provider({
+        "vector_store": {
+            "provider": "qdrant",
+            "config": {
+                "collection_name": "my_agent",
+                "host": "localhost",
+                "port": 6333,
+            }
+        }
+    })
+
+    agent = Agent(
+        name="assistant",
+        memory=memory,        # 就这一行
+        ...
+    )
+
+  相比 SimpleMemory 的优势：
+    ✅ 语义搜索（不是关键词匹配，而是理解意思）
+    ✅ 持久化存储（重启不丢失）
+    ✅ 自动记忆提取（从对话中智能抽取关键信息）
+    ✅ 支持 user_id / agent_id 多维度隔离
+""")
+
+
+# ============================================================
+# 主入口
+# ============================================================
+
+async def main():
+    print("🚀 AgentKit 记忆系统演示\n")
+
+    await demo_no_memory()
+    await demo_simple_memory()
+    demo_mem0_info()
+
+    print("=" * 55)
+    print("  演示完成 🎉")
+    print("=" * 55)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

agentkit/examples/ollama/README.md

@@ -0,0 +1,51 @@
+# Ollama 本地示例（无需 API Key）
+
+使用本地 Ollama + qwen3.5:cloud 模型的示例。**无需任何 API Key，完全本地运行。**
+
+## 环境准备
+
+```bash
+# 1. 安装 Ollama: https://ollama.com
+# 2. 拉取模型
+ollama pull qwen3.5:cloud
+
+# 3. 确认 Ollama 正在运行
+curl http://localhost:11434/api/tags
+
+# 4. 安装 Python 依赖
+pip install pydantic>=2.0 aiohttp>=3.9.0
+```
+
+## 示例列表
+
+| 文件 | 内容 | 对应教程 |
+|------|------|---------|
+| `01_basic_chat.py` | 最简 Agent — 纯对话 | QuickStart 示例 1 |
+| `02_tool_calling.py` | 带工具的 Agent — Function Calling | QuickStart 示例 2 |
+| `03_skill_usage.py` | 带 Skill 的 Agent — 领域知识包 | QuickStart 示例 3 |
+| `04_multi_agent.py` | 多 Agent 协作 — Handoff 与 as_tool | QuickStart 示例 4 |
+| `05_guardrail.py` | 安全护栏 — Guardrail 与权限控制 | QuickStart 示例 5 |
+| `06_orchestration.py` | 编排 Agent — 流水线与循环 | QuickStart 示例 6 |
+| `07_sync_async_stream.py` | 三种运行方式 — 同步/异步/流式 | 同步与异步 |
+| `08_memory.py` | 记忆系统 — 跨会话长期记忆 | 记忆系统 |
+
+## 运行
+
+```bash
+python examples/ollama/01_basic_chat.py
+python examples/ollama/02_tool_calling.py
+# ... 以此类推
+```
+
+## 更换模型
+
+如果你想使用其他 Ollama 模型，只需修改示例中的 `model` 参数：
+
+```python
+# 使用其他模型
+agent = Agent(model="ollama/llama3:8b", ...)
+agent = Agent(model="ollama/gemma:latest", ...)
+agent = Agent(model="ollama/qwen3-vl:8b", ...)
+```
+
+> 💡 不同模型的 Function Calling 能力不同。qwen3.5:cloud 已经过验证支持完整的工具调用。

agentkit/examples/quickstart.py

@@ -0,0 +1,204 @@
+"""
+examples/quickstart.py — AgentKit 快速入门示例
+
+展示框架的核心用法：Agent + Tool + Skill + 多模型。
+"""
+import asyncio
+import sys
+import os
+
+# 将项目根目录加入 path
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from agentkit import Agent, Runner, function_tool, LLMRegistry, LLMConfig
+from agentkit import Skill, SkillFrontmatter, SkillResources
+from agentkit import SequentialAgent, LoopAgent
+from agentkit import input_guardrail, GuardrailResult, PermissionPolicy
+
+
+# ============================================================
+# 示例 1：最简 Agent
+# ============================================================
+
+def example_basic():
+    """最简单的 Agent：一行配置即可运行"""
+    agent = Agent(
+        name="assistant",
+        instructions="你是一个有帮助的中文助手。简洁回答问题。",
+        model="gpt-4o",
+    )
+    result = Runner.run_sync(agent, input="什么是量子计算？请用一句话解释。")
+    print(f"[示例1] {result.final_output}")
+
+
+# ============================================================
+# 示例 2：带工具的 Agent
+# ============================================================
+
+@function_tool
+def calculate(expression: str) -> str:
+    """计算数学表达式的结果"""
+    try:
+        return str(eval(expression))
+    except Exception as e:
+        return f"计算错误: {e}"
+
+@function_tool
+def get_current_time() -> str:
+    """获取当前时间"""
+    from datetime import datetime
+    return datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+
+def example_with_tools():
+    """带工具的 Agent"""
+    agent = Agent(
+        name="math_assistant",
+        instructions="你是一个数学助手。需要计算时请使用 calculate 工具。",
+        model="gpt-4o",
+        tools=[calculate, get_current_time],
+    )
+    result = Runner.run_sync(agent, input="请计算 (15 + 27) * 3 的结果")
+    print(f"[示例2] {result.final_output}")
+
+
+# ============================================================
+# 示例 3：带 Skill 的 Agent
+# ============================================================
+
+def example_with_skill():
+    """带 Skill 的 Agent"""
+    # 代码中直接定义一个 Skill
+    greeting_skill = Skill(
+        frontmatter=SkillFrontmatter(
+            name="greeting-skill",
+            description="一个友好的问候技能，根据时间段生成个性化问候语",
+        ),
+        instructions="""## 使用步骤
+1. 使用 get_current_time 工具获取当前时间
+2. 根据时间段（早上/下午/晚上）选择合适的问候语
+3. 返回个性化的中文问候""",
+    )
+
+    agent = Agent(
+        name="greeter",
+        instructions="你是一个友好的助手，可以使用 Skill 来完成任务。",
+        model="gpt-4o",
+        skills=[greeting_skill],
+        tools=[get_current_time],
+    )
+    result = Runner.run_sync(agent, input="请跟我打个招呼")
+    print(f"[示例3] {result.final_output}")
+
+
+# ============================================================
+# 示例 4：多 Agent 协作（as_tool 模式）
+# ============================================================
+
+def example_multi_agent():
+    """Agent 当工具用——委派模式"""
+    researcher = Agent(
+        name="researcher",
+        instructions="你是一个研究助手。收到问题后，给出简短的研究结论。",
+        model="gpt-4o",
+    )
+
+    manager = Agent(
+        name="manager",
+        instructions="你是一个项目经理。需要研究信息时调用 research 工具。",
+        model="gpt-4o",
+        tools=[
+            researcher.as_tool("research", "调用研究助手获取信息"),
+        ],
+    )
+    result = Runner.run_sync(manager, input="帮我调研一下 Python 异步编程的最佳实践")
+    print(f"[示例4] {result.final_output}")
+
+
+# ============================================================
+# 示例 5：国内模型（DeepSeek）
+# ============================================================
+
+def example_domestic_model():
+    """使用国内模型"""
+    agent = Agent(
+        name="deepseek_assistant",
+        instructions="你是一个中文编程助手。",
+        model="deepseek/deepseek-chat",  # 自动路由到 OpenAICompatibleAdapter
+    )
+    result = Runner.run_sync(agent, input="用 Python 写一个快速排序")
+    print(f"[示例5] {result.final_output}")
+
+
+# ============================================================
+# 示例 6：带安全护栏
+# ============================================================
+
+@input_guardrail
+async def block_sensitive(ctx):
+    """检查是否包含敏感词"""
+    sensitive_words = ["密码", "身份证", "银行卡"]
+    for word in sensitive_words:
+        if word in ctx.input:
+            return GuardrailResult(triggered=True, reason=f"检测到敏感词: {word}")
+    return GuardrailResult(triggered=False)
+
+def example_with_guardrail():
+    """带安全护栏的 Agent"""
+    agent = Agent(
+        name="safe_assistant",
+        instructions="你是一个安全的助手。",
+        model="gpt-4o",
+        input_guardrails=[block_sensitive],
+        permission_policy=PermissionPolicy(
+            mode="ask",
+            allowed_tools={"calculate", "get_current_time"},
+        ),
+    )
+    # 这个请求会被护栏拦截
+    result = Runner.run_sync(agent, input="告诉我你的密码")
+    print(f"[示例6] 被拦截: {result.error}")
+
+    # 这个请求正常通过
+    result = Runner.run_sync(agent, input="你好，今天天气如何？")
+    print(f"[示例6] 正常: {result.final_output}")
+
+
+# ============================================================
+# 主入口
+# ============================================================
+
+if __name__ == "__main__":
+    print("=" * 60)
+    print("AgentKit 框架快速入门示例")
+    print("=" * 60)
+    print()
+    print("注意：运行示例需要配置对应的 LLM API Key。")
+    print("  - OpenAI: export OPENAI_API_KEY=sk-...")
+    print("  - DeepSeek: export DEEPSEEK_API_KEY=sk-...")
+    print()
+
+    # 可以选择运行某个示例
+    if len(sys.argv) > 1:
+        example_num = sys.argv[1]
+        examples = {
+            "1": example_basic,
+            "2": example_with_tools,
+            "3": example_with_skill,
+            "4": example_multi_agent,
+            "5": example_domestic_model,
+            "6": example_with_guardrail,
+        }
+        if example_num in examples:
+            examples[example_num]()
+        else:
+            print(f"未知示例编号: {example_num}")
+    else:
+        print("用法: python examples/quickstart.py [1-6]")
+        print()
+        print("可用示例:")
+        print("  1 - 最简 Agent")
+        print("  2 - 带工具的 Agent")
+        print("  3 - 带 Skill 的 Agent")
+        print("  4 - 多 Agent 协作")
+        print("  5 - 国内模型 (DeepSeek)")
+        print("  6 - 安全护栏")

agentkit/examples/standard/01_basic_chat.py

@@ -0,0 +1,33 @@
+"""
+示例 1：最简 Agent — 纯对话
+
+运行前请设置环境变量：
+  export OPENAI_API_KEY="sk-..."
+
+运行：
+  python examples/standard/01_basic_chat.py
+"""
+import sys, os
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "..", ".."))
+
+from agentkit import Agent, Runner
+
+# 创建最简 Agent —— 只需 3 个参数
+agent = Agent(
+    name="assistant",
+    instructions="你是一个有帮助的中文助手。回答尽量简洁。",
+    model="gpt-4o",
+)
+
+# 同步运行
+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]}")