메모
.NET 자체 호스팅 MCP 도구 지원이 곧 제공될 예정입니다.
메모
자체 호스팅 MCP 도구 지원은 현재 Go에서 사용할 수 없습니다.
에이전트 프레임워크 에이전트 또는 워크플로를 네이티브 agent-framework-hosting-mcp SDK의 도구로 노출하는 데 사용합니다. 패키지는 웹 프레임워크를 선택하거나 MCP SDK 서버 수명 주기를 래핑하지 않으며, 애플리케이션은 Server, 핸들러 등록, 전송, 세션 키 정책, 인증, 권한 부여 및 배포를 여전히 책임집니다.
pip install --pre agent-framework-hosting-mcp
프로토콜 경계에서 변환
mcp_to_run(...) 는 유효성이 검사된 MCP 도구 인수를 에이전트 프레임워크 메시지 및 선택한 채팅 옵션으로 변환하고 mcp_from_run(...) 완료된 응답을 네이티브 MCP ContentBlock 값으로 변환합니다. 애플리케이션의 도구 계약에 완전히 사용자 지정 네이티브 스키마 및 처리기가 필요한 경우 다음 두 함수를 직접 사용합니다.
@server.list_tools()
async def list_tools() -> list[types.Tool]:
"""Return the app-owned native MCP tool definition."""
return [
types.Tool(
name="run_agent_manually",
description=agent.description or "",
inputSchema={
"type": "object",
"properties": {
TASK_ARGUMENT: {
"type": "string",
"description": "The request for the hosted agent.",
},
**CHAT_OPTION_ARGUMENTS,
},
"required": [TASK_ARGUMENT],
"additionalProperties": False,
},
)
]
@server.call_tool()
async def call_tool(name: str, arguments: dict[str, object] | None) -> list[types.ContentBlock]:
"""Convert, run, and render without the agent-backed adapter."""
if name != "run_agent_manually":
raise ValueError(f"Unknown MCP tool: {name}")
run = mcp_to_run(
arguments,
argument_name=TASK_ARGUMENT,
chat_option_arguments=CHAT_OPTION_ARGUMENTS,
)
result = await agent.run(run["messages"], options=run["options"])
return mcp_from_run(result)
나열된 chat_option_arguments 인수 이름만 복사 run["options"]됩니다. 다른 MCP 인수는 메시지의 원시 표현에서 계속 사용할 수 있지만 모델 클라이언트로 전달되지는 않습니다.
에이전트를 하나의 생성된 도구로 호스트
AgentMCPTool 는 에이전트에서 네이티브 도구 이름, 설명 및 스키마를 파생시키고 목록, 구문 분석, 실행 및 결과 변환을 정렬하여 두 항목이 드리프트할 수 없도록 유지합니다.
agent_tool = AgentMCPTool(
agent,
name="run_agent",
argument_description="The request for the hosted agent.",
chat_option_parameters={
"reasoning_effort": {
"type": "string",
"enum": ["low", "medium", "high"],
"description": "Optional reasoning effort for models that support it.",
}
},
)
@server.list_tools()
async def list_tools() -> list[types.Tool]:
"""Describe the app-owned MCP tool schema."""
return await agent_tool.list_tools()
@server.call_tool()
async def call_tool(name: str, arguments: dict[str, object] | None) -> list[types.ContentBlock]:
"""Run the app-owned tool with native MCP and Agent Framework values."""
return await agent_tool.call_tool(name, arguments)
AgentMCPTool는 별도로 재정의하지 않으면 에이전트의 이름과 설명을 사용합니다.
parameters는 원시 MCP 인수에서 계속 사용 가능한 앱 소유의 JSON 스키마 속성을 추가하고, chat_option_parameters는 값이 Agent Framework 채팅 옵션에 명시적으로 복사되는 속성을 추가합니다.
각 호출마다 세션 유지
기존 AgentState와 session_id_parameter를 전달하여, 동일한 불투명한 앱에서 정의한 session_id를 사용하는 반복 호출이 하나의 대화를 계속 이어가도록 합니다.
session_locks: dict[str, asyncio.Lock] = {}
@server.list_tools()
async def list_tools() -> list[types.Tool]:
"""Return the agent-derived MCP tool definition."""
return await agent_tool.list_tools()
@server.call_tool()
async def call_tool(name: str, arguments: dict[str, object] | None) -> list[types.ContentBlock]:
"""Serialize calls per app-owned session before using ``AgentState``."""
session_id = arguments.get("session_id") if arguments else None
if not isinstance(session_id, str) or not session_id:
raise ValueError("MCP tool argument 'session_id' must be a non-empty string.")
lock = session_locks.setdefault(session_id, asyncio.Lock())
async with lock:
return await agent_tool.call_tool(name, arguments)
AgentMCPTool 세션 가져오기/실행/설정 시퀀스만 수행합니다 AgentState . 애플리케이션은 세션별 asyncio.Lock샘플과 마찬가지로 세션 식별자를 인증하거나 권한을 부여하고 동일한 세션에 대한 동시 호출을 직렬화해야 합니다. 이는 스타일 분기가 아닙니다 previous_response_id. 대화를 포크해야 하는 애플리케이션은 별도의 원본 및 대상 ID를 수락하고, 원본 세션을 복사하고, 결과를 대상 키 아래에 저장해야 합니다.
워크플로를 도구로 호스트
WorkflowMCPTool 는 워크플로의 시작 실행기 입력 형식에서 하나의 네이티브 MCP 도구를 파생시키고 완료된 워크플로 출력을 변환합니다. 데이터 클래스, Pydantic 및 기타 개체 모양의 입력은 최상위 MCP 인수가 됩니다. 기본 입력은 구성 가능한 인수 이름으로 래핑됩니다.
server = Server("agent-framework-hosting-mcp-workflow-sample")
workflow_tool = WorkflowMCPTool(
WorkflowState(create_workflow, cache_target=False),
name="draft_content",
)
워크플로 인스턴스는 실행 상태를 유지하므로 서로 독립적인 호출이 필요한 애플리케이션은 위와 같이 WorkflowState를 사용해 cache_target=False 팩터리를 제공해야 합니다. 검사점 복원, 사람 개입형 응답, 그리고 연속 식별자는 애플리케이션이 관리합니다. 워크플로가 외부 입력을 요청하는 경우, 어댑터는 빈 성공 도구 결과를 반환하는 대신 예외를 발생시킵니다.
데코레이팅된 함수에서 스키마를 파생시키는 FastMCP 변형을 포함하여 실행 가능한 서버의 전체 집합은 MCP 호스팅 샘플을 참조하세요.
Important
MCP 세션 식별자 및 앱 정의 session_id 인수를 신뢰할 수 없는 입력으로 처리합니다. 세션 상태를 로드하거나 저장하는 데 사용하기 전에 호출자를 인증하고 권한을 부여하고, 원시 값이 아닌 인증된 테넌트, 사용자 또는 작업 영역에서 지속성 분할을 파생합니다.
다음 단계
더 자세히 살펴보기: