> ## Documentation Index
> Fetch the complete documentation index at: https://ago.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```mermaid theme={null}
flowchart TD
    A[User Message] --> B[Main Router Agent<br>How can I help you today?]
    B --> C[Billing Agent<br>Payments, Invoices]
    B --> D[Technical Agent<br>Bugs, Setup, Integration]
    B --> E[Sales Agent<br>Pricing, Features]
```

### 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:

```markdown theme={null}
## 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

```mermaid theme={null}
flowchart TD
    A[1. User sends message to Main Agent] --> B[2. Main Agent analyzes intent]
    B --> C[3. Main Agent invokes Sub-Agent via tool]
    C --> D[4. Sub-Agent processes with:<br>Prompt template, Knowledge sources, Tools]
    D --> E[5. Sub-Agent returns response to Main Agent]
    E --> F[6. Main Agent integrates response]
    F --> G[7. Final response sent to user]
```

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

```mermaid theme={null}
flowchart TD
    A[Tier 1 Agent - General] -->|Cannot resolve| B[Tier 2 Agent - Specialist]
    B -->|Cannot resolve| C[Human Escalation - Ticketing Tool]
```

***

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

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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

    ***
  </Accordion>
</AccordionGroup>

## API Reference

See [Public API v1 Reference](../api/public-api-v1) for agent management endpoints.

***

## Related Documentation

* [Tools Description Guide](../guides/tools-description) - Best practices for tool descriptions
* [Agents Overview](../agent/agents) - Agent configuration
* [Tools Overview](../features/tools) - Tool configuration
* [Prompt Templates](../features/prompt-templates) - Prompt engineering