> ## 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.

# 框架集成总览

> 第一次接入先选 LangGraph 或 LangChain。Server 推理和 Pydantic AI 预览适配器需要时再读。

> [!WARNING]
>
> 各路径的 packaging 状态不同。Pydantic AI Agent 适配器仍是预览，当前没有可用的独立安装方式。LangGraph 和 LangChain 只能从 source 安装，尚未发布到 PyPI。

PowerContext 有四条 Python 框架路径。它们共用 Server 契约，但不是同一种抽象。第一次接入 Agent 时，先选 LangGraph 或 LangChain；这两条路径可以从 source 安装。尤其要分清：Server 内的 Pydantic AI 推理只配置生成、嵌入和重排序，并不是 Agent 适配器。面向 Pydantic AI Agent 的预览适配器需要时再读，不要当作第一页。

## 四种边界，不是一套封装

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
flowchart LR
  APP[Agent application]
  PA[Pydantic AI Capability or Toolset]
  LG[LangGraph Tools + Recall + Scope]
  LC[LangChain Middleware]
  PC[PowerContext Server]
  INF[Pydantic AI inference boundary]
  DB[(Artifact storage)]

  APP --> PA
  APP --> LG
  APP --> LC
  PA --> PC
  LG --> PC
  LC --> PC
  PC --> INF
  PC --> DB
```

三个外部 Agent 集成都通过公开 Python Client 调用单独运行的 PowerContext Server，不会在 Agent 进程里再启动一份 Server。

Server 内部 Pydantic AI 推理位于 Server 组合内，为生成、嵌入和可选重排序提供边界。它不会给 Agent 增加工具、召回 Hook 或中间件。

## 成熟度与安装状态

| 路径 | 状态 | 当前安装方式 | 验证说明 |
| - | - | - | - |
| Server 内 Pydantic AI 推理 | Supported | 属于 Server builtin 运行时 | 本指南对可变外部模型提供方的真实往返验证 **Not validated** |
| Pydantic AI `PowerContext` / `PowerContextToolset` | 预览 | PyPI 与直接 Git 子目录安装当前都无法解析依赖 | 独立使用当前不可用 |
| LangGraph | 源码安装 仅 | Git 子目录或本地检出；未发布 PyPI | 从可变分支安装的可复现性 **Not validated**；应固定版本提交 |
| LangChain | 源码安装 仅 | Git 子目录或本地检出；未发布 PyPI | 从可变分支安装的可复现性 **Not validated**；应固定版本提交 |

> [!NOTE]
>
> **Not validated** 不等于 **Unsupported**。Not validated 表示这条路径可能可用，但缺少这里声明的验证证据；Unsupported 表示集成根本不提供该操作。

## 最小用法：先选择边界

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Need async LangGraph tools, recall, and per-run Scope?
  -> LangGraph
Need sync or async LangChain request recall, with optional completed-turn Source capture?
  -> LangChain
Need generation, embedding, or reranking inside the Server?
  -> Pydantic AI Server inference (read when needed)
Need agent-side Memory tools plus per-run recall?
  -> Pydantic AI Capability (Preview; read when needed)
Need only three Pydantic AI Memory tools?
  -> Pydantic AI Toolset (Preview; read when needed)
```

