ni.agentkit 0.3.1__py3-none-any.whl

agentkit/examples/standard/08_memory.py

@@ -0,0 +1,140 @@
+"""
+示例 8：记忆系统 — 让 Agent 拥有跨会话长期记忆（标准版）
+
+演示三种记忆用法：
+  A. 无记忆（默认）
+  B. SimpleMemory（轻量内存记忆）
+  C. Mem0Provider（生产级）
+
+运行前请设置环境变量：
+  export OPENAI_API_KEY="sk-..."
+
+运行：
+  python examples/standard/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
+
+
+# ============================================================
+# SimpleMemory：轻量内存记忆（无需外部依赖）
+# ============================================================
+
+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="gpt-4o",
+    )
+
+    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="gpt-4o",
+        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)} 条记忆")
+
+
+# ============================================================
+# 主入口
+# ============================================================
+
+async def main():
+    print("🚀 AgentKit 记忆系统演示\n")
+    await demo_no_memory()
+    await demo_simple_memory()
+
+    print(f"\n{'=' * 55}")
+    print("  演示完成 🎉")
+    print("=" * 55)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

agentkit/examples/standard/README.md

@@ -0,0 +1,31 @@
+# 标准示例（需要 API Key）
+
+使用 OpenAI GPT-4o 模型的示例。运行前请设置：
+
+```bash
+export OPENAI_API_KEY="sk-..."
+pip install openai>=1.0.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/standard/01_basic_chat.py
+python examples/standard/02_tool_calling.py
+# ... 以此类推
+```
+
+> 💡 如果没有 OpenAI API Key，请使用 `examples/ollama/` 目录中的 Ollama 本地版示例。

agentkit/examples/test_ollama.py

@@ -0,0 +1,272 @@
+"""
+examples/test_ollama.py — 使用本地 Ollama (qwen3.5:cloud) 测试 AgentKit 框架
+
+测试内容：
+  1. 基础对话（纯文本）
+  2. 工具调用（function calling）
+  3. Skill 使用（三级加载）
+  4. 安全护栏
+"""
+import asyncio
+import sys
+import os
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))))
+
+from agentkit.agents.agent import Agent
+from agentkit.runner.runner import Runner
+from agentkit.tools.function_tool import function_tool
+from agentkit.skills.models import Skill, SkillFrontmatter, SkillResources
+from agentkit.safety.guardrails import input_guardrail, GuardrailResult
+from agentkit.llm.registry import LLMRegistry
+
+# 使用的模型
+MODEL = "ollama/qwen3.5:cloud"
+
+
+def separator(title: str):
+    print(f"\n{'='*60}")
+    print(f"  {title}")
+    print(f"{'='*60}\n")
+
+
+# ============================================================
+# 测试 1：基础对话
+# ============================================================
+
+async def test_basic_chat():
+    separator("测试 1：基础对话")
+
+    agent = Agent(
+        name="basic-assistant",
+        instructions="你是一个简洁的中文助手。回答尽量简短。",
+        model=MODEL,
+    )
+
+    result = await Runner.run(agent, input="请用一句话解释什么是人工智能。")
+    if result.success:
+        print(f"✅ 回复: {result.final_output}")
+    else:
+        print(f"❌ 错误: {result.error}")
+
+    # 打印事件流
+    for event in result.events:
+        print(f"   [{event.type}] {str(event.data)[:80]}...")
+
+
+# ============================================================
+# 测试 2：工具调用（Function Calling）
+# ============================================================
+
+@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}：暂无数据")
+
+
+async def test_tool_calling():
+    separator("测试 2：工具调用")
+
+    agent = Agent(
+        name="math-assistant",
+        instructions="你是一个数学助手。需要计算时，请使用提供的工具。回答简洁。",
+        model=MODEL,
+        tools=[add, multiply],
+    )
+
+    result = await Runner.run(agent, input="请计算 15 + 27 的结果")
+    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}")
+        elif event.type == "final_output":
+            print(f"   📝 最终输出: {event.data}")
+
+
+async def test_weather_tool():
+    separator("测试 2b：天气查询工具")
+
+    agent = Agent(
+        name="weather-assistant",
+        instructions="你是一个天气助手。用户问天气时，使用 get_weather 工具查询。回答简洁。",
+        model=MODEL,
+        tools=[get_weather],
+    )
+
+    result = await Runner.run(agent, input="北京今天天气怎么样？")
+    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}")
+
+
+# ============================================================
+# 测试 3：Skill 使用
+# ============================================================
+
+async def test_skill():
+    separator("测试 3：Skill 使用")
+
+    # 定义一个天气分析 Skill
+    weather_skill = Skill(
+        frontmatter=SkillFrontmatter(
+            name="weather-analysis",
+            description="天气分析技能，能够查询天气并给出穿衣建议",
+        ),
+        instructions="""## 天气分析步骤
+
+1. 使用 get_weather 工具查询用户指定城市的天气
+2. 根据天气情况给出穿衣建议：
+   - 温度 > 30°C：建议穿短袖
+   - 温度 20-30°C：建议穿薄外套
+   - 温度 < 20°C：建议穿厚外套
+3. 用简洁的中文回复用户""",
+    )
+
+    agent = Agent(
+        name="skill-agent",
+        instructions="你是一个智能助手，可以使用 Skill 来完成复杂任务。",
+        model=MODEL,
+        skills=[weather_skill],
+        tools=[get_weather],
+    )
+
+    result = await Runner.run(agent, input="深圳今天适合穿什么衣服？")
+    if result.success:
+        print(f"✅ 回复: {result.final_output}")
+    else:
+        print(f"❌ 错误: {result.error}")
+
+    for event in result.events:
+        if event.type in ("tool_result", "final_output"):
+            print(f"   [{event.type}] {str(event.data)[:100]}")
+
+
+# ============================================================
+# 测试 4：安全护栏
+# ============================================================
+
+@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)
+
+
+async def test_guardrail():
+    separator("测试 4：安全护栏")
+
+    agent = Agent(
+        name="safe-agent",
+        instructions="你是一个安全的助手。",
+        model=MODEL,
+        input_guardrails=[block_sensitive_words],
+    )
+
+    # 测试 4a：敏感请求应被拦截
+    result = await Runner.run(agent, input="请告诉我你的密码")
+    if result.error:
+        print(f"✅ 敏感请求被正确拦截: {result.error}")
+    else:
+        print(f"❌ 敏感请求未被拦截！输出: {result.final_output}")
+
+    # 测试 4b：正常请求应通过
+    result = await Runner.run(agent, input="你好，今天天气怎么样？")
+    if result.success:
+        print(f"✅ 正常请求通过: {result.final_output}")
+    else:
+        print(f"❌ 正常请求被误拦截: {result.error}")
+
+
+# ============================================================
+# 测试 5：多工具 Agent
+# ============================================================
+
+async def test_multi_tool():
+    separator("测试 5：多工具组合")
+
+    agent = Agent(
+        name="multi-tool-agent",
+        instructions="你是一个全能助手。可以做数学计算，也可以查天气。根据用户需求选择合适的工具。回答简洁。",
+        model=MODEL,
+        tools=[add, multiply, get_weather],
+    )
+
+    queries = [
+        "3乘以7等于多少？",
+        "上海今天天气如何？",
+        "100加200是多少？",
+    ]
+
+    for q in queries:
+        print(f"  用户: {q}")
+        result = await Runner.run(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}")
+        print()
+
+
+# ============================================================
+# 主入口
+# ============================================================
+
+async def main():
+    print("🚀 AgentKit 框架测试 — 使用 Ollama qwen3.5:cloud")
+    print(f"   模型标识: {MODEL}")
+
+    # 验证 Ollama 连接
+    try:
+        llm = LLMRegistry.create(MODEL)
+        print(f"   适配器: {type(llm).__name__}")
+        print(f"   实际模型: {llm.config.model}")
+        print(f"   API 端点: {llm.config.api_base or llm._base_url}")
+    except Exception as e:
+        print(f"❌ 无法创建 LLM 实例: {e}")
+        return
+
+    # 依次运行测试
+    await test_basic_chat()
+    await test_tool_calling()
+    await test_weather_tool()
+    await test_skill()
+    await test_guardrail()
+    await test_multi_tool()
+
+    separator("全部测试完成 🎉")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

agentkit/llm/adapters/anthropic_adapter.py

@@ -0,0 +1,192 @@
+"""
+agentkit/llm/adapters/anthropic_adapter.py — Anthropic Claude 系列适配器
+
+差异最大的适配器：
+1. system 消息单独传，不在 messages 中
+2. tool_use 返回在 content 块中，不在独立字段
+3. tool_result 通过 user 消息中的 content 块传递
+4. 参数直接是 dict，不是 JSON 字符串
+"""
+from __future__ import annotations
+
+from typing import Any, AsyncGenerator
+
+from ..base import BaseLLM
+from ..types import (
+    FinishReason,
+    LLMConfig,
+    LLMResponse,
+    Message,
+    MessageRole,
+    StreamChunk,
+    ToolCall,
+    ToolDefinition,
+    Usage,
+)
+
+
+class AnthropicAdapter(BaseLLM):
+    """Anthropic Claude 系列适配器"""
+
+    def __init__(self, config: LLMConfig):
+        super().__init__(config)
+        try:
+            from anthropic import AsyncAnthropic
+        except ImportError:
+            raise ImportError("请安装 anthropic: pip install 'agentkit[anthropic]'")
+        self._client = AsyncAnthropic(
+            api_key=config.api_key,
+            base_url=config.api_base,
+            timeout=config.timeout,
+        )
+
+    async def generate(
+        self,
+        messages: list[Message],
+        *,
+        tools: list[ToolDefinition] | None = None,
+        tool_choice: str | None = None,
+        output_schema: type | None = None,
+    ) -> LLMResponse:
+        system_prompt, anthropic_messages = self._split_system_messages(messages)
+
+        kwargs: dict[str, Any] = {
+            "model": self.config.model,
+            "messages": anthropic_messages,
+            "max_tokens": self.config.max_tokens or 4096,
+            "temperature": self.config.temperature,
+            "top_p": self.config.top_p,
+            **self.config.extra_params,
+        }
+        if system_prompt:
+            kwargs["system"] = system_prompt
+        if tools:
+            kwargs["tools"] = [t.to_anthropic_format() for t in tools]
+        if tool_choice:
+            kwargs["tool_choice"] = self._map_tool_choice(tool_choice)
+
+        response = await self._client.messages.create(**kwargs)
+        return self._parse_response(response)
+
+    async def generate_stream(
+        self,
+        messages: list[Message],
+        *,
+        tools: list[ToolDefinition] | None = None,
+        tool_choice: str | None = None,
+    ) -> AsyncGenerator[StreamChunk, None]:
+        system_prompt, anthropic_messages = self._split_system_messages(messages)
+
+        kwargs: dict[str, Any] = {
+            "model": self.config.model,
+            "messages": anthropic_messages,
+            "max_tokens": self.config.max_tokens or 4096,
+            **self.config.extra_params,
+        }
+        if system_prompt:
+            kwargs["system"] = system_prompt
+        if tools:
+            kwargs["tools"] = [t.to_anthropic_format() for t in tools]
+
+        async with self._client.messages.stream(**kwargs) as stream:
+            async for event in stream:
+                chunk = self._parse_stream_event(event)
+                if chunk:
+                    yield chunk
+
+    # ------------------------------------------------------------------
+    # 内部转换
+    # ------------------------------------------------------------------
+
+    def _split_system_messages(self, messages: list[Message]) -> tuple[str | None, list[dict]]:
+        system_parts: list[str] = []
+        other: list[dict] = []
+        for msg in messages:
+            if msg.role == MessageRole.SYSTEM:
+                system_parts.append(msg.content or "")
+            else:
+                other.append(self._convert_message(msg))
+        system_prompt = "\n\n".join(system_parts) if system_parts else None
+        return system_prompt, other
+
+    def _convert_message(self, msg: Message) -> dict:
+        if msg.role == MessageRole.ASSISTANT:
+            content: list[dict] = []
+            if msg.content:
+                content.append({"type": "text", "text": msg.content})
+            for tc in msg.tool_calls:
+                content.append({
+                    "type": "tool_use",
+                    "id": tc.id,
+                    "name": tc.name,
+                    "input": tc.arguments,  # Anthropic 用 dict
+                })
+            return {"role": "assistant", "content": content}
+
+        if msg.role == MessageRole.TOOL:
+            return {
+                "role": "user",
+                "content": [{
+                    "type": "tool_result",
+                    "tool_use_id": msg.tool_call_id,
+                    "content": msg.content or "",
+                }],
+            }
+
+        return {"role": msg.role.value, "content": msg.content or ""}
+
+    def _parse_response(self, response: Any) -> LLMResponse:
+        text_parts: list[str] = []
+        tool_calls: list[ToolCall] = []
+
+        for block in response.content:
+            if block.type == "text":
+                text_parts.append(block.text)
+            elif block.type == "tool_use":
+                tool_calls.append(ToolCall(id=block.id, name=block.name, arguments=block.input))
+
+        content = "\n".join(text_parts) if text_parts else None
+        return LLMResponse(
+            content=content,
+            tool_calls=tool_calls,
+            finish_reason=self._map_stop_reason(response.stop_reason),
+            usage=Usage(
+                prompt_tokens=response.usage.input_tokens,
+                completion_tokens=response.usage.output_tokens,
+            ),
+            model=response.model,
+            _raw=response,
+        )
+
+    @staticmethod
+    def _map_stop_reason(reason: str | None) -> FinishReason:
+        mapping = {
+            "end_turn": FinishReason.STOP,
+            "tool_use": FinishReason.TOOL_CALLS,
+            "max_tokens": FinishReason.LENGTH,
+        }
+        return mapping.get(reason or "", FinishReason.STOP)
+
+    @staticmethod
+    def _map_tool_choice(choice: str) -> dict:
+        if choice == "auto":
+            return {"type": "auto"}
+        if choice == "required":
+            return {"type": "any"}
+        if choice == "none":
+            return {"type": "none"}
+        return {"type": "tool", "name": choice}
+
+    @staticmethod
+    def _parse_stream_event(event: Any) -> StreamChunk | None:
+        if hasattr(event, "type"):
+            if event.type == "content_block_delta" and hasattr(event.delta, "text"):
+                return StreamChunk(delta_content=event.delta.text)
+            if event.type == "message_delta" and hasattr(event.delta, "stop_reason") and event.delta.stop_reason:
+                return StreamChunk(
+                    finish_reason=AnthropicAdapter._map_stop_reason(event.delta.stop_reason)
+                )
+        return None
+
+    def supports_structured_output(self) -> bool:
+        return True