AI Agent Beginner Tutorial: 11 - MCP and Multi-Agent Systems

Use tools, resources, and prompts differently

A tool is an action the model may request, such as document search. A resource is a readable object, such as a specification. A prompt is a reusable template, such as a research outline.

Static document reading fits resources, parameterized search fits tools, and a fixed working method can live in a prompt or the skill system from Chapter 8. A skill may reference both MCP tools and resources.

Connect in five steps

1. Verify server identity and operator.
2. Initialize the connection and negotiate protocol capabilities.
3. List server capabilities and filter them through a local allowlist.
4. Map allowed capabilities into the tool registry with approval, timeout, and result limits.
5. Cache the server version and rediscover after a version or schema change.

from dataclasses import dataclass

@dataclass(frozen=True)
class Capability:
    name: str
    description: str
    input_schema: dict

def filter_capabilities(discovered: list[Capability],
                        allowed: set[str]) -> dict[str, Capability]:
    return {
        capability.name: capability
        for capability in discovered
        if capability.name in allowed
    }

Remote output remains untrusted evidence. A connection timeout returns mcp_unavailable, allowing the main loop to use local sources or report an evidence gap without reconnecting forever.

Decide whether more tools justify more agents

MCP may add tools, but tool count alone does not require multiple agents. Run a single-agent baseline and observe tool-selection errors, prompt conflicts, permission separation, and team maintenance cost.

A split becomes worth testing when at least one condition appears:

• Research and writing instructions interfere, and evaluations cannot satisfy both.
• Tool groups use different identities and data boundaries.
• Specialist context can be much smaller and exclude irrelevant material.
• Separate teams need independent releases and maintenance.

Compare three multi-agent relationships

Manager                  Agent-as-Tool              Handoff
User                     User                       User
 │                        │                          │
 ▼                        ▼                          ▼
Central agent ─▶ expert   Manager ─call─▶ expert     Front agent ──▶ expert
 │              │         ▲              │                       owns next turns
 └────merge─────┘         └────result────┘

A manager uses code for central orchestration. Agent-as-tool keeps final control with the manager. A handoff transfers the conversation to a specialist for subsequent turns.

Represent a specialist tool in the Agents SDK

from agents import Agent

researcher = Agent(
    name="Researcher",
    instructions="Return evidence with source IDs. Do not draft conclusions.",
)

manager = Agent(
    name="Brief manager",
    instructions="Collect evidence, draft, validate citations, then answer.",
    tools=[
        researcher.as_tool(
            tool_name="collect_evidence",
            tool_description="Collect bounded evidence for the topic.",
        )
    ],
)

A specialist receives only the context and tools needed for its responsibility, with bounded delegation depth, concurrent specialists, and budget.

Preserve a single-agent control group

Run the same task set through a single agent, manager plus specialists, and handoff version. Compare success, citation correctness, P95 latency, tokens, cost, and maintenance time. If multiple agents improve only style while reducing citation accuracy or adding substantial cost, retain one agent.

Chapter 12 compares the single-agent and multi-agent versions on the same task set, formalizes evaluation and tracing, and connects passing gates to queues, workers, canaries, and release decisions.