ni.agentkit 0.6.2__tar.gz → 0.6.3__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ni.agentkit
-Version: 0.6.2
+Version: 0.6.3
 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.2-py3-none-any.whl   # pip install 用这个
-└── ni_agentkit-0.6.2.tar.gz             # 源码分发
+├── ni_agentkit-0.6.3-py3-none-any.whl   # pip install 用这个
+└── ni_agentkit-0.6.3.tar.gz             # 源码分发
 ```
 
 ## 📄 License

{ni_agentkit-0.6.2 → ni_agentkit-0.6.3}/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.2-py3-none-any.whl   # pip install 用这个
-└── ni_agentkit-0.6.2.tar.gz             # 源码分发
+├── ni_agentkit-0.6.3-py3-none-any.whl   # pip install 用这个
+└── ni_agentkit-0.6.3.tar.gz             # 源码分发
 ```
 
 ## 📄 License

{ni_agentkit-0.6.2 → ni_agentkit-0.6.3}/__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.2"
+__version__ = "0.6.3"
 
 
 def get_docs_dir() -> str:

{ni_agentkit-0.6.2 → ni_agentkit-0.6.3}/docs/QuickStart.md

@@ -1,6 +1,6 @@
 # AgentKit 快速入门教程
 
-> 本教程将带你从零开始，通过 18 组由简到繁的示例（含 9A/9B），掌握 AgentKit 的核心用法。
+> 本教程将带你从零开始，通过 18 组由简到繁的示例（含 8A/8B/8C、9A/9B），掌握 AgentKit 的核心用法。
 
 ---
 
@@ -608,60 +608,45 @@ asyncio.run(stream_demo())
 
 默认情况下，Agent 每次运行都是无状态的。配上记忆后，Agent 可以记住用户的偏好和历史。
 
-### 无需外部依赖的 SimpleMemory
+### 8A：SimpleMemory
 
 ```python
 from agentkit import Agent, Runner, BaseMemoryProvider, Memory
 
 class SimpleMemory(BaseMemoryProvider):
-    """轻量内存记忆——适合开发测试"""
     def __init__(self):
         self._store, 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)
         return [m]
-
     async def search(self, query, *, user_id=None, agent_id=None, limit=10):
-        # 简单关键词匹配（生产环境用 Mem0 的向量搜索）
         query_words = set(query)
         scored = [(len(query_words & set(m.content)), m) for m in self._store]
         scored.sort(reverse=True, key=lambda x: x[0])
         return [m for s, m in scored[:limit] if s > 0]
-
     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
 
-# 给 Agent 配上记忆
 memory = SimpleMemory()
-
 agent = Agent(
     name="personal-assistant",
     instructions="你是一个贴心的个人助手。根据记忆来个性化回答。",
     model="ollama/qwen3.5:cloud",
-    memory=memory,       # ← 加上这一行
+    memory=memory,
+    memory_async_write=False,
 )
 
-# 第 1 轮：告诉偏好
 Runner.run_sync(agent, input="我叫小明，我喜欢喝咖啡，讨厌喝茶", user_id="krix")
-
-# 第 2 轮：Agent 会记住偏好，推荐咖啡而不是茶
 result = Runner.run_sync(agent, input="帮我推荐一杯饮料", user_id="krix")
-print(result.final_output)  # "推荐拿铁！" — 基于记忆推荐
+print(result.final_output)  # 基于记忆推荐
 ```
 
-**要点**：
-- 默认不开启记忆，需要给 `Agent` 传 `memory=...` 参数
-- 配好后**不需要写额外代码**——框架自动在对话前检索记忆、对话后存储记忆
-- `user_id` 用于多用户隔离
-
-### 生产环境使用 Mem0
+### 8B：Mem0Provider（生产级）
 
 ```bash
 pip install mem0ai
@@ -678,11 +663,47 @@ memory = Mem0Provider({
     }
 })
 
-agent = Agent(memory=memory, ...)     # 替换 SimpleMemory 即可
+agent = Agent(memory=memory, ...)  # 先构建 memory，再注入 Agent
 ```
 
 Mem0 相比 SimpleMemory 的优势：**语义搜索**（理解意思而非关键词）、**持久化**（重启不丢失）、**智能提取**（从对话中自动抽取关键信息）。
 