| 时机 | 需求 | 下一页 |
| - | - | - |
| 第一次接入 | 为异步图增加三个 Memory 工具和临时召回 | [LangGraph](https://powercontext.mintlify.site/zh/frameworks/langgraph.md) |
| 第一次接入 | 增加 request-level 召回，并可选采集已完成轮次 Source | [LangChain](https://powercontext.mintlify.site/zh/frameworks/langchain.md) |
| 需要时再读 | 配置 Source 抽取、Experience / Skill / Handoff 生成、嵌入或重排序 | [Pydantic AI Server 推理](https://powercontext.mintlify.site/zh/frameworks/pydantic-ai-server-inference.md) |
| 需要时再读 | 查看预览能力、工具集 与采集生命周期 | [Pydantic AI Agent 适配器](https://powercontext.mintlify.site/zh/frameworks/pydantic-ai.md) |
| 需要时再读 | 不使用框架生命周期 Hook，只暴露部分显式操作 | MCP；没有自动准备、采集或刷新 |

## 能力矩阵

先按生命周期选框架，再用矩阵确认该适配器是否具备你需要的精确行为。

| 集成 | Memory 工具 | 自动召回 | 自动采集 | 刷新 | 调用方式 | 每次运行 Scope |
| - | -: | - | - | - | - | -: |
| Server 内部 Pydantic AI 推理 | 不适用 | 不适用 | 否 | 否 | Server-internal 异步 | 不适用 |
| Pydantic AI `PowerContext` | 3 个 | 每运行成功注入一次后停止；空结果/失败时后续模型请求可能重试 | 可选 Source 采集，默认关 | 采集开启时检查点 + 最终 | Pydantic AI 运行生命周期 | 是 |
| Pydantic AI `PowerContextToolset` | 3 个 | 否 | 否 | 否 | Pydantic AI 运行生命周期 | 是 |
| LangGraph | 3 个 | 按 Scope + 用户消息 ID 缓存；没有 ID 时退回 文本 键 | 否 | 否 | **仅异步** | 是 |
| LangChain | 否 | 每模型请求 | 可选 successful 已完成轮次 Source 采集，默认关 | 否 | 同步 + 异步 | 是 |

采集的含义只是“发送 Source”。只有经过 Server 抽取并提交后，Source 才可能成为 Memory；抽取也可能无变更。能力矩阵不会把这些阶段合成一步。

## 执行流程

### Server 内部 Pydantic AI 推理

Server 收到领域操作后，只在需要相应能力时调用已配置的生成、嵌入或重排序边界。结果通过验证后，领域 workflow 才继续。模型提供方输出不能直接获得写入或批准 Artifact 的权限。

### Pydantic AI 能力与 工具集

`PowerContext` 每运行解析一次 Scope、准备一次上下文，把召回的内容块标为不可信证据，并暴露三个显式 Memory 工具。采集可选；开启后，成功事件会成为 Source，能力再尝试检查点和最终刷新。

`PowerContextToolset` 只提供三个工具，不包含自动准备、采集或刷新生命周期。

### LangGraph

`PowerContextRecall` 为最新用户轮次准备一次，并在 ReAct 工具循环内复用结果。完整模型输入写入 `llm_input_messages`，不写持久化的 `messages`。`powercontext_tools()` 提供三个 Memory 工具，`PowerContextScope` 则携带每次调用的 Scope 和 connection 覆盖值。

### LangChain

`PowerContextMiddleware` 在每个模型请求前准备，只覆盖值当前请求的 `system_message`，不修改 Agent 状态。开启 `auto_capture=True` 后，成功运行结束时会把最新版本用户消息和最终 non-empty 助手结果存成一条已完成轮次 Source。它既不添加 Memory 工具，也不会刷新这条 Source。

## Scope、令牌与传输层规则

这些设置共同构成安全边界。Scope 应来自经过认证的应用状态，令牌不能进入模型可见数据，离开本机回环地址后必须使用 HTTPS。

| 集成 | Scope 优先顺序 |
| - | - |
| Pydantic AI 预览 | 构造参数 字符串/回调 → 环境变量 → 规范化的 Git 来源 → 本地 project-path 哈希 |
| LangGraph | 每次运行 `PowerContextScope` → 环境变量 → 规范化的网络 Git 远程 → 错误 |
| LangChain | 每次运行 `PowerContextScope` → 环境变量 → 规范化的网络 Git 远程 → 错误 |

Pydantic AI 会把超过公开上限的显式 Scope 哈希成有界 ID。LangGraph 与 LangChain 也会约束显式值，但都没有本地后备路径。多租户服务应从已认证的租户/项目映射派生 Scope，并按运行显式传入。

三个适配器都接收裸令牌：

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
export POWERCONTEXT_LANGGRAPH_TOKEN="opaque-token"
```

不要加 `Bearer` 前缀，也不要填完整授权信息请求头。`PowerContextClient` 会添加 `Authorization: Bearer ...`。Pydantic AI 适配器会严格校验这项约定；LangGraph 和 LangChain 会在文档中说明，但适配器边界不会严格验证令牌语法。

非本机回环地址 HTTP 必须使用 HTTPS，除非调用方自己提供传输层，并显式声明其安全性可信。令牌不能让明文传输层变安全。

## 失败、隐私与信任边界

自动召回，以及适配器自己执行的采集/刷新，都属于辅助路径。它们的 Server-call 失败会 fail-open，因此 中断 不会替换模型结果，也不会中断宿主任务。配置和 Scope 回调可能在这个边界之前失败，需要单独验证。

显式失败仍对模型可见：

* Pydantic AI 工具抛出 `ModelRetry`；
* LangGraph 工具返回简短、模型可见的的错误字符串；
* LangChain 适配器不提供 PowerContext 工具。

401/403 不是“空 Memory”。诊断信息必须有界，并排除令牌、Scope 内容、查询和响应体。

召回的内容可能含旧用户/模型 文本。应把它当作不可信证据，保持临时状态，绝不能把召回的内容块持久化到框架状态或对话历史内容。当前系统/用户指令始终优先，召回的 文本 也不能授予工具权限。

采集还需要单独的隐私决定。Pydantic AI 会排除 thinking part，并脱敏已知凭证结构，但这不是完整 DLP。LangChain 不承诺全面敏感信息脱敏。LangGraph 不做采集。

## 当前不支持或未验证

| 项目 | 状态 |
| - | - |
| 这些 Agent 适配器中的 Handoff、Candidate Review、Experience 或 Skill 操作 | **Unsupported** |
| LangGraph 自动采集或刷新 | **Unsupported** |
| LangChain PowerContext 工具或刷新 | **Unsupported**；采集只保存 Source |
| Pydantic AI 的 Temporal、DBOS、Prefect 等持久 executor | **Not validated** |
| 从可变 source 分支进行可复现部署 | **Not validated**；应固定版本提交与 dependencies |
| 文档证据中的 Server 推理真实外部模型提供方往返验证 | **Not validated** |

## 完成检查

* 所选路径与实际边界一致：Server 推理、Pydantic 适配器、图或中间件。
* 软件包状态可接受；需要可复现时，源码安装已固定版本。
* 每个运行收到预期 Scope，并有跨租户隔离负向测试。
* 令牌保持裸值且不进入状态/历史内容；远程传输层使用 HTTPS 或显式可信传输层。
* 召回的证据保持临时且不可信。
* 自动 fail-open 与显式工具失败分开测试。
* 采集、刷新与 Memory 按三个阶段分别验证。
* 部署文档没有混淆 Unsupported 与 Not validated。

> [!TIP]
>
> 只要有一项还不确定，就先停在集成的无模型或仅 Server 检查，不要继续叠加外部模型提供方。

> [card] [LangGraph](https://powercontext.mintlify.site/zh/frameworks/langgraph.md)
>
> 为异步图增加三个 Memory 工具和按轮次的临时召回。从 source 安装。

> [card] [LangChain](https://powercontext.mintlify.site/zh/frameworks/langchain.md)
>
> 为每次模型请求增加召回，并可按需捕获已完成轮次 Source。从 source 安装。

需要配置 Server 内的生成、嵌入或重排序时，再读 [Pydantic AI Server 推理](https://powercontext.mintlify.site/zh/frameworks/pydantic-ai-server-inference.md)。[Pydantic AI Agent 适配器](https://powercontext.mintlify.site/zh/frameworks/pydantic-ai.md) 仍是预览，当前没有可用的独立安装方式，不要当作第一页。


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