Pydantic AI Agent 适配器（预览）

查看 future-facing 能力与 工具集 API；当前 PyPI 和 Git 子目录安装都不可用。

预览，普通用户目前无法安装：powercontext-pydantic-ai 尚未发布到 PyPI。其 source 元数据要求最终 powercontext[client]>=0.0.3，而仓库仍是 pre-0.0.3；Git 子目录安装也会因此依赖解析失败。当前没有可用的 standalone 安装命令。

本页记录 API，供 review 和未来版本使用。仓库 contributor 可以在根目录开发环境中运行它，但这不是受支持的 consumer 安装路径。文档验证没有验证真实模型提供方调用或 durable-execution 宿主。

​

选择集成范围

​

PowerContext 能力

下面是 future-facing API，不是当前可运行的安装教程：

from pydantic_ai import Agent
from powercontext_pydantic_ai import PowerContext


agent = Agent(
    "openai:gpt-5.2",
    capabilities=[PowerContext(scope_id="project:powercontext-101")],
)

PowerContext 把三个模型工具与 once-per-run 召回组合起来。它还可以采集 Agent 事件，在采集检查点后刷新，并在运行结束后做一次最终 catch-up 刷新。采集默认关闭。

​

PowerContextToolset

下面这个 future-facing 写法只安装同样的三个工具：

from pydantic_ai import Agent
from powercontext_pydantic_ai import PowerContextToolset


agent = Agent(
    "openai:gpt-5.2",
    toolsets=[PowerContextToolset(scope_id="project:powercontext-101")],
)

它没有自动召回、采集、检查点刷新或最终刷新。

行为	PowerContext	PowerContextToolset
powercontext_search	是	是
powercontext_remember	是	是
powercontext_context	是	是
once-per-run 自动召回	是	否
可选事件采集	是；默认 false	否
检查点与最终 catch-up 刷新	是，采集开启时	否

工具会保留完整的公开客户端响应 JSON，包括状态、Citation 和 Revision 字段。客户端失败时不会返回空的成功结果。

这一页描述的是预览接口，不是当前可安装教程。阅读代码示例是为了理解未来的 Capability、工具集 和 Scope 绑定方式；如果你的目标是今天完成集成，请转到 LangGraph、LangChain 或 MCP。这里的完成结果是准确识别边界，而不是成功安装一个尚未发布的软件包。

​

跟踪一次上限运行

Agent binds the Capability or Toolset
→ resolve Scope once and open one async Client
→ Capability captures the initial prompt when enabled
→ Capability prepares and injects untrusted recall once
→ model may call one of three explicit tools
→ Capability captures visible model/tool events when enabled
→ successful capture checkpoints may flush
→ Capability makes a final catch-up flush
→ Client closes with the run

自动召回读取最新 文本 用户提示词，并把查询限制为 8192 个字符。它 prepend 一条标有 untrusted 历史 evidence 的系统请求。复用旧 message_history 时，适配器会先移除能识别的旧 PowerContext 内容块，再加入当前运行的内容块。召回的证据会被替换，不会作为持久 Agent 历史内容不断累积。

召回的内容是证据，不是指令 权威来源。执行前应根据当前文件、API、能力和授权信息重新核对。

​

理解三个工具

每个工具都限制输入大小。这个上限只约束发送给 PowerContext 的内容，不会自动授予模型持久化权限。

工具	用途	输入上限
powercontext_search(query, limit=10, mode="auto")	搜索持久 Memory，并返回精确响应元数据	查询 1–8192 字符；上限 1–50
powercontext_remember(text, kind="agent-note", reason=None)	显式写入持久 Memory	文本 1–8192 字符；类型 1–128；reason 最多 512
powercontext_context(query)	为问题准备 fresh 有界上下文 packet	查询 1–8192 字符；上下文使用配置的字节预算

MAX_BYTES 与 CAPTURE_MAX_BYTES 的可配置范围都是 512–32768 UTF-8 字节。Character 上限和字节上限不是一回事；非 ASCII 内容可能先达到字节 cap。

​

每个运行只解析一次 Scope

构造参数 字符串或回调的优先级最高：

from pydantic_ai import RunContext
from powercontext_pydantic_ai import PowerContext


def tenant_scope(ctx: RunContext[dict[str, str]]) -> str:
    return f"tenant:{ctx.deps['tenant_id']}"


capability = PowerContext(scope_id=tenant_scope)

constructor string/callback
→ POWERCONTEXT_PYDANTIC_AI_SCOPE_ID
→ normalized Git origin
→ local project path hash

