Connect agents
By the end of this page your system will have its specialist agents connected, and you will know how to write skills that route accurately.
Prerequisites
- A system created (Create a MAS).
- Admin or Developer role.
- Two or more AI Agents with status Active in the same project.
Add an agent
Click Add Agent
In Connected Agents, click Add Agent. With no members yet the panel invites you to Add First Agent and reminds you that “Each agent’s skills define routing signals.”
The dialog is titled Add Agent to Conversation Router.
Pick a specialist
Search by name or description, then select one agent. Each row shows the display name, the internal name and short ID, the description, a Conversation badge, and the agent’s status.
Only AI Agents with status Active that aren’t already members appear in the list. Task Agents are never eligible.
A row flagged “No conversation mode — may not work well in router” has no Conversation mode enabled. A router holds a conversation, so enable Conversation on the agent first — see Modes.
Click Add Selected
The agent appears as a card in Connected Agents, and its skills load automatically. Repeat for each specialist.
Adding an agent is a local change: the Unsaved badge appears in the header. Click Save to persist the member list.
What an agent card shows
| Section | What it tells you |
|---|---|
| Header | The agent’s display name, a Published badge if it has a published version, and its internal name plus short ID. |
| Skills (N) | Read-only. Collapsed it shows skill names as chips; expanded it shows each skill’s description, tags, and example queries. |
| Few-Shot Overrides (N) | Extra example phrasings for this agent — see Few-shot examples. |
| Chat Display | The name and greeting used when the conversation moves to this agent — see Fallback & handoff. |
| ⋮ menu | View Agent opens the agent in a new tab; Remove from Router takes it out of the system. |
Skills are shown here but edited on the agent itself. The card says so: “Edit skills on the agent definition page.”
Order matters, a little
Agents appear in the order you added them, and that order is saved with the system. It has one effect on behaviour: the first agent in the list receives an opening greeting, before any real question has been classified — see How routing works.
Put your most general specialist first, so a bare “hello” lands somewhere sensible. There’s no drag-to-reorder; to change the order, remove an agent and add it again.
Write skills that route well
The router classifies every message against your members’ skills. These rules matter more than any other setting in the builder.
Give every member at least one real skill. An agent with no skills shows “No active skills found. Skills are required for routing accuracy.” and the publish check warns you. The router has nothing to match on, so that agent only receives traffic through the default action.
Keep domains distinct. Two agents whose skills both claim “answer customer questions” will compete for every message. Name the domain: Sales Lookup versus Stock Check.
Write descriptions for a classifier, not a brochure. A description like “Answer questions about sales and revenue from the daily sales table” routes well. “Helps users with business needs” does not.
Use tags and example queries. Both are fed to the router. Example queries are the cheapest accuracy win available — put the phrasings real users type into the skill’s examples.
Fix routing mistakes in the skill first. Reach for a few-shot override only when a phrasing is genuinely ambiguous and the skill can’t be sharpened further.
Remove an agent
Use ⋮ → Remove from Router on the card. Like adding, this is local until you Save. Removing an agent from a system never deletes the agent itself.
If the removed agent was selected as the fallback agent, update the default action before publishing — the publish check blocks a fallback that isn’t a member.
Common issues
- An agent isn’t in the picker — It’s a Task Agent, it isn’t Active, or it’s already a member.
- The card shows no skills — The agent has no skill with status Active. Add one on the agent, then reopen the builder.
- Everything routes to one agent — Two members’ skills overlap, or one is far more specific than the others. Tighten the descriptions and tags.
- A single member answers everything — With exactly one member the router skips classification entirely and sends every message to it. Add a second specialist.
Next
- Routing — how a turn is routed, and how to shape it.