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

# Agents

> Defining agent capabilities and tools

# Agents

Agents represent AI assistants with specific capabilities. Defining agents helps TurnWise understand what tools were available during a conversation.

## Structure

```json theme={null}
{
  "agents": [
    {
      "name": "Support Agent",
      "description": "Customer support agent handling inquiries",
      "tools": {
        "lookup_order": {
          "name": "lookup_order",
          "description": "Look up order details by ID",
          "parameters": {
            "order_id": "string"
          }
        }
      }
    }
  ]
}
```

## Fields

### name (optional)

A human-readable name for the agent.

```json theme={null}
"name": "Order Management Agent"
```

### description (optional)

A description of the agent's role and capabilities.

```json theme={null}
"description": "Specialized agent for handling order-related inquiries including status checks, modifications, and cancellations"
```

### tools (optional)

An object containing tool definitions. Each key is the tool name.

## Tool Structure

```json theme={null}
"tools": {
  "tool_name": {
    "name": "tool_name",
    "description": "What the tool does",
    "parameters": {
      "param1": "type",
      "param2": "type"
    }
  }
}
```

## Example: Support Agent

```json theme={null}
{
  "agents": [
    {
      "name": "Support Agent",
      "description": "Customer support agent for order inquiries",
      "tools": {
        "lookup_order": {
          "name": "lookup_order",
          "description": "Look up order details by order ID",
          "parameters": {
            "order_id": "string"
          }
        },
        "process_refund": {
          "name": "process_refund",
          "description": "Process a refund for an order",
          "parameters": {
            "order_id": "string",
            "amount": "number"
          }
        },
        "update_shipping": {
          "name": "update_shipping",
          "description": "Update shipping address for an order",
          "parameters": {
            "order_id": "string",
            "new_address": "object"
          }
        }
      }
    }
  ]
}
```

## Multiple Agents

Conversations can have multiple agents, representing different specialists:

```json theme={null}
{
  "agents": [
    {
      "name": "Triage Agent",
      "description": "Routes inquiries to appropriate specialists",
      "tools": {
        "classify_intent": {...},
        "transfer_to_agent": {...}
      }
    },
    {
      "name": "Technical Support",
      "description": "Handles technical issues",
      "tools": {
        "check_system_status": {...},
        "create_ticket": {...}
      }
    },
    {
      "name": "Billing Support",
      "description": "Handles billing inquiries",
      "tools": {
        "lookup_invoice": {...},
        "process_payment": {...}
      }
    }
  ]
}
```

## Why Define Agents?

Defining agents enables:

* **Tool Usage Evaluation**: Verify agents used appropriate tools
* **Capability Analysis**: Understand what tools were available
* **Multi-Agent Tracking**: Distinguish between different agents in complex workflows
* **Documentation**: Self-documenting data for future reference

## Optional but Recommended

While agents are optional, defining them provides valuable context for evaluation. Without agent definitions, TurnWise can still process conversations but won't have tool context.

<Tip>
  Even if you only have one agent, defining it with its tools makes your data more self-documenting and enables tool-specific evaluations.
</Tip>