+### 8C：自定义 Memory（文件持久化）
+
+```python
+import json
+from pathlib import Path
+from agentkit import BaseMemoryProvider, Memory, Agent
+
+class FileMemoryProvider(BaseMemoryProvider):
+    def __init__(self, file_path: str):
+        self.path = Path(file_path)
+        self.records = json.loads(self.path.read_text()) if self.path.exists() else []
+    async def add(self, content, *, user_id=None, agent_id=None, metadata=None):
+        new_id = str(len(self.records) + 1)
+        self.records.append({"id": new_id, "content": content, "user_id": user_id})
+        self.path.write_text(json.dumps(self.records, ensure_ascii=False, indent=2))
+        return [Memory(id=new_id, content=content)]
+    async def search(self, query, *, user_id=None, agent_id=None, limit=10):
+        q = query.lower()
+        out = [r for r in self.records if q in r["content"].lower()]
+        return [Memory(id=r["id"], content=r["content"]) for r in out[:limit]]
+    async def get_all(self, *, user_id=None, agent_id=None):
+        return [Memory(id=r["id"], content=r["content"]) for r in self.records]
+    async def delete(self, memory_id):
+        self.records = [r for r in self.records if r["id"] != memory_id]
+        self.path.write_text(json.dumps(self.records, ensure_ascii=False, indent=2))
+        return True
+
+memory = FileMemoryProvider("/tmp/agentkit_memory.json")
+agent = Agent(memory=memory, ...)
+```
+
+**要点**：
+- 默认不开启记忆，需要给 `Agent` 传 `memory=...` 参数
+- `SimpleMemory` 适合开发测试，`Mem0Provider` 适合生产语义检索
+- 自定义 `FileMemoryProvider` 可实现轻量持久化（进程重启后仍可读取）
+
 ---
 
 ## 示例 9A：关系型数据库 — 防止 SQL 注入的参数化 Tool
@@ -1159,7 +1180,9 @@ agent = Agent(name="assistant", instructions="...")
 | [`05_guardrail.py`](../examples/standard/05_guardrail.py) | 示例 5：安全护栏 |
 | [`06_orchestration.py`](../examples/standard/06_orchestration.py) | 示例 6：编排 Agent |
 | [`07_sync_async_stream.py`](../examples/standard/07_sync_async_stream.py) | 示例 7：同步/异步/流式运行 |
-| [`08_memory.py`](../examples/standard/08_memory.py) | 示例 8：记忆系统 |
+| [`08a_memory_simple_provider.py`](../examples/standard/08a_memory_simple_provider.py) | 示例 8A：记忆系统（SimpleMemory） |
+| [`08b_memory_mem0_provider.py`](../examples/standard/08b_memory_mem0_provider.py) | 示例 8B：记忆系统（Mem0Provider） |
+| [`08c_memory_file_provider.py`](../examples/standard/08c_memory_file_provider.py) | 示例 8C：记忆系统（文件持久化） |
 | [`09a_structured_data_sql.py`](../examples/standard/09a_structured_data_sql.py) | 示例 9A：关系型数据库 |
 | [`09b_structured_data_graph.py`](../examples/standard/09b_structured_data_graph.py) | 示例 9B：图数据库 |
 | [`10_skill_lifecycle.py`](../examples/standard/10_skill_lifecycle.py) | 示例 10：Skill 生命周期 |
@@ -1183,7 +1206,9 @@ agent = Agent(name="assistant", instructions="...")
 | [`05_guardrail.py`](../examples/ollama/05_guardrail.py) | 示例 5：安全护栏 |
 | [`06_orchestration.py`](../examples/ollama/06_orchestration.py) | 示例 6：编排 Agent |
 | [`07_sync_async_stream.py`](../examples/ollama/07_sync_async_stream.py) | 示例 7：同步/异步/流式运行 |
