Skip to main content
Source: examples/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

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/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