Agen host mandiri sebagai alat MCP

Nota

Dukungan alat MCP hosting mandiri di .NET akan segera hadir.

Go mengekspos agen sebagai alat MCP dengan menggabungkan tool/agenttool, tool/mcptool, dan MCP Go SDK resmi. Bungkus agen dengan agenttool.New, daftarkan dengan mcptool.AddTool, dan jalankan melalui transport MCP.

Sampel Foundry yang dipelihara menggunakan stdio. Ini memerlukan titik akhir proyek Foundry, penyebaran model, dan kredensial Azure:

// Copyright (c) Microsoft. All rights reserved.

// This sample shows how to expose an Agent as an MCP tool.

package main

import (
    "context"

    "github.com/microsoft/agent-framework-go/agent"
    "github.com/microsoft/agent-framework-go/examples/internal/demo"
    "github.com/microsoft/agent-framework-go/provider/foundryprovider"
    "github.com/microsoft/agent-framework-go/tool/agenttool"
    "github.com/microsoft/agent-framework-go/tool/mcptool"
    "github.com/modelcontextprotocol/go-sdk/mcp"
)

// Run "npx @modelcontextprotocol/inspector go run ." to connect to this MCP server.

func main() {
    token := demo.FoundryTokenCredential()

    // Create Microsoft Foundry agent with the same configuration as the C# example.
    agent := foundryprovider.NewAgent(
        demo.FoundryProjectEndpoint,
        token,
        foundryprovider.ModelDeployment(demo.FoundryModel),
        foundryprovider.AgentConfig{
            Instructions: "You are good at telling jokes, and you always start each joke with 'Aye aye, captain!'.",
            Config: agent.Config{
                Name:        "Joker",
                Description: "An agent that tells jokes.",
            },
        },
    )

    // Create an MCP server with the agent exposed as a tool.
    srv := mcp.NewServer(&mcp.Implementation{
        Name:    "agent-mcp-server",
        Version: "1.0.0",
    }, nil)

    // Register the agent as an MCP tool.
    mcptool.AddTool(srv, agenttool.New(agent, agenttool.Config{}))

    // Run the MCP server with StdIO transport.
    if err := srv.Run(context.Background(), &mcp.StdioTransport{}); err != nil {
        demo.Panic(err)
    }
}

Lihat Integrasi alat MCP untuk pola klien dan server, dan sampel server MCP lengkap untuk instruksi eksekusi.

Gunakan agent-framework-hosting-mcp untuk mengekspos agen Agen Framework atau alur kerja sebagai alat pada Model Context Protocol SDK asli. Paket tidak memilih kerangka kerja web atau membungkus siklus hidup server MCP SDK. Aplikasi Anda masih menjadi tanggung jawab atas server MCP, pendaftaran handler, transport, kebijakan kunci sesi, autentikasi, otorisasi, dan penyebaran.

pip install --pre agent-framework-hosting-mcp

Konversi di batas protokol

mcp_to_run(...) mengonversi argumen alat MCP yang divalidasi menjadi pesan Agent Framework dan opsi obrolan yang dipilih, dan mcp_from_run(...) mengonversi respons lengkap menjadi nilai MCP ContentBlock asli. Gunakan kedua fungsi ini secara langsung ketika kontrak alat aplikasi membutuhkan skema dan handler asli yang sepenuhnya kustom:

                    "properties": {
                        TASK_ARGUMENT: {
                            "type": "string",
                            "description": "The request for the hosted agent.",
                        },
                        **CHAT_OPTION_ARGUMENTS,
                    },
                    "required": [TASK_ARGUMENT],
                    "additionalProperties": False,
                },
            )
        ]
    )


async def call_tool(
    _ctx: ServerRequestContext[dict[str, Any]], params: types.CallToolRequestParams
) -> types.CallToolResult:
    """Convert, run, and render without the agent-backed adapter."""
    name = params.name
    arguments = params.arguments or {}

    if name != "run_agent_manually":
        raise MCPError(types.INVALID_PARAMS, 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 types.CallToolResult(content=mcp_from_run(result))


server = Server("agent-framework-hosting-mcp-manual-sample", on_list_tools=list_tools, on_call_tool=call_tool)
credential = DefaultAzureCredential()

Hanya nama argumen yang tercantum dalam chat_option_arguments yang disalin ke run["options"]; argumen MCP lainnya tetap tersedia dalam representasi mentah pesan, tetapi tidak diteruskan ke klien model.

Hosting dengan MCPServer

Untuk aplikasi MCP SDK 2.x, gunakan MCPServer untuk mendapatkan skema alat MCP asli dari fungsi yang didekorasi. Kembalikan CallToolResult secara eksplisit setelah mengonversi respons Kerangka Kerja Agen yang telah selesai:

from contextlib import asynccontextmanager
from typing import Literal

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from agent_framework_hosting_mcp import mcp_from_run, mcp_to_run
from azure.identity.aio import DefaultAzureCredential
from mcp import types
from mcp.server.mcpserver import MCPServer

credential = DefaultAzureCredential()
agent = Agent(
    client=FoundryChatClient(
        project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
        model=os.environ["FOUNDRY_MODEL"],
        credential=credential,
    ),
    name="MCPHostedAgent",
    description="Answer a request with the hosted Agent Framework agent.",
    instructions="Answer the user's request clearly and concisely.",
)


@asynccontextmanager
async def lifespan(_server: MCPServer[None]) -> AsyncGenerator[None]:
    """Close the model credential when the MCP server stops."""
    async with credential:
        yield


server = MCPServer(
    name="agent-framework-hosting-mcpserver-sample",
    instructions="Expose an Agent Framework agent as an MCP tool.",
    lifespan=lifespan,
)


@server.tool(
    name="run_agent",
    description="Run the hosted Agent Framework agent.",
    structured_output=False,
)
async def run_agent(
    task: str,
    reasoning_effort: Literal["low", "medium", "high"] | None = None,
) -> types.CallToolResult:
    """Run the agent with MCPServer-validated arguments."""

Sampel menggunakan HTTP streaming tanpa status. Tambahkan autentikasi, otorisasi, dan persistensi sesi milik aplikasi sebelum mengekspos server di luar lingkungan lokal tepercaya.

Jalankan agen sebagai alat yang dibuat

AgentMCPTool memperoleh nama, deskripsi, dan skema alat bawaan dari agen, serta menjaga agar pencantuman, penguraian, eksekusi, dan konversi hasil tetap selaras sehingga keduanya tidak mungkin menyimpang satu sama lain:

) -> types.CallToolResult:
    """Run the app-owned tool with native MCP and Agent Framework values."""
    return await agent_tool.call_tool(params.name, params.arguments)


