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

# Ticketing Tool

> Create support tickets and escalate conversations to human agents

The AGO Ticketing Tool enables agents to create support tickets and escalate conversations to human agents when needed.

## Overview

**Tool Name:** `ago_ticketing`

The ticketing tool provides a direct escalation path from AI conversations to human support. When an agent cannot resolve an issue or a user requests human assistance, this tool creates a ticket with full conversation context.

## Key Features

* Create support tickets from conversation context
* Escalate to human support teams
* Attach full conversation history to tickets
* Integrate with external ticketing systems (Zendesk, HelpScout)
* Customizable ticket forms and fields
* Priority and category assignment

***

## When to Use

The ticketing tool should be triggered when:

| Scenario                      | Example                             |
| ----------------------------- | ----------------------------------- |
| User requests human help      | "Can I speak to someone?"           |
| Issue requires account access | Password resets, billing changes    |
| Complex issues                | Multi-step troubleshooting failures |
| User frustration detected     | Multiple failed attempts            |
| Sensitive topics              | Legal, compliance, security         |
| Out of scope requests         | Topics agent isn't trained for      |

***

## Configuration

### Global Settings

Configure the ticketing tool system-wide via backend configuration:

* **Add ticketing tool to all agents**: Automatically include this tool for every agent
* **Default tool description**: The prompt that tells agents when to use the ticketing tool

| Setting                          | Description                                        |
| -------------------------------- | -------------------------------------------------- |
| Add ticketing tool to all agents | Automatically include this tool for every agent    |
| Default tool description         | Prompt that guides agent on when to create tickets |

### Default Tool Description

```
You are the ticketing system. Use this tool when the user wants:
- to talk to a human / call the support
- if you detect frustrations
- the user wants to open a ticket
- the user wants to perform an action that needs to open a ticket
The prerequisite is that the user has previously given information about
its problem otherwise we can't help them with this tool.
```

### Per-Agent Configuration

To customize the ticketing tool for a specific agent:

1. Navigate to **AI Studio** → **Tools**
2. Click **Create Tool**
3. Select **Ticketing** as the tool type
4. Configure the tool:
   * **Name**: Internal identifier (e.g., "support\_escalation")
   * **Display Name**: User-facing name (e.g., "Contact Support")
   * **Description**: Brief description for the agent
   * **Prompt**: When the agent should use this tool
5. Define the **Input Schema** with custom fields:
   * Subject (required)
   * Priority (optional: low, normal, high, urgent)
   * Category (optional: based on your support categories)
6. Click **Save**
7. Assign the tool to your agent in **AI Studio** → **Agents** → **\[Agent Name]** → **Tools**

***

## Input Schema

### Standard Fields

| Field       | Type   | Required | Description                |
| ----------- | ------ | -------- | -------------------------- |
| subject     | string | Yes      | Ticket subject line        |
| description | string | No       | Detailed issue description |
| priority    | enum   | No       | low, normal, high, urgent  |
| category    | string | No       | Issue category             |

### Custom Fields

Add custom fields based on your ticketing system needs. When editing the tool's input schema, you can add fields such as:

| Field               | Type | Example Values                        |
| ------------------- | ---- | ------------------------------------- |
| subject             | text | Required ticket subject               |
| product\_area       | enum | dashboard, api, integrations, billing |
| customer\_type      | enum | free, pro, enterprise                 |
| reproduction\_steps | text | Steps to reproduce the issue          |
| browser             | text | User's browser information            |
| urgency\_reason     | text | Why the issue is urgent               |

Each field can be configured as required or optional, with default values and descriptions to guide the agent.

***

## Ticket Creation Flow

```mermaid theme={null}
flowchart TD
    A[User Requests Help] --> B[Agent Evaluates<br>Can I help?<br>Is escalation appropriate?]
    B --> C[Gather Context<br>Issue summary<br>Steps tried<br>User info]
    C --> D[Call Ticketing Tool]
    D --> E[Create Ticket<br>Attach history<br>Set priority<br>Assign team]
    E --> F[Confirm to User<br>Ticket number<br>Expected SLA]
```

***

## AI Pre-Fill

The ticketing tool can extract ticket information from the conversation using AI. When a ticket form is configured with pre-fillable fields, the system automatically generates a prompt that instructs the LLM to extract values for those fields from the conversation.

### How It Works

1. Admin marks specific form fields as **AI pre-fill enabled** in the ticket form configuration
2. When the agent triggers the ticketing tool, the system builds a dynamic extraction prompt listing all pre-fillable fields with their types, options, and validation rules
3. The LLM extracts values from the conversation and pre-fills the form
4. The user reviews and submits the form with pre-filled values

