Microsoft Agent Framework MCP로 Sume 연결하기

Python에서 Microsoft Agent Framework는 MCPStreamableHTTPTool로 에이전트를 원격 MCP 서버에 연결합니다. name과 서버의 url을 지정해 에이전트에 도구로 넘기면, 에이전트가 그 서버의 도구를 호출할 수 있습니다. Sume 호스팅 MCP 서버라면 URL은 https://mcp.sume.com/mcp이고, Sume API 키는 static_headers나 header_provider로 설정한 Authorization: Bearer 헤더에 담겨 전달됩니다.

Agent Framework 쪽 내용은 Microsoft Learn의 에이전트에서 MCP 도구 사용하기, MCPStreamableHTTPTool 레퍼런스, 도구 승인 페이지에서, Sume 쪽 내용은 MCP OAuth와 API 키, MCP 도구와 게이트, Job과 결과 (영문)에서 가져왔으며, 모두 2026-09-28에 확인했습니다. Sume에는 Agent Framework 전용 커넥터가 없습니다. 프레임워크 자체의 MCP 클라이언트가 Sume 원격 서버와 통신하는 방식이며, Sume 기초 페이지는 호스팅 MCP가 여전히 동작하지만 현재 주 경로는 아니라고 설명합니다. 다른 Python 프레임워크는 Pydantic AI MCP 서버에서 다룹니다.

Agent Framework 에이전트를 Sume에 어떻게 연결하나요?

Microsoft는 최소 구성으로 설치한 Python 환경이라면 MCPStreamableHTTPTool이 동작하기 전에 mcp --pre를 설치해야 할 수 있다고 안내합니다. 예제는 에이전트에 Sume 도구 네 개를 주고, generate_video는 사람이 승인할 때까지 보류합니다.

import asyncio
import os
from agent_framework import Agent, MCPStreamableHTTPTool
from agent_framework.openai import OpenAIChatClient

async def main() -> None:
    key = os.environ["SUME_API_KEY"]
    sume = MCPStreamableHTTPTool(
        name="Sume",
        url="https://mcp.sume.com/mcp",
        header_provider=lambda _kwargs: {"Authorization": f"Bearer {key}"},
        allowed_tools=["tools_schema", "generate_video", "jobs_wait", "jobs_result"],
        approval_mode={"always_require_approval": ["generate_video"]},
    )
    async with Agent(
        client=OpenAIChatClient(),
        name="VideoAgent",
        instructions="Preview paid calls with dry_run=true. Wait with jobs_wait; never resubmit.",
        tools=sume,
    ) as agent:
        result = await agent.run("A 5-second clip of waves at sunset.")
        for request in result.user_input_requests:
            print(request.function_call.name, request.function_call.arguments)

asyncio.run(main())

키는 static_headers와 header_provider 중 어디에 넣어야 하나요?

Microsoft 페이지는 둘 다 소개합니다. static_headers는 고정 자격 증명용이고, header_provider는 실행마다 도출되는 값용입니다. 이 페이지의 완성된 API 키 예제는 위 코드처럼 Authorization 헤더를 반환하는 header_provider를 쓰며, 이 provider는 연결 시점의 요청과 도구 호출 요청을 모두 인증합니다. 두 방식 모두 설정한 origin으로 가는 요청에만 헤더를 붙이고 cross-origin 리다이렉트에서는 헤더를 제거하며, 둘이 같은 헤더를 제공하면 header_provider 값이 우선합니다.

• header_provider는 실행의 호스트 function_invocation_kwargs만 받고, 모델이 작성하는 도구 인수는 절대 받지 않으므로, 모델은 어떤 키가 전송될지 바꿀 수 없습니다.
• 사용자별 키에는 이 방식을 쓰세요. Sume API 키와 지출은 워크스페이스 단위로 해석되므로, 어느 워크스페이스가 비용을 낼지는 키가 정합니다.
• Sume는 Authorization: Bearer나 x-api-key를 받습니다. 하나만 보내세요. 현재 코드에서는 둘 다 실은 요청이 Send only one MCP credential.로 거부됩니다.
• Microsoft는 원격 MCP 서버와 공유하는 API 키나 기타 자격 증명을 모두 검토하라고 요청합니다.

에이전트에는 어떤 Sume 도구를 보여 줘야 하나요?

API 키 세션에는 유료 도구를 포함한 Sume의 전체 호스팅 도구 세트가 보입니다. allowed_tools는 에이전트가 받는 도구를 좁히고, approval_mode는 "always_require", "never_require", 또는 always_require_approval이나 never_require_approval 아래에 도구 이름을 나열한 dict를 받습니다. Sume의 원래 도구 이름을 그대로 쓰세요. 설정한 이름이 정규화 후 여러 원격 이름과 일치하면 Agent Framework가 ToolExecutionException을 발생시킵니다. Sume 인증 문서는 쓰기나 유료 생성 전에 명시적 확인을 요구하라고 안내합니다.

유료 호출에 승인이 필요하면 어떻게 되나요?

승인이 필요한 에이전트 실행은 최종 답변 대신 user_input_requests와 함께 완료됩니다. 요청마다 함수 호출의 이름과 인수가 담겨 있습니다. 이를 사람에게 보여 주고, request.to_function_approval_response(True)(또는 False)를 지금까지의 대화와 함께 새 실행으로 에이전트에 돌려주세요. 남은 요청이 없을 때까지 이를 반복합니다. 이 승인을 어디에 두어야 하는지는 휴먼 인 더 루프 AI 에이전트에서 다룹니다.

승인은 프리뷰를 본 뒤에 하세요. 유료 도구에 대한 Sume 플레이북은 dry_run=true로 호출해 추정치, 잔액, 큐 동작을 확인한 다음, 모든 유료 도구에 필요한 새 idempotency_key를 넣어 제출하는 것입니다. max_spend_usd는 값을 넘긴 경우에만 호출의 상한이 됩니다. approval_mode는 인수가 아니라 도구를 지정하므로, generate_video에 대한 dry run 호출도 승인을 요청합니다.

긴 Sume Job은 타임아웃되나요? 그 밖에 무엇을 알아야 하나요?

• Sume jobs_wait 호출 한 번은 최대 55초, timeout_seconds를 생략하면 50초 동안 대기합니다. Agent Framework API 레퍼런스에는 모든 요청에 쓰이는 초 단위 기본 타임아웃인 request_timeout이 나와 있으니, 이 값을 설정한다면 55보다 크게 두세요.
• wait_slice_expired를 받으면 에이전트는 같은 id로 jobs_wait를 다시 호출해야 하며, 유료 create는 절대 다시 제출하면 안 됩니다.
• 이 글의 방식은 로컬 MCP 도구로, 여러분의 프로세스가 Sume를 호출합니다. Microsoft는 Foundry 에이전트용 호스팅 MCP 도구도 문서화하는데, 이 경우에는 뒤에서 받쳐 주는 AI 서비스가 MCP 도구를 실행합니다. 이는 별도의 설정입니다.
• 호스팅 MCP는 노트북의 파일을 읽을 수 없습니다.