Pydantic AI 运行时适配器（Pydantic AI Runtime Adapter）

目标关联

该特性支撑专业工作执行、领域扩展、可审计交付和专业可靠性。

实现的关键特性：

• Configurable Professional Identity
• Skill-Driven Capability System
• Tool-Mediated Action System
• Sandbox-First Work Execution
• Quality and Governance System

技术设计对齐

Pydantic AI 是执行引擎，但 kgent 的产品概念留在 engine 外。Adapter 只负责将 kgent context 转换为 Pydantic AI agent invocation，并将 engine result/error 转换回 kgent result。

范围

Phase 1 包含创建 Pydantic AI agent、传入 effective system prompt、注册 toolsets、运行 prompt、支持 streaming、记录高层结果、转换 engine errors。

排除 multi-agent handoff、complex graph orchestration、model router、automatic provider fallback、advanced tracing、fine-tuning。

概念模型

Kgent Runtime
  owns product context

Pydantic AI Adapter
  translates kgent context into Pydantic AI agent invocation

Pydantic AI
  executes model calls and tool calls

Adapter 不拥有 profile semantics、skill registry、memory policy、sandbox layout、deliverable validation。

接口

class AgentEngine:
    def run(self, request: AgentRunRequest) -> AgentResult:
        ...

class AgentRunRequest:
    context: RunContext
    prompt: str
    timeout_seconds: int | None
    max_steps: int | None
    stream: bool
    cancellation_token: object | None
    event_callback: object | None

输出：

AgentResult
  status
  final_text
  usage summary if available
  error if failed

AgentError
  code
  message
  retryable
  provider
  raw_type

Scheduler Control Surface

Adapter 必须为未来 scheduler 预留：

• timeout
• max steps
• cancellation token placeholder
• stream event callback
• structured error reporting

Phase 1 可只实现底层 API 支持的部分，但接口字段必须保留。

运行时行为

Runtime 解析 config、创建 sandbox、构建 skill index 和 memory summary、渲染 prompt、构建 toolsets，然后调用 adapter。Adapter 创建 Pydantic AI agent 并运行任务，所有 tool calls 经过 kgent wrappers。Adapter 返回 result 或 structured error。

产物

Adapter 本身不直接写大量 artifacts。Runtime 和 records 写入：

runs/<run-id>/events.jsonl
runs/<run-id>/transcript.md
runs/<run-id>/logs/errors.jsonl

质量和治理

• model config 无效时清晰失败。
• 不泄漏 secrets 到 logs。
• 所有 tools 通过 kgent wrappers。
• 尽可能遵守 max steps 或等价限制。
• engine exceptions 转换为 structured run errors。

性能和调度考虑

支持 streaming；保持 prompt context 有边界；避免在重复 tool calls 中重建昂贵状态；可用时记录 model usage。Adapter 不依赖全局状态，失败可被未来 scheduler 重试。

验收标准

1. Pydantic AI 使用隔离在 engine/。
2. Runtime 可从 config 和 context 构造 agent。
3. Toolsets 通过 adapter 传递。
4. Agent 可运行 prompt。
5. Streaming 可由 config 控制。
6. Engine errors 变成 structured kgent failures。
7. 产品概念不进入 adapter。
8. Tests 可 mock engine。
9. Adapter interface 暴露 timeout、max steps、cancellation placeholder、event callback。