ConnecterConnecterMicrosoft Agent Framework

MCP Client

Microsoft Agent Framework

Ajoutez un contexte de mémoire XMemo délimité et porteur de provenance à Microsoft Agent Framework en Python, avec capture explicitement sur option.

Public visé et limites de l'intégration

Ce guide décrit xmemo-agent-framework 0.2.0, un fournisseur de contexte Python pour Microsoft Agent Framework. Il permet de récupérer un contexte XMemo borné et accompagné d'une provenance immuable, et propose un hook de capture distinct sur option (opt-in). Il s'agit d'une intégration communautaire indépendante et non d'un produit ou d'une distribution officielle de Microsoft. Ce package ne publie ni ne déploie de serveur XMemo.

Conditions préalables

Utilisez Python et Microsoft Agent Framework Core. L'extra optionnel maf verrouille agent-framework-core==1.21.0. Définissez l'origine XMemo et la clé API dans l'environnement du processus avant de créer une connexion :

  • XMEMO_URL doit impérativement être une origine HTTPS.
  • XMEMO_API_KEY est transmise exclusivement dans un en-tête Authorization.
  • Le propriétaire et le locataire effectifs sont déterminés par l'autorisation du serveur, et non par des déclarations d'identité fournies par le client.

Installation

Après la publication du package, installez la version épinglée avec l'extra Microsoft Agent Framework :

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

Configuration de la connexion

Transmettez l'origine et la clé API XMemo au processus qui démarre l'agent :

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

Lecture du contexte XMemo

La route de lecture par défaut est POST /v1/recall/context. Choisissez une autre route avec la valeur documentée de ReadRoute lorsque votre cas d'usage le nécessite :

  • ReadRoute.RECALL : POST /v1/recall/context (par défaut).
  • 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)

Utilisation des outils XMemo via MCP

Le fournisseur de contexte Microsoft Agent Framework ne remplace pas la surface d'outils MCP de XMemo. Configurez séparément une connexion MCP XMemo lorsque l'agent a besoin d'outils de mémoire explicites tels que remember, recall, search ou forget.

  • Consultez la [vue d'ensemble MCP](/docs/mcp/overview) pour connaître les chemins de connexion et les profils d'outils.
  • Consultez [remember](/docs/tools/remember), [recall](/docs/tools/recall), [search](/docs/tools/search) et [forget](/docs/tools/forget) pour la documentation des outils de mémoire.
  • Pour des exemples de configuration de client, reportez-vous à [Codex](/docs/mcp/codex) ou [GitHub Copilot](/docs/mcp/copilot).

Capture sur option (Opt-in)

La capture est désactivée par défaut. Elle ne s'exécute que lorsqu'un CaptureProvider distinct est transmis à XMemoContextProvider avec une identité d'écriture résolue par le serveur et une paire cible/comportement explicite. STATE requiert state_key et EVENT requiert event_type ; les deux utilisent [a-z0-9][a-z0-9_.:-]{0,127}.

  • Target.REMEMBER envoie POST /api/v1/remember avec Behavior.SEMANTIC_KEY_SAME_CONTENT_NOOP.
  • Target.STATE envoie POST /api/v1/update_state avec Behavior.STATE_VERSIONED_UPSERT et requiert une state_key bornée en minuscules.
  • Target.EVENT envoie POST /api/v1/timeline/events avec Behavior.EVENT_APPEND_NO_DEDUPE et requiert un event_type borné en minuscules.

Configuration du fournisseur de capture

Cet exemple active une cible REMEMBER unique, où resolved_identity provient de ResolvedIdentity.from_server_responses(...) dans xmemo_agent_framework.capture. Utilisez les paires documentées de cible et de comportement lors de l'activation d'un autre chemin de capture :

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)

Limites de capture et isolation des défaillances

La capture n'accepte que du contenu délimité (8 Kio par défaut, configurable jusqu'à la limite de la politique). Tout contenu non borné n'est jamais capturé. Les secrets contenus dans le contenu capturé (clés API, jetons porteurs, clés privées, motifs de secrets détectés) ne sont jamais inclus dans le corps d'écriture ; le secret de connexion reste exclusivement dans l'en-tête Authorization. Les candidats non sécurisés sont rejetés si le caviardage ne permet pas de sécuriser la requête.

  • Le hook n'envoie au maximum qu'une seule requête d'écriture par réponse d'assistant et ne réessaie jamais une écriture.
  • Tout résultat d'écriture rejeté, échoué ou inconnu est isolé du résultat de l'assistant, préservant la réponse fournie.
  • L'hôte reçoit des métadonnées de capture assainies plutôt que des détails bruts du serveur ou des informations d'identification.

Provenance et limites d'autorisation

Chaque élément injecté comporte une provenance immuable et un reçu d'adaptateur. Le texte récupéré constitue un contexte enregistré non fiable, et non une instruction. L'autorisation du serveur détermine le propriétaire et le locataire effectifs ; la capture ne confère aucune autorité au modèle et ne modifie pas le périmètre d'autorisation du fournisseur de lecture.

Exigences relatives au serveur

Les routes de lecture nécessitent le contrat REST XMemo correspondant. La capture de REMEMBER, STATE et EVENT avec réponses d'écriture auditées nécessite le serveur XMemo v0.4.436 ou ultérieur, que le service hébergé sur xmemo.dev exécute déjà.

Dépannage

Utilisez les signaux de compatibilité et de validation documentés du package :

  • Si l’import de xmemo_agent_framework.maf lève ImportError, installez l’extra facultatif maf pour disposer de la dépendance du framework hôte.
  • XMEMO_URL doit être une origine HTTPS et XMEMO_API_KEY est envoyé uniquement dans l’en-tête Authorization.
  • Si le résultat de capture est rejeté, en échec ou inconnu, le résultat de l’assistant est conservé ; l’hôte reçoit des métadonnées assainies et l’écriture n’est pas réessayée.

Source : Intégration Microsoft Agent Framework