-| [`08_memory.py`](../examples/ollama/08_memory.py) | 示例 8：记忆系统 |
+| [`08a_memory_simple_provider.py`](../examples/ollama/08a_memory_simple_provider.py) | 示例 8A：记忆系统（SimpleMemory） |
+| [`08b_memory_mem0_provider.py`](../examples/ollama/08b_memory_mem0_provider.py) | 示例 8B：记忆系统（Mem0Provider） |
+| [`08c_memory_file_provider.py`](../examples/ollama/08c_memory_file_provider.py) | 示例 8C：记忆系统（文件持久化） |
 | [`09a_structured_data_sql.py`](../examples/ollama/09a_structured_data_sql.py) | 示例 9A：关系型数据库 |
 | [`09b_structured_data_graph.py`](../examples/ollama/09b_structured_data_graph.py) | 示例 9B：图数据库 |
 | [`10_skill_lifecycle.py`](../examples/ollama/10_skill_lifecycle.py) | 示例 10：Skill 生命周期 |

{ni_agentkit-0.6.2 → ni_agentkit-0.6.3}/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.2-green.svg)]()
+[![Version](https://img.shields.io/badge/Version-0.6.3-green.svg)]()
 [![License](https://img.shields.io/badge/License-MIT-yellow.svg)]()
 
 ---

ni_agentkit-0.6.3/docs/TestReport.md

@@ -0,0 +1,90 @@
+# AgentKit 示例测试报告
+
+> 测试时间：`2026-04-23`  
+> 测试环境：`macOS (Apple Silicon)`  
+> 模型：Ollama `qwen3.5:cloud`  
+> AgentKit 版本：v0.6.3  
+> Thinking 模式：开启（默认）  
+> LLM 调用模式：非流式（默认）  
+> 缓存：开启（默认）  
+> 执行脚本：`examples/test_ollama.py`
+
+---
+
+## 测试结果
+
+| # | 示例 | 文件 | 耗时 | 状态 | 说明 |
+|---|------|------|-----:|:----:|------|
+| 1 | 基础对话 | `01_basic_chat.py` | 16.51s | ✅ | 运行通过 |
+| 2 | 工具调用 | `02_tool_calling.py` | 12.51s | ✅ | 运行通过 |
+| 3 | Skill 使用 | `03_skill_usage.py` | 82.73s | ✅ | 运行通过 |
+| 4 | 多 Agent 协作 | `04_multi_agent.py` | 97.29s | ✅ | 运行通过 |
+| 5 | 安全护栏 | `05_guardrail.py` | 7.33s | ✅ | 运行通过 |
+| 5H | HITL 工具触发（Playground 专用） | `05_human_in_the_loop.py` | 0.18s | ✅ | 运行通过 |
+| 6 | 编排 Agent | `06_orchestration.py` | 290.84s | ✅ | 运行通过 |
+| 7 | 同步/异步/流式 | `07_sync_async_stream.py` | 13.51s | ✅ | 运行通过 |
+| 8 | 记忆系统（综合） | `08_memory.py` | 537.55s | ✅ | 运行通过（本轮最慢） |
+| 8A | SimpleMemory | `08a_memory_simple_provider.py` | 45.82s | ✅ | 运行通过 |
+| 8B | Mem0Provider | `08b_memory_mem0_provider.py` | 0.19s | ✅ | 未配置 `OPENAI_API_KEY` 时自动跳过 |
+| 8C | 文件持久化 Memory | `08c_memory_file_provider.py` | 157.72s | ✅ | 运行通过 |
+| 9A | 结构化数据（SQL） | `09a_structured_data_sql.py` | 5.72s | ✅ | 运行通过 |
+| 9B | 结构化数据（图） | `09b_structured_data_graph.py` | 30.72s | ✅ | 运行通过 |
+| 10 | Skill 生命周期 | `10_skill_lifecycle.py` | 2.36s | ✅ | 运行通过 |
+| 11 | 编排增强 | `11_orchestration_enhancement.py` | 57.63s | ✅ | 运行通过 |
+| 12 | 序列化协议 | `12_run_context_serialization.py` | 0.19s | ✅ | 运行通过 |
+| 13 | Human in the Loop | `13_human_in_the_loop.py` | 8.06s | ✅ | 运行通过 |
+| 14 | Event 标准化 | `14_event_standardization.py` | 5.70s | ✅ | 运行通过 |
+| 15 | 多租户隔离 | `15_multi_tenant_isolation.py` | 0.29s | ✅ | 运行通过 |
+| 16 | 生命周期 Hooks | `16_lifecycle_hooks.py` | 0.27s | ✅ | 运行通过 |
+| 17 | Checkpoint + Handoff + Resume | `17_checkpoint_handoff_resume.py` | 0.18s | ✅ | 运行通过 |
+| 18 | ModelCosplay | `18_model_cosplay.py` | 0.18s | ✅ | 运行通过 |
+| 19 | HITL 确定性触发 | `19_hitl_deterministic.py` | 0.17s | ✅ | 运行通过（本轮最快） |
+| | **合计** | | **1373.65s** | **24/24** | |
+
+## 耗时分析
+
+- **最快示例**：19 HITL 确定性触发（0.17s）
+- **最慢示例**：8 记忆系统（537.55s）
+- **耗时集中区间**：涉及多轮推理/记忆写入/编排循环的示例耗时显著更高
+
+## 各示例 LLM 调用次数估算
+
+| # | 示例 | LLM 调用次数 | 说明 |
+|---|------|:-----------:|------|
+| 1 | 基础对话 | 1 | 单次对话 |
+| 2 | 工具调用 | ~6 | 多次工具调用与回复生成 |
+| 3 | Skill 使用 | ~9 | load_skill + 工具调用 + 回复 |
+| 4 | 多 Agent 协作 | ~8 | as_tool + handoff 链路 |
+| 5 | 安全护栏 | ~3 | 拦截与放行混合路径 |
+| 5H | HITL 工具触发（Playground 专用） | ~0 | 仅触发挂起事件，不走 LLM |
+| 6 | 编排 Agent | ~12 | Sequential + Parallel + Loop |
+| 7 | 同步/异步/流式 | ~7 | 三种运行模式覆盖 |
+| 8 | 记忆系统（综合） | ~10 | 记忆读写与多轮对话 |
+| 8A | SimpleMemory | ~2 | 轻量关键词检索 |
+| 8B | Mem0Provider | ~0 | 未配置 `OPENAI_API_KEY` 时自动跳过 |
+| 8C | 文件持久化 Memory | ~2 | 本地文件读写 + 记忆检索 |
+| 9A | 结构化数据（SQL） | ~2 | 参数化查询 + 汇总 |
+| 9B | 结构化数据（图） | ~2 | 图查询 + 汇总 |
+| 10 | Skill 生命周期 | 1 | 单轮校验 |
+| 11 | 编排增强 | ~4 | loop_condition + early_exit |
+| 12 | RunContext 序列化 | 0 | 纯本地序列化 |
+| 13 | HITL 断点续跑 | ~3 | 挂起 + 恢复 |
+| 14 | 事件协议标准化 | 1 | 标准事件输出 |
+| 15 | 多租户隔离 | ~3 | 多会话隔离验证 |
+| 16 | 生命周期 Hooks | ~2 | Hook 链路验证 |
+| 17 | Checkpoint Handoff 恢复 | 0 | 自定义事件流，不依赖 LLM |
+| 18 | ModelCosplay | 0 | 仅验证模型改写开关与运行时覆盖逻辑，不调用 LLM |
+| 19 | HITL 确定性触发 | 0 | 自定义事件流，不依赖 LLM |
+
+## 已知问题
+
+| 问题 | 严重程度 | 说明 |
+|------|:--------:|------|
+| 运行异常 | - | 无，24 个示例全部通过（8B 在无 `OPENAI_API_KEY` 时自动跳过） |
+
+## 运行方式
+
+```bash
+# 在 agentkit 目录执行
+python examples/test_ollama.py
+```

{ni_agentkit-0.6.2 → ni_agentkit-0.6.3}/examples/ollama/01_basic_chat.py

@@ -21,14 +21,15 @@ agent = Agent(
 )
 
 # 同步运行
-result = Runner.run_sync(agent, input="什么是量子计算？请用一句话解释。")
+if __name__ == "__main__":
+    result = Runner.run_sync(agent, input="什么是量子计算？请用一句话解释。")
 
-if result.success:
-    print(f"✅ 回复: {result.final_output}")
-else:
-    print(f"❌ 错误: {result.error}")
+    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]}")
+    # 查看事件流
+    print("\n📋 事件流:")
+    for event in result.events:
+        print(f"  [{event.type}] {str(event.data)[:80]}")

ni_agentkit-0.6.3/examples/ollama/05_human_in_the_loop.py

@@ -0,0 +1,42 @@
+"""
+示例 5（Playground/HITL 专用）：Human-in-the-loop Agent（Ollama 版）
+
+用途：
+- 提供一个可被 AgentHub `entry` 直接加载的 `agent` 实例；
+- 在工具执行前通过 `request_human_input(...)` 触发挂起，便于在 Playground 中演示 HITL。
+"""
+import os
+import sys
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "..", ".."))
+
+from agentkit import Agent
+from agentkit.tools.base_tool import request_human_input
+from agentkit.tools.function_tool import FunctionTool
+
+
+def confirm_action(action: str) -> str:
+    """敏感操作执行前请求人工确认。"""
+    request_human_input(f"即将执行敏感操作: {action}，请确认 (approve/reject)")
+
+
+def execute_action(action: str) -> str:
+    """执行操作（示例返回）。"""
+    return f"操作 '{action}' 已执行。"
+
+
+confirm_tool = FunctionTool.from_function(confirm_action)
+execute_tool = FunctionTool.from_function(execute_action)
+
+
+agent = Agent(
+    name="hitl-agent",
+    instructions=(
+        "你是一个需要人工审批的运维助手。"
+        "当用户要求执行敏感操作时，必须先调用 confirm_action 请求人工确认；"
+        "收到确认后再调用 execute_action。"
+    ),
+    # 使用纯本地模型，避免 cloud 变体在未鉴权/网络抖动时触发远端 502。
+    model="ollama/qwen3.5:4b",
+    tools=[confirm_tool, execute_tool],
+)

