> ## Documentation Index
> Fetch the complete documentation index at: https://powercontext.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Pydantic AI Agent 适配器（预览）

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

> [!WARNING]
>
> 预览，普通用户目前无法安装：`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，不是当前可运行的安装教程：

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 写法只安装同样的三个工具：

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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。这里的完成结果是准确识别边界，而不是成功安装一个尚未发布的软件包。

## 跟踪一次上限运行

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 历史内容不断累积。

> [!WARNING]
>
> 召回的内容是证据，不是指令 权威来源。执行前应根据当前文件、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

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

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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)
```

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
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，不是安装命令：

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 边界。

已采集事件使用：

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](https://powercontext.mintlify.site/zh/frameworks/langgraph.md)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.