# Microsoft Agent Framework

明示的なオプトインキャプチャを備えた、Python 版 Microsoft Agent Framework 向けの有界で来歴付き XMemo メモリコンテキストの追加。

- Canonical: https://docs.xmemo.dev/ja/docs/connect/microsoft-agent-framework
- Locale: ja-JP
- Content-Locale: ja-JP
- Canonical-Content-Digest: b26ffb1f7eddfb7748bc9906f2f5b5988eaea1b8f16713552898166896fff2dc
- Edition-Digest: 4ded9410881555f0e3ae31f3ed139db04da2f34466b29096e9572e8ee72fb4a3
- Source-Revision: sha256:5399e70deb5585a9984211e6023140506e30b65f4991a6b02e62390ec0816879

## 対象読者と統合の境界

本ガイドでは、Microsoft Agent Framework 向けの Python コンテキストプロバイダーである xmemo-agent-framework 0.2.0 について説明します。有界で来歴を保持する XMemo コンテキストを取得し、個別のオプトインキャプチャフックを提供します。これは独立したコミュニティ統合であり、マイクロソフトの公式製品または配布物ではありません。本パッケージは XMemo サーバーの公開やデプロイを行いません。

## 前提条件

Python および Microsoft Agent Framework Core を使用します。オプションの maf エクストラは agent-framework-core==1.21.0 を固定します。接続を作成する前に、プロセス環境に XMemo のオリジンと API キーを設定してください。

- XMEMO_URL は HTTPS オリジンである必要があります。
- XMEMO_API_KEY は Authorization ヘッダーとしてのみ送信されます。
- 有効な所有者とテナントは、クライアントが提供するアイデンティティクレームではなく、サーバーの認証によって決定されます。

## インストール

パッケージが公開された後は、Microsoft Agent Framework エクストラを指定して固定バージョンをインストールします：

```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 の値で別のルートを選択してください。host agent の context-provider 設定に 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 に渡された場合にのみ実行されます。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 ターゲットを有効にしており、resolved_identity は xmemo_agent_framework.capture の ResolvedIdentity.from_server_responses(...) から取得されます。別のキャプチャパスを有効にする場合は、文書化されたターゲットと動作のペアを使用してください：

```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、ポリシー制限まで設定可能）。無制限のコンテンツはキャプチャされません。API キー、ベアラートークン、秘密鍵、検出されたシークレットパターンなどの機密情報は、書き込みボディに含まれません。接続資格情報は Authorization ヘッダーにのみ保持されます。安全でない候補は、墨消し後も安全でない場合は拒否されます。

- フックはアシスタントの応答ごとに最大 1 回の書き込み要求を送信し、書き込みを再試行しません。
- 拒否、失敗、または不明な書き込み結果はアシスタントの結果から分離され、結果自体には影響しません。
- ホストは生のサーバー詳細や資格情報ではなく、サニタイズされたキャプチャメタデータを受け取ります。

## 来歴と認証境界

注入されるすべての項目は、不変の来歴とアダプター受領書を保持します。取得されたテキストは信頼できない保存されたコンテキストであり、指示ではありません。サーバー認証が有効な所有者とテナントを管理します。キャプチャによってモデルの権限が付与されることはなく、読み取りプロバイダーの認可境界が変更されることもありません。

## サーバー要件

読み取りルートには対応する XMemo REST contract が必要です。REMEMBER、STATE、EVENT のキャプチャと監査済み書き込み応答には XMemo サーバー v0.4.436 以降が必要であり、ホスト型サービス xmemo.dev ではすでに稼働しています。

## トラブルシューティング

パッケージに記載されている互換性および検証シグナルを使用してください：

- xmemo_agent_framework.maf のインポートで ImportError が発生する場合は、ホストフレームワークの依存関係を利用できるよう、オプションの maf エクストラをインストールしてください。
- XMEMO_URL は HTTPS オリジンである必要があり、XMEMO_API_KEY は Authorization ヘッダーでのみ送信されます。
- キャプチャが拒否、失敗、または不明な結果になった場合も、アシスタントの結果は保持されます。ホストにはサニタイズ済みメタデータが渡され、書き込みは再試行されません。