ni_agentkit-0.6.3/examples/ollama/08a_memory_simple_provider.py

@@ -0,0 +1,59 @@
+import asyncio
+import os
+import sys
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "..", ".."))
+
+from agentkit import Agent, BaseMemoryProvider, Memory, Runner
+
+MODEL = "ollama/qwen3.5:cloud"
+
+
+class SimpleMemory(BaseMemoryProvider):
+    def __init__(self) -> None:
+        self._store: list[Memory] = []
+        self._counter = 0
+
+    async def add(self, content, *, user_id=None, agent_id=None, metadata=None):
+        self._counter += 1
+        item = Memory(id=str(self._counter), content=content)
+        self._store.append(item)
+        return [item]
+
+    async def search(self, query, *, user_id=None, agent_id=None, limit=10):
+        query_chars = set(query)
+        scored: list[tuple[int, Memory]] = []
+        for item in self._store:
+            overlap = len(query_chars & set(item.content))
+            if overlap > 0:
+                scored.append((overlap, item))
+        scored.sort(reverse=True, key=lambda x: x[0])
+        return [m for _, m in scored[:limit]]
+
+    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
+
+
+async def main() -> None:
+    print("=== 示例 8A：SimpleMemory ===")
+    memory = SimpleMemory()
+    agent = Agent(
+        name="remembering",
+        instructions="你是贴心助手。根据记忆回答，回答简洁。",
+        model=MODEL,
+        memory=memory,
+        memory_async_write=False,
+    )
+
+    await Runner.run(agent, input="我叫小明，喜欢咖啡，讨厌茶。", user_id="user_001")
+    result = await Runner.run(agent, input="帮我推荐一杯饮料。", user_id="user_001")
+    print("推荐:", result.final_output)
+    print("记忆条数:", len(await memory.get_all()))
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

