# Microsoft Agent Framework

Agregue contexto de memoria XMemo limitado y con procedencia a Microsoft Agent Framework en Python, con captura explícitamente opcional.

- Canonical: https://docs.xmemo.dev/es/docs/connect/microsoft-agent-framework
- Locale: es-ES
- Content-Locale: es-ES
- Canonical-Content-Digest: b26ffb1f7eddfb7748bc9906f2f5b5988eaea1b8f16713552898166896fff2dc
- Edition-Digest: eaecaef4e6a835dc435c30481f357d7a0340697588864dda5b681b7eeeeb6f5f
- Source-Revision: sha256:5399e70deb5585a9984211e6023140506e30b65f4991a6b02e62390ec0816879

## Destinatarios y límites de la integración

Esta guía cubre xmemo-agent-framework 0.2.0, un proveedor de contexto de Python para Microsoft Agent Framework. Recupera contexto de XMemo acotado y con procedencia verificable, y ofrece un enlace de captura opcional e independiente. Se trata de una integración comunitaria independiente y no de un producto o distribución oficial de Microsoft. El paquete no publica ni implementa un servidor XMemo.

## Requisitos previos

Utilice Python y Microsoft Agent Framework Core. El extra opcional maf fija agent-framework-core==1.21.0. Establezca el origen de XMemo y la clave API en el entorno del proceso antes de crear una conexión:

- XMEMO_URL debe ser un origen HTTPS.
- XMEMO_API_KEY se envía únicamente como un encabezado de Authorization.
- El propietario y el inquilino efectivos se determinan mediante la autorización del servidor, no por reclamos de identidad suministrados por el cliente.

## Instalación

Tras la publicación del paquete, instale la versión fijada con el extra de Microsoft Agent Framework:

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

## Configuración de la conexión

Proporcione el origen y la clave API de XMemo al proceso que inicia el agente:

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

## Lectura del contexto de XMemo

La ruta de lectura predeterminada es POST /v1/recall/context. Elija una ruta diferente mediante el valor de ReadRoute documentado cuando el caso de uso lo requiera:

- ReadRoute.RECALL: POST /v1/recall/context (predeterminado).
- 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 herramientas de XMemo mediante MCP

El proveedor de contexto de Microsoft Agent Framework no sustituye la superficie de herramientas MCP de XMemo. Configure una conexión MCP de XMemo independiente si el agente necesita herramientas de memoria explícitas como remember, recall, search o forget.

- Consulte la [descripción general de MCP](/docs/mcp/overview) para conocer las rutas de conexión y perfiles de herramientas.
- Consulte [remember](/docs/tools/remember), [recall](/docs/tools/recall), [search](/docs/tools/search) y [forget](/docs/tools/forget) para las herramientas de memoria documentadas.
- Para ejemplos de configuración de clientes, consulte [Codex](/docs/mcp/codex) o [GitHub Copilot](/docs/mcp/copilot).

## Captura opcional (Opt-in)

La captura está desactivada de forma predeterminada. Solo se ejecuta cuando se pasa un CaptureProvider independiente a XMemoContextProvider con una identidad de escritura resuelta por el servidor y un par explícito de objetivo/comportamiento. STATE requiere state_key y EVENT requiere event_type; ambos usan [a-z0-9][a-z0-9_.:-]{0,127}.

- Target.REMEMBER envía POST /api/v1/remember con Behavior.SEMANTIC_KEY_SAME_CONTENT_NOOP.
- Target.STATE envía POST /api/v1/update_state con Behavior.STATE_VERSIONED_UPSERT y requiere una state_key en minúsculas y acotada.
- Target.EVENT envía POST /api/v1/timeline/events con Behavior.EVENT_APPEND_NO_DEDUPE y requiere un event_type en minúsculas y acotado.

## Configuración del proveedor de captura

Este ejemplo habilita un único objetivo REMEMBER, donde resolved_identity se obtiene de ResolvedIdentity.from_server_responses(...) en xmemo_agent_framework.capture. Utilice los pares de destino y comportamiento documentados al habilitar otra ruta 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)
```

## Límites de captura y aislamiento de fallos

La captura solo acepta contenido acotado (8 KiB por defecto, configurable hasta el límite de la política). El contenido no acotado nunca se captura. Los secretos incrustados en el contenido capturado, incluidas claves API, tokens de portador, claves privadas y patrones de secretos detectados, nunca se incluyen en el cuerpo de escritura; la credencial de conexión permanece únicamente en el encabezado de Authorization. Los candidatos no seguros se rechazan si la redacción aún deja la solicitud insegura.

- El enlace envía como máximo una solicitud de escritura por respuesta del asistente y nunca reintenta una escritura.
- Un resultado de escritura rechazado, fallido o desconocido se aísla del resultado del asistente, protegiendo la respuesta entregada.
- El host recibe metadatos de captura saneados en lugar de detalles o credenciales sin procesar del servidor.

## Procedencia y límites de autorización

Cada elemento inyectado incluye procedencia inmutable y un recibo del adaptador. El texto recuperado constituye contexto guardado no confiable, no una instrucción. La autorización del servidor controla el propietario y el inquilino efectivos; la captura no concede autoridad al modelo ni modifica el límite de autorización del proveedor de lectura.

## Requisitos del servidor

Las rutas de lectura requieren el contrato REST correspondiente de XMemo. La captura de REMEMBER, STATE y EVENT con respuestas de escritura auditadas requiere el servidor XMemo v0.4.436 o posterior, que el servicio alojado en xmemo.dev ya ejecuta.

## Resolución de problemas

Utilice las señales de compatibilidad y validación documentadas del paquete:

- Si al importar xmemo_agent_framework.maf se produce ImportError, instale el extra opcional maf para que esté disponible la dependencia del framework host.
- XMEMO_URL debe ser un origen HTTPS, y XMEMO_API_KEY se envía únicamente en el encabezado Authorization.
- Si la captura se rechaza, falla o queda en estado desconocido, se conserva el resultado del asistente; el host recibe metadatos depurados y no se reintenta la escritura.