ni.agentkit 0.7.3__tar.gz → 0.8.0__tar.gz

{ni_agentkit-0.7.3 → ni_agentkit-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ni.agentkit
-Version: 0.7.3
+Version: 0.8.0
 Summary: A Python-native Agent framework with first-class Skill support and multi-LLM adapter
 Author-email: Krix Tam <krix.tam@qq.com>
 License: MIT
@@ -155,8 +155,8 @@ python "$(python -c "import agentkit, os; print(os.path.join(agentkit.get_exampl
 
 ```bash
 dist/
-├── ni_agentkit-0.7.3-py3-none-any.whl   # pip install 用这个
-└── ni_agentkit-0.7.3.tar.gz             # 源码分发
+├── ni_agentkit-0.7.4-py3-none-any.whl   # pip install 用这个
+└── ni_agentkit-0.7.4.tar.gz             # 源码分发
 ```
 
 ## 📄 License

{ni_agentkit-0.7.3 → ni_agentkit-0.8.0}/README.md

@@ -112,8 +112,8 @@ python "$(python -c "import agentkit, os; print(os.path.join(agentkit.get_exampl
 
 ```bash
 dist/
-├── ni_agentkit-0.7.3-py3-none-any.whl   # pip install 用这个
-└── ni_agentkit-0.7.3.tar.gz             # 源码分发
+├── ni_agentkit-0.7.4-py3-none-any.whl   # pip install 用这个
+└── ni_agentkit-0.7.4.tar.gz             # 源码分发
 ```
 
 ## 📄 License

{ni_agentkit-0.7.3 → ni_agentkit-0.8.0}/__init__.py

@@ -33,7 +33,7 @@ from .tools.function_tool import FunctionTool, function_tool
 from .tools.structured_data import ResultFormatter, StructuredDataTool
 from .tools.sqlite_tool import SQLiteTool, SQLiteResultFormatter
 
-__version__ = "0.7.2"
+__version__ = "0.8.0"
 
 
 def get_docs_dir() -> str:

{ni_agentkit-0.7.3 → ni_agentkit-0.8.0}/agents/agent.py

@@ -153,8 +153,7 @@ class Agent(BaseAgent):
 
         async def _invoke(**kwargs: Any) -> Any:
             input_text = kwargs.get("input", "")
-            from ..runner.runner import Runner
-            result = await Runner.run(agent_ref, input=str(input_text))
+            result = await agent_ref.ainvoke(input=str(input_text))
             return result.final_output
 
         return FunctionTool(
@@ -293,11 +292,12 @@ class Agent(BaseAgent):
 
                 # 5. 调用 LLM（支持缓存）
                 cached = False
+                cache_key: str | None = None
 
                 # 检查缓存
                 if self.enable_cache:
                     cache = self._get_cache()
-                    cached_response = cache.get(messages, tool_defs if tool_defs else None)
+                    cache_key, cached_response = cache.get_with_key(messages, tool_defs if tool_defs else None)
                     if cached_response is not None:
                         response = cached_response
                         cached = True
@@ -318,7 +318,10 @@ class Agent(BaseAgent):
 
                     # 写入缓存
                     if self.enable_cache:
-                        cache.put(messages, tool_defs if tool_defs else None, response)
+                        if cache_key is not None:
+                            cache.put_with_key(cache_key, response)
+                        else:
+                            cache.put(messages, tool_defs if tool_defs else None, response)
 
                 cache_key_ms = 0.0
                 if self.enable_cache:

{ni_agentkit-0.7.3 → ni_agentkit-0.8.0}/agents/base_agent.py

@@ -96,6 +96,122 @@ class BaseAgent(BaseModel):
                     elif result is not None:
                         yield Event(agent=self.name, type="callback", data={"result": result, "duration": duration})
 
+    async def stream(
+        self,
+        input: str,
+        context: Any = None,
+        user_id: str | None = None,
+        session_id: str | None = None,
+        max_turns: int = 10,
+    ) -> AsyncGenerator[Event, None]:
+        import uuid
+
+        from ..runner.context import RunContext
+        from ..runner.events import EventType
+        from ..runner.runner import Runner
+
+        ctx = RunContext(
+            input=input,
+            shared_context=context,
+            user_id=user_id,
+            session_id=session_id or str(uuid.uuid4()),
+        )
+        current_agent: BaseAgent = self
+        handoff_agent_cache: dict[str, BaseAgent | None] = {}
+
+        for _ in range(max_turns):
+            input_guardrails = getattr(current_agent, "input_guardrails", None)
+            if input_guardrails:
+                for guardrail in input_guardrails:
+                    result = await guardrail.check(ctx)
+                    if result.triggered:
+                        yield Event(agent=current_agent.name, type=EventType.ERROR, data=f"输入被安全护栏拦截: {result.reason}")
+                        return
+
+            async for event in current_agent.run(ctx):
+                yield event
+
+                if event.type == EventType.FINAL_OUTPUT:
+                    output_guardrails = getattr(current_agent, "output_guardrails", None)
+                    if output_guardrails:
+                        for guardrail in output_guardrails:
+                            result = await guardrail.check(ctx, event.data)
+                            if result.triggered:
+                                yield Event(agent=current_agent.name, type=EventType.ERROR, data=f"输出被安全护栏拦截: {result.reason}")
+                                return
+                    return
+
+                if event.type == EventType.HANDOFF:
+                    target_name = event.data.get("target", "") if isinstance(event.data, dict) else ""
+                    if target_name in handoff_agent_cache:
+                        new_agent = handoff_agent_cache[target_name]
+                    else:
+                        new_agent = Runner._find_agent(self, target_name)
+                        handoff_agent_cache[target_name] = new_agent
+
+                    if new_agent:
+                        current_agent = new_agent
+                        break
+
+                    yield Event(agent=current_agent.name, type=EventType.ERROR, data=f"Handoff 目标 '{target_name}' 未找到")
+                    return
+
+                if event.type == EventType.ERROR:
+                    return
+
+        yield Event(agent=current_agent.name, type=EventType.ERROR, data=f"超过最大轮次 {max_turns}")
+
+    async def ainvoke(
+        self,
+        input: str,
+        context: Any = None,
+        user_id: str | None = None,
+        session_id: str | None = None,
+        max_turns: int = 10,
+    ) -> Any:
+        from ..runner.events import EventType, RunResult
+
+        events: list[Event] = []
+        final_output = None
+        error = None
+        last_agent = self.name
+
+        async for event in self.stream(
+            input=input,
+            context=context,
+            user_id=user_id,
+            session_id=session_id,
+            max_turns=max_turns,
+        ):
+            events.append(event)
+            last_agent = event.agent
+            if event.type == EventType.FINAL_OUTPUT:
+                final_output = event.data
+            elif event.type == EventType.ERROR:
+                error = str(event.data)
+
+        return RunResult(final_output=final_output, error=error, events=events, last_agent=last_agent)
+
+    def invoke(
+        self,
+        input: str,
+        context: Any = None,
+        user_id: str | None = None,
+        session_id: str | None = None,
+        max_turns: int = 10,
+    ) -> Any:
+        import asyncio
+
+        return asyncio.run(
+            self.ainvoke(
+                input=input,
+                context=context,
+                user_id=user_id,
+                session_id=session_id,
+                max_turns=max_turns,
+            )
+        )
+
     @abstractmethod
     async def _run_impl(self, ctx: "RunContext") -> AsyncGenerator[Event, None]:
         raise NotImplementedError

{ni_agentkit-0.7.3 → ni_agentkit-0.8.0}/docs/Architecture.md

@@ -91,7 +91,14 @@ Application → Agent → Skill → Tool → Foundation
 
 ## 核心执行流程
 
-当你调用 `Runner.run(agent, input="...")` 时，框架内部的完整流程如下：
+虽然 Agent 现在具备了独立执行的能力（`agent.invoke` / `agent.stream` 等），但 `Runner` 依然作为底层编排引擎存在，提供复杂场景下的能力：
+
+- 统一的事件与 Hooks 调度
+- 多 Agent `Handoff` 接力
+- 异常兜底与错误报告
+- Human-in-the-loop 挂起（Checkpoint）与恢复（Resume）
+
+当你调用 `agent.invoke(input="...")` 时，它内部实际上也是通过委托 `Runner` 来完成的完整流程：
 
 ```
 用户输入
@@ -99,7 +106,7 @@ Application → Agent → Skill → Tool → Foundation
   ▼
 Runner.run()
   │
-  ├─ 创建 RunContext
+  ├─ 初始化 RunContext
   │
   ├─ 检查输入护栏（InputGuardrail）
   │    └─ 如果触发 → 返回错误
@@ -225,18 +232,20 @@ Agent.run()                ← 异步生成器（async generator，yield Event
 
 ### 三种运行方式
 
+AgentKit 提供了三种执行方式，你可以直接在 Agent 对象上调用：
+
 | 方式 | API | 适用场景 |
 |------|-----|---------|
-| **同步** | `Runner.run_sync(agent, input=...)` | 脚本、快速测试、简单场景 |
-| **异步** | `await Runner.run(agent, input=...)` | Web 服务、并发任务、生产环境 |
-| **流式** | `async for event in Runner.run_streamed(agent, input=...)` | 实时展示进度、逐 token 输出 |
+| **同步** | `agent.invoke(input=...)` | 脚本、快速测试、简单场景 |
+| **异步** | `await agent.ainvoke(input=...)` | Web 服务、并发任务、生产环境 |
+| **流式** | `async for event in agent.stream(input=...)` | 实时展示进度、逐 token 输出 |
 
 ### 为什么选择异步优先？
 
 1. **LLM 调用是 I/O 密集型**：一次 LLM 调用可能耗时几秒到几十秒，异步可以在等待期间处理其他请求
 2. **并行 Agent 需要并发**：`ParallelAgent` 并行执行多个子 Agent，必须用 `asyncio.gather`
 3. **工具可能涉及网络**：调用外部 API、数据库查询等都是异步操作
-4. **`run_sync()` 兜底**：不熟悉异步的用户可以直接用同步入口，零学习成本
+4. **`invoke()` 兜底**：不熟悉异步的用户可以直接用同步入口，零学习成本
 
 ### 流式运行示例
 
@@ -244,7 +253,7 @@ Agent.run()                ← 异步生成器（async generator，yield Event
 from agentkit.runner.events import EventType
 
 async def main():
-    async for event in Runner.run_streamed(agent, input="你好"):
+    async for event in agent.stream(input="你好"):
         # 推荐使用 EventType 枚举匹配标准事件类型
         if event.type == EventType.LLM_RESPONSE:
             print("LLM 思考中...")
@@ -417,8 +426,8 @@ AgentKit 的记忆系统遵循**可选、可插拔、自动化**三个原则：
 
 ```python
 # 不同用户的记忆互不干扰
-await Runner.run(agent, input="我喜欢咖啡", user_id="user_A")
-await Runner.run(agent, input="我喜欢茶", user_id="user_B")
+await agent.ainvoke(input="我喜欢咖啡", user_id="user_A")
+await agent.ainvoke(input="我喜欢茶", user_id="user_B")
 ```
 
 ---
@@ -471,6 +480,7 @@ agent.clear_cache()
 > - 缓存仅在单 Agent 实例内有效，重新创建 Agent 会清空缓存
 > - 默认最大 128 条缓存，LRU 淘汰最久未使用的条目
 > - 缓存实现内置 key 生成统计：`key_gen_calls / key_gen_total_ms / key_gen_last_ms / key_gen_avg_ms`
+> - 缓存实现对同一轮的缓存 key 计算做了复用（避免 miss 场景下重复算 key）
 
 ### 3. 记忆异步写入