Agent Invocation Tool

Call specialized agents from other agents for multi-agent workflows

The Agent Invocation Tool enables agents to call other specialized agents, creating multi-agent architectures and complex workflows.

Overview

Tool Name: ago_agent_invocation

This tool allows a main agent to delegate tasks to specialized sub-agents, enabling sophisticated multi-agent systems where different agents handle different domains or tasks.

Key Features

• Call specialized agents from a general agent
• Circular call detection (prevents infinite loops)
• Optional context sharing between agents
• Configurable call depth limits
• Automatic response integration

---

Architecture

Multi-Agent Pattern

Benefits

Benefit	Description
Specialization	Each agent optimized for specific domain
Scalability	Add new agents without changing main agent
Maintainability	Update domain knowledge independently
Accuracy	Focused prompts produce better responses

---

Configuration

Enable Agent as Tool

To enable an agent to be called as a tool:

1. Navigate to AI Studio → Agents
2. Select the agent you want to enable as a tool
3. Go to the Settings tab
4. Enable Can be used as tool
5. Enter a clear Tool Description that explains when this agent should be called
6. Click Save

Configuration Fields

Setting	Default	Description
Enable as Tool	Off	Allow this agent to be invoked by other agents
Tool Description	(empty)	Description shown to the calling agent to decide when to invoke
Share Conversation Context	Off	Pass parent conversation history to the sub-agent
Max Call Depth	5	Maximum nesting depth (prevents infinite loops)

Assign Agent Tools

To configure which agents the main agent can invoke:

1. Navigate to AI Studio → Agents
2. Select the main (router) agent
3. Go to the Agent Tools tab
4. Add the specialized agents you want to make available
5. Click Save

---

Tool Description

Write clear tool descriptions to help the main agent route correctly:

Good Examples

# Billing Agent
"Handles all billing and payment questions including:
- Invoice inquiries and payment history
- Subscription changes (upgrade, downgrade, cancel)
- Refund requests
- Payment method updates
- Pricing questions for existing customers"

# Technical Agent
"Handles technical support and troubleshooting:
- Bug reports and error messages
- Integration and API questions
- Setup and configuration help
- Performance issues
- Feature usage questions"

# Sales Agent
"Handles pre-sales inquiries:
- Product feature comparisons
- Pricing for new customers
- Demo requests
- Enterprise solutions
- Custom requirements"

Bad Examples

# Too vague
"Helps with billing stuff"

# Too broad
"Can answer any question about the product"

# Overlapping
"Handles customer questions" (all agents do this)

---

Routing Logic

Main Agent Prompt

Configure routing in the main agent’s prompt:

## Agent Routing

You are a support router. Analyze each user message and route to the appropriate specialist:

### Billing Agent
Use when the user asks about:
- Payments, invoices, receipts
- Subscription status or changes
- Refunds or credits
- Payment methods

### Technical Agent
Use when the user asks about:
- Errors or bugs
- How to use features
- API or integrations
- Performance issues

### Sales Agent
Use when the user asks about:
- Pricing for new customers
- Product comparisons
- Demo requests
- Enterprise features

### Handle Directly
For general questions like:
- Company information
- Simple greetings
- Unclear requests (ask for clarification)

---

Context Sharing

Without Context Sharing (Default)

The sub-agent receives only the current message:

Main Agent Context:
- Full conversation history

Sub-Agent Receives:
- Current user message only
- Sub-agent's own knowledge sources

With Context Sharing

To enable context sharing, go to the sub-agent’s settings and enable Share Conversation Context.

When enabled, the sub-agent receives:

• Full conversation history from the parent agent
• Current user message
• Sub-agent’s own knowledge sources

When to Use Context Sharing

Use Context	Don’t Use Context
Follow-up questions	Independent queries
Complex multi-turn conversations	Simple lookups
When history affects answer	Privacy-sensitive domains

---

Call Depth Protection

Preventing Infinite Loops

The max call depth setting prevents circular calls:

Agent A → Agent B → Agent C → [STOP at max_call_depth]

Default Limits

Configure the max call depth in the agent settings. The default is 5 levels deep, which is sufficient for most use cases. For simpler architectures, consider setting it to 2–3.

Circular Call Detection

The system automatically detects and prevents:

• Agent A calling Agent B calling Agent A
• Self-invocation (Agent A calling Agent A)

---

Response Flow

Invocation Sequence

Response Integration

The main agent can:

• Pass through sub-agent response directly
• Summarize or format the response
• Add additional context
• Combine with other information

---

Examples

Customer Support Router

To set up a customer support routing system:

Step 1: Create Specialized Agents

Agent	Tool Description	Knowledge Sources
Technical Support	”Handles technical issues, bugs, and feature questions”	Technical documentation
Billing Support	”Handles billing, payments, and subscription questions”	Billing documentation

For each specialized agent:

1. Create the agent in AI Studio → Agents
2. Enable Can be used as tool
3. Add a clear tool description
4. Assign relevant knowledge sources

Step 2: Create the Router Agent

1. Create a new agent named “Support Assistant”
2. In Agent Tools, add Technical Support and Billing Support
3. Configure the prompt template with routing logic (see Routing Logic section above)

Escalation Chain

---

Best Practices

Agent Design

• Clear boundaries: Each agent should have distinct responsibilities
• Minimal overlap: Avoid ambiguous routing decisions
• Focused knowledge: Assign only relevant sources to each agent
• Consistent tone: Maintain brand voice across all agents

Routing Logic

• Explicit triggers: Define clear routing keywords
• Fallback handling: Default behavior for unclear requests
• Confirmation: Consider confirming routing for complex queries
• Logging: Track routing decisions for optimization

Performance

• Limit depth: Keep the max call depth low (2–3 for most cases)
• Selective context: Only share context when necessary
• Monitor latency: Multi-agent calls add response time
• Cache patterns: Identify common routing patterns

---

Troubleshooting

Issue: Agent not appearing as tool option

Problem: Main agent doesn’t see target agent as available tool.

Solutions:

1. Verify “Enable as Tool” is turned on for the target agent
2. Check the target agent is in the main agent’s Agent Tools list
3. Ensure both agents are active
4. Verify target agent has a tool description set

Issue: Infinite loop detected

Problem: Error about circular calls or max depth exceeded.

Solutions:

1. Review agent tool assignments for circular references
2. Increase the max call depth if legitimately needed
3. Simplify agent hierarchy
4. Check if agent is calling itself

Issue: Sub-agent response not integrated properly

Problem: Main agent doesn’t use sub-agent’s response correctly.

Solutions:

1. Review main agent’s prompt for response handling instructions
2. Check the “Share Conversation Context” setting
3. Verify sub-agent is returning expected format
4. Test sub-agent directly to verify responses

Issue: Wrong agent being called

Problem: Main agent routes to incorrect sub-agent.

Solutions:

1. Improve tool descriptions with clearer boundaries
2. Add more specific routing rules to main agent’s prompt
3. Add negative examples (“Do NOT use this agent for…”)
4. Review and refine keyword triggers

---

API Reference

See Public API v1 Reference for agent management endpoints.

---

Related Documentation

• Tools Description Guide - Best practices for tool descriptions
• Agents Overview - Agent configuration
• Tools Overview - Tool configuration
• Prompt Templates - Prompt engineering