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

---

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 for setup.

HelpScout Integration

Connect to HelpScout:

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

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

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

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

Issue: Missing conversation context

Solutions:

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

Issue: Wrong assignee or priority

Solutions:

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

---

API Reference

For programmatic access, see:

• Public API v1 Reference - Tool management and ticket creation

---

Related Documentation

• Tools Description Guide - Best practices for tool descriptions
• Ticketing Overview - Ticketing system setup
• Tools Overview - Tool configuration
• Zendesk Integration - Zendesk setup
• HelpScout Integration - HelpScout setup