a13n-harness

技能简介

a13n-harness 是 Agent Foundation 项目的进程级 Agent 执行框架，基于 Pydantic AI 构建，为 AI Agent 提供可靠的运行时基础设施。它的核心设计理念是将 Agent 行为分解为可组合的 Capability（能力单元），包括动态环境感知、运行时上下文管理、自我修复模型调用、任务交接、状态持久化和用户交互六大能力维度，开发者通过组合不同 Capability 灵活定制 Agent 行为，无需从零构建执行循环。框架内置本地 MCP 客户端支持，可直接对接 MCP 服务器扩展工具集，无需额外依赖。

核心能力

1. Capability 组合系统：通过 Pydantic AI Capabilities 接口将 Agent 行为分解为独立模块（动态环境、运行时上下文、自我修复模型调用、Handoff 交接、工作状态、用户交互），按需组合避免行为逻辑耦合。

2. 进程级执行隔离：每个独立 Run 在独立的 Provider Environment 中执行，生命周期由 Harness 管理，适配器在 Run 结束时关闭但不销毁底层资源，保证隔离性的同时维持资源高效利用。

3. 本地 MCP 集成：内置 MCP 客户端支持，无需额外 extra 即可在 AgentSpec.capabilities 中通过 pydantic_ai.capabilities.MCP 接入 MCP 服务器，扩展 Agent 工具生态。

4. 动态环境配置（DynamicEnvironmentCapability）：支持在运行时动态切换环境配置，可为不同 Run 挂载不同的 Environment 和 EnvironmentMount，实现多租户或场景隔离。

5. 自我修复模型调用（SelfHealingModelCapability）：当模型调用失败或输出异常时，Capability 触发自动重试或降级策略，提升 Agent 执行健壮性。

6. Provider 无关架构：依赖 provider-neutral 端口（FileOperator、MediaReader、DocumentConverter、WebClient），切换底层模型提供商（如 OpenAI→Anthropic）无需修改工具集代码。

安装配置

环境要求：

• Python 3.10 及以上

安装：

pip install a13n-harness

核心依赖（自动安装）：

• pydantic-ai
• pydantic（>=2.0）

使用步骤

第一步：定义 Capabilities

from a13n_harness.capabilities import (
    HandoffCapability,
    RuntimeContextCapability,
    UserInteractionCapability,
    WorkingStateCapability,
)
from a13n_harness.environment import (
    DynamicEnvironmentCapability,
    DynamicEnvironmentConfiguration,
)
from a13n_harness.models import SelfHealingModelCapability

capabilities = (
    DynamicEnvironmentCapability(DynamicEnvironmentConfiguration()),
    RuntimeContextCapability(),
    SelfHealingModelCapability(),
    HandoffCapability(),
    WorkingStateCapability(),
    UserInteractionCapability(),
)

第二步：配置 Run Environment

from a13n_harness.environment import Environment, EnvironmentRuntime

env = Environment(
    model="openai/gpt-4o",
    api_key=os.getenv("OPENAI_API_KEY"),
)

result = await agent.run(
    user_input,
    environment=env,
)

第三步：使用 MCP 扩展工具集

from pydantic_ai.capabilities import MCP

mcp_server = MCP(
    command=["npx", "@modelcontextprotocol/server-filesystem"],
    args=["/path/to/directory"],
)

agent_spec = AgentSpec(
    capabilities=[*capabilities, mcp_server],
    # ...
)

第四步：Advanced — 自定义 EnvironmentRuntime

from a13n_harness.environment import EnvironmentRuntime, RunBindings

runtime = EnvironmentRuntime()
bindings = RunBindings.embedded()
result = await agent.run(user_input, environment=runtime, bindings=bindings)

适用场景

1. 构建企业级 AI Agent：需要稳定、可测试的 Agent 执行框架，Capability 组合方式便于单元测试和集成测试。

2. 多租户隔离环境：不同用户的 Agent Run 需要完全隔离，DynamicEnvironmentCapability 提供运行时环境配置隔离。

3. 复杂工具集编排：需要组合 MCP 服务器、本地工具和云端 API 构建复杂 Agent，Pydantic AI MCP 原生支持简化集成。

4. Agent 交接场景：HandoffCapability 支持在多个 Agent 之间传递上下文和状态，适合客服转接、专家会诊等场景。

适用人群

• AI 应用开发者：使用 Pydantic AI 构建复杂 Agent，需要成熟的执行基础设施而非自行实现 Run Loop。
• 平台工程师：需要多租户隔离、运行日志和审计能力的企业 AI 平台开发者。
• AI Agent 框架开发者：构建上层 Agent 框架，基于 a13n-harness 的 Capability 系统快速获得 MCP 支持和环境隔离能力。

工作原理

a13n-harness 基于 Pydantic AI 的 Agent 执行模型进行了进程级封装。核心是 Capability 接口——每个 Capability 拥有生命周期钩子（on_start / on_end）和对应的纯工具集（Toolsets），工具集只依赖 provider-neutral 端口而非特定模型 API。Harness 作为执行容器，为每个 Run 创建独立的 Environment，Environment 持有模型配置和适配器生命周期；Run 结束时 Harness 关闭适配器但保留资源（如数据库连接池），下次 Run 可复用，避免重复创建开销。

官方链接

• PyPI 主页：https://pypi.org/project/a13n-harness/
• 相关项目：https://github.com/agentfoundation（Agent Foundation 组织）