# Microsoft Agent Framework

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

- Canonical: https://docs.xmemo.dev/pt-br/docs/connect/microsoft-agent-framework
- Locale: pt-BR
- Content-Locale: pt-BR
- Canonical-Content-Digest: b26ffb1f7eddfb7748bc9906f2f5b5988eaea1b8f16713552898166896fff2dc
- Edition-Digest: c0c3f502ee4710614e1e9ee11ee16339721bd86d74380b77594ceb671e55a517
- Source-Revision: sha256:5399e70deb5585a9984211e6023140506e30b65f4991a6b02e62390ec0816879

## 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:

```bash
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:

```bash
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.

```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)
```

## 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:

```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)
```

## 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.