Kitaru 实战：记录、回放、改进 AI Agent 的每一次运行

AI 编码 Agent（Claude Code、Codex、Cursor 等）正在改变我们的开发方式，但它们也带来一个新问题：Agent 运行过程不透明，出错了难以排查。Agent 跑了几分钟，生成了几 MB 的日志，然后失败了——你完全不知道它在哪个步骤出错、为什么出错、换了参数会怎样。

Kitaru（来る，日语”到来”）正是为了解决这个问题而生的。它是一个开源的 Agent 运行时层，由 MLOps 平台 ZenML 团队开发，能够在你的 Agent 运行过程中自动记录每一步——每次模型调用、每个工具调用、每个决策点——保存为可重放的检查点（checkpoint）。更关键的是，你可以在任意检查点重新运行，替换模型、修改参数、注入不同的工具输出，然后观察变化。

这意味着：当 Agent 给出错误答案时，你可以精确回放到出错的那一步，换一个模型或改一个参数重来，而不是从头再跑一遍。

Kitaru 的核心定位

Kitaru 不取代你的 Agent 框架（Pydantic AI、LangGraph、OpenAI Agents SDK 等），而是作为一层执行运行时嵌入其中：

Kitaru 位于中间层——框架定义行为，平台定义策略，Kitaru 提供执行记录和回放能力。

快速上手

安装

pip install kitaru
uv pip install kitaru

如果需要与 Pydantic AI 集成：

uv pip install "kitaru[pydantic-ai]"

初始化项目

kitaru init

这会在当前目录生成 Kitaru 配置文件。

编写第一个 Flow

from kitaru import checkpoint, flow

@checkpoint
def fetch_data(url: str) -> str:
    return "some data"

@checkpoint
def process_data(data: str) -> str:
    return data.upper()

@flow
def my_pipeline(url: str) -> str:
    raw = fetch_data(url)
    result = process_data(raw)
    return result

@checkpoint 装饰器标记需要记录输出的函数。@flow 装饰器定义整个工作流。运行：

python agent.py

管理和回放执行

每次运行后，Kitaru 会将所有 checkpoint 输出保存到你的对象存储中。你可以通过 CLI 查看和管理执行记录：

kitaru executions list

kitaru executions get 

kitaru executions logs 

kitaru executions replay  --at process_data

kitaru executions replay  --at fetch_data \
  --flow-overrides '{"url": "https://other.example.com"}'

最核心的操作是 replay：它不会从头执行整个 flow，而是从指定的 checkpoint 恢复——所有之前的 checkpoint 返回缓存输出，只重新运行目标和后续的步骤。这大大节省了时间和 token 开销。

与 Pydantic AI 集成

Kitaru 提供了 KitaruAgent 适配器，可以直接包装 Pydantic AI 的 Agent：

from kitaru import flow
from kitaru.adapters.pydantic_ai import KitaruAgent
from pydantic_ai import Agent

researcher = KitaruAgent(
    Agent("openai:gpt-5.4", system_prompt="你是一个研究助手。")
)

@flow
def research_flow(topic: str) -> str:
    return researcher.run_sync(f"调研以下主题：{topic}")

部署 Flow

Kitaru 支持将 flow 部署为可调用的版本化服务：

my_agent.deploy(url="https://example.com")

from kitaru import KitaruClient
KitaruClient().deployments.invoke(
    flow="my_agent",
    inputs={"url": "https://example.com"},
)

版本管理也支持：

kitaru flow tag my_agent latest --stage=prod

kitaru flow tag my_agent v2 --stage=prod

应用场景

1. Agent 故障排查

Agent 在运行到第 5 个步骤时返回了错误结果。传统做法：看日志、猜原因、从头跑一遍。Kitaru 的做法：

kitaru executions replay  --at step_3

你可以在不同 checkpoint 切换模型或注入不同的参数，对比输出差异。

2. 模型对比测试

想知道 GPT-5.4 和 Claude 4 在某个 Agent 任务上谁表现更好？Kitaru 支持分叉（fork）运行——从同一个 checkpoint 出发，只改模型，其他不变：

kitaru executions replay  --at step_1 \
  --flow-overrides '{"model": "claude-4"}'

3. Crash 恢复

Agent 运行时容器被驱逐、超时或崩溃——传统做法是全部重来。Kitaru 的 crash recovery 机制让已完成的 checkpoint 返回缓存输出，只重新运行中断后的步骤。

架构原理

Kitaru 的核心是检查点系统（checkpoint system）。每次 Agent 运行都被分解为多个检查点，每个检查点记录以下信息：

• 输入：当前步骤接收的参数和上下文
• 输出：步骤执行后的结果
• 模型调用：如果有 LLM 调用，记录 prompt、response、token 数和延迟
• 工具调用：如果步骤中调用了外部工具，记录工具名称、输入和输出
• 时间戳：每个步骤的开始和结束时间

这些检查点数据被写入你指定的对象存储（本地文件系统或 S3 兼容存储）。重要的是，检查点输出是类型化的、版本化的——你可以跨运行 diff 同一个步骤的输出，精确追踪变化。

当使用 kitaru executions replay 时，Kitaru 不会从头执行整个 flow，而是：

1. 从对象存储中读取已完成检查点的缓存输出
2. 从指定检查点开始重新执行
3. 如果指定了 --flow-overrides，在对应步骤注入新参数

这种设计使得回放操作几乎零成本——已完成步骤不会重新调用模型，只有目标步骤及其后续步骤才消耗 token。

支持的工具和框架

Kitaru 目前支持的 Agent 框架（harness）包括：

为什么选择 Kitaru？

• 框架无关：支持 Pydantic AI、LangGraph、OpenAI Agents SDK 等主流框架
• 自托管：所有数据存在你自己的对象存储中，不需要上传到第三方
• 内置 UI：自带的 dashboard 可以可视化查看运行历史
• Apache-2.0 开源：由 ZenML 团队维护，社区活跃

与其他工具的对比

市面上有一些 Agent 日志查看工具（如 agent-log-viewer），但它们主要是被动观察者——读取已存在的日志文件并提供可视化界面。Kitaru 则是一个主动运行引擎——它不仅能记录，还能精确回放、修改参数、对比运行结果。前者适合调试，后者适合系统性改进 Agent 行为。

Kitaru 的核心理念可以概括为：每次 Agent 运行都是一次可复现的实验。它把 AI Agent 从”黑盒”变成了”可调试、可回放、可改进”的透明系统。

对于正在构建生产级 Agent 应用的团队来说，Kitaru 填补了一个重要的基础设施空白——不只是一个日志查看器，而是一个完整的执行记录和回放引擎。

相关链接： – Kitaru GitHub – Kitaru 官网 – ZenML 官方文档