PydanticAI 的可组合能力与扩展生态

PydanticAI 的可组合能力与扩展生态

学习目标

补充理解：

• Agent Spec（YAML/JSON）声明式 Agent 定义
• Harness Capability Library 的设计
• 第三方 Capability 的接口约定

前置知识

• Skill 设计 — 通用 Skill 设计概念

---

1. Agent Spec：YAML 声明式定义

PydanticAI 支持通过 YAML/JSON 定义 Agent，无需代码：

model: anthropic:claude-sonnet-4-6
instructions: "You are a helpful assistant."
capabilities:
  - type: thinking
    effort: high
  - type: web_search
    local: duckduckgo
output_type:
  type: tool
  schema:
    type: object
    properties:
      answer: { type: string }

限制：

• 只支持可序列化的 Capability——接受 callable 的 Capability（如 Hooks）不能用于 Spec
• 工具函数需要通过 MCP 或外部工具集注册

2. Harness Capability Library

Pydantic AI Harness 提供可复用的 Capability 集合：

Capability	用途
Memory	Agent 记忆管理
Guardrails	输入/输出护栏
Cost Tracking	费用追踪
Rate Limiting	速率限制
Caching	响应缓存

这些 Capability 可以作为第三方包安装：

pip install pydantic-ai-harness-memory

3. 第三方 Capability 接口约定

自定义 Capability 需要遵循 AbstractCapability 接口：

class MyCapability(AbstractCapability):
    def get_toolset(self):
        """返回工具集（可选）"""
        return None

    def get_model_settings(self):
        """返回模型设置（可选）"""
        return None

    def get_instructions(self):
        """返回系统提示追加（可选）"""
        return None

    def get_native_tools(self):
        """返回原生工具列表（可选）"""
        return []

    # 生命周期钩子
    def wrap_model_request(self, ctx, request_ctx, handler):
        return await handler(request_ctx)

4. 与通用 Skill 设计的对比

维度	通用 Skill	PydanticAI Capability
注册方式	配置文件/注册表	构造函数参数或 YAML Spec
执行环境	独立进程/容器	同一进程内（中间件链）
组合方式	Pipeline/Orchestrator	CombinedCapability 拓扑排序
沙箱	隔离执行	共享进程（通过类型安全保障）
状态	独立状态	共享 GraphAgentState

PydanticAI 的 Capability 更接近中间件而非独立的 Skill——它们在同一个进程中执行，通过类型安全的接口通信，不需要进程隔离。