ni_agentkit-0.6.3/examples/ollama/08b_memory_mem0_provider.py

@@ -0,0 +1,57 @@
+import asyncio
+import os
+import sys
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "..", ".."))
+
+from agentkit import Agent, Runner
+
+MODEL = "ollama/qwen3.5:cloud"
+
+
+async def main() -> None:
+    print("=== 示例 8B：Mem0Provider ===")
+    try:
+        from agentkit.memory.mem0_provider import Mem0Provider
+    except Exception:
+        print("未安装 mem0ai，跳过运行。")
+        print("安装: pip install mem0ai")
+        print("并启动 qdrant: docker run -p 6333:6333 qdrant/qdrant")
+        return
+
+    if not os.getenv("OPENAI_API_KEY"):
+        print("未设置 OPENAI_API_KEY，跳过运行。")
+        return
+
+    try:
+        memory = Mem0Provider(
+            {
+                "vector_store": {
+                    "provider": "qdrant",
+                    "config": {
+                        "collection_name": "agentkit_quickstart",
+                        "host": "localhost",
+                        "port": 6333,
+                    },
+                }
+            }
+        )
+    except Exception as exc:
+        print(f"Mem0 初始化失败，跳过运行: {exc}")
+        return
+
+    agent = Agent(
+        name="mem0-assistant",
+        instructions="你是贴心助手。根据记忆回答，回答简洁。",
+        model=MODEL,
+        memory=memory,
+        memory_async_write=False,
+    )
+
+    await Runner.run(agent, input="记住：我喜欢低糖拿铁。", user_id="user_001")
+    result = await Runner.run(agent, input="给我推荐一杯饮料。", user_id="user_001")
+    print("推荐:", result.final_output)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

