Zelf-gehoste agents als MCP-hulpmiddelen

Gebruik agent-framework-hosting-mcp dit om een Agent Framework-agent of -werkstroom beschikbaar te maken als een hulpprogramma in de systeemeigen Model Context Protocol SDK. Het pakket kiest geen webframework of verpakt de levenscyclus van de MCP SDK-server; uw toepassing is nog steeds eigenaar van het Serverbeleid voor handlerregistratie, transport, sessiesleutelbeleid, verificatie, autorisatie en implementatie.

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

Converteren op de protocolgrens

mcp_to_run(...) converteert gevalideerde MCP-hulpprogrammaargumenten naar Agent Framework-berichten en geselecteerde chatopties en mcp_from_run(...) converteert een voltooid antwoord naar systeemeigen MCP-waarden ContentBlock . Gebruik deze twee functies rechtstreeks wanneer het hulpprogrammacontract van een toepassing een volledig aangepast systeemeigen schema en handler nodig heeft:

@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)

Alleen argumentnamen die in chat_option_arguments staan vermeld, worden naar run["options"] gekopieerd; andere MCP-argumenten blijven beschikbaar in de ruwe weergave van het bericht, maar worden niet doorgestuurd naar de modelclient.

Een agent hosten als één gegenereerd hulpprogramma

AgentMCPTool leidt de oorspronkelijke toolnaam, beschrijving en het schema af van een agent, en houdt weergave, parsing, uitvoering en resultaatconversie op elkaar afgestemd, zodat beide niet uit elkaar kunnen gaan lopen:

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 gebruikt de naam en beschrijving van de agent, tenzij anders ingesteld. parameters voegt eigenschappen toe die eigendom zijn van het JSON-schema die beschikbaar blijven in de onbewerkte MCP-argumenten en chat_option_parameters voegt eigenschappen toe waarvan de waarden expliciet worden gekopieerd naar chatopties van Agent Framework.

Een sessie per gesprek behouden

Geef een bestaande AgentState en een session_id_parameter door, zodat herhaalde aanroepen met hetzelfde ondoorzichtige, door de app gedefinieerde session_id dezelfde conversatie voortzetten:

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 voert alleen de AgentState sessie get/run/set-reeks uit; uw toepassing moet de sessie-id verifiëren of autoriseren en gelijktijdige aanroepen voor dezelfde sessie serialiseren, zoals het voorbeeld doet met een sessie per sessie asyncio.Lock. Dit is geen previous_response_idvertakking in stijl. Een toepassing die een gesprek moet vertakken, moet afzonderlijke bron- en doel-id's accepteren, de bronsessie kopiëren en het resultaat opslaan onder de doelsleutel.

Een werkstroom hosten als hulpprogramma

WorkflowMCPTool leidt één native MCP-tool af uit het start-executor-invoertype van een workflow en converteert de uitvoer van voltooide workflows. Dataclass, Pydantic en andere objectvormige invoer worden MCP-argumenten op het hoogste niveau; primitieve invoer wordt verpakt in een configureerbare argumentnaam:

server = Server("agent-framework-hosting-mcp-workflow-sample")
workflow_tool = WorkflowMCPTool(
    WorkflowState(create_workflow, cache_target=False),
    name="draft_content",
)

Workflowinstanties behouden hun uitvoeringsstatus, dus toepassingen die onafhankelijke oproepen vereisen, moeten een WorkflowState-factory met cache_target=False opgeven, zoals hierboven is weergegeven. Herstel van controlepunten, antwoorden met menselijke tussenkomst en vervolgidentificatoren blijven eigendom van de applicatie; als een workflow externe invoer aanvraagt, genereert de adapter een fout in plaats van een leeg, succesvol toolresultaat te retourneren.

Zie de voorbeelden voor MCP-hosting voor de volledige set uitvoerbare servers, inclusief de FastMCP-variant die het schema genereert op basis van een gedecoreerde functie.

Volgende stappen 

Ga dieper in:

• Overzicht van selfhosting
• OpenAI-antwoorden
• Telegram