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

{
  "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.

"name": "Order Management Agent"

description (optional)

A description of the agent’s role and capabilities.

"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

"tools": {
  "tool_name": {
    "name": "tool_name",
    "description": "What the tool does",
    "parameters": {
      "param1": "type",
      "param2": "type"
    }
  }
}

Example: Support Agent

{
  "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:

{
  "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.

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