ni_agentkit-0.6.3/examples/ollama/08c_memory_file_provider.py

@@ -0,0 +1,102 @@
+import asyncio
+import json
+import os
+import sys
+from pathlib import Path
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "..", ".."))
+
+from agentkit import Agent, BaseMemoryProvider, Memory, Runner
+
+MODEL = "ollama/qwen3.5:cloud"
+MEMORY_FILE = "/tmp/agentkit_memory_ollama.json"
+
+
+class FileMemoryProvider(BaseMemoryProvider):
+    def __init__(self, file_path: str) -> None:
+        self._path = Path(file_path)
+        self._records: list[dict] = []
+        self._counter = 0
+        self._load()
+
+    def _load(self) -> None:
+        if self._path.exists():
+            try:
+                self._records = json.loads(self._path.read_text(encoding="utf-8"))
+            except Exception:
+                self._records = []
+        if self._records:
+            self._counter = max(int(r.get("id", 0)) for r in self._records)
+
+    def _save(self) -> None:
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        self._path.write_text(json.dumps(self._records, ensure_ascii=False, indent=2), encoding="utf-8")
+
+    @staticmethod
+    def _to_memory(record: dict) -> Memory:
+        return Memory(id=str(record["id"]), content=str(record["content"]))
+
+    async def add(self, content, *, user_id=None, agent_id=None, metadata=None):
+        self._counter += 1
+        record = {
+            "id": str(self._counter),
+            "content": content,
+            "user_id": user_id,
+            "agent_id": agent_id,
+            "metadata": metadata or {},
+        }
+        self._records.append(record)
+        self._save()
+        return [self._to_memory(record)]
+
+    async def search(self, query, *, user_id=None, agent_id=None, limit=10):
+        q = str(query).lower()
+        matched: list[Memory] = []
+        for record in self._records:
+            if user_id is not None and record.get("user_id") != user_id:
+                continue
+            if agent_id is not None and record.get("agent_id") != agent_id:
+                continue
+            if q in str(record.get("content", "")).lower():
+                matched.append(self._to_memory(record))
+            if len(matched) >= limit:
+                break
+        return matched
+
+    async def get_all(self, *, user_id=None, agent_id=None):
+        out: list[Memory] = []
+        for record in self._records:
+            if user_id is not None and record.get("user_id") != user_id:
+                continue
+            if agent_id is not None and record.get("agent_id") != agent_id:
+                continue
+            out.append(self._to_memory(record))
+        return out
+
+    async def delete(self, memory_id):
+        before = len(self._records)
+        self._records = [r for r in self._records if str(r.get("id")) != str(memory_id)]
+        self._save()
+        return len(self._records) < before
+
+
+async def main() -> None:
+    print("=== 示例 8C：自定义 FileMemoryProvider（文件持久化） ===")
+    memory = FileMemoryProvider(MEMORY_FILE)
+    agent = Agent(
+        name="file-memory-assistant",
+        instructions="你是贴心助手。根据记忆回答，回答简洁。",
+        model=MODEL,
+        memory=memory,
+        memory_async_write=False,
+    )
+
+    await Runner.run(agent, input="记住：我早餐喜欢美式咖啡。", user_id="user_001")
+    result = await Runner.run(agent, input="推荐一杯饮料。", user_id="user_001")
+    print("推荐:", result.final_output)
+    print("持久化文件:", MEMORY_FILE)
+    print("当前记忆数:", len(await memory.get_all(user_id="user_001")))
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

