ConectarConectarMicrosoft Agent Framework

MCP Client

Microsoft Agent Framework

Adicione contexto de memória XMemo delimitado e com proveniência ao Microsoft Agent Framework em Python, com captura explicitamente opcional.

Público-alvo e limites da integração

Este guia aborda o xmemo-agent-framework 0.2.0, um provedor de contexto Python para o Microsoft Agent Framework. Ele recupera contexto do XMemo delimitado e com proveniência imutável, além de oferecer um gancho de captura opcional independente. Trata-se de uma integração comunitária independente e não de um produto ou distribuição oficial da Microsoft. O pacote não publica nem implanta um servidor XMemo.

Pré-requisitos

Utilize o Python e o Microsoft Agent Framework Core. O extra opcional maf fixa agent-framework-core==1.21.0. Defina a origem do XMemo e a chave de API no ambiente do processo antes de criar uma conexão:

  • XMEMO_URL deve ser uma origem HTTPS.
  • XMEMO_API_KEY é enviada exclusivamente como um cabeçalho de Authorization.
  • O proprietário e o locatário efetivos são determinados pela autorização do servidor, e não por declarações de identidade fornecidas pelo cliente.

Instalação

Após a publicação do pacote, instale a versão fixada com o extra do Microsoft Agent Framework:

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

Configuração da conexão

Forneça a origem e a chave de API do XMemo ao processo que inicializa o agente:

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

Leitura do contexto do XMemo

A rota de leitura padrão é POST /v1/recall/context. Selecione uma rota diferente usando o valor documentado de ReadRoute conforme a necessidade de seu caso de uso:

  • ReadRoute.RECALL: POST /v1/recall/context (padrão).
  • 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)

Uso de ferramentas do XMemo via MCP

O provedor de contexto do Microsoft Agent Framework não substitui a superfície de ferramentas MCP do XMemo. Configure uma conexão MCP do XMemo separadamente quando o agente precisar de ferramentas explícitas de memória como remember, recall, search ou forget.

  • Consulte a [visão geral do MCP](/docs/mcp/overview) para conhecer os caminhos de conexão e perfis de ferramentas.
  • Consulte [remember](/docs/tools/remember), [recall](/docs/tools/recall), [search](/docs/tools/search) e [forget](/docs/tools/forget) para ferramentas de memória documentadas.
  • Para obter exemplos de configuração de clientes, consulte [Codex](/docs/mcp/codex) ou [GitHub Copilot](/docs/mcp/copilot).

Captura opcional (Opt-in)

A captura fica desativada por padrão. Ela só é executada quando um CaptureProvider separado é passado para o XMemoContextProvider com uma identidade de escrita autenticada pelo servidor e um par explícito de destino/comportamento. STATE requer state_key e EVENT requer event_type; ambos usam [a-z0-9][a-z0-9_.:-]{0,127}.

  • Target.REMEMBER envia POST /api/v1/remember com Behavior.SEMANTIC_KEY_SAME_CONTENT_NOOP.
  • Target.STATE envia POST /api/v1/update_state com Behavior.STATE_VERSIONED_UPSERT e exige uma state_key minúscula e delimitada.
  • Target.EVENT envia POST /api/v1/timeline/events com Behavior.EVENT_APPEND_NO_DEDUPE e exige um event_type minúsculo e delimitado.

Configuração do provedor de captura

Este exemplo habilita um único destino REMEMBER, onde resolved_identity é obtido de ResolvedIdentity.from_server_responses(...) em xmemo_agent_framework.capture. Utilize os pares de destino e comportamento documentados ao habilitar outro caminho de captura:

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 captura e isolamento de falhas

A captura aceita apenas conteúdo delimitado (8 KiB por padrão, configurável até o limite da política). Conteúdo não delimitado nunca é capturado. Segredos embutidos no conteúdo capturado, como chaves de API, tokens de portador, chaves privadas e padrões de segredos detectados, nunca são incluídos no corpo de escrita; a credencial de conexão permanece apenas no cabeçalho de Authorization. Candidatos não seguros são rejeitados caso a redação ainda resulte em uma requisição insegura.

  • O gancho envia no máximo uma solicitação de escrita por resposta do assistente e nunca repete uma escrita.
  • Um resultado de escrita rejeitado, com falha ou desconhecido é isolado do resultado do assistente, preservando a resposta entregue.
  • O host recebe metadados de captura higienizados em vez de detalhes ou credenciais brutas do servidor.

Proveniência e limites de autorização

Cada item injetado carrega proveniência imutável e um comprovante do adaptador. O texto recuperado representa contexto salvo não confiável, e não uma instrução de execução. A autorização do servidor controla o proprietário e o locatário efetivos; a captura não concede autoridade ao modelo nem altera o limite de autorização do provedor de leitura.

Requisitos do servidor

As rotas de leitura exigem o contrato REST correspondente do XMemo. A captura de REMEMBER, STATE e EVENT com respostas de escrita auditadas requer o servidor XMemo v0.4.436 ou posterior, que o serviço hospedado em xmemo.dev já executa.

Solução de problemas

Utilize os sinais documentados de compatibilidade e validação do pacote:

  • Se a importação de xmemo_agent_framework.maf gerar ImportError, instale o extra opcional maf para disponibilizar a dependência do framework hospedeiro.
  • XMEMO_URL deve ser uma origem HTTPS, e XMEMO_API_KEY é enviado somente no cabeçalho Authorization.
  • Se uma captura for rejeitada, falhar ou tiver resultado desconhecido, o resultado do assistente é preservado; o host recebe metadados sanitizados e a gravação não é repetida.

Origem: Integração com o Microsoft Agent Framework