Skip to main content
Source: examples/agent-with-sub-agents

​
Overview

This template shows how to deploy multiple specialist agents from a single service using the app/agents/ directory. Each file in app/agents/ becomes an independent A2A endpoint alongside the main app/agent.ts coordinator. The example has three agents and two tools:
  • Coordinator (app/agent.ts) — routes users to the right specialist
  • Math specialist (app/agents/math.ts) — performs arithmetic using the calculate tool
  • Text specialist (app/agents/text.ts) — analyzes text using the word-count tool

​
Project Structure

agent-with-sub-agents/
  aixyz.config.ts           # Agent metadata and skills
  app/
    agent.ts                # Coordinator agent → /agent
    agents/
      math.ts               # Math sub-agent → /math/agent
      text.ts               # Text sub-agent → /text/agent
    tools/
      calculate.ts          # Arithmetic tool (add/subtract/multiply/divide)
      word-count.ts         # Text analysis tool (words/characters/sentences)
    icon.png
  package.json
  vercel.json

​
Endpoints

A single deployment exposes three independent A2A endpoints:
EndpointAgentDescription
/agentCoordinatorRoutes users to specialists
/math/agentMathArithmetic calculations
/text/agentTextWord / character / sentence count
/.well-known/agent-card.jsonCoordinatorA2A discovery card
/math/.well-known/agent-card.jsonMathA2A discovery card
/text/.well-known/agent-card.jsonTextA2A discovery card
/mcp—MCP tool endpoint

​
Sub-Agent Definition

Each file in app/agents/ follows the same pattern as app/agent.ts: 
// app/agents/math.ts
import { openai } from "@ai-sdk/openai";
import { stepCountIs, ToolLoopAgent } from "ai";
import type { Accepts } from "aixyz/accepts";
import calculate from "../tools/calculate";

export const accepts: Accepts = { scheme: "exact", price: "$0.001" };

export default new ToolLoopAgent({
  model: openai("gpt-4o-mini"),
  instructions: "You are a math specialist...",
  tools: { calculate },
  stopWhen: stepCountIs(5),
});
The filename (math.ts) determines the URL prefix (/math/agent).

​
Key Features

  • Auto-discovery — All .ts files in app/agents/ are automatically registered
  • Independent endpoints — Each sub-agent gets its own A2A endpoint and agent card
  • Shared tools via MCP — Tools in app/tools/ are exposed on a single /mcp endpoint
  • Mixed deployment — app/agent.ts and app/agents/ can coexist in the same project

​
Running

cd examples/agent-with-sub-agents
bun install
bun run dev
Agents available at http://localhost:3000:
EndpointProtocolDescription
/.well-known/agent-card.jsonA2ACoordinator discovery
/agentA2ACoordinator JSON-RPC
/math/.well-known/agent-card.jsonA2AMath sub-agent discovery
/math/agentA2AMath sub-agent JSON-RPC
/text/.well-known/agent-card.jsonA2AText sub-agent discovery
/text/agentA2AText sub-agent JSON-RPC
/mcpMCPShared tool endpoint