ni_agentkit-0.6.3/examples/ollama/19_hitl_deterministic.py

@@ -0,0 +1,57 @@
+"""
+示例 19（Playground/HITL 专用）：确定性触发挂起（必现）
+
+用途：
+- 提供一个可被 AgentHub `entry` 直接加载的 `agent` 实例；
+- 首次运行必然发出 `suspend_requested`，便于 Playground 稳定演示 HITL 闭环。
+"""
+from __future__ import annotations
+
+import os
+import sys
+from typing import AsyncGenerator
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "..", ".."))
+
+from agentkit.agents.base_agent import BaseAgent
+from agentkit.runner.context import RunContext
+from agentkit.runner.events import Event, EventType
+
+
+class DeterministicHITLAgent(BaseAgent):
+    async def _run_impl(self, ctx: RunContext) -> AsyncGenerator[Event, None]:
+        # 第一次进入会话时，确定性触发挂起。
+        if not ctx.state.get("deterministic_hitl_suspended_once"):
+            ctx.state["deterministic_hitl_suspended_once"] = True
+            suspension = ctx.register_suspension(
+                tool_call_id="det-hitl-1",
+                tool_name="manual_approval",
+                prompt="请审批该操作（approve/reject）",
+            )
+            yield Event(
+                agent=self.name,
+                type=EventType.SUSPEND_REQUESTED,
+                data={
+                    "suspension_id": suspension.suspension_id,
+                    "prompt": "请审批该操作（approve/reject）",
+                    "tool": "manual_approval",
+                    "tool_call_id": "det-hitl-1",
+                },
+            )
+            return
+
+        decision = "unknown"
+        for msg in reversed(ctx.messages):
+            if msg.get("role") == "tool" and msg.get("tool_call_id") == "det-hitl-1":
+                decision = msg.get("content", "unknown")
+                break
+
+        yield Event(
+            agent=self.name,
+            type=EventType.FINAL_OUTPUT,
+            data=f"已收到人工决策: {decision}",
+        )
+
+
+agent = DeterministicHITLAgent(name="deterministic-hitl-agent")
+