Custom Agents – GudDesk

Docs

Custom Agents

Build your own AI agents using the GudDesk Agent API.

The built-in agents cover common support patterns, but your business has unique workflows. The GudDesk Agent API lets you build custom agents that integrate with your tools and data.

Agent API Overview

Custom agents are TypeScript/JavaScript modules that:

Listen for specific conversation events (new message, tag added, etc.)
Process the conversation context (messages, customer data, tags)
Act by replying, tagging, assigning, resolving, or escalating

Basic Structure

import { GudDeskAgent } from "@guddesk/agents";
 
const myAgent = new GudDeskAgent({
  name: "RefundBot",
  description: "Handles refund requests automatically",
  trigger: "intent:refund_request",
 
  async handler(conversation) {
    // Access conversation data
    const customerEmail = conversation.customer.email;
    const latestMessage = conversation.messages.at(-1);
 
    // Integrate with your systems
    const order = await yourAPI.lookupOrder(customerEmail);
 
    if (order && order.isRefundable) {
      await yourAPI.processRefund(order.id);
      return conversation.resolve(
        `Your refund for order #${order.id} has been processed. ` +
        `You'll see it in 3-5 business days.`
      );
    }
 
    // Escalate if we can't handle it
    return conversation.escalate("refund-team", {
      note: `Customer requested refund. Order #${order?.id || "not found"}.`,
    });
  },
});

Triggers

Agents can be triggered by:

Trigger	Description
`message:new`	Any new customer message
`intent:<name>`	Detected intent (e.g., `intent:refund_request`)
`tag:<name>`	Conversation tagged with specific label
`event:assigned`	Conversation was assigned
`event:unresolved`	Previously resolved conversation was reopened
`schedule:cron`	Scheduled recurring trigger

Conversation Object

The conversation object gives you access to:

interface Conversation {
  id: string;
  status: "open" | "snoozed" | "resolved";
  customer: {
    id: string;
    email: string;
    name?: string;
    metadata?: Record<string, unknown>;
  };
  messages: Message[];
  tags: string[];
  assignee?: TeamMember;
  createdAt: Date;
 
  // Actions
  reply(text: string): Promise<void>;
  resolve(text?: string): Promise<void>;
  escalate(team: string, opts?: object): Promise<void>;
  tag(label: string): Promise<void>;
  assign(memberId: string): Promise<void>;
  addNote(text: string): Promise<void>;
}

Deploying Custom Agents

Via the Dashboard

Go to Settings > AI Agents > Custom
Click New Agent
Paste your agent code
Configure the trigger and priority
Click Deploy

Via the API

curl -X POST https://your-guddesk.com/api/agents \
  -H "Authorization: Bearer gd_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "RefundBot",
    "trigger": "intent:refund_request",
    "code": "... (base64 encoded)"
  }'

Testing

Test your agents before deploying to production:

import { testAgent } from "@guddesk/agents/testing";
 
const result = await testAgent(myAgent, {
  messages: [{ role: "customer", text: "I want a refund for order #1234" }],
  customer: { email: "test@example.com" },
});
 
console.log(result.action); // "resolve" | "escalate" | "reply"
console.log(result.response);

Best Practices

Start simple — Build agents for one specific task, not general-purpose bots
Always have an escalation path — If your agent can't handle something, route to a human
Log everything — Use conversation.addNote() to leave an audit trail
Test with real data — Use the testing framework with actual conversation samples
Monitor performance — Check resolution rates and customer satisfaction scores

Next Steps

API Overview — Full REST API documentation
Webhooks — Listen for events from external services

Built-In Agents API Overview