### Supported Field Types

AI pre-fill works with all custom field types: text, textarea, tagger, multiselect, checkbox, integer, and regexp-validated fields. For fields with predefined options (tagger, multiselect), the LLM is given the available choices to select from.

### Custom Extraction Instructions

Each ticket form has an optional **System Prompt** field where you can add custom extraction instructions. For example: "Always extract reproduction steps if the user describes a bug" or "Mark priority as High when the user mentions the word urgent."

***

## Embedded Forms

Ticket forms support two display modes:

| Mode               | Description                                                         |
| ------------------ | ------------------------------------------------------------------- |
| **Form** (default) | AGO renders the form inline in the chat widget                      |
| **Embed**          | An external form (e.g. HubSpot, Typeform) is displayed in an iframe |

### Configuring Embedded Forms

1. In the ticket form settings, set **Mode** to **Embed**
2. Paste the external form HTML/script in the **Embed HTML** field
3. Optionally add an **Embed Description** shown above the form

When a user triggers ticket creation with an embed form, the external form is displayed in the chat. After the user submits, the captured data is processed and a ticket is created.

***

## Integration with Ticketing Systems

### Zendesk Integration

Connect to Zendesk for ticket creation:

1. Configure Zendesk connector in **Settings** → **Ticketing**
2. Map ticket fields to Zendesk fields
3. Configure assignee rules

See [Zendesk Ticketing Integration](../data-connector/zendesk-ticketing-integration) for setup.

### HelpScout Integration

Connect to HelpScout:

1. Configure HelpScout connector
2. Map conversation to HelpScout conversation
3. Set mailbox assignment

See [HelpScout Integration](../data-connector/helpscout-integration) for setup.

### Internal Ticketing

Use AGO's built-in ticketing without external integration:

* Tickets stored in AGO database
* Manage via admin interface
* Export to CSV/JSON

***

## Conversation Context

When a ticket is created, the tool automatically includes:

| Context             | Description                     |
| ------------------- | ------------------------------- |
| Full conversation   | All messages in the thread      |
| User information    | Name, email, account details    |
| Documents retrieved | Knowledge used in conversation  |
| Tool calls made     | Previous tool executions        |
| Session metadata    | Timestamp, duration, agent used |

***

## Best Practices

### Prompt Engineering

Write clear escalation triggers in the agent's prompt:

```markdown theme={null}
## Escalation Rules

Create a support ticket when:
1. User explicitly says "speak to a human" or similar
2. You cannot resolve the issue after 2-3 troubleshooting attempts
3. The issue requires account-level access you don't have
4. User expresses significant frustration

Before creating a ticket:
1. Summarize the issue clearly
2. List what you've already tried
3. Ask the user to confirm they want to create a ticket
```

### User Experience

* **Confirm before creating**: Always verify with the user
* **Set expectations**: Provide estimated response times
* **Provide reference**: Give ticket number for tracking
* **Offer alternatives**: Suggest self-service options first

### Quality Control

* **Rich context**: Include all relevant details
* **Clear categorization**: Use accurate priority and category
* **Avoid duplicates**: Check for existing tickets
* **Follow up**: Track resolution rates

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Issue: Tickets not being created">
    **Solutions:**

    1. Verify ticketing tool is assigned to agent
    2. Check external ticketing credentials
    3. Review tool logs for errors
    4. Verify user has ticket creation permissions
  </Accordion>

  <Accordion title="Issue: Missing conversation context">
    **Solutions:**

    1. Check thread ID is being passed correctly
    2. Verify conversation history storage
    3. Review ticket connector configuration
  </Accordion>

  <Accordion title="Issue: Wrong assignee or priority">
    **Solutions:**

    1. Review input schema configuration
    2. Check default values
    3. Verify mapping rules in connector

    ***
  </Accordion>
</AccordionGroup>

## API Reference

For programmatic access, see:

* [Public API v1 Reference](../api/public-api-v1) - Tool management and ticket creation

***

## Related Documentation

* [Tools Description Guide](../guides/tools-description) - Best practices for tool descriptions
* [Ticketing Overview](../features/ticketing) - Ticketing system setup
* [Tools Overview](../features/tools) - Tool configuration
* [Zendesk Integration](../data-connector/zendesk-ticketing-integration) - Zendesk setup
* [HelpScout Integration](../data-connector/helpscout-integration) - HelpScout setup