Compose agents with a concierge

Concierge answers general questions itself and sends every weather question to the weather agent. The connection is one file. The Agent SDK turns the target agent's MCP endpoint into tools the concierge can call.

Use this example when two agents are useful on their own and one should delegate a narrow class of work to the other.

Browse the Concierge source.

Delegate through a peer MCP connection

Concierge has no domain tool of its own. Its capability comes from a peer MCP connection:

export default defineConnection({
  agent: "weather-agent",
  description:
    "The weather-agent peer: delegate weather questions with ask; it runs its own tools (live Open-Meteo data) in its own context.",
});

The filename weather.ts makes the MCP server name weather. The agent field points to the sibling project's mount slug.

This differs from a subagent. A peer keeps its own:

• root instructions,
• tools and MCP connections,
• durable sessions,
• playground, and
• public MCP endpoint.

An SDK subagent inherits the parent's execution surface and only its parent can invoke it. See Agent-to-agent for the full comparison.

Follow a delegated request

1. A user asks Concierge what to pack for Paris.
2. instructions.md classifies packing advice as weather-related.
3. The model calls weather.ask with the city, timeframe, units, and the complete question.
4. The Agent SDK creates an MCP-channel session inside weather-agent.
5. Weather agent calls its own Open-Meteo tools and returns a reply.
6. If the turn exceeds the bounded MCP wait, ask returns status: "running". Concierge calls weather.check with the returned sessionId.
7. Concierge relays the result and may add one sentence of travel advice.

The weather session appears in the weather agent's playground. It doesn't share Concierge's conversation history.

Map the delegation files

File	Purpose
agent/agent.ts	Describes the root agent and selects the local runtime.
agent/instructions.md	Draws a strict weather-only delegation boundary.
agent/mcp-connections/weather.ts	Resolves the peer by its weather-agent slug.
agent/storage.ts	Persists sessions and events with cursorHostedStorage.

Concierge doesn't author channels, tools, skills, subagents, schedules, hooks, A/B experiments, or evals. The built-in HTTP and MCP surfaces still exist.

Its own MCP endpoint exposes ask and check. It doesn't expose call_tool because Concierge has no server tools. The target weather agent does expose call_tool, so that tool also appears under Concierge's weather connection.

Mount both agents

A peer can only resolve within a multi-agent serve host. Validating Concierge alone checks its files, but serving it alone fails because weather-agent isn't mounted.

From packages/agent-serve, validate both projects:

agent-sdk validate --dir examples/concierge
agent-sdk validate --dir examples/weather-agent

Don't serve the repository's whole examples/ directory for this proof. Several advanced examples subscribe to live GitHub events. Create an ignored two-project mount instead. Copy only the authored files needed for this proof, leaving Weather's Slack channels out:

mkdir -p "$PWD/.agent-serve"
PAIR_DIR=$(mktemp -d "$PWD/.agent-serve/concierge-weather.XXXXXX")
mkdir -p "$PAIR_DIR/concierge" "$PAIR_DIR/weather-agent/agent"
cp -R examples/concierge/agent "$PAIR_DIR/concierge/"
cp examples/concierge/package.json "$PAIR_DIR/concierge/"
cp examples/weather-agent/agent/{agent.ts,instructions.md,ab.ts,ab.config.ts} \
  "$PAIR_DIR/weather-agent/agent/"
cp -R examples/weather-agent/agent/{tools,skills,mcp-connections,subagents,schedules,hooks,lib} \
  "$PAIR_DIR/weather-agent/agent/"
cp -R examples/weather-agent/mcp "$PAIR_DIR/weather-agent/"
cp examples/weather-agent/package.json "$PAIR_DIR/weather-agent/"
agent-sdk dev "$PAIR_DIR"

The host resolves the peer after it knows every mount. The local peer URL is http://127.0.0.1:3000/weather-agent/v1/mcp. You still need an agent-runtime credential for both model turns.

Exercise delegation

Send a weather request to the running Concierge:

agent-sdk chat \
  --url http://127.0.0.1:3000/concierge \
  --message "What should I pack for Paris tomorrow?"

Open both playgrounds:

• http://127.0.0.1:3000/concierge/playground
• http://127.0.0.1:3000/weather-agent/playground

The Concierge transcript shows the MCP call. The weather playground shows a separate session on the mcp channel with live weather tool calls.

Now send a general request:

agent-sdk chat \
  --url http://127.0.0.1:3000/concierge \
  --message "Give me three ideas for a quiet weekend."

The instructions tell Concierge to answer without delegating. This contrast is the proof loop: weather goes to the peer, unrelated work stays local.

Preserve peer context

weather.ask returns a peer sessionId. Passing it back to a later ask continues the same weather conversation. Concierge's instructions require this for follow-ups dependent on an earlier answer.

Use a fresh call when the tasks are independent. Reuse the peer session when the second question needs facts or choices from the first.

Keep delegation bounded

The Agent SDK rejects unknown peer slugs and self-references during startup. It doesn't stop a cycle across several valid peers. If agent A delegates all work to B and B delegates all work to A, they can recurse.

The prompt provides the guardrail here:

• delegate every weather request,
• include complete context, and
• never delegate unrelated work.

Write similarly narrow routing rules for each peer. A tool description helps the model choose the connection, but the always-on instructions own the policy.

Use peers from cloud turns

Local turns reach peers over loopback. A cloud VM can't reach the serve host's loopback address. Set a public URL when a cloud agent needs the peer:

agent-sdk serve --dir "$PAIR_DIR" \
  --public-url https://agents.example.com \
  --bearer-token "$AGENT_TOKEN"

The Agent SDK attaches the bearer token to peer calls. Without --public-url, cloud turns omit peer connections and the server logs a warning.

Compose your own pair

To compose your own agents:

1. Give each project a stable directory slug.
2. Add agent/mcp-connections/<name>.ts to the caller.
3. Set agent to the target slug.
4. Describe the exact work the peer owns.
5. Mount both projects from their parent directory.
6. Add evals for delegated and non-delegated requests.

Keep the peer independently useful. If the specialist only makes sense inside one parent and needs no independent sessions, use a subagent instead.

Where to go next

• Agent-to-agent
• MCP connections
• Subagents
• Sessions and streaming