VerbindenVerbindenMicrosoft Agent Framework

MCP Client

Microsoft Agent Framework

Fügen Sie Microsoft Agent Framework in Python begrenzten, herkunftsnachweisbaren XMemo-Speicherkontext mit expliziter Opt-in-Erfassung hinzu.

Zielgruppe und Integrationsgrenzen

Dieser Leitfaden beschreibt xmemo-agent-framework 0.2.0, einen Python-Kontextanbieter für das Microsoft Agent Framework. Er ruft begrenzten, herkunftsnachweisbaren XMemo-Kontext ab und stellt einen separaten, zustimmungspflichtigen (Opt-in) Erfassungs-Hook bereit. Hierbei handelt es sich um eine unabhängige Community-Integration und kein offizielles Microsoft-Produkt oder eine offizielle Distribution. Das Paket veröffentlicht oder implementiert keinen XMemo-Server.

Voraussetzungen

Verwenden Sie Python und Microsoft Agent Framework Core. Das optionale maf-Extra fixiert agent-framework-core==1.21.0. Konfigurieren Sie den XMemo-Origin und den API-Schlüssel in der Prozessumgebung, bevor Sie eine Verbindung herstellen:

  • XMEMO_URL muss ein HTTPS-Origin sein.
  • XMEMO_API_KEY wird ausschließlich als Authorization-Header übertragen.
  • Die tatsächlichen Eigentümer und Mandanten werden durch die Server-Autorisierung bestimmt, nicht durch vom Client übermittelte Identitätsansprüche.

Installation

Nach der Veröffentlichung des Pakets installieren Sie die fixierte Version mit dem Microsoft Agent Framework-Extra:

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

Verbindung konfigurieren

Stellen Sie dem Prozess, der den Agenten startet, den XMemo-Origin und den API-Schlüssel bereit:

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

XMemo-Kontext lesen

Die Standard-Lese-Route ist POST /v1/recall/context. Wählen Sie bei Bedarf über den dokumentierten ReadRoute-Wert eine andere Route aus:

  • ReadRoute.RECALL: POST /v1/recall/context (Standard).
  • ReadRoute.PROJECT: POST /v1/projects/{project_id}/context.
  • ReadRoute.SEARCH: GET /v1/memories/search.
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)

XMemo-Tools über MCP nutzen

Der Microsoft Agent Framework-Kontextanbieter ersetzt nicht die MCP-Tool-Oberfläche von XMemo. Konfigurieren Sie eine separate XMemo MCP-Verbindung, wenn der Agent explizite Speicher-Tools wie remember, recall, search oder forget benötigt.

  • Siehe [MCP-Übersicht](/docs/mcp/overview) für Verbindungspfade und Tool-Profile.
  • Siehe [remember](/docs/tools/remember), [recall](/docs/tools/recall), [search](/docs/tools/search) und [forget](/docs/tools/forget) für die dokumentierten Speicher-Tools.
  • Beispiele für Client-Konfigurationen finden Sie unter [Codex](/docs/mcp/codex) oder [GitHub Copilot](/docs/mcp/copilot).

Erfassung ist zustimmungspflichtig (Opt-in)

Die Erfassung ist standardmäßig deaktiviert. Sie wird nur ausgeführt, wenn ein separater CaptureProvider mit einer vom Server aufgelösten Schreibidentität und einem expliziten Ziel-/Verhaltenspaar an XMemoContextProvider übergeben wird. STATE erfordert state_key und EVENT erfordert event_type; beide verwenden [a-z0-9][a-z0-9_.:-]{0,127}.

  • Target.REMEMBER sendet POST /api/v1/remember mit Behavior.SEMANTIC_KEY_SAME_CONTENT_NOOP.
  • Target.STATE sendet POST /api/v1/update_state mit Behavior.STATE_VERSIONED_UPSERT und erfordert einen begrenzten state_key in Kleinbuchstaben.
  • Target.EVENT sendet POST /api/v1/timeline/events mit Behavior.EVENT_APPEND_NO_DEDUPE und erfordert einen begrenzten event_type in Kleinbuchstaben.

Erfassungsanbieter konfigurieren

Dieses Beispiel aktiviert ein einzelnes REMEMBER-Ziel, wobei resolved_identity über ResolvedIdentity.from_server_responses(...) aus xmemo_agent_framework.capture bezogen wird. Verwenden Sie die dokumentierten Ziel- und Verhaltenspaare, wenn Sie einen anderen Erfassungspfad aktivieren:

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)

Erfassungsgrenzen und Fehlerisolation

Die Erfassung akzeptiert nur begrenzte Inhalte (standardmäßig 8 KiB, konfigurierbar bis zum Richtlinienlimit). Unbegrenzte Inhalte werden niemals erfasst. In den erfassten Inhalten enthaltene Geheimnisse (einschließlich API-Schlüssel, Bearer-Token, private Schlüssel und erkannte Geheimnismuster) werden niemals in den Schreib-Body aufgenommen; die Verbindungsanmeldeinformationen verbleiben ausschließlich im Authorization-Header. Unsichere Kandidaten werden abgewiesen, wenn die Schwärzung die Anfrage weiterhin unsicher hinterlässt.

  • Der Hook sendet maximal eine Schreibanforderung pro Assistentenantwort und wiederholt Schreibvorgänge niemals.
  • Ein abgewiesenes, fehlgeschlagenes oder unbekanntes Schreibergebnis wird vom Assistentenergebnis isoliert, sodass die Ausgabe geschützt bleibt.
  • Der Host erhält bereinigte Erfassungsmetadaten anstelle von Rohdaten oder Anmeldeinformationen des Servers.

Herkunftsnachweis und Autorisierungsgrenzen

Jedes injizierte Element trägt einen unveränderlichen Herkunftsnachweis und eine Adapter-Quittung. Der abgerufene Text stellt nicht vertrauenswürdigen gespeicherten Kontext dar, keine Handlungsanweisung. Die Server-Autorisierung steuert den tatsächlichen Eigentümer und Mandanten; die Erfassung gewährt dem Modell keine Autorität und ändert nicht die Autorisierungsgrenze des Leseanbieters.

Serveranforderungen

Lese-Routen erfordern den entsprechenden XMemo-REST-Vertrag. Die REMEMBER-, STATE- und EVENT-Erfassung mit auditierten Schreibantworten erfordert den XMemo-Server v0.4.436 oder neuer, welcher auf dem gehosteten Dienst unter xmemo.dev bereits ausgeführt wird.

Fehlerbehebung

Nutzen Sie die dokumentierten Kompatibilitäts- und Validierungssignale des Pakets:

  • Wenn der Import von xmemo_agent_framework.maf einen ImportError auslöst, installieren Sie das optionale maf-Extra, damit die Abhängigkeit des Host-Frameworks verfügbar ist.
  • XMEMO_URL muss ein HTTPS-Ursprung sein, und XMEMO_API_KEY wird ausschließlich im Authorization-Header gesendet.
  • Bei abgelehnter, fehlgeschlagener oder unbekannter Erfassung bleibt das Ergebnis des Assistenten erhalten; der Host erhält bereinigte Metadaten, und der Schreibvorgang wird nicht wiederholt.

Quelle: Microsoft Agent Framework-Integration