ni.agentkit 0.7.4__tar.gz → 0.8.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ni.agentkit
-Version: 0.7.4
+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

{ni_agentkit-0.7.4 → 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.4 → 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(

{ni_agentkit-0.7.4 → 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.4 → 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")
 ```
 
 ---