# Microsoft Agent Framework

为 Python 版 Microsoft Agent Framework 添加范围受限且带有来源信息的 XMemo 记忆上下文；只有明确选择启用时才会捕获内容。

- Canonical: https://docs.xmemo.dev/zh/docs/connect/microsoft-agent-framework
- Locale: zh-CN
- Content-Locale: zh-CN
- Canonical-Content-Digest: b26ffb1f7eddfb7748bc9906f2f5b5988eaea1b8f16713552898166896fff2dc
- Edition-Digest: abcabcee1f277d0fad2435752889c7e247de923d664fc02e42b30eebeebe956f
- Source-Revision: sha256:5399e70deb5585a9984211e6023140506e30b65f4991a6b02e62390ec0816879

## 适用对象与集成边界

本指南介绍 xmemo-agent-framework 0.2.0，这是面向 Microsoft Agent Framework 的 Python 上下文提供程序。它会检索范围受限且带有来源信息的 XMemo 上下文，并提供单独的选择性捕获钩子。这是一个独立的社区集成，并非 Microsoft 官方产品或发行版。此软件包不会发布或部署 XMemo 服务器。

## 前提条件

使用 Python 和 Microsoft Agent Framework Core。可选的 maf extra 固定依赖 agent-framework-core==1.21.0。创建连接前，请在进程环境中设置 XMemo 源站和 API 密钥。

- XMEMO_URL 必须是 HTTPS 源站。
- XMEMO_API_KEY 仅通过 Authorization 请求头发送。
- 有效的 owner 和 tenant 由服务器授权确定，而非由客户端提供的身份声明确定。

## 安装

软件包发布后，安装包含 Microsoft Agent Framework extra 的固定版本：

```bash
pip install "xmemo-agent-framework[maf]==0.2.0"
```

## 配置连接

将 XMemo 源站和 API 密钥提供给启动代理的进程：

```bash
export XMEMO_URL="https://your-xmemo-origin"
export XMEMO_API_KEY="your-api-key"
```

## 读取 XMemo 上下文

默认路由为 POST /v1/recall/context。需要时，可使用文档中的 ReadRoute 值选择其他路由。将 context_provider 传入 host agent 的 context-provider 配置，并在 host session 结束时关闭 connection：

- ReadRoute.RECALL：POST /v1/recall/context（默认）。
- ReadRoute.PROJECT：POST /v1/projects/{project_id}/context。
- ReadRoute.SEARCH：GET /v1/memories/search。

```python
import os
from xmemo_agent_framework import Connection, Policy, Provider, ReadRoute
from xmemo_agent_framework.maf import XMemoContextProvider

connection = Connection(os.environ["XMEMO_URL"], os.environ["XMEMO_API_KEY"])
read_provider = Provider(
    connection,
    Policy(
        recall_enabled=True,
        route=ReadRoute.RECALL,
        scope="tenant:project:my-project",
        max_items=8,
        max_tokens=2000,
    ),
)
context_provider = XMemoContextProvider(read_provider)
```

## 通过 MCP 使用 XMemo 工具

Microsoft Agent Framework 上下文提供程序不会取代 XMemo 的 MCP 工具接口。如果代理需要 remember、recall、search 或 forget 等显式记忆工具，请另外配置 XMemo MCP 连接。

- 连接方式和工具配置请从 [MCP 概览](/docs/mcp/overview) 开始了解。
- 文档中的记忆工具参见 [remember](/docs/tools/remember)、[recall](/docs/tools/recall)、[search](/docs/tools/search) 和 [forget](/docs/tools/forget)。
- 客户端配置示例请参见 [Codex](/docs/mcp/codex) 或 [GitHub Copilot](/docs/mcp/copilot)。

## 捕获需要主动启用

捕获默认关闭。只有将单独的 CaptureProvider 传给 XMemoContextProvider，并提供由服务器解析的写入身份以及明确的 target/behavior 组合时，才会执行捕获。STATE 需要 state_key，EVENT 需要 event_type；二者都必须符合 [a-z0-9][a-z0-9_.:-]{0,127}。

- Target.REMEMBER 使用 Behavior.SEMANTIC_KEY_SAME_CONTENT_NOOP 向 POST /api/v1/remember 发送请求。
- Target.STATE 使用 Behavior.STATE_VERSIONED_UPSERT 向 POST /api/v1/update_state 发送请求，并要求提供范围受限的小写 state_key。
- Target.EVENT 使用 Behavior.EVENT_APPEND_NO_DEDUPE 向 POST /api/v1/timeline/events 发送请求，并要求提供范围受限的小写 event_type。

## 配置捕获提供程序

此示例只启用一个 REMEMBER target，其中的 resolved_identity 来自 xmemo_agent_framework.capture 中的 ResolvedIdentity.from_server_responses(...)。启用其他捕获路径时，请使用文档中列出的 target 和 behavior 组合：

```python
from xmemo_agent_framework.capture import (
    Behavior,
    CapturePolicy,
    CaptureProvider,
    Target,
)

capture = CaptureProvider(
    connection,
    CapturePolicy(
        enabled=True,
        target=Target.REMEMBER,
        behavior=Behavior.SEMANTIC_KEY_SAME_CONTENT_NOOP,
    ),
    identity=resolved_identity,
)
context_provider = XMemoContextProvider(read_provider, capture=capture)
```

## 捕获限制与故障隔离

捕获只接受范围受限的内容（默认 8 KiB，可配置至 policy limit）。不会捕获无界内容。API 密钥、bearer token、私钥和检测到的机密模式都不会写入请求正文；连接凭据只保留在 Authorization 请求头中。如果 redaction 后请求仍不安全，则会拒绝该候选内容。

- 每条 assistant 回复最多发送一次写入请求，且不会重试。
- 写入被拒绝、失败或结果未知，都不会改变 assistant 的回复。
- host 收到的是经过清理的捕获 metadata，不包含原始服务器或凭据详情。

## 来源信息与授权

每个注入的条目都带有不可变的来源信息和 adapter receipt。检索到的文本是保存的不可信上下文，不是指令。有效的 owner 和 tenant 由服务器授权决定；捕获不会赋予模型权限，也不会改变 read provider 的授权边界。

## 服务器要求

读取路由需要相应的 XMemo REST contract。REMEMBER、STATE 和 EVENT 捕获及其经过审计的写入响应需要 XMemo 服务端 v0.4.436 或更新版本，托管服务 xmemo.dev 已在运行该版本。

## 故障排查

请查看软件包文档中列出的兼容性和验证信号：

- 如果导入 xmemo_agent_framework.maf 时出现 ImportError，请安装可选的 maf extra，以提供宿主框架依赖项。
- XMEMO_URL 必须是 HTTPS 源站，XMEMO_API_KEY 仅通过 Authorization 标头发送。
- 如果捕获被拒绝、失败或结果未知，助手的结果仍会保留；宿主只会收到已清理的元数据，写入不会重试。