Agent-to-Agent Links

Agent-to-Agent Links let one agent automatically delegate questions to specialist agents in your workspace. Your main agent acts as an orchestrator — when a consumer asks something a linked agent specializes in, it passes the question to that specialist and incorporates the response.

How It Works

1. You link specialist agents to your main agent
2. Linked agents are automatically registered as tools during consumer chat
3. When your agent decides a specialist would provide a better answer, it calls that agent
4. The specialist responds using its own system prompt, model, and knowledge base
5. Your main agent incorporates the specialist’s response into its answer to the user

The consumer sees a seamless conversation — they don’t need to know multiple agents are involved.

Setting Up Agent Links

To remove a linked agent, click the x button next to its name in the Agent Tools list.

What Gets Passed to Specialists

When a linked agent is called:

Each call is a single turn — the specialist responds once and returns the result. There’s no multi-turn conversation between agents.

Per-user OAuth credentials (Google Drive, Outlook, etc.) are not shared with linked agents by default. If you want consumers to connect an integration once on the hub agent and have linked agents in the same workspace reuse it, turn on the hub agent’s Share connected credentials with linked agents toggle in the Agent Tools card (shareConsumerCredentialsWithLinkedAgents).

Structured Response Contracts

By default a specialist replies in free-form text. The calling agent can instead declare a response contract: a set of named fields (each with a description and an optional type) that the specialist must return. This happens automatically when the calling model decides it needs a machine-readable answer, and requires no configuration.

When a contract is declared:

• The specialist is told it is being called programmatically and must not reply conversationally.
• Its answer comes back as a JSON object with exactly the declared fields ({"status": "ok", "data": {...}}).
• If the specialist is missing information it needs, it pushes back with {"status": "needs_clarification", "question": "..."} instead of guessing, and the calling agent can follow up or ask the user.
• Fields the specialist genuinely cannot determine come back as null rather than fabricated values.

Example: a Butler agent asked “what important emails did I get in the past 24 hours?” can call an inbox specialist with a contract like [{name: "important_emails", type: "object[]", description: "Sender, subject, and a one-line reason each email matters"}, {name: "total_count", type: "number", description: "Total emails received"}] and receive structured data it can reason over, instead of prose it has to re-parse.

Step Limit for Linked Agents

A linked agent works in steps. A step is one model turn that can use tools (a search, a record lookup, a file read). By default a linked agent gets 5 steps per call. If it is still working at the limit, it is forced to answer with what it has, and its reply is marked as possibly incomplete.

If a specialist needs more steps (for example it searches records, pages through results, then writes a summary), raise its limit:

Things to know:

• The limit is a whole number from 1 to 25. The default is 5. Leave the box empty to use the default.
• The setting belongs to the agent that makes the call (your main agent), not to the specialist.
• A value on one linked agent wins over the value for the whole app. The app value wins over the default.
• It applies right away. You do not need to publish again.
• Agents calling agents: only the first hop, your main agent calling a specialist, can use a limit above 5. When a specialist calls another linked agent, that second call is always held to at most 5 steps.
• Higher limits can use more tokens. Usage is billed to your organization as usual, so raise the limit only for agents that need it.

Knowing when an answer was cut off

Every linked-agent reply includes a small status block that your main agent can read. It says whether the specialist hit its step limit (truncated), how many steps it used (iterationsUsed), the limit it ran with (effectiveBudget), and why it stopped (finishReason: completed, max_iterations, error, refused_payment, invalid_contract or error_before_loop).

{
  "completion": {
    "truncated": true,
    "iterationsUsed": 5,
    "effectiveBudget": 5,
    "budgetSource": "default",
    "finishReason": "max_iterations",
    "callDepth": 1
  },
  "response": "Here is what I found so far. [Note: this specialist agent reached its internal step limit ...]"
}

The short note at the end of a cut-off reply is still there, so older prompts keep working. For new instructions, tell your main agent to look at completion.truncated instead of the note: for example, “If completion.truncated is true, ask the specialist a narrower question or tell the user the answer may be incomplete.”

Delegation Topology

Together, your agents and their links form a delegation topology: the directed graph of who can call whom, and the contracts governing each hand-off. You can ask the Alchemist copilot to build one for you in a single step (“create a client-onboarding system with a front-door agent, a document collector, and a compliance checker”), or ask it “how are my agents wired together?” to read your workspace’s current topology back as nodes, edges, and hub/specialist roles.

Delegation Depth

Linked agents can themselves have linked agents, enabling multi-hop delegation:

• Depth 0: Consumer talks to your main agent
• Depth 1: Main agent calls a specialist
• Depth 2: That specialist calls one of its linked agents
• Depth 3: Maximum nesting depth (no further delegation)

This prevents infinite recursion while supporting reasonable multi-hop scenarios. Calls below the first hop are held to the default of 5 steps each (see Step Limit for Linked Agents).

Use Cases

Billing

When a linked agent is called, token usage is billed to the source app’s organization (the app the consumer is talking to). There’s no separate fee for agent-to-agent calls — it’s part of your standard LLM token billing.

Tips

• Write clear descriptions for your specialist agents. Your main agent uses the description to decide when to delegate, so make it specific.
• Keep specialists focused. A “billing expert” agent with a tailored system prompt and billing knowledge base will outperform a general-purpose agent.
• Test delegation patterns. In the chat preview, ask questions that should trigger delegation and verify the right specialist handles them.

Troubleshooting

Agent not delegating?

• Check that the specialist agent is linked in the Agent Tools card (Brain → Integrations tab)
• Verify the specialist’s description clearly indicates its specialty
• The main agent may handle the question itself if it has sufficient knowledge

Wrong specialist being called?

• Update specialist descriptions to be more specific about their domains
• Review your main agent’s system prompt — you can add instructions about when to delegate

Specialist reply says it reached its step limit?

• Raise the step limit for that agent (or for all linked agents) as described above, up to 25
• Or ask a narrower question so it can finish in fewer steps
• If the cut-off agent is a second-level agent (called by another linked agent), its limit is fixed at 5

Slow responses?

• Each delegation adds a round trip to another LLM call
• Consider whether the specialist adds enough value to justify the latency
• Avoid deep nesting (depth 2-3) unless necessary