연결연결Microsoft Agent Framework

MCP Client

Microsoft Agent Framework

Python의 Microsoft Agent Framework에 범위가 제한되고 출처 정보가 포함된 XMemo 메모리 컨텍스트를 추가하며, 캡처는 명시적으로 선택한 경우에만 활성화합니다.

대상 및 통합 경계

이 안내서는 Microsoft Agent Framework용 Python 컨텍스트 공급자인 xmemo-agent-framework 0.2.0을 다룹니다. 범위가 제한되고 출처 정보가 포함된 XMemo 컨텍스트를 가져오며, 별도의 선택적 캡처 훅을 제공합니다. 독립적인 커뮤니티 통합이며 Microsoft의 공식 제품이나 배포판이 아닙니다. 이 패키지는 XMemo 서버를 게시하거나 배포하지 않습니다.

사전 요구 사항

Python과 Microsoft Agent Framework Core를 사용합니다. 선택적 maf extra는 agent-framework-core==1.21.0을 고정합니다. 연결을 만들기 전에 프로세스 환경에 XMemo origin과 API key를 설정하세요.

  • XMEMO_URL은 HTTPS origin이어야 합니다.
  • XMEMO_API_KEY는 Authorization 헤더로만 전송됩니다.
  • 실제 owner와 tenant는 서버 권한 부여로 결정되며 클라이언트가 제공한 identity claim으로 결정되지 않습니다.

설치

패키지가 게시된 후 Microsoft Agent Framework extra를 포함한 고정 버전을 설치하세요:

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

연결 구성

에이전트를 실행하는 프로세스에 XMemo origin과 API key를 전달하세요:

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

XMemo 컨텍스트 읽기

기본 경로는 POST /v1/recall/context입니다. 사용 사례에 따라 문서화된 ReadRoute 값으로 다른 경로를 선택하세요. host agent의 context-provider 구성에 context_provider를 전달하고 host session이 끝나면 connection을 닫으세요:

  • ReadRoute.RECALL: POST /v1/recall/context(기본값).
  • 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)

MCP를 통해 XMemo 도구 사용

Microsoft Agent Framework 컨텍스트 공급자는 XMemo의 MCP 도구 표면을 대체하지 않습니다. remember, recall, search, forget 같은 명시적 메모리 도구가 필요하면 XMemo MCP 연결을 별도로 구성하세요.

  • 연결 경로와 도구 프로필은 [MCP 개요](/docs/mcp/overview)에서 확인하세요.
  • 문서화된 메모리 도구는 [remember](/docs/tools/remember), [recall](/docs/tools/recall), [search](/docs/tools/search), [forget](/docs/tools/forget)을 참조하세요.
  • 클라이언트 구성 예시는 [Codex](/docs/mcp/codex) 또는 [GitHub Copilot](/docs/mcp/copilot)을 참조하세요.

캡처는 선택 사항

캡처는 기본적으로 꺼져 있습니다. 서버에서 확인된 쓰기 identity와 명시적인 target/behavior 조합으로 별도의 CaptureProvider를 XMemoContextProvider에 전달한 경우에만 실행됩니다. STATE에는 state_key, EVENT에는 event_type이 필요하며 두 값 모두 [a-z0-9][a-z0-9_.:-]{0,127} 패턴을 따릅니다.

  • Target.REMEMBER는 Behavior.SEMANTIC_KEY_SAME_CONTENT_NOOP으로 POST /api/v1/remember를 전송합니다.
  • Target.STATE는 Behavior.STATE_VERSIONED_UPSERT로 POST /api/v1/update_state를 전송하며 범위가 제한된 소문자 state_key가 필요합니다.
  • Target.EVENT는 Behavior.EVENT_APPEND_NO_DEDUPE로 POST /api/v1/timeline/events를 전송하며 범위가 제한된 소문자 event_type이 필요합니다.

캡처 공급자 구성

이 예시는 REMEMBER target 하나만 활성화하며, resolved_identity는 xmemo_agent_framework.capture의 ResolvedIdentity.from_server_responses(...)에서 가져옵니다. 다른 캡처 경로를 활성화할 때는 문서화된 target과 behavior 조합을 사용하세요:

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)

캡처 제한 및 실패 격리

캡처는 범위가 제한된 콘텐츠만 허용합니다(기본값 8 KiB, policy limit까지 구성 가능). 범위를 벗어난 콘텐츠는 캡처되지 않습니다. API key, bearer token, private key, 탐지된 secret pattern은 쓰기 본문에 포함되지 않으며 연결 credential은 Authorization 헤더에만 남습니다. redaction 후에도 요청이 안전하지 않으면 안전하지 않은 후보를 거부합니다.

  • 훅은 assistant 응답마다 최대 한 번만 쓰기 요청을 보내며 재시도하지 않습니다.
  • 쓰기 결과가 거부, 실패 또는 알 수 없는 상태여도 assistant 결과는 바뀌지 않습니다.
  • host에는 원시 서버 또는 credential 세부 정보 대신 정제된 캡처 metadata가 전달됩니다.

출처 정보 및 권한 부여

주입되는 모든 항목에는 변경할 수 없는 출처 정보와 adapter receipt가 포함됩니다. 검색된 텍스트는 저장된 신뢰할 수 없는 컨텍스트이며 지시가 아닙니다. 실제 owner와 tenant는 서버 권한 부여가 결정합니다. 캡처는 모델 권한을 부여하거나 read provider의 권한 경계를 바꾸지 않습니다.

서버 요구 사항

읽기 경로에는 해당 XMemo REST contract가 필요합니다. 감사된 쓰기 응답이 포함된 REMEMBER, STATE, EVENT 캡처에는 XMemo 서버 v0.4.436 이상이 필요하며, 호스팅 서비스 xmemo.dev에서 이미 실행 중입니다.

문제 해결

패키지에서 문서화한 호환성 및 검증 신호를 확인하세요:

  • xmemo_agent_framework.maf를 가져올 때 ImportError가 발생하면 호스트 프레임워크 종속성을 사용할 수 있도록 선택 사항인 maf extra를 설치합니다.
  • XMEMO_URL은 HTTPS 오리진이어야 하며 XMEMO_API_KEY는 Authorization 헤더로만 전송됩니다.
  • 캡처가 거부되거나 실패하거나 결과를 알 수 없는 경우에도 어시스턴트 결과는 유지됩니다. 호스트에는 정제된 메타데이터가 전달되며 쓰기는 재시도되지 않습니다.

출처: Microsoft Agent Framework 통합