Tools

Extend agent capabilities with actions like API calls, tickets, and emails

Tools extend agent capabilities by allowing them to perform actions beyond answering questions. Agents can create tickets, query APIs, send emails, and execute custom workflows through tools.

AI Studio - Tools List

Overview

Tools in AGO enable agents to:

• Execute external API calls
• Create support tickets and escalate to humans
• Send emails
• Invoke other specialized agents
• Search knowledge with parameters
• Return structured UI components
• Perform web searches

Prerequisites

System Requirements

• AGO platform deployed and accessible
• Admin access to configure tools

Knowledge Required

• Understanding of REST APIs (for HTTP tools)
• JSON Schema basics (for custom input schemas)

Configuration Required

• Agent created and configured
• API credentials for external services (if using HTTP tools)

---

Built-in Tools

AGO provides several built-in tools ready to use. Each tool has dedicated documentation with complete configuration guides.

Ticketing Tool

Create support tickets and escalate to humans (ago_ticketing)

HTTP Request Tool

Make HTTP requests to external APIs (ago_http_request)

Send Email Tool

Send emails via AWS SES (ago_send_email)

Agent Invocation Tool

Delegate tasks to other agents (ago_agent_invocation)

Parameterized Search Tool

Search knowledge with filters (ago_parameterized_search)

UI Resource Tool

Return rich UI components (ui_resource)

Additional Tools

Tool	Name	Description
Report Knowledge Gap	report_knowledge_gap	Signals missing or incomplete knowledge so you can fill gaps
Conversation Tagger	conv_tagger	Automatically tags conversations with categories for analytics
Linkup Web Search	ago_linkup	Web search for real-time information
AGO API POST	ago_api_post	Specialized POST requests for API integrations
Search and Enrich	ago_search_and_enrich	Search knowledge and enrich with metadata

---

Tool Configuration

Tool Configuration Fields

Setting	Description
Name	Internal identifier (must be unique)
Display Name	User-facing name shown in tool calls
Description	What the tool does (helps the AI decide when to use it)
Tool Type	Template that provides default configuration
Additional Info	Tool-specific configuration (base URL, API key, etc.)
Input Schema	Parameter schema defining what the tool accepts (see below)
Prompt	Instructions for when and how to use the tool
Secret Key	API keys or secrets (stored encrypted)
Strict Mode	Enforce OpenAI function calling compliance
Forward User Auth	Pass user credentials to external APIs

Permission and Security Fields

Setting	Description
Required Permissions	Permissions a user must have to use this tool
Source Restrictions	Limit the tool to specific knowledge sources
Admin Tags	Tags automatically applied when the tool executes

---

Input Schema

Tools use input schemas to define their parameters. AGO supports two formats.

Simplified Format

Easy-to-use format for common parameter types:

{
  "input_schema": {
    "customer_email": {
      "type": "str",
      "description": "Customer email address"
    },
    "priority": {
      "type": "int",
      "default": 1,
      "description": "Ticket priority (1-5)"
    },
    "notify": {
      "type": "bool",
      "default": true,
      "description": "Send notification"
    },
    "category": {
      "type": "str",
      "enum": ["billing", "technical", "general"],
      "description": "Ticket category"
    },
    "tags": {
      "type": "str[]",
      "description": "List of tags"
    }
  }
}

Supported Types:

• str - String
• int - Integer
• float - Float
• bool - Boolean
• str[] or list[str] - Array of strings
• int[] or list[int] - Array of integers

Optional Properties:

• default - Default value
• enum - Allowed values
• description - Parameter description

JSON Schema Format

For complex schemas, use standard JSON Schema (must include $schema key):

{
  "input_schema": {
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Search query"
      },
      "filters": {
        "type": "object",
        "properties": {
          "date_from": { "type": "string", "format": "date" },
          "date_to": { "type": "string", "format": "date" }
        }
      }
    },
    "required": ["query"]
  }
}

---

Tool Execution States

Tools can have different execution states, enabling interactive workflows.

State	Description
CREATED	Tool call created, not yet executed
WAITING_CONFIRMATION	Awaiting user confirmation
CONFIRMED	User confirmed, proceeding
REJECTED	User rejected the action
WAITING_INPUT	Tool needs additional user input
RUNNING	Tool is executing
DONE	Execution completed successfully
ERROR	Execution failed

Interactive Tools

Tools can request user input mid-execution using WAITING_INPUT state:

1. Tool returns status: "WAITING_INPUT" with a form_schema
2. Frontend renders the form to the user
3. User submits the form via /api/tool-calls/{id}/submit/
4. Tool continues execution with user input

---

Creating Custom Tools