回调在运行绑定时执行一次，因此所有自动动作和工具都使用同一个 Scope。显式 Scope 超过共享上限时会改为 sha256:<digest>；过长的 派生的 Git Scope 会使用 git:sha256:<digest>。Scope 只负责选数据，不是认证或权限。

回调异常、缺少依赖、返回空值都发生在自动 HTTP fail-open 边界之前，可能阻止运行绑定。应单独测试解析器。

​

安全配置传输层

这些是未来适配器的 setting，不是安装命令：

export POWERCONTEXT_PYDANTIC_AI_BASE_URL=http://127.0.0.1:8000
export POWERCONTEXT_PYDANTIC_AI_TOKEN=opaque-server-token
export POWERCONTEXT_PYDANTIC_AI_SCOPE_ID=project:powercontext-101
export POWERCONTEXT_PYDANTIC_AI_MAX_BYTES=8000
export POWERCONTEXT_PYDANTIC_AI_CAPTURE_EVENTS=false

设置	默认值	范围或规则
TIMEOUT	10 秒	正数
MAX_BYTES	8000	512–32768
CAPTURE_EVENTS	false	Boolean
CAPTURE_CHECKPOINT_EVERY	5	1–100
CAPTURE_MAX_BYTES	8192	512–32768

TOKEN 必须是没有空白字符的 bare printable ASCII 令牌，不能带 Bearer 。基础 URL 必须使用 HTTP 或 HTTPS，不能含凭证、查询或片段；客户端对 非本机回环地址 明文 HTTP 的限制仍然生效。

​

决定采集可以发送什么

开启采集后，适配器可以发送：

• initial 文本 提示词；
• visible 模型 文本 和工具调用；
• completed 工具 argument 和结果。

Thinking/reasoning part 会被排除。疑似凭证 键、已知凭证环境值和配置的认证值会在 Source 采集前被脱敏。敏感代码、提示词、业务数据或工具结果仍可能保留；脱敏不是 DLP 边界。

已采集事件使用：

powercontext.pydantic-ai-capture-event/v1

采集创建 Source，不会直接产生已批准 Memory。如果 Server 配有生成，成功的检查点/最终刷新可能触发抽取，但生成的持久 knowledge 仍受 PowerContext 领域 规则 与 Review 规则 约束。

​

区分自动与显式失败

同一个传输错误，会因为操作发起方不同而产生不同的用户可见结果。用下表保留这个区别。

路径	失败行为
自动召回	客户端错误 fail-open；模型请求在没有已注入上下文的情况下继续
自动采集	客户端或 serialization 错误 fail-open；Agent 运行继续
Checkpoint/最终刷新	客户端错误、超时或游标无进展时 fail-open
显式工具	客户端Error 转为 ModelRetry；不会报告为空的成功结果
Binding 阶段的 Scope/配置	在自动 HTTP 边界前传播
第一次 401/403	发出一次有界警告，不含令牌或内容

召回、采集、刷新是彼此独立的辅助程序路径。它们失败并不说明 Scope 为空，fail-open 也不会绕过 URL 或令牌校验。

​

适配器不可用时使用 MCP

PowerContext MCP 不需要 Pydantic AI 专用软件包。它可以向 Agent 暴露显式操作，但不会复现该能力的自动 prepare_context、临时历史内容替换内容、事件采集或检查点/最终刷新。

​

当前不支持或尚未验证

项目	状态
公开 PyPI 安装	Unsupported；当前没有可用安装
从当前仓库执行 Git 子目录安装	Unsupported；最终 >=0.0.3 依赖会解析失败
Handoff 操作	Unsupported；此适配器不提供
Candidate Review 操作	Unsupported；此适配器不提供
直接 Experience 或 Skill 操作	Unsupported；此适配器不提供
Temporal、DBOS、Prefect 等持久执行	Not validated
在受支持 consumer 安装上运行真实模型提供方调用	Not validated；当前不存在该安装路径
把召回的证据持久化为可信 Agent 历史内容	Unsupported；它是不可信内容，每个运行都会替换

​

完成检查

采用未来的兼容版本前，确认：

• 适配器与兼容的正式版 powercontext[client] 软件包都能实际安装；
• 需要生命周期行为时选择 PowerContext，只要工具时选择 PowerContextToolset；
• 未完成隐私审查前，采集保持关闭；
• Scope 回调确定性、tenant-safe，并已在 fail-open 处理之外单独测试；
• 令牌是 bare printable ASCII，Server URL 通过传输层 restriction；
• 查询、工具上限和 上下文字节上限都会执行；
• 自动失败允许运行继续，显式工具失败仍然可见；
• 召回的证据被当作 temporary 不可信历史内容；
• 如果需要 Handoff、Review、Experience、Skill，通过另一个获准范围提供。

下一页进入 LangGraph。