Docs
AI Agents Overview
AI Agents Overview
Understand how GudDesk agents work and how they automate your customer support.
Agents in GudDesk are external services that receive webhook events and interact with your workspace via the REST API. Each agent brings its own logic, LLM, and billing — GudDesk provides the conversation data and actions.
How Agents Work
- An event happens in your workspace (new message, new conversation, etc.)
- GudDesk sends a webhook to every installed agent that subscribes to that event
- The agent processes the event — searches knowledge bases, calls LLMs, checks your systems
- The agent acts via the GudDesk API — replying, tagging, assigning, or resolving conversations
- The entire interaction is logged in your inbox
Agent Architecture
Agents are not hosted by GudDesk. They're external web services at HTTPS URLs, similar to how apps work on Shopify or Slack. This means:
- You choose your LLM — use Claude, GPT, Llama, or no LLM at all
- You own your billing — charge users however you want; GudDesk doesn't take a cut
- You control the logic — agents can integrate with your internal systems, CRMs, order databases, etc.
- Any language — write agents in TypeScript, Python, Go, Rust, or anything that can serve HTTP
Installing Agents
Install agents in Settings > AI Agents. When you install an agent, GudDesk creates:
- A webhook endpoint — GudDesk sends events to your agent's URL, signed with HMAC SHA-256
- A dedicated API key — your agent uses this to call the GudDesk API (READ_WRITE permission, scoped to the workspace)
Both credentials are shown once at install time and must be stored securely.
Agent Types
| Type | Description |
|---|---|
| Built-in | Platform-provided agents (coming soon) |
| Marketplace | Third-party agents from the GudDesk marketplace (coming soon) |
| Custom | Self-hosted agents you install by providing a webhook URL |
Available Events
| Event | Description |
|---|---|
message.created | A visitor or agent sent a message |
conversation.created | A new conversation started |
conversation.closed | A conversation was resolved |
conversation.assigned | A conversation was assigned to a team member |
Example Flow
Customer sends: "I want a refund for order #1234"
↓
GudDesk dispatches webhook to RefundBot
↓
RefundBot checks order database
↓
RefundBot calls POST /api/agent/reply
"Your refund has been processed!"
↓
RefundBot calls PATCH /api/v1/conversations/:id
{ "status": "CLOSED", "tags": ["refund", "resolved"] }
Reference Implementation
gud-agent is an open-source AI support agent that uses this exact pattern. It's a great starting point for building your own agent.
Next Steps
- Build a custom agent — step-by-step guide with code examples
- API Overview — full REST API documentation
- Webhooks — webhook event reference and payload format