1. Create Tool Type (Optional)

   Tool types serve as templates with default configurations:

   1. Navigate to AI Studio → Tools, then click Tool Types
   2. Click Create Tool Type
   3. Configure the template:
      • Name: Internal identifier (e.g., “custom_api_tool”)
      • Description: What this tool type is for
      • Additional Info Schema: Define required configuration fields
   4. Click Save
2. Create Tool Instance

   1. Navigate to AI Studio → Tools
   2. Click Create Tool
   3. Select your tool type (or a built-in type)
   4. Configure the tool:
      • Name: Internal identifier
      • Display Name: User-facing name
      • Description: What the tool does
      • Additional Info: Tool-specific configuration (base URL, API key, etc.)
      • Input Schema: Define parameters
      • Prompt: Instructions for when/how to use
   5. Click Save
3. Assign to Agent

   1. Navigate to AI Studio → Agents
   2. Select the agent
   3. Go to the Tools tab
   4. Add your custom tool to the agent’s tool list
   5. Click Save

---

Tool Permissions

Restricting Tool Access

Tools can be restricted to users with specific permissions:

1. Edit the tool in AI Studio → Tools
2. Go to the Permissions section
3. Add Required Permissions to limit access
4. Click Save

Only users with the specified permissions will see and use the tool.

Source Restrictions

Limit tools to specific knowledge sources:

1. Edit the tool
2. Go to the Sources section
3. Add Source Restrictions to limit which knowledge sources the tool can access
4. Click Save

The tool will only operate on documents from the specified sources.

Approval for Background Runs

For tools that perform sensitive write actions (issuing a refund, updating a record), you can require a human decision before a background agent may use them:

1. Edit the tool
2. Go to the Access & Restrictions tab
3. Turn on Require approval in background runs
4. Click Save

When a background agent reaches this tool, the run pauses and staff users get an approval card in the conversation showing the tool and the values it wants to send. The agent only executes the action after a staff member approves it; a rejected or expired approval (72 hours) skips the action. Regular chat agents are not affected by this setting — it applies to background runs only. See Action Approvals for the full flow.

---

Agents Using a Tool

When editing a tool, the Agents tab lists every agent that has this tool attached. Use it to check what depends on a tool before you change or remove it.

1. Edit the tool in AI Studio → Tools
2. Open the Agents tab
3. Click an agent in the list to open it

If no agent uses the tool, the tab shows an empty state.

---

API Reference

For programmatic tool management, see the Public API v1 Reference.

---

Best Practices

Tool Design

• Clear descriptions: Write descriptions that help the LLM understand when to use the tool
• Focused purpose: Each tool should do one thing well
• Sensible defaults: Provide default values for optional parameters
• Validation: Use input schemas to validate parameters

Security

• Least privilege: Only grant necessary permissions
• Source restrictions: Limit tools to relevant knowledge sources
• Secret management: Store API keys in the Secret Key field (encrypted at rest)
• Auth forwarding: Use Forward User Auth carefully, only when needed

Performance

• Timeout handling: External APIs may be slow; implement timeouts
• Error handling: Return helpful error messages
• Caching: Consider caching frequent tool responses

---

Troubleshooting

Tool not appearing for users

Problem: Users can’t see or use a configured tool.

Solutions:

1. Check if the tool is assigned to the agent in the Tools tab
2. Verify the user has the required permissions
3. Verify the tool status is active

HTTP tool requests failing

Problem: AGO HTTP Request Tool returns errors.

Solutions:

1. Check if target URL is accessible (not internal IP - SSRF protection)
2. Verify API credentials in the tool’s Additional Info configuration
3. Check request format matches API expectations
4. Review tool logs for detailed error messages

Tool validation fails

Problem: Tool creation/update fails with validation errors.

Solutions:

1. Verify the Input Schema format (simplified or JSON Schema)
2. Check that the Additional Info matches the expected schema of the tool type
3. Check that required fields are provided

Agent not using tool when expected

Problem: Agent doesn’t call tool when it should.

Solutions:

1. Review the tool’s Description and Prompt — make them clearer
2. Check if tool is assigned to the agent
3. Verify user message clearly indicates need for tool
4. Test with explicit tool-triggering phrases

Interactive tool form not appearing

Problem: Tool is in WAITING_INPUT but no form shows.

Solutions:

1. Verify the form schema is properly formatted
2. Check frontend widget supports interactive tools
3. Verify tool returns correct status

---

Related

Ticketing Tool

Create support tickets

HTTP Request Tool

Call external APIs

Send Email Tool

Send emails

Agent Invocation Tool

Delegate to other agents

Parameterized Search Tool

Advanced retrieval

UI Resource Tool

Rich UI responses

Writing Tool Descriptions

How to write effective descriptions