ni.agentkit 0.6.0__tar.gz → 0.6.2__tar.gz

{ni_agentkit-0.6.0 → ni_agentkit-0.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ni.agentkit
-Version: 0.6.0
+Version: 0.6.2
 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
@@ -153,8 +153,8 @@ python "$(python -c "import agentkit, os; print(os.path.join(agentkit.get_exampl
 
 ```bash
 dist/
-├── ni_agentkit-0.6.0-py3-none-any.whl   # pip install 用这个
-└── ni_agentkit-0.6.0.tar.gz             # 源码分发
+├── ni_agentkit-0.6.2-py3-none-any.whl   # pip install 用这个
+└── ni_agentkit-0.6.2.tar.gz             # 源码分发
 ```
 
 ## 📄 License

{ni_agentkit-0.6.0 → ni_agentkit-0.6.2}/README.md

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

{ni_agentkit-0.6.0 → ni_agentkit-0.6.2}/__init__.py

@@ -31,7 +31,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.6.0"
+__version__ = "0.6.2"
 
 
 def get_docs_dir() -> str:

{ni_agentkit-0.6.0 → ni_agentkit-0.6.2}/agents/agent.py

@@ -190,6 +190,7 @@ class Agent(BaseAgent):
         llm = self._resolve_model()
         memory_injection = ""
         skill_prompt_injection = ""
+        runtime_skill_toolset: SkillToolset | None = None
         history_messages: list[Message] = []
         parsed_history_len = 0
         last_tool_signature: tuple[tuple[str, int], ...] = tuple()
@@ -206,8 +207,8 @@ class Agent(BaseAgent):
                 logger.warning("检索记忆失败: %s", e)
 
         if self.skills:
-            skill_toolset = SkillToolset(skills=self.skills)
-            skill_prompt_injection = "\n\n" + skill_toolset.get_system_prompt_injection()
+            runtime_skill_toolset = SkillToolset(skills=self.skills)
+            skill_prompt_injection = "\n\n" + runtime_skill_toolset.get_system_prompt_injection()
 
         try:
             while round_count < self.max_tool_rounds:
@@ -219,7 +220,32 @@ class Agent(BaseAgent):
                 instructions += skill_prompt_injection
 
                 # 2. 获取工具
-                tools = await self.get_all_tools(ctx)
+                tools: list[BaseTool] = []
+                for tool_union in self.tools:
+                    if isinstance(tool_union, BaseTool):
+                        tools.append(tool_union)
+                    elif isinstance(tool_union, BaseToolset):
+                        tools.extend(await tool_union.get_tools(ctx))
+                    elif callable(tool_union):
+                        fn_key = id(tool_union)
+                        cached_tool = self._callable_tool_cache.get(fn_key)
+                        if cached_tool is None:
+                            cached_tool = FunctionTool.from_function(tool_union)
+                            self._callable_tool_cache[fn_key] = cached_tool
+                        tools.append(cached_tool)
+
+                if runtime_skill_toolset is not None:
+                    runtime_skill_toolset.set_additional_tools(tools.copy())
+                    tools.extend(await runtime_skill_toolset.get_tools(ctx))
+
+                for target in self.handoffs:
+                    if isinstance(target, BaseAgent):
+                        target_key = id(target)
+                        cached_handoff_tool = self._handoff_tool_cache.get(target_key)
+                        if cached_handoff_tool is None:
+                            cached_handoff_tool = self._create_handoff_tool(target)
+                            self._handoff_tool_cache[target_key] = cached_handoff_tool
+                        tools.append(cached_handoff_tool)
                 tool_signature = tuple((tool.name, id(tool)) for tool in tools)
                 tool_defs_start = time.perf_counter()
                 if tool_signature != last_tool_signature:
@@ -388,13 +414,24 @@ class Agent(BaseAgent):
                         try:
                             result = await tool.execute(ctx, tool_call.arguments)
                         except HumanInputRequested as e:
-                            # 触发挂起事件，并记录挂起的工具信息
-                            ctx.state["__suspended_tool_call_id__"] = tool_call.id
-                            ctx.state["__suspended_tool_name__"] = tool_call.name
+                            suspension = ctx.register_suspension(
+                                tool_call_id=tool_call.id,
+                                tool_name=tool_call.name,
+                                prompt=e.prompt,
+                                form_schema=e.kwargs.get("form_schema"),
+                                resume_strategy=e.kwargs.get("resume_strategy", "as_tool_result"),
+                            )
                             yield Event(
                                 agent=self.name, 
                                 type=EventType.SUSPEND_REQUESTED, 
-                                data={"prompt": e.prompt, "tool": tool_call.name, "tool_call_id": tool_call.id, **e.kwargs}
+                                data={
+                                    "suspension_id": suspension.suspension_id,
+                                    "prompt": e.prompt,
+                                    "tool": tool_call.name,
+                                    "tool_call_id": tool_call.id,
+                                    "resume_strategy": suspension.resume_strategy,
+                                    **e.kwargs,
+                                },
                             )
                             return
                         except Exception as e:

{ni_agentkit-0.6.0 → ni_agentkit-0.6.2}/agents/base_agent.py

@@ -5,7 +5,9 @@ agentkit/agents/base_agent.py — 所有 Agent 的基类
 """
 from __future__ import annotations
 
+import asyncio
 from abc import abstractmethod
+from contextlib import aclosing
 from typing import TYPE_CHECKING, Any, AsyncGenerator, Callable, Optional
 
 from pydantic import BaseModel, ConfigDict, Field
@@ -62,30 +64,37 @@ class BaseAgent(BaseModel):
 
     async def run(self, ctx: "RunContext") -> AsyncGenerator[Event, None]:
         """运行入口 — 子类不可覆盖"""
-        # 1. before callback
-        if self.before_agent_callback:
-            result, duration, err = await self._run_hook(self.before_agent_callback, "before_agent_callback", ctx)
-            if err:
-                yield Event(agent=self.name, type="error", data={"hook": "before_agent", "error": str(err), "duration": duration})
-                if self.fail_fast_on_hook_error:
+        emit_after_events = True
+        try:
+            # 1. before callback
+            if self.before_agent_callback:
+                result, duration, err = await self._run_hook(self.before_agent_callback, "before_agent_callback", ctx)
+                if err:
+                    yield Event(agent=self.name, type="error", data={"hook": "before_agent", "error": str(err), "duration": duration})
+                    if self.fail_fast_on_hook_error:
+                        return
+                elif result is not None:
+                    yield Event(agent=self.name, type="callback", data={"result": result, "duration": duration})
                     return
-            elif result is not None:
-                yield Event(agent=self.name, type="callback", data={"result": result, "duration": duration})
-                return
-
-        # 2. 核心逻辑（子类实现）
-        async for event in self._run_impl(ctx):
-            yield event
 
-        # 3. after callback
-        if self.after_agent_callback:
-            result, duration, err = await self._run_hook(self.after_agent_callback, "after_agent_callback", ctx)
-            if err:
-                yield Event(agent=self.name, type="error", data={"hook": "after_agent", "error": str(err), "duration": duration})
-                if self.fail_fast_on_hook_error:
-                    return
-            elif result is not None:
-                yield Event(agent=self.name, type="callback", data={"result": result, "duration": duration})
+            # 2. 核心逻辑（子类实现）
+            impl_stream = self._run_impl(ctx)
+            async with aclosing(impl_stream):
+                async for event in impl_stream:
+                    yield event
+        except (GeneratorExit, asyncio.CancelledError):
+            # 外部提前中断时不再尝试向外 yield 事件，但必须执行 after 回调逻辑
+            emit_after_events = False
+            raise
+        finally:
+            # 3. after callback（保证执行）
+            if self.after_agent_callback:
+                result, duration, err = await self._run_hook(self.after_agent_callback, "after_agent_callback", ctx)
+                if emit_after_events:
+                    if err:
+                        yield Event(agent=self.name, type="error", data={"hook": "after_agent", "error": str(err), "duration": duration})
+                    elif result is not None:
+                        yield Event(agent=self.name, type="callback", data={"result": result, "duration": duration})
 
     @abstractmethod
     async def _run_impl(self, ctx: "RunContext") -> AsyncGenerator[Event, None]:

{ni_agentkit-0.6.0 → ni_agentkit-0.6.2}/agents/orchestrators.py

@@ -8,6 +8,7 @@ agentkit/agents/loop_agent.py      — 循环执行子 Agent
 from __future__ import annotations
 
 import asyncio
+from contextlib import aclosing
 from typing import TYPE_CHECKING, Any, AsyncGenerator, Callable
 
 from ..runner.events import Event
@@ -22,10 +23,11 @@ class SequentialAgent(BaseAgent):
 
     async def _run_impl(self, ctx: "RunContext") -> AsyncGenerator[Event, None]:
         for sub in self.sub_agents:
-            async for event in sub.run(ctx):
-                yield event
-                if event.type == "escalate":
-                    return
+            async with aclosing(sub.run(ctx)) as stream:
+                async for event in stream:
+                    yield event
+                    if event.type == "escalate":
+                        return
 
 
 class ParallelAgent(BaseAgent):
@@ -60,12 +62,13 @@ class ParallelAgent(BaseAgent):
         async def run_branch(agent: BaseAgent, branch_ctx: "RunContext") -> None:
             branch_status[agent.name] = "running"
             try:
-                async for event in agent.run(branch_ctx):
-                    all_events[agent.name].append(event)
-                    await queue.put((agent.name, event))
-                    if event.type == "escalate":
-                        branch_status[agent.name] = "escalated"
-                        return
+                async with aclosing(agent.run(branch_ctx)) as stream:
+                    async for event in stream:
+                        all_events[agent.name].append(event)
+                        await queue.put((agent.name, event))
+                        if event.type == "escalate":
+                            branch_status[agent.name] = "escalated"
+                            return
                 branch_status[agent.name] = "completed"
             except asyncio.CancelledError:
                 branch_status[agent.name] = "cancelled"
@@ -112,10 +115,11 @@ class LoopAgent(BaseAgent):
     async def _run_impl(self, ctx: "RunContext") -> AsyncGenerator[Event, None]:
         for iteration in range(self.max_iterations):
             for sub in self.sub_agents:
-                async for event in sub.run(ctx):
-                    yield event
-                    if event.type == "escalate":
-                        return
+                async with aclosing(sub.run(ctx)) as stream:
+                    async for event in stream:
+                        yield event
+                        if event.type == "escalate":
+                            return
 
             if self.loop_condition is not None:
                 # Provide ctx and current iteration index (0-based) as state

{ni_agentkit-0.6.0 → ni_agentkit-0.6.2}/docs/Architecture.md

@@ -157,6 +157,8 @@ Runner.run()
 
 **9 个回调点**标记为 ❶ ~ ❾，覆盖了 Agent、Model、Tool、Handoff 四个层面的前后拦截及错误处理（含 `on_error_callback`）。
 
+补充说明：`after_agent_callback` 通过 `finally` 语义保证执行。即使上游编排发生提前 `return`（如 `escalate`）或外部关闭流式生成器（`aclose`），也会触发该回调；但在生成器关闭路径下，不保证回调事件继续对外 `yield`。
+
 ---
 
 ## Human-in-the-loop (HITL) 与状态管理
@@ -170,18 +172,19 @@ AgentKit 原生支持在任务执行过程中安全地挂起（Suspend）并持
       │
       ├─ 遇到需要人工确认的工具 (抛出 HumanInputRequested)
       │
-      ├─ Runner 捕获异常，触发 suspend_requested 事件
+      ├─ Agent 捕获异常，注册 SuspensionRecord 并触发 suspend_requested 事件（含 suspension_id）
       │
-      ├─ ContextStore 保存当前 RunContext (包含会话状态、记忆、执行分支等)
+      ├─ ContextStore 保存当前 RunContext (包含会话状态、执行分支、suspensions、resume_idempotency 等)
       │
       ▼
 [进程可完全退出 / 释放资源]
       │
       ├─ 外部人工提供输入
       │
-      ├─ Runner.resume(session_id, user_input, context_store)
+      ├─ Runner.resume(session_id, user_input, context_store, suspension_id=None, idempotency_key=None)
       │
-      ├─ ContextStore 恢复 RunContext，将人工输入作为挂起工具的结果
+      ├─ ContextStore 恢复 RunContext，按 suspension_id（或最新 pending）定位挂起点
+      │    └─ resume_strategy=as_tool_result 时将 user_input 注入对应 tool_call 结果
       │
       ▼
 [Agent 恢复运行，继续未完成的对话与工具链]
@@ -540,7 +543,7 @@ agent = Agent(memory=my_memory, memory_async_write=False, ...)
 
 #### 生命周期 Hooks / Callbacks
 AgentKit 提供细粒度的执行拦截点，支持同步/异步回调，并允许请求与响应改写：
-- **`before_agent_callback` / `after_agent_callback`**: 拦截整个 Agent 会话。
+- **`before_agent_callback` / `after_agent_callback`**: 拦截整个 Agent 会话。`after_agent_callback` 在提前中断/外部关闭流的场景下也会执行（收尾保证），但关闭路径不保证继续外发 callback 事件。
 - **`before_model_callback` / `after_model_callback`**: 在 LLM 调用前后拦截，允许改写 Prompt 和模型输出。
 - **`before_tool_callback` / `after_tool_callback`**: 在工具执行前后拦截，允许改写执行结果。
 - **`before_handoff_callback` / `after_handoff_callback`**: 在触发 Handoff 转移前拦截，可动态修改目标 Agent。

{ni_agentkit-0.6.0 → ni_agentkit-0.6.2}/docs/README.md

@@ -3,7 +3,7 @@
 > Python 原生的 Agent 开发框架，内置一等公民级别的 Skill 支持和自研多模型适配层。
 
 [![Python](https://img.shields.io/badge/Python-≥3.11-blue.svg)](https://python.org)
-[![Version](https://img.shields.io/badge/Version-0.6.0-green.svg)]()
+[![Version](https://img.shields.io/badge/Version-0.6.2-green.svg)]()
 [![License](https://img.shields.io/badge/License-MIT-yellow.svg)]()
 
 ---

{ni_agentkit-0.6.0 → ni_agentkit-0.6.2}/docs/Reference.md

@@ -72,7 +72,7 @@ from agentkit import Agent
 | `memory_async_write` | `bool` | `True` | 记忆写入模式。`True`=fire-and-forget 异步写入（不阻塞返回）；`False`=同步等待写入完成（多轮串行对话推荐） |
 | `model_cosplay_enabled` | `bool` | `False` | 是否开启 ModelCosplay。关闭时如果类已预设 `model`，实例化时不允许覆盖；开启后允许实例化和运行时改写模型 |
 | `before_agent_callback` | `Callable \| None` | `None` | Agent 运行前回调 |
-| `after_agent_callback` | `Callable \| None` | `None` | Agent 运行后回调 |
+| `after_agent_callback` | `Callable \| None` | `None` | Agent 运行后回调。通过 `finally` 语义保证执行；即使上游提前中断或外部关闭流（`aclose`）也会触发，但关闭路径不保证继续外发 callback 事件 |
 | `before_model_callback` | `Callable \| None` | `None` | LLM 调用前回调（可拦截/改写） |
 | `after_model_callback` | `Callable \| None` | `None` | LLM 调用后回调（可改写响应） |
 | `before_tool_callback` | `Callable \| None` | `None` | 工具调用前回调（可拦截执行） |
@@ -116,7 +116,7 @@ agent = Agent(
 | `description` | `str` | 描述 |
 | `sub_agents` | `list[BaseAgent]` | 子 Agent（自动建立父子关系） |
 | `before_agent_callback` | `Callable \| None` | 运行前回调 |
-| `after_agent_callback` | `Callable \| None` | 运行后回调 |
+| `after_agent_callback` | `Callable \| None` | 运行后回调。支持提前中断/流关闭场景下的收尾触发（关闭路径不保证事件外发） |
 | `model_cosplay_enabled` | `bool` | 是否开启 ModelCosplay（默认 `False`） |
 
 **子类化**：
@@ -181,7 +181,7 @@ from agentkit import Runner
 | `run_sync` | `(agent, **kwargs) -> RunResult` | 同步运行（内部调用 asyncio.run） |
 | `run_streamed` | `async (agent, *, input, user_id=None, session_id=None, **kwargs) -> AsyncGenerator[Event, None]` | 流式运行，实时产出 Event |
 | `run_with_checkpoint` | `async (agent, *, input, session_id, context_store, ..., max_turns=10) -> AsyncGenerator[Event, None]` | 流式运行（支持挂起），遇到 `suspend_requested` 时自动保存上下文与执行指针（turn/current_agent/agent_path），并追加发出 `suspended` 事件 |
-| `resume` | `async (agent, *, session_id, user_input, context_store, ...) -> AsyncGenerator[Event, None]` | 恢复被挂起会话；优先按 checkpoint 的 `agent_path` 定位恢复节点，再将 `user_input` 作为挂起工具结果继续流转 |
+| `resume` | `async (agent, *, session_id, user_input, context_store, ..., suspension_id=None, idempotency_key=None) -> AsyncGenerator[Event, None]` | 恢复被挂起会话；优先按 checkpoint 的 `agent_path` 定位恢复节点，再按 `suspension_id`（或最新 pending）恢复挂起点；支持 `idempotency_key` 幂等 |
 
 **参数**：
 
@@ -211,7 +211,9 @@ from agentkit.runner.context import RunContext
 | `user_id` | `str \| None` | 用户 ID（用于多租户和记忆隔离） |
 | `session_id` | `str` | 会话 ID，默认随机生成（用于断点续跑和上下文隔离） |
 | `messages` | `list[dict]` | 当前完整的对话消息链 |
-| `state` | `dict` | 运行期间的内部状态，挂起工具等信息暂存于此 |
+| `state` | `dict` | 运行期间的内部状态（不再承载挂起协议字段） |
+| `suspensions` | `list[SuspensionRecord]` | 框架托管的挂起记录列表（含 `suspension_id/tool_call_id/tool_name/prompt/form_schema/resume_strategy`） |
+| `resume_idempotency` | `dict[str, dict]` | resume 幂等记录，避免重复提交人工输入 |
 
 **方法**：
 

{ni_agentkit-0.6.0 → ni_agentkit-0.6.2}/docs/TestReport.md

@@ -1,9 +1,9 @@
 # AgentKit 示例测试报告
 
-> 测试时间：2026-04-19  
-> 测试环境：macOS (Apple Silicon)  
+> 测试时间：`2026-04-22`  
+> 测试环境：`macOS (Apple Silicon)`  
 > 模型：Ollama `qwen3.5:cloud`  
-> AgentKit 版本：v0.6.0  
+> AgentKit 版本：v0.6.2  
 > Thinking 模式：开启（默认）  
 > LLM 调用模式：非流式（默认）  
 > 缓存：开启（默认）  
@@ -15,31 +15,31 @@
 
 | # | 示例 | 文件 | 耗时 | 状态 | 说明 |
 |---|------|------|-----:|:----:|------|
-| 1 | 基础对话 | `01_basic_chat.py` | 30.52s | ✅ | 运行通过 |
-| 2 | 工具调用 | `02_tool_calling.py` | 42.10s | ✅ | 运行通过 |
-| 3 | Skill 使用 | `03_skill_usage.py` | 200.30s | ✅ | 运行通过 |
-| 4 | 多 Agent 协作 | `04_multi_agent.py` | 110.67s | ✅ | 运行通过 |
-| 5 | 安全护栏 | `05_guardrail.py` | 7.19s | ✅ | 运行通过 |
-| 6 | 编排 Agent | `06_orchestration.py` | 54.30s | ✅ | 运行通过 |
-| 7 | 同步/异步/流式 | `07_sync_async_stream.py` | 32.54s | ✅ | 运行通过 |
-| 8 | 记忆系统 | `08_memory.py` | 778.88s | ✅ | 运行通过（本轮最慢） |
-| 9A | 结构化数据（SQL） | `09a_structured_data_sql.py` | 148.74s | ✅ | 运行通过 |
-| 9B | 结构化数据（图） | `09b_structured_data_graph.py` | 31.25s | ✅ | 运行通过 |
-| 10 | Skill 生命周期 | `10_skill_lifecycle.py` | 72.92s | ✅ | 运行通过 |
-| 11 | 编排增强 | `11_orchestration_enhancement.py` | 139.09s | ✅ | 运行通过 |
-| 12 | 序列化协议 | `12_run_context_serialization.py` | 0.33s | ✅ | 运行通过 |
-| 13 | Human in the Loop | `13_human_in_the_loop.py` | 9.75s | ✅ | 运行通过 |
-| 14 | Event 标准化 | `14_event_standardization.py` | 11.32s | ✅ | 运行通过 |
-| 15 | 多租户隔离 | `15_multi_tenant_isolation.py` | 0.39s | ✅ | 运行通过 |
-| 16 | 生命周期 Hooks | `16_lifecycle_hooks.py` | 0.29s | ✅ | 运行通过 |
-| 17 | Checkpoint + Handoff + Resume | `17_checkpoint_handoff_resume.py` | 0.30s | ✅ | 运行通过 |
-| 18 | ModelCosplay | `18_model_cosplay.py` | 0.21s | ✅ | 运行通过 |
-| | **合计** | | **1671.09s** | **19/19** | |
+| 1 | 基础对话 | `01_basic_chat.py` | 124.36s | ✅ | 运行通过 |
+| 2 | 工具调用 | `02_tool_calling.py` | 30.32s | ✅ | 运行通过 |
+| 3 | Skill 使用 | `03_skill_usage.py` | 258.00s | ✅ | 运行通过（本轮最慢） |
+| 4 | 多 Agent 协作 | `04_multi_agent.py` | 183.07s | ✅ | 运行通过 |
+| 5 | 安全护栏 | `05_guardrail.py` | 21.82s | ✅ | 运行通过 |
+| 6 | 编排 Agent | `06_orchestration.py` | 156.18s | ✅ | 运行通过 |
+| 7 | 同步/异步/流式 | `07_sync_async_stream.py` | 17.57s | ✅ | 运行通过 |
+| 8 | 记忆系统 | `08_memory.py` | 148.30s | ✅ | 运行通过 |
+| 9A | 结构化数据（SQL） | `09a_structured_data_sql.py` | 3.99s | ✅ | 运行通过 |
+| 9B | 结构化数据（图） | `09b_structured_data_graph.py` | 8.48s | ✅ | 运行通过 |
+| 10 | Skill 生命周期 | `10_skill_lifecycle.py` | 1.77s | ✅ | 运行通过 |
+| 11 | 编排增强 | `11_orchestration_enhancement.py` | 86.13s | ✅ | 运行通过 |
+| 12 | 序列化协议 | `12_run_context_serialization.py` | 0.31s | ✅ | 运行通过 |
+| 13 | Human in the Loop | `13_human_in_the_loop.py` | 6.21s | ✅ | 运行通过 |
+| 14 | Event 标准化 | `14_event_standardization.py` | 50.10s | ✅ | 运行通过 |
+| 15 | 多租户隔离 | `15_multi_tenant_isolation.py` | 0.44s | ✅ | 运行通过 |
+| 16 | 生命周期 Hooks | `16_lifecycle_hooks.py` | 0.27s | ✅ | 运行通过 |
+| 17 | Checkpoint + Handoff + Resume | `17_checkpoint_handoff_resume.py` | 0.17s | ✅ | 运行通过（本轮最快） |
+| 18 | ModelCosplay | `18_model_cosplay.py` | 0.18s | ✅ | 运行通过 |
+| | **合计** | | **1097.67s** | **19/19** | |
 
 ## 耗时分析
 
-- **最快示例**：18 ModelCosplay（0.21s）
-- **最慢示例**：8 记忆系统（778.88s）
+- **最快示例**：17 Checkpoint + Handoff + Resume（0.17s）
+- **最慢示例**：3 Skill 使用（258.00s）
 - **耗时集中区间**：涉及多轮推理/记忆写入/编排循环的示例耗时显著更高
 
 ## 各示例 LLM 调用次数估算

{ni_agentkit-0.6.0 → ni_agentkit-0.6.2}/examples/ollama/17_checkpoint_handoff_resume.py

@@ -22,12 +22,20 @@ class ReviewAgent(BaseAgent):
     async def _run_impl(self, ctx: RunContext) -> AsyncGenerator[Event, None]:
         if not ctx.state.get("review_suspended_once"):
             ctx.state["review_suspended_once"] = True
-            ctx.state["__suspended_tool_call_id__"] = "manual-review-1"
-            ctx.state["__suspended_tool_name__"] = "manual_review"
+            suspension = ctx.register_suspension(
+                tool_call_id="manual-review-1",
+                tool_name="manual_review",
+                prompt="请审批该任务（approve/reject）",
+            )
             yield Event(
                 agent=self.name,
                 type=EventType.SUSPEND_REQUESTED,
-                data={"prompt": "请审批该任务（approve/reject）", "tool": "manual_review", "tool_call_id": "manual-review-1"},
+                data={
+                    "suspension_id": suspension.suspension_id,
+                    "prompt": "请审批该任务（approve/reject）",
+                    "tool": "manual_review",
+                    "tool_call_id": "manual-review-1",
+                },
             )
             return
 

{ni_agentkit-0.6.0 → ni_agentkit-0.6.2}/examples/standard/17_checkpoint_handoff_resume.py

@@ -23,13 +23,20 @@ class ReviewAgent(BaseAgent):
         # 第一次进入：请求人工输入并挂起
         if not ctx.state.get("review_suspended_once"):
             ctx.state["review_suspended_once"] = True
-            # 用于 Runner.resume 注入 user_input 到 tool message
-            ctx.state["__suspended_tool_call_id__"] = "manual-review-1"
-            ctx.state["__suspended_tool_name__"] = "manual_review"
+            suspension = ctx.register_suspension(
+                tool_call_id="manual-review-1",
+                tool_name="manual_review",
+                prompt="请审批该任务（approve/reject）",
+            )
             yield Event(
                 agent=self.name,
                 type=EventType.SUSPEND_REQUESTED,
-                data={"prompt": "请审批该任务（approve/reject）", "tool": "manual_review", "tool_call_id": "manual-review-1"},
+                data={
+                    "suspension_id": suspension.suspension_id,
+                    "prompt": "请审批该任务（approve/reject）",
+                    "tool": "manual_review",
+                    "tool_call_id": "manual-review-1",
+                },
             )
             return
 

{ni_agentkit-0.6.0 → ni_agentkit-0.6.2}/ni.agentkit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ni.agentkit
-Version: 0.6.0
+Version: 0.6.2
 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
@@ -153,8 +153,8 @@ python "$(python -c "import agentkit, os; print(os.path.join(agentkit.get_exampl
 
 ```bash
 dist/
-├── ni_agentkit-0.6.0-py3-none-any.whl   # pip install 用这个
-└── ni_agentkit-0.6.0.tar.gz             # 源码分发
+├── ni_agentkit-0.6.2-py3-none-any.whl   # pip install 用这个
+└── ni_agentkit-0.6.2.tar.gz             # 源码分发
 ```
 
 ## 📄 License

{ni_agentkit-0.6.0 → ni_agentkit-0.6.2}/ni.agentkit.egg-info/SOURCES.txt

@@ -182,6 +182,9 @@ skills/__init__.py
 skills/loader.py
 skills/models.py
 skills/registry.py
+tests/test_after_callback.py
+tests/test_quickstart_core.py
+tests/test_runner_checkpoint_resume.py
 tools/__init__.py
 tools/base_tool.py
 tools/function_tool.py

{ni_agentkit-0.6.0 → ni_agentkit-0.6.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ni.agentkit"
-version = "0.6.0"
+version = "0.6.2"
 description = "A Python-native Agent framework with first-class Skill support and multi-LLM adapter"
 authors = [
     { name = "Krix Tam", email = "krix.tam@qq.com" }

{ni_agentkit-0.6.0 → ni_agentkit-0.6.2}/runner/context.py

@@ -6,12 +6,27 @@ from __future__ import annotations
 import copy
 import json
 import logging
-from dataclasses import dataclass, field
+import time
+from dataclasses import asdict, dataclass, field
 from typing import Any, Optional
 from uuid import uuid4
 
 logger = logging.getLogger(__name__)
 
+
+@dataclass
+class SuspensionRecord:
+    suspension_id: str
+    tool_call_id: str
+    tool_name: str
+    prompt: str
+    form_schema: dict[str, Any] | None = None
+    resume_strategy: str = "as_tool_result"
+    created_at: float = field(default_factory=time.time)
+    resolved_at: float | None = None
+    resolved_input: str | None = None
+
+
 @dataclass
 class RunContext:
     """一次运行的完整上下文"""
@@ -30,6 +45,10 @@ class RunContext:
 
     # 分支（并行 Agent 用）
     branch: Optional[str] = None
+    # 挂起记录（框架托管，业务侧无需关注内部协议）
+    suspensions: list[SuspensionRecord] = field(default_factory=list)
+    # resume 幂等记录：idempotency_key -> 已处理结果
+    resume_idempotency: dict[str, dict[str, Any]] = field(default_factory=dict)
 
     def add_message(self, role: str, content: Any) -> None:
         self.messages.append({"role": role, "content": content})
@@ -49,6 +68,45 @@ class RunContext:
         branch_ctx.branch = branch_name
         return branch_ctx
 
+    def register_suspension(
+        self,
+        *,
+        tool_call_id: str,
+        tool_name: str,
+        prompt: str,
+        form_schema: dict[str, Any] | None = None,
+        resume_strategy: str = "as_tool_result",
+    ) -> SuspensionRecord:
+        record = SuspensionRecord(
+            suspension_id=str(uuid4()),
+            tool_call_id=tool_call_id,
+            tool_name=tool_name,
+            prompt=prompt,
+            form_schema=form_schema,
+            resume_strategy=resume_strategy,
+        )
+        self.suspensions.append(record)
+        return record
+
+    def get_pending_suspension(self, suspension_id: str | None = None) -> SuspensionRecord | None:
+        pending = [s for s in self.suspensions if s.resolved_at is None]
+        if not pending:
+            return None
+        if suspension_id:
+            for s in pending:
+                if s.suspension_id == suspension_id:
+                    return s
+            return None
+        return pending[-1]
+
+    def resolve_suspension(self, suspension_id: str, user_input: str) -> SuspensionRecord | None:
+        for s in self.suspensions:
+            if s.suspension_id == suspension_id and s.resolved_at is None:
+                s.resolved_at = time.time()
+                s.resolved_input = user_input
+                return s
+        return None
+
     def to_dict(self) -> dict[str, Any]:
         """将 RunContext 序列化为字典，支持 shared_context 自定义协议"""
         serialized_shared = None
@@ -74,6 +132,8 @@ class RunContext:
             "messages": copy.deepcopy(self.messages),
             "state": copy.deepcopy(self.state),
             "branch": self.branch,
+            "suspensions": [asdict(s) for s in self.suspensions],
+            "resume_idempotency": copy.deepcopy(self.resume_idempotency),
         }
 
     @classmethod
@@ -94,6 +154,8 @@ class RunContext:
             messages=data.get("messages", []),
             state=data.get("state", {}),
             branch=data.get("branch"),
+            suspensions=[SuspensionRecord(**s) for s in data.get("suspensions", [])],
+            resume_idempotency=data.get("resume_idempotency", {}),
         )
 
     def to_json(self) -> str:
@@ -104,4 +166,3 @@ class RunContext:
     def from_json(cls, json_str: str, shared_context_cls: Optional[Any] = None) -> "RunContext":
         """从 JSON 字符串反序列化 RunContext"""
         return cls.from_dict(json.loads(json_str), shared_context_cls)
-