server = Server("agent-framework-hosting-mcp-sample", on_list_tools=list_tools, on_call_tool=call_tool)
credential = DefaultAzureCredential()
agent = Agent(
    client=FoundryChatClient(
        project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
        model=os.environ["FOUNDRY_MODEL"],
        credential=credential,
    ),
    name="MCPHostedAgent",
    description="Answer a request with the hosted Agent Framework agent.",
    instructions="Answer the user's request clearly and concisely.",
)
agent_tool = AgentMCPTool(
    agent,
    name="run_agent",
    argument_description="The request for the hosted agent.",
    chat_option_parameters={
        "reasoning_effort": {
            "type": "string",

AgentMCPTool menggunakan nama dan deskripsi agen kecuali ditentukan lain. parameters menambahkan properti Skema JSON milik aplikasi yang tetap tersedia dalam argumen MCP mentah, dan chat_option_parameters menambahkan properti yang nilainya secara eksplisit disalin ke dalam opsi obrolan Agent Framework.

Mempertahankan sesi untuk setiap panggilan

Berikan AgentState yang sudah ada dan session_id_parameter agar panggilan berulang dengan session_id buram yang sama, yang ditentukan aplikasi, dapat melanjutkan satu percakapan:

state = AgentState(agent)
agent_tool = AgentMCPTool(
    state,
    name="run_agent",
    argument_description="The request for the hosted agent.",
    parameters={
        "session_id": {
            "type": "string",
            "minLength": 1,
            "description": (
                "Opaque, app-defined conversation key. Reuse the same value to continue and update one conversation."
            ),
        }
    },
    required_parameters={"session_id"},
    chat_option_parameters={
        "reasoning_effort": {
            "type": "string",

AgentMCPTool hanya melakukan urutan sesi AgentState get/run/set; aplikasi Anda harus mengautentikasi atau mengautorisasi pengidentifikasi sesi dan menserialkan panggilan serentak untuk sesi yang sama, seperti yang dilakukan sampel dengan asyncio.Lock per sesi. Ini bukan pencabangan gaya previous_response_id — aplikasi yang perlu memecah percakapan harus menerima ID sumber dan ID tujuan yang terpisah, menyalin sesi sumber, dan menyimpan hasilnya dengan kunci tujuan.

Jadikan alur kerja sebagai alat

WorkflowMCPTool menghasilkan satu tool MCP native dari jenis input start-executor alur kerja dan mengonversi output alur kerja yang selesai. Dataclass, Pydantic, dan input berbentuk objek lainnya menjadi argumen MCP tingkat atas; input primitif dibungkus dalam nama argumen yang dapat dikonfigurasi:

async def list_tools(
    _ctx: ServerRequestContext[dict[str, Any]], params: types.PaginatedRequestParams | None
) -> types.ListToolsResult:

Instans workflow menyimpan status eksekusi, sehingga aplikasi yang memerlukan pemanggilan independen harus menyediakan WorkflowState factory dengan cache_target=False, seperti yang ditunjukkan di atas. Pemulihan titik pemeriksaan, respons human-in-the-loop, dan pengidentifikasi kelanjutan tetap dimiliki aplikasi; jika alur kerja meminta input eksternal, adaptor akan muncul alih-alih mengembalikan hasil alat yang berhasil kosong.

Untuk kumpulan lengkap server yang dapat dijalankan, termasuk MCPServer varian, lihat sampel hosting MCP.

Penting

Perlakukan pengidentifikasi sesi MCP dan argumen apa pun yang ditentukan session_id aplikasi sebagai input yang tidak tepercaya. Lakukan autentikasi dan otorisasi terhadap pemanggil sebelum menggunakan salah satunya untuk memuat atau menyimpan status sesi, dan tentukan partisi persisten berdasarkan tenant, pengguna, atau ruang kerja yang telah diautentikasi, bukan berdasarkan nilai mentah.

Langkah berikutnya

Pelajari tentang hosting A2A

Masuk lebih dalam:

• Gambaran umum hosting mandiri
• Respon OpenAI
• Telegram