# Autonomous Agents
Source: https://docs.duckie.ai/agents/autonomous-agents
Configure agents that decide which resources and tools to use at run time
Autonomous agents handle open-ended customer conversations by deciding what to research, which tools to call, and when to respond.
Instead of starting from one fixed runbook or workflow, an autonomous agent starts from your instructions and the resources you make available: runbooks, workflows, knowledge, guidelines, guardrails, and tools.
## When to Use Autonomous Agents
Use an autonomous agent when the conversation needs judgment, research, or flexible sequencing.
| Use autonomous when | Use a workflow or runbook when |
| ------------------------------------------------------------------------------- | --------------------------------------------------------- |
| Customer requests vary widely | The process follows the same steps every time |
| The agent needs to choose between multiple runbooks or workflows | You already know the exact procedure to run |
| The agent may need to search knowledge, call tools, then decide what to do next | Compliance requires a deterministic branch-by-branch flow |
| The same deployment handles many support topics | The deployment is scoped to one known task |
## How Autonomous Agents Work
When an autonomous agent runs, Duckie gives it the conversation, your agent instructions, and the resources enabled for that agent.
The agent can:
* Read relevant runbooks before taking action
* Follow guidelines and guardrails assigned to the agent
* Search available knowledge
* Call Duckie tools, app tools, custom tools, MCP tools, and workflows
* Delegate focused tasks to callable agents
* Send a customer response through an available responder tool
* End its turn when the work is complete
Autonomous agents also keep run history in Duckie, so you can review what they researched, which tools they called, and what response they sent.
## Create an Autonomous Agent
Go to **Build → Agents** and click **Create Agent**.
Choose **Autonomous** in the mode selector.
Add a clear name, choose a status, and optionally adjust the model settings.
Describe the agent's job, scope, decision rules, and handoff expectations.
Good instructions tell the agent what it is responsible for, what it should avoid, and how it should decide between available resources.
Open the configuration sections to choose tools, knowledge tags, rules, tracking, runbooks, and workflows.
Save the agent, then test it in the [playground](/testing/playground) before deploying it to customers.
## Configuration Reference
### Instructions
Instructions are the primary behavior definition for an autonomous agent.
Use them to define:
* The agent's role and scope
* When to research before answering
* Which situations require escalation
* How to choose between runbooks, workflows, and tools
* Tone or format requirements that are specific to this agent
Example:
```text theme={null}
You are a billing support agent. Help customers understand invoices, payment failures, refunds, and plan changes.
Always check relevant billing runbooks before answering. If a customer asks for a refund, verify eligibility before making promises. Escalate disputes, chargebacks, legal threats, and account ownership questions.
```
### Model
Autonomous agents have model settings in the agent editor. Use the default model for most agents, and increase reasoning effort only when the agent needs deeper analysis.
### Tools
Autonomous agents can use enabled tools from the agent's **Tools** section.
Tool access can include:
* [Duckie Tools](/tools/duckie-tools)
* [App Tools](/tools/app-tools)
* [Custom Tools](/tools/custom-tools)
* [MCP tools](/tools/mcp-servers)
If all available tools are selected, Duckie stores that as all tools enabled. If you select a smaller set, the autonomous agent can only call the selected tools.
### Callable Agents
Use **Callable agents** to control which other agents an autonomous agent can invoke as sub-agents.
| Setting | Behavior |
| --------------- | ----------------------------------------------------------------- |
| None | Agent cannot call other agents |
| All | Agent can call any active agent in the organization except itself |
| Specific agents | Agent can only call the selected agents |
When a callable agent is available, Duckie presents it to the autonomous agent by name and description. The autonomous agent sends a task and chooses whether the child run should include the current conversation history.
[Learn more about sub-agents ->](/agents/sub-agents)
### Knowledge
Use **Knowledge Tags** to limit which knowledge the agent can search.
| Setting | Behavior |
| ------------------------- | ------------------------------------------ |
| No tags selected | Agent can access all knowledge |
| One or more tags selected | Agent can access knowledge with those tags |
| No Tags selected | Agent can access untagged knowledge only |
### Rules
Use **Guidelines** for communication behavior and **Guardrails** for restrictions and escalation rules.
If you do not select specific guidelines or guardrails, the agent can use all available rules for the organization.
### Runbooks and Workflows
Autonomous agents can use runbooks and workflows as resources.
| Setting | Behavior |
| -------------------------- | ----------------------------------------- |
| Only allow these runbooks | Limits which runbooks the agent can read |
| Block these runbooks | Hides specific runbooks from the agent |
| Only allow these workflows | Limits which workflows the agent can call |
| Block these workflows | Hides specific workflows from the agent |
Runbooks are the highest-priority procedural resource. If a relevant runbook exists, the autonomous agent is expected to read it before searching broader knowledge.
### Tracking
Use **Attributes**, **Categories**, and **Resolution Tracking** to control how completed runs are classified for analytics.
## Best Practices
* Give the agent a clear job boundary.
* Make escalation conditions explicit.
* Keep powerful write actions limited to agents that need them.
* Use runbook and workflow allowlists for specialized agents.
* Test common, edge-case, and escalation scenarios in the playground.
* Start deployments in testing mode before switching to live traffic.
## Next Steps
Build deterministic flows autonomous agents can call
Delegate work to other agents
Write procedures autonomous agents can read
Configure actions the agent can take
Test the agent before deployment
# Agent Configuration
Source: https://docs.duckie.ai/agents/configuration
Deep dive into all agent settings
This page covers all configuration options available for Duckie agents. Access these settings by clicking on any agent in **Build → Agents**.
## Basic Settings
### Name & Description
* **Name** — Displayed throughout the app and in analytics
* **Description** — Help your team understand what this agent does
Descriptions also help other agents decide when to call this agent as a [sub-agent](/agents/sub-agents).
To edit: Click the agent name or description in the header.
### Status
Agents can be:
* **Active** — Available for deployments and testing
* **Inactive** — Saved but not active
* **Draft** — In progress and not ready for production use
## Starting Logic
The start mode defines how your agent begins handling a conversation. Choose one:
### Autonomous
An autonomous agent starts from instructions and decides which resources and tools to use.
**When to use:**
* Requests vary across many topics
* The agent needs to research before deciding what to do
* The agent may need to choose between multiple runbooks, workflows, or tools
[Learn more about Autonomous Agents →](/agents/autonomous-agents)
### Duckie Assistant
A Duckie Assistant agent is a Duckie copilot for working with Duckie objects.
It uses the same autonomous run infrastructure as an autonomous agent, but its configuration is lighter. Duckie Assistant agents use instructions, model settings, and tools. They do not use runbooks, workflows, guidelines, guardrails, classification, resolution tracking, or callable-agent configuration.
**When to use:**
* You want an assistant that can inspect or update Duckie configuration
* The agent should work through Duckie Assistant MCP tools
* You want behavior controlled primarily by the agent instructions and selected tools
[Learn more about Duckie Assistant Agents ->](/agents/duckie-assistant-agents)
### Workflow
A workflow is a visual graph that defines exact steps and branches.
**When to use:**
* Process must follow exact steps every time
* Compliance requires predictable, auditable execution
* Multiple tools must be called in a specific order
[Learn more about Workflows →](/workflows/overview)
### Runbook
A runbook is natural language instructions that guide the agent while allowing flexibility.
**When to use:**
* Conversations require judgment and adaptation
* Process has a general structure but varies by situation
* You want to leverage AI reasoning within guidelines
[Learn more about Runbooks →](/runbooks/overview)
## Autonomous Instructions
Autonomous and Duckie Assistant agents include an instructions editor and model settings.
Use instructions to define:
* The agent's role and scope
* How it should decide what to research
* When it should call tools
* When it should escalate
* Any tone, format, or process rules specific to this agent
Autonomous agents can also use runbooks and workflows as resources when you allow them in the **Runbooks & Workflows** section.
Duckie Assistant agents use the same instructions editor, but the prompt is framed as a Duckie copilot instead of a customer-support agent. Put core behavior, boundaries, and object-editing expectations directly in the instructions.
## Knowledge Configuration
Control what information the agent can access when searching.
### Tag Filtering
Filter by knowledge tags:
* Leave tags empty to allow all connected and custom knowledge
* Select tags to allow knowledge with those tags
* Select **No Tags** to allow untagged knowledge only
### Strategy Tips
| Goal | Approach |
| ---------------- | ----------------------------------------- |
| Broad access | Leave knowledge tags empty |
| Domain-specific | Use tags like "billing", "technical" |
| Product-specific | Tag articles by product, filter per agent |
## Guidelines
Assign guideline sections that shape how the agent communicates.
### Section Assignment
* Check sections to include
* Sections are combined when multiple are selected
* Order doesn't matter — all selected guidelines apply
### Common Sections
* **Tone & Voice** — How the agent should sound
* **Formatting** — Response structure and length
* **Brand** — Terminology and phrases
* **Domain** — Product-specific instructions
[Learn more about Guidelines →](/guidelines/overview)
## Guardrails
Define safety constraints that protect customers and your brand.
### Escalation Rules
Select rules that trigger handoff to humans:
* Each rule defines a condition (e.g., "customer is angry")
* When triggered, agent escalates instead of responding
* Multiple rules can be active simultaneously
### Restrictions
Select hard limits on agent behavior:
* Highest priority — checked before processing
* Define what the agent cannot do or say
* Provide alternative responses when triggered
[Learn more about Guardrails →](/guardrails/overview)
## Classification
Configure how the agent tags conversations for analytics.
### Categories
Select categories the agent should assign:
* Agent picks one category per conversation
* Categories appear in breakdown analytics
* Leave unselected to disable category assignment
### Attributes
Select attributes to extract:
* Agent identifies values for each attribute
* Can be single or multi-select
* Attributes appear in analytics and can be used for filtering
[Learn more about Classification →](/tagging/overview)
## Tools
Configure which tools an autonomous agent can use.
Workflow and runbook agents get tool behavior from the selected workflow or runbook. Per-agent tool access applies to autonomous and Duckie Assistant agents.
### Duckie Tools
Built-in capabilities:
* **Responder** — Generate and send responses
* **Knowledge Search** — Search the knowledge base
* **Escalator** — Hand off to humans
* **Ask and Wait** — Ask clarifying questions
### App Tools
Tools from connected integrations:
* Automatically available when integrations are connected
* Enable/disable specific tools per agent
* Examples: Update Zendesk ticket, Create Jira issue
### Custom Tools
Your own HTTP-based tools:
* Created in **Build → Tools**
* Enable per agent as needed
### MCP Tools
Tools discovered from MCP servers:
* Added in **Build → Tools → MCP Servers**
* Grouped by server in the tool access dialog
* Enable per agent as needed
New Duckie Assistant agents start with Responder and Duckie Assistant MCP tools selected when those tools are available. You can still edit the selected tools after creation.
[Learn more about Tools →](/tools/overview)
## Advanced Settings
### Runbooks & Workflows
For autonomous agents, control which runbooks and workflows the agent can use:
* **Only allow these runbooks** — Limit the runbooks the agent can read
* **Block these runbooks** — Hide specific runbooks from the agent
* **Only allow these workflows** — Limit the workflows the agent can call
* **Block these workflows** — Hide specific workflows from the agent
Duckie Assistant agents do not use agent runbook or workflow configuration.
### Callable Agents
For autonomous agents, use **Callable agents** to control which other agents this agent can invoke as sub-agents.
| Setting | Behavior |
| --------------- | ----------------------------------------------------------------- |
| None | Agent cannot call other agents |
| All | Agent can call any active agent in the organization except itself |
| Specific agents | Agent can only call the selected agents |
[Learn more about sub-agents ->](/agents/sub-agents)
Duckie Assistant agents do not use callable-agent configuration.
### Tables
For autonomous agents, use **Tables** to attach [Agent Tables](/concepts/agent-tables) the agent can query and update during a run.
Tables are useful when the agent needs structured working memory, such as a per-ticket checklist, run-local scratchpad, shared workspace queue, or agent-specific working set.
| Setting | Behavior |
| ------------------ | ------------------------------------------------------------------------------------- |
| No tables attached | The agent only sees tables that are available through the table's broader row scope |
| Specific tables | The agent can use those table definitions when row scope and runtime context allow it |
Table definitions are managed in **Build -> Tables**. The agent editor only attaches existing tables; it does not edit table schemas inline.
Duckie Assistant agents do not use runtime Agent Tables as support configuration, but authorized Duckie Assistant MCP tools can create or update table definitions when you ask the assistant to configure them.
### Conversation Context
Agents use conversation history and run context when processing customer messages.
Autonomous agents can continue work across turns on the same ticket by using prior conversation context and saved run memory.
### Deployment Behavior
Deployment settings control whether the agent runs in testing mode or responds live to customers.
## Next Steps
Configure agents that choose resources and tools at run time
Build deterministic agent flows
Write flexible procedures for agents
Configure actions agents can take
Configure agent-to-agent delegation
Validate in the playground
# Creating Agents
Source: https://docs.duckie.ai/agents/creating-agents
Step-by-step guide to creating your first agent
This guide walks you through creating and configuring a new Duckie agent from scratch.
## Before You Start
For the best experience, have these ready before creating your agent:
| Preparation | Why |
| --------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| [Knowledge sources](/knowledge/connecting-sources) connected | So your agent has information to work with |
| [Guidelines](/guidelines/overview) created | So your agent knows how to communicate |
| [Runbooks](/runbooks/overview), [workflows](/workflows/overview), or agent instructions | So your agent knows what to do |
| [Tools](/tools/overview) configured | So autonomous and Duckie Assistant agents can take the right actions |
You can create an agent without these and add them later. Duckie Assistant agents can start with instructions and tools only; support agents usually need knowledge, guidelines, and procedures to be useful.
## Creating a New Agent
Go to **Build → Agents** in your Duckie dashboard.
Click the **Create Agent** button to open the creation drawer.
Fill in the basics:
* **Name** — A descriptive name (e.g., "Support Agent", "Billing Bot", "Technical Help")
* **Description** — What this agent does (optional but helpful for your team)
Choose how the agent should operate:
* **Autonomous** — Write instructions and let the agent decide which resources and tools to use
* **Duckie Assistant** — Create a Duckie copilot for managing Duckie objects with tools
* **Workflow** — Select a workflow for deterministic, step-by-step execution
* **Runbook** — Select a runbook for one flexible procedure
For autonomous agents, add instructions, choose model settings, and configure access to tools, runbooks, and workflows.
For Duckie Assistant agents, add instructions, choose model settings, and configure tools. New Duckie Assistant agents start with Duckie Assistant MCP tools and Responder selected when those tools are available.
For workflow or runbook agents, select the workflow or runbook the agent should start with.
Click **Create** to save your new agent. The agent detail view will open.
## Configuring Your Agent
After creating, configure these sections in the agent detail view:
### Instructions
Autonomous agents include an **Instructions** editor. Use it to define the agent's job, boundaries, escalation expectations, and how it should choose between available resources.
[Learn more about Autonomous Agents →](/agents/autonomous-agents)
### Duckie Assistant
Duckie Assistant agents also include an **Instructions** editor and model settings, but they are designed for working with Duckie configuration instead of handling support conversations.
Duckie Assistant agents hide support-resource configuration, including runbooks, workflows, guidelines, guardrails, classification, resolution tracking, and callable agents. Use the **Tools** section to control which Duckie tools, app tools, custom tools, and MCP tools the agent can call.
[Learn more about Duckie Assistant Agents ->](/agents/duckie-assistant-agents)
### Knowledge
Select which knowledge the agent can access:
1. Go to the **Knowledge** tab
2. Leave **Knowledge Tags** empty to allow all knowledge, OR
3. Select knowledge tags to filter available content
**Start broad, then narrow.** It's often easier to leave tags empty first, then restrict based on testing results.
### Guidelines
Assign communication guidelines:
1. Go to the **Guidelines** tab
2. Select which guideline sections apply to this agent
3. Guidelines are additive — select multiple sections to combine them
### Guardrails
Set up safety constraints:
1. Go to the **Guardrails** tab
2. Select **Escalation Rules** that should trigger handoff to humans
3. Select **Restrictions** that define hard limits on agent behavior
### Classification
Configure how conversations are tagged:
1. Go to the **Classification** tab
2. Select which **Categories** the agent should assign
3. Select which **Attributes** to extract
### Tools
For autonomous agents, use the **Tools** section to control which Duckie tools, app tools, custom tools, and MCP tools the agent can call.
## Testing Your Agent
Before deploying, always test in the playground:
Go to **Test → Playground**.
Choose your newly created agent from the dropdown.
Try various scenarios:
* Common questions your customers ask
* Edge cases and unusual requests
* Messages that should trigger escalation
Check responses and execution steps. Adjust configuration as needed.
## Best Practices
### Naming
* Use clear, descriptive names: "Billing Support Agent" not "Agent 1"
* Include the purpose or team in the name
* Add descriptions explaining what the agent handles
### Configuration
* **Start simple** — Begin with basic configuration and add complexity as needed
* **Test thoroughly** — Use the playground before every deployment
* **Iterate** — Refine based on real results, not assumptions
* **Limit powerful tools** — Give autonomous agents only the write actions they need
### Deployment
* **Testing first** — Start new agents in testing mode before live traffic
* **Review responses** — Check test runs before going live
* **Monitor closely** — Watch performance metrics after going live
## Common Patterns
### General Support Agent
* Autonomous mode for broad triage and research
* Broad knowledge access (all sources)
* Friendly, helpful guidelines
* Escalation rules for angry customers and complex issues
* Categories: Billing, Technical, Account, General
### Specialized Agent
* Autonomous mode with allowlisted runbooks, workflows, and tools
* Narrow knowledge access (tagged sources only)
* Domain-specific guidelines
* Strict guardrails for the domain
* Specific categories and attributes
### Triage Agent
* Autonomous mode or a deterministic workflow, depending on how fixed the triage process is
* Minimal knowledge (just enough to categorize)
* Short, clarifying responses
* Quick escalation to specialized agents or humans
* Focus on classification over resolution
## Next Steps
Deep dive into all settings
Configure flexible agents for open-ended conversations
Validate before deploying
Connect to a customer channel
# Duckie Assistant Agents
Source: https://docs.duckie.ai/agents/duckie-assistant-agents
Configure Duckie copilot agents that work with Duckie objects
Duckie Assistant agents help your team inspect, understand, and update Duckie configuration from inside Duckie.
They use the same run, run-step, run-message, tool, and responder infrastructure as autonomous agents, but they are prompted as Duckie copilots instead of customer-support agents. Use them when the agent's job is to work with Duckie objects such as agents, runbooks, workflows, guidelines, guardrails, tools, deployments, categories, attributes, and organization overview.
## When to Use Duckie Assistant Agents
Use a Duckie Assistant agent when you want an AI assistant to help manage Duckie itself.
| Use Duckie Assistant when | Use Autonomous when |
| -------------------------------------------------------- | ----------------------------------------------------------------------------- |
| The agent should inspect or update Duckie configuration | The agent should handle open-ended customer conversations |
| Instructions should be the main behavior source | Runbooks, workflows, guidelines, and guardrails should guide support behavior |
| The agent should work through Duckie Assistant MCP tools | The agent should combine support resources, knowledge, and tools |
| You want a lighter configuration surface | You need full support-agent configuration |
## How Duckie Assistant Agents Work
When a Duckie Assistant agent runs, Duckie gives it the conversation, your agent instructions, organization overview, and enabled tools.
The agent can:
* Inspect Duckie runs and core objects through MCP tools
* Create, update, and delete writable core objects when its tools and API key scopes allow it
* Call enabled Duckie tools, app tools, custom tools, and MCP tools
* Use responder behavior the same way autonomous agents do
* Keep run history, run steps, and run messages for review
Duckie Assistant agents do not load or register support-resource tools for runbooks, guidelines, guardrails, workflows, or callable agents.
## Create a Duckie Assistant Agent
Go to **Build -> Tools -> MCP Servers** and connect **Duckie Assistant MCP** if it is not connected yet.
Go to **Build -> Agents** and click **Create Agent**.
Choose **Duckie Assistant** in the mode selector.
Add a clear name, choose a status, and optionally adjust the model settings.
Describe what the assistant should manage, when it should ask before changing objects, and which types of changes are allowed.
New Duckie Assistant agents start with Responder and Duckie Assistant MCP tools selected when those tools are available. Open **Tools** to adjust the selected tools.
Save the agent, then test it in the [playground](/testing/playground).
## Configuration Reference
### Instructions
Instructions are the primary behavior definition for a Duckie Assistant agent.
Use them to define:
* Which Duckie objects the agent should manage
* Which updates it may make without asking first
* Which changes require confirmation
* How it should summarize changes
* Any naming, formatting, or review expectations for object edits
Example:
```text theme={null}
You help maintain our Duckie workspace. Keep changes small and reversible.
Before updating an agent, summarize the current configuration and the proposed change. Do not delete objects unless the user explicitly asks. When you update an object, explain what changed and link to the updated object if a URL is available.
```
### Model
Duckie Assistant agents have model settings in the agent editor. Use the default model for most assistants, and increase reasoning effort only when the assistant needs deeper planning or comparison across objects.
### Tools
Duckie Assistant agents can use enabled tools from the **Tools** section.
Tool access can include:
* [Duckie Tools](/tools/duckie-tools)
* [App Tools](/tools/app-tools)
* [Custom Tools](/tools/custom-tools)
* [MCP tools](/tools/mcp-servers)
New Duckie Assistant agents default to Responder and Duckie Assistant MCP tools. You can edit the selected tools after creation. If all available tools are selected, Duckie stores that as all tools enabled.
### Duckie Assistant MCP
Duckie Assistant MCP is the first-party MCP server that exposes Duckie runs and core objects as tools.
Use API key scopes to control what the MCP tools can do:
| Scope | Allows |
| ---------------- | ------------------------------------------------------------ |
| `api:runs:read` | List and retrieve runs through MCP |
| `api:core:read` | Describe, list, and retrieve core objects through MCP |
| `api:core:write` | Create, update, and delete writable core objects through MCP |
[Learn more about the MCP endpoint ->](/api/mcp)
## Hidden Support Configuration
Duckie Assistant agents intentionally hide support-agent configuration that would make the agent treat Duckie objects as its own support resources.
Hidden sections include:
* Runbooks
* Workflows
* Guidelines
* Guardrails
* Resolution tracking and resolution rules
* Attributes and categories
* Knowledge tag filters
* Callable agents
Put core behavior in the agent instructions and control operational access through selected tools and API key scopes.
## Changelog Attribution
When a Duckie Assistant agent updates a core object through Duckie Assistant MCP, Duckie attributes the changelog entry to the assistant. The changelog shows the agent name as the actor display name.
## Best Practices
* Keep the assistant's authority explicit in instructions.
* Grant `api:core:write` only when the assistant should make object changes.
* Keep destructive changes, such as deletes, behind explicit user requests.
* Ask the assistant to summarize changes after edits.
* Test object updates in the playground before relying on the assistant for repeated workspace maintenance.
## Next Steps
Connect Duckie Assistant MCP
Review MCP tools and scopes
Deep dive into agent settings
Test the agent before use
# Agents Overview
Source: https://docs.duckie.ai/agents/overview
Learn about Duckie agents and what they can do
Agents are the AI assistants at the heart of Duckie. Each agent is a configured AI that handles customer conversations or Duckie configuration tasks according to your instructions, resources, and deployment settings.
## What is an Agent?
An agent is a complete AI assistant configured with:
* **Start mode** — Autonomous, Duckie Assistant, workflow, or runbook behavior
* **Instructions** — The agent's role, scope, and decision rules
* **Knowledge** — Sources it can search for information
* **Guidelines** — Rules for communication style and tone
* **Guardrails** — Safety constraints and escalation rules
* **Tools** — Actions it can perform (respond, search, escalate, call APIs)
Think of each agent as a specialized team member trained for a specific job.
## Agent Capabilities
Agents can:
| Capability | Description |
| --------------------------------- | ------------------------------------------------------------------- |
| **Respond to customers** | Generate and send replies across Zendesk, Slack, Intercom, and more |
| **Search knowledge** | Find relevant information from your connected documentation |
| **Follow procedures** | Execute runbooks or workflows you define |
| **Delegate to sub-agents** | Call specialized agents for focused parts of a conversation |
| **Take actions** | Create tickets, update records, send messages, call APIs |
| **Escalate** | Hand off to humans when guardrails trigger |
| **Classify** | Tag conversations with categories and attributes |
| **Use structured working memory** | Query and update attached Agent Tables during autonomous runs |
## Start Modes
Every agent has a start mode:
| Mode | Best for | How it works |
| -------------------- | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Autonomous** | Open-ended support where the agent needs to choose what to research or do | Starts from agent instructions and decides which runbooks, workflows, knowledge, and tools to use |
| **Duckie Assistant** | Managing Duckie configuration through a copilot-style agent | Uses the autonomous runtime, but focuses on instructions and tools instead of support resources like runbooks, guidelines, guardrails, and classification |
| **Workflow** | Deterministic processes | Starts at a selected workflow and follows its nodes and branches |
| **Runbook** | One flexible procedure | Starts from a selected runbook and follows its instructions |
Learn how to configure agents that decide which resources and tools to use at run time.
Learn how to configure Duckie copilots that work with Duckie objects.
Learn how autonomous agents and workflows can delegate work to other agents.
## Agent Configuration
### Knowledge Sources
Control what information the agent can access:
* Leave knowledge tags empty to allow all connected and custom knowledge
* Use knowledge tags to narrow what's searchable
* Mix connected sources with custom articles
### Guidelines
Shape how the agent communicates:
* Tone and voice (friendly, professional, casual)
* Response format and length
* Brand terminology and phrases
* Domain-specific instructions
### Guardrails
Define safety boundaries:
* **Escalation rules** — When to hand off to humans
* **Restrictions** — What the agent cannot do or say
### Classification
Configure how conversations are tagged:
* Categories (Billing, Technical Support, etc.)
* Custom attributes (Priority, Product Area, etc.)
## Multiple Agents
You can create multiple agents for different purposes:
| Strategy | Example |
| --------------- | --------------------------------------------------- |
| **By team** | Billing Agent, Technical Support Agent, Sales Agent |
| **By channel** | Slack Agent (casual), Zendesk Agent (formal) |
| **By customer** | Enterprise Agent (high-touch), Self-serve Agent |
| **By product** | Product A Agent, Product B Agent |
Each agent can have completely different knowledge, guidelines, and behavior.
## Agent vs Runbook vs Workflow
| Concept | What It Is | Example |
| ------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| **Agent** | The complete AI assistant with instructions, resources, tools, and deployment settings | "Support Agent" |
| **Autonomous mode** | A start mode where the agent decides which resources and tools to use | "Research the issue, read relevant runbooks, call tools as needed, then respond" |
| **Duckie Assistant mode** | A copilot start mode for working with Duckie objects | "Update agent instructions, review workflows, and edit guidelines through MCP tools" |
| **Runbook** | Flexible instructions the agent follows | "When a customer asks about refunds, verify their order, check eligibility, process or explain policy" |
| **Workflow** | Visual process with explicit steps and branches | Start → Check Order → Decision: Eligible? → Yes: Process Refund / No: Explain Policy |
An agent can start autonomously, as Duckie Assistant, from a workflow, or from a runbook. It then combines that start mode with the configuration that applies to that mode.
## Next Steps
Step-by-step guide to your first agent
Deep dive into all settings
Configure flexible agents for open-ended conversations
Configure Duckie copilots for working with Duckie objects
Delegate work to specialized agents
Learn about visual workflows
Learn about flexible, AI-driven runbooks
# Sub-Agents
Source: https://docs.duckie.ai/agents/sub-agents
Delegate work from an autonomous agent or workflow to another agent
Sub-agents let one Duckie run invoke another active agent as a child run.
Use a sub-agent when a specialized agent should handle part of a conversation while the parent agent or workflow keeps ownership of the overall process. The child agent follows its own start mode and configured access.
## When to Use Sub-Agents
Sub-agents are useful when:
| Use case | Example |
| --------------------- | ----------------------------------------------------------------------------- |
| Specialized expertise | A general support agent delegates billing questions to a Billing Agent |
| Reusable workflows | Several parent workflows call the same Refund Specialist Agent |
| Safer tool access | Only a dedicated agent can use sensitive account or billing tools |
| Clear handoffs | A triage agent gathers context, then delegates a narrow task to another agent |
## How Agents Can Invoke Sub-Agents
Duckie supports sub-agent calls from autonomous agents and workflows.
### From an Autonomous Agent
An autonomous agent can call other agents as tools when those agents are enabled in **Callable agents**.
To configure this:
1. Open **Build > Agents**.
2. Open the autonomous agent that will call other agents.
3. In **Callable agents**, choose **None**, **All**, or specific agents.
4. Save the agent.
When the autonomous agent runs, each callable active agent is described to it by name and description. The calling agent decides when to delegate, sends a task, and chooses whether to include the current conversation history.
Agent descriptions matter for delegation. The calling agent uses the target agent's name and description to decide which sub-agent is appropriate.
### From a Workflow
Workflows can invoke an agent from a Tool node by selecting an agent in the **Agents** tab.
To add an Agent action:
1. Open a workflow in the builder.
2. Add a **Tool** node.
3. Open the tool selector and choose **Agents**.
4. Select an active agent.
5. Configure the Agent action inputs.
The selected agent can start autonomously, as Duckie Assistant, from a workflow, or from a runbook. Duckie routes the child run based on that agent's start mode.
## Child Agent Inputs
Every child agent run must receive at least one of:
* **Instructions** - the task or instruction for the child agent
* **Conversation history** - the parent run's customer-visible messages
Workflows can also pass **Additional context**.
| Input combination | What the child receives |
| ------------------------------------- | ------------------------------------------------------------------------------------- |
| Instructions only | The delegated instructions become the child run's message |
| Conversation history and instructions | The parent conversation is copied first, then the delegated instructions are appended |
| Conversation history only | The copied parent conversation becomes the child run input |
Autonomous agent calls always include a task and a required conversation-history choice. Workflow Agent actions can use any valid combination.
### Conversation History
Use conversation history when the child agent needs prior customer messages to complete the task. Workflow Agent actions include conversation history by default.
Turn conversation history off when the delegated instructions contain all required context and the child agent should not reason over the full parent conversation.
### Additional Context
Additional context is available on workflow Agent actions. It is a list, so you can pass more than one context item.
Use additional context for structured handoff details such as:
* An order lookup result
* A policy excerpt
* A customer segment or plan
* A value generated by an earlier workflow node
Duckie adds additional context to the child run metadata under `additional_context`. Child runs also inherit the parent run metadata.
Do not pass secrets, credentials, API keys, tokens, or similar values as additional context.
## What the Parent Receives
The parent receives a compact result from the child run. The child run's full transcript and steps stay available on the child run.
| Caller | Parent-facing output |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| Autonomous agent | A tool result with `success`, `child_run_id`, `status`, and `compact_result` |
| Workflow Agent action | A node output with `status`, `resolutionSummary`, `resolutionType`, `subRunId`, `agentId`, `startWithType`, and `waitingForInput` when relevant |
For autonomous child agents, the child returns its internal result with **Send result to calling agent**. That result becomes the parent-facing summary. This is separate from responder tools.
## Customer-Visible Responses
Responder tools still send customer-visible messages. If a child agent uses a responder, Duckie also copies the child-authored response into the parent run messages so the parent run transcript stays complete.
Use **Send result to calling agent** for internal parent-facing output. Use a responder only when the child agent should send a customer-visible response.
## Best Practices
* Give each sub-agent a clear job boundary.
* Keep agent names and descriptions specific enough for another agent to choose correctly.
* Pass focused instructions, even when including conversation history.
* Include conversation history only when the child needs it.
* Use additional context as a short list of relevant facts, not as a dump of every previous node output.
* Test parent and child behavior together in the [playground](/testing/playground).
## Next Steps
Configure agents that can delegate work at run time
Add Agent actions to deterministic workflows
Review agent settings and access control
Test sub-agent handoffs before deployment
Let a customer-owned orchestration agent call Duckie as a focused subagent.
# Alerts
Source: https://docs.duckie.ai/analytics/alerts
Configure guardrail, tool failure, and agent-triggered alerts
Alerts help your team notice important agent events and follow up quickly.
Use **Analyze -> Alerts** to manage alert definitions and review triggered alerts.
## Alert Types
| Alert type | What triggers it | Use it for |
| ------------------- | ----------------------------------------------------- | ---------------------------------------------------------------------- |
| Guardrail Violation | A selected guardrail is violated | Safety, policy, compliance, or escalation events |
| Tool Failure | A selected tool fails during a run | Broken integrations, failed writes, or important workflow dependencies |
| Agent Triggered | An agent calls Create Alert with the alert name or ID | Situations that require judgment, review, or team visibility |
## Create An Alert Definition
Go to **Analyze -> Alerts**.
Click **Create Alert**.
Select **Guardrail Violation**, **Tool Failure**, or **Agent Triggered**.
For a guardrail alert, choose the guardrail. For a tool failure alert, choose the tool. For an Agent Triggered alert, enter the alert name and description.
Choose **Critical**, **Warning**, or **Info**. Add email recipients or Slack channels when the alert should notify a team.
Save the alert definition. Enabled definitions can trigger new alerts.
## Agent Triggered Alerts
Agent Triggered alerts let an agent raise a configured alert during a run.
Use them when the agent can detect that something needs human visibility, but the condition is not tied to one guardrail or one tool failure. Examples include:
* a billing exception that needs review
* a customer request that matches a high-priority escalation pattern
* a failed multi-step process where the right next step is human triage
* a case that should appear in an operations queue
For each Agent Triggered alert:
* Use a clear, unique name. Agents can trigger the alert by name or ID.
* Write a description that explains when the agent should use it.
* Choose severity based on the operational urgency.
* Configure email recipients or Slack channels when someone should be notified.
Then enable the **List Alerts** and **Create Alert** Duckie tools for the agent or flow that should trigger it. Create Alert is a write action because it creates a visible alert record and can notify configured recipients.
Example agent instruction:
```text theme={null}
If the customer reports a billing exception that cannot be resolved with the available tools,
call List Alerts and then Create Alert for Billing Review Needed.
Include a concise message body with the customer issue, attempted checks, and recommended next step.
```
## Triggered Alert History
Triggered alerts appear in the alert history with severity, status, type, source details, related run or ticket context when available, and timestamps.
Alert statuses are:
| Status | Meaning |
| ------------ | ---------------------------------------- |
| Unread | The alert has not been handled yet |
| Acknowledged | Someone has seen it and is investigating |
| Resolved | The issue was handled |
| Dismissed | The alert no longer requires action |
Use alert history with **Analyze -> Runs** when you need to inspect the run, tool calls, and context that produced the alert.
## Manage Alert Definitions
From the configured alerts list, you can edit, enable, disable, or delete alert definitions.
Disabling an alert definition stops new alerts from being created from that definition. Existing triggered alerts remain in alert history.
## Related Docs
Learn how List Alerts and Create Alert work.
Configure escalation rules and restrictions.
Inspect the run behind an alert.
Control which tools each agent can use.
# Breakdown Analysis
Source: https://docs.duckie.ai/analytics/breakdown
Visualize ticket distribution
Breakdown analysis visualizes how conversations are distributed across categories and attributes — essential for understanding what customers are asking about.
## Category Breakdown
See distribution by conversation type:
**Example:**
* Billing: 35%
* Technical Support: 40%
* Account Issues: 15%
* Feature Requests: 5%
* General: 5%
### What It Tells You
* Which topics dominate support volume
* Where to focus knowledge improvements
* Staffing and resource allocation needs
## Attribute Breakdown
See distribution per attribute:
**Priority:**
* High: 20%
* Medium: 45%
* Low: 35%
**Product Area:**
* Dashboard: 50%
* API: 30%
* Mobile: 20%
## Viewing Breakdown
Go to **Analyze → Breakdown**.
Choose Category view or Attribute view.
Choose the time period to analyze.
See distribution visualizations.
## Drill-Down
Click any segment to see matching conversations:
1. Click a pie slice or bar
2. See list of conversations in that segment
3. Click individual runs for details
This helps you:
* Understand what's in each category
* Identify patterns within segments
* Find examples for training
## Comparing Periods
Compare distribution across time:
| Category | This Week | Last Week | Change |
| --------- | --------- | --------- | ------ |
| Billing | 35% | 30% | +5% |
| Technical | 40% | 45% | -5% |
| Account | 15% | 15% | — |
**What changes tell you:**
* Emerging issues (category growing)
* Resolved issues (category shrinking)
* Seasonal patterns
## Cross-Analysis
Combine category and attribute analysis:
**High Priority by Category:**
* Technical: 45%
* Billing: 35%
* Account: 15%
This reveals:
* Which categories have urgent issues
* Where to prioritize improvements
* Resource allocation needs
## Metrics by Segment
See performance metrics per segment:
| Category | Volume | Resolution Rate | Escalation Rate |
| --------- | ------ | --------------- | --------------- |
| Billing | 350 | 82% | 8% |
| Technical | 400 | 68% | 15% |
| Account | 150 | 91% | 3% |
**Takeaways:**
* Technical has lower resolution — needs more knowledge
* Account resolves well — keep doing what works
* Billing escalation is moderate — check guardrails
## What Breakdown Shows
### High-Volume Categories
If a category dominates:
* Ensure knowledge coverage is excellent
* Consider specialized agents
* Review common questions
### Growing Categories
If a category is increasing:
* Investigate root cause
* Add knowledge proactively
* Consider product changes
### Low Resolution Categories
If a category resolves poorly:
* Review knowledge for gaps
* Check agent configuration
* Analyze escalation reasons
## Exporting Data
Export breakdown data for further analysis:
* **CSV:** Raw data for spreadsheets
* **Chart image:** For presentations
## Next Steps
See aggregate KPIs
Investigate individual runs
# Analytics Overview
Source: https://docs.duckie.ai/analytics/overview
Understand and improve agent performance
Analytics help you understand how your agents are performing and identify opportunities for improvement.
## Available Analytics
### Performance Metrics
Key performance indicators for your agents:
* **Deflection Rate** — Conversations handled without human help
* **Resolution Rate** — Conversations successfully resolved
* **Escalation Rate** — Conversations handed to humans
* **Response Time** — How fast agents respond
* **Time to Resolution** — Total time to resolve issues
Track your KPIs
### Breakdown Analysis
Visualize distribution by category and attributes:
* Pie charts and bar charts
* Drill-down into segments
* Compare over time
Analyze distribution
### Run History
Complete execution logs:
* Every agent run
* Step-by-step details
* Searchable and filterable
View execution logs
### Alerts
Notifications for important agent events:
* Guardrail violations
* Tool failures
* Agent-triggered review or escalation events
* Email and Slack notification targets
Configure event alerts
## Using Analytics
### Daily Monitoring
Quick health check:
1. Check performance dashboard
2. Review escalation trends
3. Spot any anomalies
4. Address urgent issues
### Weekly Review
Deeper analysis:
1. Analyze breakdown by category
2. Review individual runs behind important metric changes
3. Fill knowledge gaps
4. Plan improvements
### Monthly Analysis
Strategic review:
1. Compare metrics month-over-month
2. Identify trends
3. Evaluate ROI
4. Adjust strategy
## Key Metrics at a Glance
| Metric | What It Tells You |
| ------------------- | --------------------------------------- |
| **Deflection Rate** | How much AI is handling without humans |
| **Resolution Rate** | How well issues are being resolved |
| **Escalation Rate** | When humans need to step in |
| **Response Time** | How fast customers get answers |
| **CSAT** | Customer satisfaction with AI responses |
## Analytics Navigation
Access analytics from the **Analyze** section:
```
Analyze
├── Performance — Metrics and trends
├── Breakdown — Category/attribute distribution
├── Runs — Execution history
└── Alerts — Event notifications and alert history
```
## Next Steps
Start with KPIs
View individual runs
Analyze distribution
Stay informed
# Performance Metrics
Source: https://docs.duckie.ai/analytics/performance-metrics
Track agent volume, resolution, deflection, escalation, and timing
Performance metrics show how your agents are handling conversations over time. Use this page to monitor volume, outcome rates, and timing distributions, then investigate specific changes in Run History or Breakdown.
## Before you use Performance
Performance metrics depend on each run's outcome. Configure resolution rules before using the page to judge agent quality.
Define when Duckie should treat conversations as resolved, deflected, escalated, or unresolved.
## Open Performance
Open **Analyze → Performance**.
Select **Last 24 hours**, **Last 7 days**, **Last 14 days**, **Last 30 days**, **Last 90 days**, or a custom range.
Select **All Deployments** or a specific deployment.
Use the cards, trend charts, and time distributions to understand agent performance.
## Metric cards
The top cards summarize volume and outcomes for the selected date range and deployment.
| Metric | What it shows |
| ------------------- | ----------------------------------------- |
| **Total Tickets** | Runs included in the selected range |
| **Total Messages** | Messages across those runs |
| **Deflections** | Runs marked with the `deflected` outcome |
| **Resolutions** | Runs marked with the `resolved` outcome |
| **Deflection Rate** | `deflected` runs divided by total tickets |
| **Resolution Rate** | `resolved` runs divided by total tickets |
Each card includes a percentage change compared with the previous period of the same length.
## Charts
### Volume Over Time
Shows daily counts for:
* Deflections
* Resolutions
* Escalations
* Total Tickets
Use this chart to spot changes in traffic or outcome mix.
### Quality Rates Over Time
Shows daily deflection and resolution rates.
Use this chart to see whether agent outcomes are improving or declining across the selected period.
### Escalation Rate Over Time
Shows the daily percentage of runs marked as `escalated`.
Escalation is not always bad. Some conversations should go to a human. Use this chart to find unexpected spikes or sustained changes.
## Time distributions
Performance includes two timing histograms:
| Chart | What it shows |
| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **Response Time Distribution** | Run durations grouped into fixed buckets: `< 10s`, `10-30s`, `30s-1m`, `1-2m`, `2-5m`, and `> 5m` |
| **Time to Resolution Distribution** | Durations for resolved or deflected runs grouped into fixed buckets: `< 5m`, `5-15m`, `15-30m`, `30m-1h`, `1-2h`, and `> 2h` |
These charts show distribution by bucket, not percentile metrics.
## How to investigate changes
When a metric moves unexpectedly:
1. Check whether the date range or deployment filter changed.
2. Open **Run History** to inspect individual runs, tool calls, and outcomes.
3. Use **Breakdown** to compare performance by category or attribute.
4. Review resolution rules if resolved, deflected, or escalated counts look wrong.
5. Update knowledge, guidelines, runbooks, tools, or agent configuration when the run details show a configuration gap.
## Next Steps
Analyze performance by category and attribute
Investigate individual runs
# Run History
Source: https://docs.duckie.ai/analytics/runs
Complete execution history
Run history provides a complete log of every agent execution — essential for debugging, auditing, and understanding agent behavior.
## What is a Run?
A **run** is a single execution of an agent in response to a customer message. Each run captures:
* The triggering message and conversation
* All steps the agent took
* Knowledge searched and retrieved
* Tools called and their results
* Response generated
* Classification applied
## Viewing Run History
Go to **Analyze → Runs**.
View the list or use filters to find specific runs.
Click any run to see full execution details.
## Run List View
The list shows:
| Column | Description |
| ------------ | -------------------------- |
| **Time** | When the run occurred |
| **Status** | Success, escalated, error |
| **Source** | Channel/deployment |
| **Category** | Assigned category |
| **Preview** | First line of conversation |
## Filtering Runs
### By Date Range
* Last 24 hours
* Last 7 days
* Last 30 days
* Custom range
### By Status
* **Success** — Completed normally
* **Escalated** — Handed to human
* **Error** — Something went wrong
### By Category
Filter by assigned category.
### By Deployment
Filter by specific agent deployment.
### By Search
Search conversations by keyword.
## Run Details
Click any run to see complete details:
### Conversation
Full message thread between customer and agent:
### Execution Steps
Step-by-step breakdown of what happened:
1. **Message received** — Initial trigger
2. **Guardrails checked** — Safety evaluation
3. **Knowledge searched** — What was found
4. **Runbook executed** — Steps followed
5. **Response generated** — Final output
6. **Classification applied** — Category and attributes
### Knowledge Retrieved
See what knowledge was used:
* Articles retrieved
* Relevance scores
* Content highlighted
### Tool Calls
See what actions were taken:
| Field | Description |
| ------------ | --------------------- |
| **Tool** | Which tool was called |
| **Inputs** | Parameters passed |
| **Output** | Result returned |
| **Duration** | How long it took |
| **Status** | Success or failure |
### Classification
See how the conversation was tagged:
* **Category:** Billing, Technical, etc.
* **Attributes:** Priority, Product Area, etc.
* **Resolution:** Resolved or not
## Use Cases
### Debugging Issues
When something goes wrong:
1. Find the problematic run
2. Review execution steps
3. Identify where it failed
4. Fix the underlying issue
### Auditing Responses
Review what the agent said:
1. Filter by date range
2. Sample runs
3. Check response quality
4. Identify improvement areas
### Understanding Escalations
Why did the agent escalate?
1. Filter by status = Escalated
2. Review the conversation
3. Check which guardrail triggered
4. Decide if escalation was appropriate
### Training Improvement
Learn from real conversations:
1. Review successful runs
2. Identify patterns
3. Create knowledge from good examples
4. Update guidelines based on findings
## Volume Chart
See run volume over time:
* Identify busy periods
* Spot anomalies
* Correlate with events
## Exporting Runs
Export run data for analysis:
* CSV export
* Include conversation, metadata, classification
* Filter before export
## Next Steps
See aggregate metrics
Get notified of issues
# List agents
Source: https://docs.duckie.ai/api-reference/agents/list-agents
api-reference/openapi.json GET /api/v1/agents
# Retrieve an agent
Source: https://docs.duckie.ai/api-reference/agents/retrieve-an-agent
api-reference/openapi.json GET /api/v1/agents/{agent_id}
# List guardrails
Source: https://docs.duckie.ai/api-reference/guardrails/list-guardrails
api-reference/openapi.json GET /api/v1/guardrails
# Retrieve a guardrail
Source: https://docs.duckie.ai/api-reference/guardrails/retrieve-a-guardrail
api-reference/openapi.json GET /api/v1/guardrails/{guardrail_id}
# List guidelines
Source: https://docs.duckie.ai/api-reference/guidelines/list-guidelines
api-reference/openapi.json GET /api/v1/guidelines
Returns published guidelines.
# Retrieve a guideline
Source: https://docs.duckie.ai/api-reference/guidelines/retrieve-a-guideline
api-reference/openapi.json GET /api/v1/guidelines/{guideline_id}
# List runbooks
Source: https://docs.duckie.ai/api-reference/runbooks/list-runbooks
api-reference/openapi.json GET /api/v1/runbooks
Returns published, non-deleted runbooks.
# Retrieve a runbook
Source: https://docs.duckie.ai/api-reference/runbooks/retrieve-a-runbook
api-reference/openapi.json GET /api/v1/runbooks/{runbook_id}
# List run tool filter options
Source: https://docs.duckie.ai/api-reference/runs/list-run-tool-filter-options
api-reference/openapi.json GET /api/v1/runs/tool-options
Returns historical tool-call names that can be used with the `tool_name` run filter.
# List runs
Source: https://docs.duckie.ai/api-reference/runs/list-runs
api-reference/openapi.json GET /api/v1/runs
Returns a cursor-paginated list of run summaries. The list response does not include conversation messages or execution steps.
# Retrieve a run
Source: https://docs.duckie.ai/api-reference/runs/retrieve-a-run
api-reference/openapi.json GET /api/v1/runs/{run_id}
Returns one run with conversation messages, execution steps, evaluation attributes, and redacted tool payloads.
# List tools
Source: https://docs.duckie.ai/api-reference/tools/list-tools
api-reference/openapi.json GET /api/v1/tools
Returns the organization's tool catalog, including Duckie tools, app tools, custom tools, and MCP tools.
# Retrieve a tool
Source: https://docs.duckie.ai/api-reference/tools/retrieve-a-tool
api-reference/openapi.json GET /api/v1/tools/{tool_id}
# API-Key Management
Source: https://docs.duckie.ai/api/api-key-management
Create, copy, rename, expire, and revoke Duckie API keys
Manage Duckie API keys from **Settings -> API & MCP**.
The API & MCP section shows each key's name, preview, scopes, creator, created time, last-used time, expiration, and status.
It also includes an **MCP endpoint** panel with the endpoint URL, auth header format, JSON-RPC examples, and a connection test for a stored customer API key.
## Create a Key
Go to **Settings -> API & MCP**.
Click **Create key**.
Use a name that identifies the integration or environment, such as `Warehouse export` or `Production reporting`.
Select the read scopes this key should have. All read scopes are selected by default.
Select **No expiration**, **90 days**, or **1 year**.
Copy the full key from the one-time reveal dialog and store it in your secret manager.
The full API key is shown only once. Duckie stores a hash and a preview after creation.
## Scopes
Scopes are grouped by how they are used.
### Customer API
These scopes control direct `/api/v1` requests.
| Scope label | Scope value | Allows |
| ----------- | --------------------- | ------------------------------------- |
| Runs | `api:runs:read` | Read runs and run tool filter options |
| Tools | `api:tools:read` | Read tools |
| Agents | `api:agents:read` | Read agents |
| Guidelines | `api:guidelines:read` | Read guidelines |
| Guardrails | `api:guardrails:read` | Read guardrails |
| Runbooks | `api:runbooks:read` | Read runbooks |
### Duckie Assistant MCP
These scopes control the first-party Duckie Assistant MCP core object tools.
| Scope label | Scope value | Allows |
| ------------------ | ---------------- | ------------------------------------------------------------ |
| Core objects read | `api:core:read` | Describe, list, and retrieve core objects through MCP |
| Core objects write | `api:core:write` | Create, update, and delete writable core objects through MCP |
Create separate keys for separate integrations when they need different scopes or rotation schedules.
MCP clients see only the wrapper tools allowed by the key's scopes. For example, a key with `api:runs:read` can list and retrieve runs through MCP, and a key with `api:core:write` can call MCP write tools for writable core objects.
## Rename a Key
Use rename when the integration name changes or you want a clearer label. Renaming changes only the display name. The API key value and scopes stay the same.
## Revoke a Key
Revoking a key stops new requests with that key immediately.
Go to **Settings -> API & MCP** and find the key in the table.
Click the revoke action and confirm.
Update any integration that used the revoked key with a newly created key.
## Statuses
| Status | Meaning |
| ------- | ---------------------------------------------------------------- |
| Active | The key can authenticate requests until it expires or is revoked |
| Expired | The key is past its configured expiration |
| Revoked | The key was manually revoked |
# Authentication
Source: https://docs.duckie.ai/api/authentication
Authenticate Duckie API requests with bearer API keys
Duckie API requests use API keys created in Duckie. Send the full key in the `Authorization` header using the bearer scheme.
```http theme={null}
Authorization: Bearer dk_live_your_api_key
```
## Create an API Key
Create keys from **Settings -> API & MCP**. The full key is shown once after creation, so store it before closing the dialog.
Keys start with `dk_live_`. Duckie stores only a hash and a display preview after creation.
## Example Request
```bash theme={null}
curl "https://app.useduckie.ai/api/v1/tools?type=custom_tool" \
-H "Authorization: Bearer dk_live_your_api_key"
```
## Scopes
Every key has one or more scopes. A request fails with `403 permission_denied` when the key does not include the required scope.
| Scope | Allows |
| --------------------- | ------------------------------------- |
| `api:runs:read` | Read runs and run tool filter options |
| `api:tools:read` | Read tools |
| `api:agents:read` | Read agents |
| `api:guidelines:read` | Read guidelines |
| `api:guardrails:read` | Read guardrails |
| `api:runbooks:read` | Read runbooks |
| `api:core:read` | Read core objects through MCP |
| `api:core:write` | Write core objects through MCP |
The create-key dialog groups scopes into Customer API scopes and Duckie Assistant MCP scopes. You can remove scopes when you want a key to access only a subset of the API or MCP tools.
## Invalid or Expired Keys
The API returns `401 unauthenticated` when a key is missing, malformed, unknown, expired, or revoked.
```json theme={null}
{
"error": {
"code": "unauthenticated",
"message": "Invalid API key",
"request_id": "req_123"
}
}
```
Revoking a key in Settings stops new requests with that key immediately.
# Error Responses
Source: https://docs.duckie.ai/api/errors
Handle API errors consistently
Duckie API errors use a single JSON shape.
```json theme={null}
{
"error": {
"code": "invalid_request",
"message": "limit must be a positive integer",
"request_id": "req_123"
}
}
```
Always log `request_id` when you contact Duckie support about a failed API request.
## Error Codes
| HTTP status | Code | Meaning |
| ----------- | ------------------- | ------------------------------------------------------------------------------ |
| `400` | `invalid_request` | A path parameter, query parameter, cursor, or request format was invalid |
| `401` | `unauthenticated` | The `Authorization` header is missing, malformed, unknown, expired, or revoked |
| `403` | `permission_denied` | The API key does not include the required read scope |
| `404` | `not_found` | The requested resource was not found in the API key's organization |
| `429` | `rate_limited` | A pre-auth, key, organization, or endpoint rate limit was exceeded |
| `500` | `internal_error` | Duckie could not complete the request |
## Authentication Errors
Missing or malformed authentication returns:
```json theme={null}
{
"error": {
"code": "unauthenticated",
"message": "Authorization header must be 'Bearer '",
"request_id": "req_123"
}
}
```
Unknown, expired, or revoked keys return:
```json theme={null}
{
"error": {
"code": "unauthenticated",
"message": "Invalid API key",
"request_id": "req_123"
}
}
```
## Permission Errors
If a key is valid but lacks the required scope, the API returns:
```json theme={null}
{
"error": {
"code": "permission_denied",
"message": "API key does not have the required scope",
"request_id": "req_123"
}
}
```
Create a new key with the needed scope or update your integration to call only endpoints the key can access.
## Not Found Errors
Detail endpoints return `404 not_found` when the resource does not exist in the API key's organization. This includes valid UUIDs that belong to another organization.
# MCP Endpoint
Source: https://docs.duckie.ai/api/mcp
Connect MCP clients to Duckie runs and core objects
Duckie's MCP endpoint exposes Duckie runs and core configuration objects as Model Context Protocol tools.
Use it when an MCP client needs to inspect Duckie runs or read and write Duckie configuration objects without calling each endpoint directly.
## Endpoint
```text theme={null}
https://app.useduckie.ai/api/mcp
```
Send JSON-RPC requests with `POST`.
For direct MCP clients that let you configure headers, authenticate with a customer API key.
```http theme={null}
Authorization: Bearer dk_live_your_api_key
Content-Type: application/json
```
Create and manage customer API keys from **Settings -> API & MCP**.
The endpoint also supports OAuth for Claude custom connectors. In that flow, Claude sends a Duckie-issued OAuth access token instead of a static customer API key.
## Connect from Claude
Use the MCP endpoint URL when you add Duckie as a Claude custom connector.
```text theme={null}
https://app.useduckie.ai/api/mcp
```
You do not need to create a Duckie API key, OAuth client ID, or OAuth client secret for Claude.
Claude discovers Duckie's OAuth configuration from the MCP endpoint, registers itself as a public OAuth client, and redirects you to Duckie. After you sign in and approve access, Duckie issues OAuth tokens for Claude to use.
```http theme={null}
Authorization: Bearer dk_mcp_access_...
```
That token is tied to the Duckie user, organization, and approved scopes. Claude uses it to call the same MCP endpoint that direct clients can call with a customer API key.
The user who connects Claude must have permission to manage API keys in Duckie. If Claude shows optional advanced fields for OAuth Client ID or OAuth Client Secret, leave them blank unless Duckie Support has given you specific values.
Do not put a Duckie API key in the MCP URL or paste it into Claude as a static bearer token. Claude remote custom connectors use OAuth for authenticated servers.
For more detail on Claude's connector behavior, see Claude's [custom connector setup guide](https://support.anthropic.com/en/articles/11175166-getting-started-with-custom-integrations-using-remote-mcp) and [connector authentication reference](https://claude.com/docs/connectors/building/authentication).
## Find the MCP setup panel
Go to **Settings -> API & MCP**.
In the **MCP endpoint** panel, copy the endpoint URL, auth header format, or a JSON-RPC request example.
Paste a customer API key into **Test connection** and click **Test**. Duckie sends an MCP `initialize` request to confirm the key can authenticate.
The full API key is shown only once when you create it. The MCP test field is for keys you already stored outside Duckie.
## Initialize
Duckie currently returns MCP protocol version `2025-06-18`.
```json theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2025-06-18",
"capabilities": {},
"clientInfo": {
"name": "your-client",
"version": "1.0.0"
}
}
}
```
Successful initialization returns the `duckie-customer-api` server info and tool capabilities.
## List available tools
Use `tools/list` to list the wrapper tools available to the customer API key or OAuth token.
```json theme={null}
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/list"
}
```
The response includes only tools allowed by the credential's scopes.
| Scope | Tools |
| ---------------- | ------------------------------------------------------------------------------------- |
| `api:runs:read` | `duckie_list_runs`, `duckie_get_run`, `duckie_list_run_tool_options` |
| `api:core:read` | `duckie_describe_core_objects`, `duckie_list_core_objects`, `duckie_get_core_object` |
| `api:core:write` | `duckie_create_core_object`, `duckie_update_core_object`, `duckie_delete_core_object` |
The individual REST API read scopes, such as `api:agents:read` and `api:tools:read`, apply to direct `/api/v1` requests. MCP uses `api:runs:read` for run tools and `api:core:*` for core object tools.
## Core objects
Use `duckie_describe_core_objects` to see the currently supported object types, their readable fields, writable fields, and required create fields.
Supported core object types include:
| Object type | Access |
| ----------------------- | -------------------------------------------- |
| `agents` | Read/write |
| `runbooks` | Read/write |
| `workflows` | Read/write |
| `snippets` | Read/write |
| `folders` | Read/write |
| `guidelines` | Read/write |
| `guideline_sections` | Read/write |
| `guardrails` | Read/write |
| `alerts` | Read-only |
| `alert_definitions` | Read/write Agent Triggered alert definitions |
| `attributes` | Read/write |
| `attribute_options` | Read/write |
| `categories` | Read/write |
| `resolution_rules` | Read/write |
| `custom_knowledge` | Read/write |
| `knowledge_tags` | Read/write |
| `custom_tools` | Read/write |
| `deployments` | Read-only |
| `organization_overview` | Read/write overview field |
Core object responses include a `url` when Duckie can build a dashboard link for that object. Run responses also include a `url`, such as:
```text theme={null}
https://app.useduckie.ai/analyze/runs?id=00000000-0000-4000-8000-000000000000
```
## Call a tool
Use `tools/call` with a tool name and arguments.
```json theme={null}
{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "duckie_list_runs",
"arguments": {
"limit": 10,
"status": ["completed", "failed"]
}
}
}
```
Tool-call results return MCP content where the first text item contains the JSON payload from the underlying Duckie API response.
```json theme={null}
{
"jsonrpc": "2.0",
"id": 3,
"result": {
"content": [
{
"type": "text",
"text": "{\n \"data\": [],\n \"pagination\": {\n \"limit\": 10,\n \"next_cursor\": null,\n \"has_more\": false\n }\n}"
}
],
"isError": false
}
}
```
## Arguments
MCP tool arguments match the filters and IDs used by the REST API.
For example, `duckie_list_runs` supports pagination, run filters, duration filters, and metadata filters. `duckie_get_run` requires `run_id`.
Core object tools use `object_type`. List calls accept `limit` and `cursor`. Get, update, and delete calls require `id` except for `organization_overview`, which can omit `id` because it is a singleton for the current organization.
If an argument does not match the tool input schema, Duckie returns a JSON-RPC `-32602` error.
## Related pages
Create an API key and send it with each request.
See the run filters mirrored by the MCP wrapper tools.
# Duckie API Overview
Source: https://docs.duckie.ai/api/overview
Export Duckie data and connect MCP clients
The Duckie API gives external systems access to your organization's runs and configuration data.
Use the REST API to export run history, analyze tool usage, sync agent configuration, or connect Duckie data to your internal reporting workflows. Use the MCP endpoint when an MCP client needs run tools or read/write access to core Duckie objects.
## Base URL
```text theme={null}
https://app.useduckie.ai
```
REST API endpoints are under `/api/v1`. MCP clients use `/api/mcp`.
## Available Resources
| Resource | What you can read |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| Runs | Run summaries, run details, conversation messages, execution steps, evaluation attributes, and tool-call payloads after redaction and truncation |
| Tools | Duckie tools, app tools, custom tools, and MCP tools available to your organization |
| Agents | Agent configuration, instructions, linked tools, guidelines, guardrails, runbooks, workflows, categories, and attributes |
| Guidelines | Published guidelines and guideline section summaries |
| Guardrails | Escalation and restriction guardrails |
| Runbooks | Published, non-deleted runbooks |
| MCP endpoint | Run tools plus core object read/write tools |
## Request Example
```bash theme={null}
curl "https://app.useduckie.ai/api/v1/runs?limit=25&status=completed" \
-H "Authorization: Bearer dk_live_your_api_key"
```
List endpoints return `data` plus a pagination object:
```json theme={null}
{
"data": [],
"pagination": {
"limit": 25,
"next_cursor": null,
"has_more": false
}
}
```
Detail endpoints return one resource in `data`:
```json theme={null}
{
"data": {
"id": "00000000-0000-4000-8000-000000000000",
"object": "run"
}
}
```
## Endpoint Summary
| Method | Path | Description |
| ------ | ----------------------------------- | -------------------------------------------------------------- |
| `GET` | `/api/v1/runs` | List run summaries |
| `GET` | `/api/v1/runs/{run_id}` | Retrieve one run with conversation, steps, and evaluation data |
| `GET` | `/api/v1/runs/tool-options` | List historical tool names for run filtering |
| `GET` | `/api/v1/tools` | List tools |
| `GET` | `/api/v1/tools/{tool_id}` | Retrieve one tool |
| `GET` | `/api/v1/agents` | List agents |
| `GET` | `/api/v1/agents/{agent_id}` | Retrieve one agent |
| `GET` | `/api/v1/guidelines` | List published guidelines |
| `GET` | `/api/v1/guidelines/{guideline_id}` | Retrieve one guideline |
| `GET` | `/api/v1/guardrails` | List guardrails |
| `GET` | `/api/v1/guardrails/{guardrail_id}` | Retrieve one guardrail |
| `GET` | `/api/v1/runbooks` | List published runbooks |
| `GET` | `/api/v1/runbooks/{runbook_id}` | Retrieve one runbook |
| `POST` | `/api/mcp` | Call Duckie MCP tools through JSON-RPC |
## Next Steps
Create an API key and send it with each request.
Connect MCP clients to Duckie runs and core objects.
Page through large exports and narrow run lists.
Plan around per-key, per-organization, and endpoint limits.
Handle common API failures consistently.
# Pagination and Filtering
Source: https://docs.duckie.ai/api/pagination-and-filtering
Page through API results and filter run exports
List endpoints use cursor pagination. Pass `limit` to choose a page size, then pass `pagination.next_cursor` as `cursor` to request the next page.
## Pagination
Runs default to `limit=50` and are capped at `100`.
Tools, agents, guidelines, guardrails, and runbooks default to `limit=100` and are capped at `200`.
```bash theme={null}
curl "https://app.useduckie.ai/api/v1/runs?limit=50" \
-H "Authorization: Bearer dk_live_your_api_key"
```
```json theme={null}
{
"data": [],
"pagination": {
"limit": 50,
"next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wNi0wM1QwMDowMDowMC4wMDBaIiwiaWQiOiIwMDAwMDAwMC0wMDAwLTQwMDAtODAwMC0wMDAwMDAwMDAwMDAifQ",
"has_more": true
}
}
```
Use the returned cursor as an opaque string:
```bash theme={null}
curl "https://app.useduckie.ai/api/v1/runs?limit=50&cursor=eyJjcmVhdGVkX2F0IjoiMjAyNi0wNi0wM1QwMDowMDowMC4wMDBaIiwiaWQiOiIwMDAwMDAwMC0wMDAwLTQwMDAtODAwMC0wMDAwMDAwMDAwMDAifQ" \
-H "Authorization: Bearer dk_live_your_api_key"
```
## Runs Filters
`GET /api/v1/runs` supports these filters:
| Filter | Behavior |
| ----------------- | ---------------------------------------------------------------------- |
| `created_after` | ISO timestamp lower bound |
| `created_before` | ISO timestamp upper bound |
| `status` | One or more of `completed`, `running`, `failed`, `cancelled`, `paused` |
| `ticket_id` | Exact source ticket or conversation ID |
| `agent_id` | Agent UUID |
| `source` | Exact source match |
| `resolution_type` | One or more of `deflected`, `resolved`, `escalated`, `pending` |
| `duration[eq]` | Exact duration in seconds |
| `duration[gt]` | Duration greater than a number of seconds |
| `duration[gte]` | Duration greater than or equal to a number of seconds |
| `duration[lt]` | Duration less than a number of seconds |
| `duration[lte]` | Duration less than or equal to a number of seconds |
| `tool_name` | Exact recorded tool name from a tool-call step |
| `search` | Text search over ticket title, ticket ID, and agent name |
| `metadata.` | Metadata key/value filter |
Repeat `status`, `ticket_id`, `agent_id`, `source`, `resolution_type`, or `tool_name` to OR together multiple values.
```bash theme={null}
curl "https://app.useduckie.ai/api/v1/runs?status=completed&status=failed&duration[gte]=60&duration[lt]=300" \
-H "Authorization: Bearer dk_live_your_api_key"
```
## Tool-Name Filters
Run tool filters use the recorded `run_steps.tool_name` value for steps where `type` is `tool_call`. Display labels are not accepted as filter values.
Use the tool-options endpoint to discover valid historical values:
```bash theme={null}
curl "https://app.useduckie.ai/api/v1/runs/tool-options" \
-H "Authorization: Bearer dk_live_your_api_key"
```
```json theme={null}
{
"data": [
{
"tool_name": "knowledge_search",
"display_name": "Knowledge Search",
"run_count": 42
}
]
}
```
## Tools Filters
`GET /api/v1/tools` supports these filters:
| Filter | Behavior |
| ------------------- | ------------------------------------------------------------------------ |
| `type` | One or more of `duckie_tool`, `app_tool`, `custom_tool`, `mcp_tool` |
| `search` | Search tool name, description, app integration name, and MCP server name |
| `is_write_action` | `true` or `false` |
| `requires_approval` | `true` or `false` |
| `integration_id` | Match app tools for one integration |
| `mcp_server_id` | Match MCP tools for one server UUID |
```bash theme={null}
curl "https://app.useduckie.ai/api/v1/tools?type=custom_tool&requires_approval=true" \
-H "Authorization: Bearer dk_live_your_api_key"
```
## Guardrail Filters
`GET /api/v1/guardrails` accepts `type=escalation` or `type=restriction`.
# Rate Limits
Source: https://docs.duckie.ai/api/rate-limits
Understand API request limits and retry headers
Duckie API rate limits use one-minute windows. Every authenticated request is checked against layered limits.
| Bucket | Default limit |
| --------------------------------------------------- | ----------------------------------- |
| Missing or invalid key attempts | 60 requests/minute/IP |
| Global key traffic | 5,000 requests/minute/key |
| Global organization traffic | 25,000 requests/minute/organization |
| Runs list | 600 requests/minute/key |
| Run tool options | 600 requests/minute/key |
| Run detail | 2,400 requests/minute/key |
| Tools, agents, guidelines, guardrails, and runbooks | 2,400 requests/minute/key |
## Rate-Limit Headers
Successful authenticated responses include rate-limit headers for the active limiting bucket.
```http theme={null}
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 599
X-RateLimit-Reset: 1780444830
```
| Header | Meaning |
| ----------------------- | ---------------------------------------- |
| `X-RateLimit-Limit` | Request limit for the active bucket |
| `X-RateLimit-Remaining` | Requests remaining in the current window |
| `X-RateLimit-Reset` | Unix timestamp when the bucket resets |
## Rate-Limited Responses
When a request exceeds a limit, Duckie returns `429 rate_limited`.
```http theme={null}
HTTP/1.1 429 Too Many Requests
Retry-After: 12
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1780444830
```
```json theme={null}
{
"error": {
"code": "rate_limited",
"message": "Rate limit exceeded",
"request_id": "req_123",
"retry_after": 12
}
}
```
Wait at least the `Retry-After` number of seconds before retrying. If you are exporting a large data set, keep using cursor pagination and back off when `X-RateLimit-Remaining` gets low.
# Agent Tables
Source: https://docs.duckie.ai/concepts/agent-tables
Use scoped structured tables as working memory for autonomous agents
Agent Tables give autonomous agents a small structured workspace they can query and update while they work.
Use them when an agent needs more than conversational memory, but you do not want to give it raw database access or make a customer system the scratchpad.
## What Agent Tables Are
An Agent Table is a workspace-level table definition with a name, description, row scope, and column schema. You create and manage table definitions in **Build -> Tables**, then attach tables to autonomous agents from the agent's **Tables** configuration.
During a run, the agent can use table tools to:
* list the tables available to the run
* inspect a table's schema and row scope
* query visible rows with filters and sorting
* insert rows or replace rows with the same stable `row_key`
* update or delete selected rows
Agent Tables are not raw SQL tables exposed to the model. Duckie owns the table definition, validates rows against the schema, and applies row visibility from the table's configured scope.
## What Tables Can Do
| Pattern | Scope to start with | How it helps |
| ---------------------------------- | ------------------- | -------------------------------------------------------------------------------------------------- |
| Run scratchpad | Run | Collect candidates, intermediate results, or decisions that only matter during one run |
| Ticket checklist | Ticket | Track missing facts, completed steps, or follow-up state across turns on the same ticket |
| Agent working set | Agent | Give one specialist agent a private structured list it can reuse across runs |
| Workspace queue | Workspace | Share lightweight review items or triage rows between agents in the same workspace |
| Organization registry | Organization | Keep a shared structured list that agents can reference across the organization boundary |
| Parent and sub-agent collaboration | Agent or ticket | Let child agents contribute rows that the parent agent can read later in the same scoped workspace |
Good table use cases have a clear shape: rows, columns, and a small number of actions the agent should take. If the data already belongs in Zendesk, Salesforce, your database, or another system of record, use tools to read or update that system instead.
## Choose A Row Scope
The row scope controls which rows are visible when an agent reads or writes the table.
| Row scope | Use it when |
| ----------- | --------------------------------------------------------------------------------------- |
| `run` | Rows should reset between individual runs |
| `ticket` | Rows should follow the current support ticket or conversation |
| `agent` | Rows should belong to the configured agent, and the table should be explicitly attached |
| `workspace` | Agents in the current workspace should share the same row set |
| `org` | The row set should be shared at the organization level |
Start with the narrowest scope that still supports the job. A per-ticket checklist should not be organization scoped. A shared escalation review list should not be run scoped.
## Design The Schema
Agent Tables support columns with these types: `text`, `number`, `boolean`, `date`, `datetime`, and `json`.
Keep schemas small and task-shaped:
* Use names that describe the agent's job, such as `case_id`, `status`, `next_step`, or `needs_review`.
* Mark a column required only when every row should have it.
* Use `json` for flexible metadata, not as a place to hide an entire unstructured document.
* Include a stable identifier column when the agent will need to update the same real-world item later.
When the agent writes rows, prefer stable `row_key` values. Reusing the same `row_key` lets the agent replace the same row instead of creating duplicates.
## Write Instructions For The Agent
Attaching a table makes it available, but instructions tell the agent how to use it.
A good instruction says:
* when to call `list_agent_tables`
* which table to read or update
* what each row represents
* which `row_key` to use for repeatable updates
* when to update, delete, or leave rows alone
Example:
```text theme={null}
Use the Ticket Checklist table to track support steps for this ticket.
Call list_agent_tables before writing. Use one row per checklist item.
Use row_key values like eligibility_checked, customer_confirmed, and refund_submitted.
Update a row when the step status changes instead of creating a duplicate row.
```
## Avoid These Misuses
* Do not use Agent Tables as the source of truth for customer records, billing state, inventory, or permissions.
* Do not store secrets or credentials in table rows.
* Do not create a broad organization-scoped table when ticket or agent scope would work.
* Do not rely on table rows alone for compliance-sensitive approval. Use workflows, approvals, guardrails, and run history where review matters.
## Related Docs
Attach tables to autonomous agents.
Decide what should be context, knowledge, memory, or a structured table.
Design safe agent actions.
Inspect what agents read, wrote, and called during a run.
# Autonomous Agents vs Workflows vs Runbooks
Source: https://docs.duckie.ai/concepts/autonomous-agents-vs-workflows-vs-runbooks
Choose the right Duckie building block for flexible support, repeatable processes, and procedural guidance
An **Agent** is what you deploy. **Autonomous**, **Workflow**, and **Runbook** describe how the agent starts and how much structure Duckie should follow.
These are not competing features. Strong Duckie systems often combine all three: an autonomous agent for flexible support, workflows for controlled processes, and runbooks for reusable operating guidance.
## Comparison
| Concept | Best for | How it runs | What you configure | Watch-out |
| -------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| **Autonomous agent** | Broad support, triage, research, ambiguous customer requests | Starts from **Instructions**, then chooses resources and tools as needed | Model, Instructions, Tools, Callable agents, Knowledge Tags, Guidelines, Guardrails, Runbooks & Workflows | Needs clear scope, escalation rules, and careful access to write actions |
| **Workflow** | Exact processes, compliance steps, approvals, routing, repeatable tool sequences | Visual graph with **Start**, **Tool**, **Decision**, and **End** nodes | Nodes, branches, Rule or AI decisions, Else paths, Ticket Data, Previous Node outputs | Less natural for broad, open-ended conversations |
| **Runbook** | Flexible procedures, support playbooks, policy-guided conversations | Natural-language guidance the agent follows while adapting to context | Objective, steps, conditional guidance, tool references, snippets, escalation criteria | Not ideal when every branch and action must happen in an exact order |
## Use Autonomous Agents When
Use an autonomous agent when the request is open-ended and Duckie needs to decide what to research, which tools to use, and how to respond.
Good fits include:
* Broad support queues
* Triage across many topics
* Research-heavy questions
* Conversations that may need different runbooks, workflows, tools, or sub-agents
* Situations where natural language judgment improves the outcome
Keep autonomous agents focused with clear Instructions, scoped Tools, Knowledge Tags, Guidelines, Guardrails, and Runbooks & Workflows access.
## Use Workflows When
Use a workflow when the process must follow exact steps, branches, approvals, retries, or tool order.
Good fits include:
* Eligibility checks
* Required approvals
* Deterministic routing
* Compliance-sensitive paths
* Multi-step tool orchestration
* Reusable subprocesses that other agents or workflows can call
A workflow can call Agents, Runbooks, and other Workflows from a **Tool** node.
## Use Runbooks When
Use a runbook when there is a known procedure but the conversation still needs judgment and flexibility.
Good fits include:
* Troubleshooting guides
* Policy-guided responses
* Support playbooks
* Escalation criteria
* Procedures that are easier to maintain as natural language than as a visual graph
A runbook is operating guidance, not a rigid script. If every branch and action must happen in a fixed order, use a workflow.
## Examples
| Scenario | Good design |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Password reset | Runbook for flexible troubleshooting, workflow if security checks must happen in fixed order, autonomous agent if Duckie first needs to classify the issue |
| Refund request | Workflow for eligibility and approval gates, runbook for policy-guided customer messaging, autonomous billing agent to choose the right path |
| Chargeback handling | Workflow backbone for deadlines and required fields, autonomous agents for reading notes, drafting evidence, and summarizing context |
| Internal review | Workflow routes the approval step, then uses Ask and Wait, Escalator, or an agent to involve a human |
## How to Decide
Start with the strictest requirement:
1. If exact order or auditability matters, start with a workflow.
2. If a flexible procedure is enough, start with a runbook.
3. If the agent must choose the path, start with an autonomous agent.
4. If one part needs a specialist, add a sub-agent.
5. If a human must approve, add an approval or escalation path.
## Related Docs
Configure agents that choose resources and tools at run time.
Build visual process logic.
Write flexible procedures.
Review start modes and access settings.
# Choosing an Agent Architecture
Source: https://docs.duckie.ai/concepts/choosing-an-agent-architecture
Decide how to combine agents, workflows, runbooks, tools, and deployments
An agent architecture is the shape of your Duckie system: which agent owns the work, what process it follows, what tools it can use, when it delegates, and where humans stay involved.
Start with the business process, not the Duckie object. Ask what needs to happen, what must be controlled, where judgment is useful, and what should be reviewed before customers are affected.
## Quick Recommendations
| If the work looks like this | Start with |
| --------------------------------------------------------------- | ---------------------------------------------------------------- |
| Many customer topics enter one queue | An **Autonomous** agent with clear scope and guarded tool access |
| The same exact steps must happen every time | A **Workflow** |
| There is a known procedure, but conversations vary | A **Runbook** |
| One part needs a specialist | A parent agent or workflow with a **sub-agent** |
| The source, event, tag, or schedule already identifies the task | A targeted **Deployment** |
| The action is risky or policy-sensitive | Guardrails, approvals, or human review before Live mode |
## The Core Decision
Duckie systems work best when each part has a clear job:
* **Deployments** bring work in from channels, webhooks, events, and schedules.
* **Agents** own customer-facing or internal work.
* **Workflows** control known steps, routing, approvals, and exact tool order.
* **Runbooks** give flexible procedural guidance.
* **Sub-agents** handle focused specialist tasks.
* **Tools** read information, send messages, update systems, or call your APIs.
* **Guardrails** define when Duckie should stop, avoid something, or involve a human.
* **Runs** show what happened so you can debug and improve.
A good design often uses a workflow backbone for predictable process logic, with agents at the points where judgment, language, or research matters.
## Questions to Ask
### How predictable is the process?
Use a **Workflow** when the process should follow the same path, checks, and branches each time.
Use a **Runbook** when the procedure is known but the conversation needs flexibility.
Use an **Autonomous** agent when the request may require research, choosing between resources, deciding which tool to call, or handling many possible topics.
### Who owns the overall journey?
If the process has known states, approvals, retries, or routing, let a workflow own the journey.
If the work is an open-ended customer conversation, let an autonomous agent own the journey.
If the work is one focused procedure, a runbook may be enough.
### Does the system need specialists?
Use **Callable agents** when a parent agent or workflow should keep ownership but a specialist should handle one part. Specialist agents are useful for billing, technical triage, account review, evidence drafting, or internal approvals.
### How risky are the actions?
Limit write tools to the agents that need them. Use **Testing** mode, **Internal notes only**, **No write actions**, **Restrictions**, **Escalation Rules**, and tool approvals for sensitive actions.
### How will you improve it?
Review **Analyze > Runs**, track **Categories**, **Attributes**, and **Resolution Tracking**, then test changes in **Test > Playground**, **Test > Replay Chats**, and **Test > Batch Test**.
## Common Architectures
| Pattern | Use it when | Example |
| ------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------ |
| Single autonomous agent | One broad queue needs flexible handling | General support agent for common product and billing questions |
| Workflow-first process | The sequence must be controlled | Refund eligibility, approval, and response |
| Runbook-led agent | The task follows a procedure but needs judgment | Password reset troubleshooting |
| Workflow with specialist agents | The process is known, but steps need judgment | Intake workflow calls a classification agent and evidence drafting agent |
| Human review path | The next step affects money, access, data, or customer trust | Duckie prepares an action and a teammate approves it |
| Scheduled internal agent | Work happens on a recurring cadence | Daily run summary or escalation review |
## Example
For a refund process:
1. A deployment starts when a refund request arrives.
2. A workflow looks up the order and checks eligibility.
3. A runbook guides policy-based customer messaging.
4. A specialist agent reviews unusual edge cases.
5. A human approves high-value exceptions.
6. Analyze > Runs shows the final path, tool calls, outcome, and any escalation.
## Related Docs
Learn what agents can do and how start modes work.
Build deterministic process logic.
Write flexible procedures for agents.
See advanced system patterns.
# Context, Knowledge, and Memory
Source: https://docs.duckie.ai/concepts/context-knowledge-and-memory
Understand what Duckie knows now, what it can look up, and what carries forward in a ticket
Duckie answers well when it knows the current situation, can search the right company information, and can continue an ongoing conversation without starting over.
Use **context** for the current situation, **knowledge** for reusable facts, and **memory** for continuity across turns.
## The Difference
| Concept | Question it answers | Examples |
| ---------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| **Context** | What is happening in this conversation? | Customer message, prior conversation history, ticket metadata, source channel, tool results, workflow outputs |
| **Knowledge** | What does our company know about this topic? | Product docs, policies, troubleshooting steps, FAQs, internal procedures, approved answers |
| **Memory** | What has Duckie already learned or done in this ongoing ticket? | The order number the customer provided, a prior lookup result, a question Duckie already asked |
| **Agent Tables** | What structured working set should an autonomous agent query or update? | Per-ticket checklist rows, run scratchpads, workspace queues, agent-specific review lists |
## Context: What Duckie Knows Right Now
Context is the situation around the current run. It can include:
* The customer's latest message
* Prior conversation history
* The source channel and ticket metadata
* Customer or account details from connected systems
* Tool results
* Workflow outputs
* Handoff details from a parent run or sub-agent
Context is temporary and situational. It changes from run to run.
Example: the customer is writing from a Zendesk ticket, already shared an order number, and the order lookup shows the shipment is delayed.
## Knowledge: What Duckie Can Look Up
Knowledge is reusable information Duckie can search or read before answering.
Use knowledge for:
* Product facts
* Help center articles
* Refund, billing, security, and account policies
* Troubleshooting steps
* Common questions
* Internal procedures
* Approved answers
Manage this in **Train > Knowledge** with Knowledge Base sources, Custom Knowledge, Support Knowledge, Knowledge Tags, and Gaps.
Example: your refund policy, password reset steps, and known outage response belong in knowledge, not only in one agent's instructions.
## Memory: What Carries Forward
Memory is continuity within an ongoing conversation or ticket.
For autonomous agents, Duckie can use prior conversation context and saved run memory to continue work across turns on the same ticket.
Example: if Duckie already asked for an order number and the customer replies with it later, memory helps Duckie continue instead of starting over.
## Agent Tables: Structured Working Memory
[Agent Tables](/concepts/agent-tables) are for structured rows that an autonomous agent should query or update during a run.
Use Agent Tables when the agent needs a scoped table-like working set: a checklist, queue, candidate list, extracted facts table, or status tracker. Use ordinary memory when the agent only needs conversational continuity.
## How They Work Together
For a failed payment question:
1. Context tells Duckie the customer's plan, billing ticket, and latest message.
2. Knowledge gives Duckie the payment retry policy.
3. A tool lookup returns the current invoice status.
4. Memory helps Duckie remember that it already checked the invoice when the customer follows up.
5. An Agent Table can track structured follow-up rows if the process needs a checklist or review queue.
## Common Mistakes
* Do not put permanent policy only in agent instructions. Put it in knowledge.
* Do not expect memory to replace clear knowledge articles.
* Do not pass every detail to a sub-agent. Pass only the Conversation history or Additional context it needs.
* Do not rely on customer-provided identifiers alone for account actions. Use verified context and scoped tools.
## Where to Manage Each
| Area | Where to work |
| ------------ | --------------------------------------------------------------------------------------------- |
| Context | Analyze > Runs, workflow inputs, source metadata, tool outputs, custom tool Context Variables |
| Knowledge | Train > Knowledge, Knowledge Tags, Knowledge Gaps, connected sources, Custom Knowledge |
| Memory | Multi-turn testing, Test > Playground, Test > Replay Chats, Test > Batch Test, Analyze > Runs |
| Agent Tables | Build > Tables and the Tables section in autonomous agent configuration |
## Related Docs
Manage the information agents can search.
Scope knowledge, runbooks, workflows, tools, and callable agents.
Give autonomous agents scoped structured working memory.
Pass Conversation history and Additional context to child agents.
Inspect context, steps, tool calls, and outcomes.
# Guardrails, Escalation, and Human Review
Source: https://docs.duckie.ai/concepts/guardrails-escalation-and-human-review
Know when Duckie should continue, stop, ask for approval, or hand off to a teammate
Duckie can handle routine work directly, but some conversations need firm boundaries or a human decision.
Guardrails define those boundaries. Escalation hands work to a teammate. Human review lets people inspect sensitive responses, actions, and outcomes before or after they affect customers.
## Key Concepts
| Concept | Meaning |
| -------------------- | -------------------------------------------------------------------------------------------------- |
| **Guardrails** | Safety rules that define what Duckie should not do and when it should involve a human |
| **Restrictions** | Hard limits for topics, claims, or actions Duckie should avoid |
| **Escalation Rules** | Conditions where Duckie should hand the conversation or decision to a human |
| **Human Review** | A broader pattern that includes escalations, approvals, testing review, and run audits |
| **Approvals** | A way to let Duckie prepare sensitive work while a person approves or rejects it before it happens |
| **Testing** | A safer deployment mode for reviewing behavior before Duckie responds live |
## When to Escalate
Escalate when the customer or situation requires human judgment, authority, or empathy:
* The customer explicitly asks for a human or manager.
* The customer is angry, abusive, or highly frustrated.
* Legal, regulatory, chargeback, PR, safety, or compliance concerns come up.
* Identity, account ownership, privacy, or account deletion is involved.
* Duckie has low confidence, missing information, or conflicting evidence.
* The request falls outside policy or needs an exception.
* A high-value, VIP, wholesale, or urgent case needs special handling.
* A tool fails repeatedly or the next step could affect money, access, data, or customer trust.
## Restriction vs Escalation vs Approval
| Use | When | Example |
| --------------------- | ---------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| **Restriction** | Duckie should avoid a topic or action but may continue helping | Do not promise refund amounts outside policy |
| **Escalation Rule** | A human should take over the conversation or decision | Escalate if the customer threatens legal action |
| **Requires Approval** | Duckie can prepare the action, but a person should approve it before it runs | Issuing a refund, changing account data, submitting an external claim |
## Human Review Patterns
| Pattern | How to use it |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| Pre-launch review | Use Test > Playground, Test > Replay Chats, and Test > Batch Test to verify responses, guardrails, and edge cases |
| Safe rollout | Start deployments in Testing with Internal notes only and No write actions before switching to Live |
| Conversation handoff | Use the Escalator tool when Duckie should pass a case to a teammate with context and a clear reason |
| Sensitive action approval | Mark tools as Write Action and enable Requires Approval so a teammate can Approve or Reject before the action runs |
| Ongoing audit | Review Analyze > Runs, especially runs with Escalated resolution or Waiting for Approval status |
| Continuous improvement | Use escalations, failed runs, approval history, and knowledge gaps to refine guardrails, guidelines, knowledge, and instructions |
## Examples
* If a customer asks to speak to a person, Duckie escalates instead of continuing the conversation.
* If a customer asks for a refund outside policy, Duckie explains the policy and escalates if an exception is needed.
* If a customer reports unauthorized account access, Duckie stops routine troubleshooting and hands the case to a human.
* If Duckie prepares a sensitive account update, a teammate reviews the action before it runs.
* If Duckie cannot find a confident answer after checking company docs, it asks a clarifying question or escalates with context.
## Related Docs
Configure escalation rules and restrictions.
Define when Duckie should hand off.
Use Escalator, Ask and Wait, and Responder.
Review escalations, approvals, tool calls, and outcomes.
# Overview
Source: https://docs.duckie.ai/concepts/overview
Decision guides for designing effective Duckie agent systems
Concepts explain the design choices behind Duckie systems. Use these pages when you are deciding how to structure agents, workflows, knowledge, tools, guardrails, workspaces, and testing.
If the product docs explain how to configure something, the concept docs explain when to use it and how it fits with the rest of your system.
## Agent System Design
Start with the business process, then choose agents, workflows, runbooks, sub-agents, and deployments.
Decide how much structure Duckie should follow for a given support process.
Decide when one agent is enough and when to delegate focused work to specialist agents.
Choose where routing should happen: deployments, workflows, autonomous agents, or human review.
## Operating Model
Understand what Duckie knows now, what it can look up, and what carries forward in a ticket.
Use scoped structured tables as working memory for autonomous agents.
Control what agents can do and how to test actions safely.
Know when Duckie should continue, stop, ask for approval, or hand off to a teammate.
Separate teams, products, regions, channels, permissions, and analytics with the right boundaries.
Use testing and analytics to launch safely and improve agent behavior over time.
# Routing and Orchestration Patterns
Source: https://docs.duckie.ai/concepts/routing-and-orchestration-patterns
Choose how Duckie sends work to the right agent, workflow, or human review path
Routing decides what starts a run and who should handle it. Orchestration decides what happens after the run starts.
A simple mental model:
* **Deployments** bring work in.
* **Agents** handle or delegate.
* **Workflows** control known steps.
* **Runbooks** guide flexible procedures.
* **Guardrails** route risky situations to humans.
* **Runs** show what happened.
## Pattern 1: Route at the Deployment
Use deployment routing when the channel, event, group, tag, webhook, or schedule already tells Duckie what should happen.
Examples:
* Zendesk new ticket in a billing group starts a Billing Agent.
* Slack mention in a support channel starts a Support Agent.
* A custom webhook from an internal system starts an intake workflow.
* A scheduler starts a reporting agent every weekday morning.
This keeps the entry point simple and makes ownership clear before the run begins.
## Pattern 2: Use a Workflow Backbone
Use workflows for repeatable routing, required checks, approvals, retries, and exact tool order.
Keep known process state in the workflow. Call agents only where judgment, language, research, or specialist review is needed.
Examples:
* Refund eligibility: look up order, check policy, respond or escalate.
* Case intake: validate required fields, classify, route missing data to enrichment.
* Sensitive account update: verify the account, branch to approval, then update.
## Pattern 3: Let an Autonomous Agent Choose the Path
Use autonomous agents when requests vary and Duckie needs to choose knowledge, runbooks, workflows, tools, or sub-agents.
This works well for broad support, triage, research-heavy questions, and multi-topic conversations. Keep the agent's scope clear with Tools, Knowledge Tags, Runbooks & Workflows, and Callable agents.
## Pattern 4: Delegate to Specialist Agents
Use sub-agents for focused expertise, safer tool access, or clean handoffs.
The parent workflow or agent keeps ownership of the customer experience. The child agent handles a narrower task and returns a useful result.
Examples:
* General Support Agent delegates a billing question to Billing Agent.
* Workflow calls Evidence Drafting Agent, then routes the output to approval.
## Pattern 5: Keep Humans in the Loop
Use Escalation Rules, Restrictions, the Escalator tool, and approval settings when the situation needs human judgment.
Common triggers include legal threats, account security, VIP handling, high-value refunds, angry customers, low confidence, and requests outside policy.
## Pattern 6: Run Recurring Operational Work
Use scheduled deployments for daily summaries, SLA checks, periodic reviews, and feedback loops.
Duckie Assistant agents fit well for reporting, run review, and Duckie configuration improvement. They are not usually the primary choice for real-time customer support routing.
## Choosing the Pattern
| Use this | When |
| ------------------ | -------------------------------------------------------- |
| Deployment routing | Source, event, filter, or schedule is enough |
| Workflow | Steps must happen predictably |
| Autonomous agent | Judgment, research, or flexible sequencing matters |
| Runbook | A procedure is structured but still conversational |
| Sub-agent | One part of the job needs a specialist |
| Human review | Risk, policy, confidence, or authority requires approval |
## Test and Monitor
Start deployments in **Testing** mode when possible. Use **Test > Playground**, **Test > Replay Chats**, and **Test > Batch Test** before switching to **Live**.
After launch, review **Analyze > Runs** and track Categories, Attributes, and Resolution Tracking so you can see which routes are working.
## Related Docs
Connect agents and workflows to channels, events, webhooks, and schedules.
Build deterministic routing and process logic.
Let agents choose resources and tools at run time.
Route risky situations to escalation or restriction paths.
# Single Agents vs Sub-Agents
Source: https://docs.duckie.ai/concepts/single-agents-vs-sub-agents
Decide when one agent should own a conversation and when to delegate focused work to specialist agents
Use a single agent when one assistant can own the customer experience end to end. Use sub-agents when a parent agent or workflow should keep ownership, but a specialist agent should handle one focused part.
Sub-agents are useful for clear handoffs, reusable expertise, and safer access to sensitive tools.
## Comparison
| Question | Single agent | Sub-agents |
| ------------------------------ | --------------------------------------- | ----------------------------------------------------------------- |
| Who owns the customer journey? | One agent owns everything | A parent agent or workflow owns the overall journey |
| Best for | Simple or moderately broad support work | Complex work split into focused specialties |
| Tool access | Same tool set for the whole job | Sensitive tools can stay with specialist agents |
| Reuse | Logic stays inside one agent | Specialist agents can be reused across workflows or parent agents |
| Context | One agent sees the full conversation | Pass conversation history only when the child agent needs it |
| Testing | Easier to test one path | Test the parent and child behavior together |
| Risk | Agent scope can become too broad | Handoffs need clear names, descriptions, and instructions |
## When a Single Agent Is Enough
A single agent is usually enough when:
* One support domain or queue is in scope.
* The same knowledge, tools, guidelines, and tone apply to most requests.
* The process is easy to test as one customer journey.
* The agent can safely own the response without specialist review.
Example: a Billing Support Agent answers invoice questions, checks refund policy, searches company docs, and responds to the customer.
## When to Use Sub-Agents
Use sub-agents when:
* A general agent needs specialist help.
* Multiple workflows reuse the same specialist.
* Sensitive tools should only be available to a narrow agent.
* A workflow owns the process, but one step needs judgment, language, or research.
* A parent agent should delegate without giving up ownership of the conversation.
Example: a dispute workflow calls a Reason Classification Agent, an Evidence Drafting Agent, and a Slack Escalation Agent while the workflow keeps the process moving.
## Good Delegation Boundaries
Good sub-agent tasks are focused:
* "Review this refund request against the refund policy and return a recommendation."
* "Summarize the technical issue and identify the likely integration."
* "Draft an internal escalation note with the customer impact and missing information."
* "Review this order lookup result and identify whether the customer is eligible."
Avoid broad tasks that duplicate the parent agent's job:
* "Handle this whole customer conversation."
* "Do whatever is needed."
* "Fix the issue."
## Context Passed to Sub-Agents
Every child run needs a useful task. Add **Conversation history** when the child needs previous customer messages. Add **Additional context** when the parent workflow has structured details such as an order lookup, policy excerpt, customer segment, or previous node output.
Pass only what the child needs. Focused handoffs make child results easier to trust and easier to test.
## Examples
| Scenario | Design |
| --------------------------------------- | ----------------------------------------------------------------------------------------------- |
| General support with billing edge cases | General Support Agent delegates invoice disputes to Billing Agent |
| Refund workflow | Workflow calls Refund Specialist Agent for exception review, then continues the workflow |
| Technical triage | Technical Triage Agent delegates integration-specific debugging to Integration Specialist Agent |
| Evidence preparation | Workflow calls Evidence Drafting Agent with order lookup results as Additional context |
| Human approval | Approval workflow calls Slack Escalation Agent to ask a reviewer for a decision |
## Related Docs
Configure agent-to-agent delegation.
Let agents call approved specialists.
Call agents from workflow Tool nodes.
Review parent runs, sub-runs, and agent calls.
Call Duckie from a customer-owned orchestration agent.
# Testing, Observability, and Iteration
Source: https://docs.duckie.ai/concepts/testing-observability-and-iteration
Use Duckie's testing and analytics surfaces to launch agents safely, monitor quality, and improve over time
Duckie agents improve through a loop: test, deploy carefully, observe real runs, then update the agent.
This is an operating model, not just a debugging process. Validate before public replies, watch early performance, and keep improving based on real conversations.
## Key Concepts
| Concept | Meaning |
| ----------------------------- | ------------------------------------------------------------------------------------------------- |
| **Run** | One agent execution triggered by a customer message, replay, batch test, schedule, or deployment |
| **Testing** | Deployment mode for reviewing behavior before Duckie responds live |
| **Live** | Deployment mode where responses and actions can affect real customer systems |
| **Rubric** | Scoring criteria for Batch Test results |
| **Resolution** | How Duckie determines whether a conversation was resolved, deflected, escalated, or still pending |
| **Categories and Attributes** | Labels that make performance easier to analyze by topic, priority, product area, or outcome |
## The Testing and Rollout Loop
1. Configure the agent with knowledge, guidelines, guardrails, runbooks, workflows, and tools.
2. Use **Test > Playground** for fast, interactive scenario testing.
3. Use **Test > Replay Chats** to compare Duckie against real historical conversations.
4. Turn important scenarios into **Test > Batch Test** suites.
5. Run Batch Tests with a **Rubric** and optional Agent test instructions.
6. Create a deployment in **Testing** mode with **Internal notes only** and **No write actions** when needed.
7. Review **Analyze > Runs** and fix gaps in knowledge, guidelines, guardrails, runbooks, workflows, or tool access.
8. Switch the deployment to **Live** only after quality is consistent.
9. Monitor **Performance**, **Breakdown**, **Runs**, and **Alerts** after launch.
10. Repeat the loop after major product, policy, or workflow changes.
## What to Observe
| Surface | Use it for |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------- |
| Analyze > Runs | Inspect Conversation, Agent Steps, Agent Calls, Attributes, Category, Resolution, Event Source, Tool Input, and Tool Output |
| Analyze > Performance | Track volume, deflection, resolution, escalation, response time, and time to resolution |
| Analyze > Breakdown | Review Category Breakdown and Attribute Breakdown, then drill into matching runs |
| Analyze > Alerts | Notify the team when escalation rate, response time, error rate, volume, or resolution rate changes unexpectedly |
| Train > Knowledge > Gaps | Turn unanswered questions into better knowledge coverage |
## Examples
| Situation | Loop |
| --------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| Launching a new support agent | Playground, Replay Chats, Batch Test, Testing deployment, then Live |
| Updating a refund policy | Add Batch Test cases, use Agent test instructions, compare old and new results |
| Investigating an escalation spike | Start in Performance, filter Runs, inspect Agent Steps and Resolution, then update guardrails or knowledge |
| Filling knowledge gaps | Identify repeated unanswered questions, create or link knowledge, replay the original conversation |
| Testing tool-heavy workflows | Use Testing mode with No write actions before allowing real updates |
## Signs You Should Iterate
* The agent escalates too often or too rarely.
* Runs show repeated failed tool calls.
* Customers ask questions that knowledge does not answer.
* Batch Test scores drop after a policy, product, or prompt change.
* Resolution rates vary sharply by category or attribute.
* Reviewers frequently reject approval requests.
## Related Docs
Learn about Playground, Replay Testing, and Batch Testing.
Inspect execution details and outcomes.
Track volume, resolution, deflection, escalation, and timing.
Find and close unanswered questions.
# Tools, Permissions, and Side Effects
Source: https://docs.duckie.ai/concepts/tools-permissions-and-side-effects
Understand what agents can do, how access is controlled, and how to test actions safely
Tools are the actions Duckie agents can perform. Some tools only read information. Others create visible or persistent changes in customer systems, internal systems, or Duckie itself.
Treat every tool choice as a permissions decision: what should this agent be able to see, say, update, or trigger?
## Tool Categories
| Tool type | What it does |
| ---------------- | ------------------------------------------------------------------------------------------------------------------- |
| **Duckie Tools** | Built-in actions such as Responder, Ask and Wait, Search Company Docs, Escalator, LLM Call, Save Value, and End Run |
| **App Tools** | Actions from connected apps such as Zendesk, Slack, Intercom, HubSpot, Jira, Linear, Gmail, Plain, or Pylon |
| **Custom Tools** | Your own HTTP-based tools for internal APIs and systems |
| **MCP Servers** | MCP tools discovered from configured servers |
Tools can search docs, read records, send messages, create tickets, update fields, call APIs, or return values to later workflow steps.
## Permissions Happen in Layers
| Layer | What it controls |
| ------------------------ | ------------------------------------------------------------------------------------------------- |
| Connections | App tools depend on connected platforms in Settings > Connections |
| Tool Access | Agents and assistant agents only use tools enabled for them |
| Roles and API scopes | Workspace roles and Settings > API & MCP scopes control who or what can manage Duckie objects |
| External app permissions | Zendesk, Slack, Jira, Gmail, and other apps still enforce the connected account's own permissions |
| Agent design | Instructions, workflows, runbooks, guardrails, and approvals shape when tools are used |
## Read Tools vs Side Effects
A side effect is anything visible or persistent outside the agent's reasoning.
Examples of side effects:
* Sending a customer response with Responder
* Adding an internal note or public reply in a ticketing system
* Creating or updating a ticket, issue, task, page, note, or conversation
* Sending Slack, Discord, Teams, or Gmail messages
* Updating tags, priority, assignment, status, custom fields, labels, or metadata
* Calling a Custom Tool that changes your internal system
* Using Duckie Assistant MCP tools to create, update, or delete Duckie objects
Customer replies and internal notes are side effects. **Write Action** is the product label for tools that modify data.
## Safe Tool Access Patterns
* Start with least privilege: enable only the tools an agent needs.
* Prefer read and search tools before write tools.
* Keep write tools narrow and specific.
* For custom tools, mark the tool as **Write Action** when it modifies data.
* Use **Requires Approval** for sensitive or high-impact actions.
* Use **Slack Approval Notify** when reviewers should approve from Slack.
* Use workflows for predictable lookup, verification, approval, and action order.
* Add Restrictions and Escalation Rules for requests that need human judgment.
* Test tool-heavy designs before allowing real updates.
## Testing Without Unintended Changes
Use **Testing** mode before **Live** mode. For early rollout, use **Internal notes only** and **No write actions** when available.
In Test > Playground, Test > Replay Chats, and Test > Batch Test, review whether the agent chose the right tool, used the right input, and produced the expected result.
Use **Analyze > Runs** to inspect tool calls, inputs, outputs, status, and outcomes.
## Related Docs
Explore Duckie Tools, App Tools, Custom Tools, and MCP Servers.
Connect Duckie to your internal APIs.
Use Testing and Live modes safely.
Design safer actions for account-sensitive work.
# Workspaces and System Boundaries
Source: https://docs.duckie.ai/concepts/workspaces-and-system-boundaries
Decide how to separate teams, products, regions, and support motions in Duckie
Boundaries help teams keep the right people, knowledge, channels, actions, and analytics together.
The practical question is: which part of the business should this agent belong to, and what should it be allowed to see or do?
## Organization vs Workspace
A **top-level organization** is the billing and account umbrella. A **workspace** is an isolated Duckie environment under that organization.
Billing rolls up to the top-level organization. Configuration and data stay separate inside each workspace.
## What a Workspace Separates
Each workspace has its own:
| Area | What is scoped |
| ---------------------- | --------------------------------------------------------------------------------- |
| Members and roles | Workspace membership and role assignments |
| Connections | Connected integrations and credentials |
| Agents and deployments | Agent configuration, deployment settings, and production runs |
| Knowledge and training | Knowledge items, guidelines, guardrails, runbooks, snippets, tools, and workflows |
| Analytics and testing | Runs, usage attribution, playground activity, and batch tests |
Changing one workspace does not change a sibling workspace.
## Workspace Examples
| Workspace | Why it helps |
| --------------------------------------- | ------------------------------------------------------------------------------------------- |
| EMEA Support | Regional ownership, channels, localized knowledge, and escalation paths |
| Product A Support and Product B Support | Separate docs, agents, tools, and analytics by product |
| Internal Support and Customer Support | Different audiences, policies, integrations, and tone |
| Enterprise Support | High-touch customers, stricter guardrails, dedicated connections, and specialist agents |
| Pilot Support | Useful only when the pilot needs separate data or configuration; otherwise use Testing mode |
## Boundary Choices
| Use this | When |
| ------------------------- | --------------------------------------------------------------------------------------- |
| **Workspace** | You need hard separation of members, connections, agents, knowledge, runs, and settings |
| **Knowledge Tags** | The same workspace is fine, but an agent should search only certain knowledge |
| Separate **agents** | Jobs, tone, tools, or escalation rules differ |
| Deployment filters | The same agent should handle only certain channels, groups, tags, events, or schedules |
| Tool access and approvals | You need to limit what agents can do |
| Guardrails | You need shared restrictions and escalation rules |
| Testing surfaces | You want to validate behavior before expanding live scope |
## Recommended Setup Flow
1. Start from your business structure: teams, products, regions, customer segments, and support motions.
2. Create workspaces only where separation is needed.
3. Connect only the integrations each workspace should use.
4. Configure agents with scoped knowledge, tools, guidelines, guardrails, runbooks, and workflows.
5. Deploy in **Testing** mode first.
6. Review **Analyze > Runs** and testing results.
7. Expand to **Live** once behavior and ownership are clear.
## Related Docs
Create and manage isolated Duckie workspaces.
Manage people and roles.
Scope knowledge within a workspace.
Connect the right systems to each workspace.
# Core Concepts
Source: https://docs.duckie.ai/core-concepts
Understand the key building blocks of Duckie
This page introduces the fundamental concepts you'll work with in Duckie. Understanding these will help you build effective AI-powered support.
## Agents
**Agents** are the AI assistants that handle customer conversations. Each agent is configured with:
* A **start mode**: autonomous, workflow, or runbook
* **Instructions** that define what it is responsible for
* **Knowledge sources** it can search for information
* **Guidelines** that shape its communication style
* **Guardrails** that define safety constraints and escalation rules
* **Categories and attributes** for classifying conversations
Think of an agent as a virtual team member with specific training and responsibilities.
Deep dive into agent configuration and capabilities
## Runbooks
**Runbooks** are flexible, AI-driven procedures written in natural language. They guide agents through specific processes while allowing them to adapt to unique situations.
Example runbook for password reset:
> 1. Verify the customer's identity using email
> 2. Check for any security flags on the account
> 3. If verified, send password reset email
> 4. If unable to verify, escalate to security team
Create effective runbooks for your agents
## Workflows
**Workflows** are visual, graph-based automations for precise control over agent behavior. Use workflows when you need deterministic, step-by-step execution.
Workflows consist of:
* **Action nodes** — Execute tools and integrations
* **Decision nodes** — Branch based on conditions
* **AI nodes** — Use LLM for dynamic decisions
Build visual workflows for complex processes
## Knowledge Base
The **knowledge base** is a searchable repository of information your agents can reference. It includes:
* **Connected sources** — Notion, Confluence, Google Drive, etc.
* **Custom articles** — Content created directly in Duckie
* **Knowledge gaps** — Questions your agent couldn't answer (for improvement)
Build and manage your agent's knowledge
## Guidelines
**Guidelines** are instructional rules that shape how your agent communicates. They cover:
* Voice and tone
* Response format and length
* Brand standards and terminology
* Domain-specific instructions
Define your agent's communication style
## Guardrails
**Guardrails** are safety constraints that protect customers and your brand:
* **Escalation rules** — When to hand off to humans
* **Restrictions** — Hard limits on what the agent cannot do
Set up safety constraints and escalation rules
## Deployments
**Deployments** connect agents to real customer channels. Each deployment specifies:
* Which **agent** to run
* A **trigger** (channel + event, e.g., "New Zendesk ticket")
* A **mode** (live, shadow, or testing)
Deploy agents to customer channels
## Tools
**Tools** are actions your agents can perform:
* **Duckie tools** — Built-in capabilities (respond, search, escalate, etc.)
* **App tools** — Actions from connected integrations (update ticket, send message, etc.)
* **Custom tools** — Your own HTTP-based integrations
* **MCP tools** — Tools discovered from Model Context Protocol servers
Explore available tools and capabilities
## How They Connect
## Next Steps
See the full message-to-response flow
Build and configure an agent
# Creating Deployments
Source: https://docs.duckie.ai/deployments/creating-deployments
Deploy your agent to a channel
This guide walks you through creating a deployment to connect your agent to a customer channel.
## Before You Start
Before creating a deployment:
* [Create and configure an agent](/agents/creating-agents)
* [Connect the integration](/settings/connections) you want to deploy to
* [Test your agent](/testing/playground) in the playground
## Creating a Deployment
Go to **Deploy** in your dashboard.
Click **Create Deployment** to open the configuration.
Choose which agent will handle conversations.
Select the channel and events.
**Channel or trigger type:** Zendesk, Slack, Intercom, Custom Webhook, Scheduler, etc.
**Events or schedule:** New ticket, message received, recurring schedule, etc.
Narrow when the agent responds:
* **Channels/Groups:** Specific Slack channels or Zendesk groups
* **Tags:** Only tickets with certain tags
* **@mention only:** Only when the bot is mentioned
Choose how the agent responds:
* **Live:** Responds directly to customers
* **Testing:** Runs with testing options before live traffic
Click **Create** to save. Set status to **Active** to start.
## Configuration Details
### Agent Selection
Choose the agent that will handle incoming messages:
* Agent's start mode and instructions define behavior
* Agent's knowledge determines what it can answer
* Agent's guardrails define safety constraints
You can change the agent later without recreating the deployment.
### Trigger Configuration
#### Channel
Select the connected integration:
* Only integrations you've connected appear
* Must have agent channel capability (not just knowledge)
#### Events
Select which events trigger the agent:
| Channel | Common Events |
| ------------------ | -------------------------------------------- |
| **Zendesk** | Ticket created, Comment added, Internal note |
| **Slack** | Channel message, Direct message, App mention |
| **Intercom** | Conversation created, Customer replied |
| **Custom Webhook** | JSON event payloads from your own system |
| **Scheduler** | Recurring schedule |
### Filters
Narrow the scope of the deployment:
#### Channel Filters
Respond only in specific channels:
```
Slack: #support, #customer-questions
Zendesk: Support group, VIP group
```
#### Tag Filters (Zendesk)
Respond only to tickets with specific tags:
```
Tags: duckie-enabled, ai-support
```
#### @Mention Only
Only respond when explicitly mentioned:
* Useful for shared channels
* Prevents unwanted responses
* Customer must @mention the bot
### Mode Selection
We strongly recommend starting new deployments in **Testing** mode.
| Mode | Use Case |
| ----------- | --------------------------------------------------- |
| **Testing** | New deployments, debugging, and building confidence |
| **Live** | Validated, ready for customers |
## After Creating
### Activate the Deployment
Deployments are created in "Paused" status. To activate:
1. Click on the deployment
2. Toggle status to **Active**
3. Agent begins processing messages
### Monitor Performance
After activation:
1. Go to **Analyze → Runs** to see activity
2. Check response quality
3. Review any escalations
4. Watch key metrics
### Iterate
Based on results:
* Adjust agent configuration
* Refine filters
* Update guardrails
* Graduate from testing to live
## Common Configurations
### Zendesk Support
```
Agent: Support Agent
Channel: Zendesk
Events: Ticket created, Comment added (public)
Filters: Support group only
Mode: Testing → Live
```
### Slack Customer Channel
```
Agent: Support Agent
Channel: Slack
Events: App mention
Filters: #customer-support channel
Mode: Live (after testing)
```
### Intercom Chat
```
Agent: Support Agent
Channel: Intercom
Events: Conversation created, Customer replied
Filters: None (all conversations)
Mode: Testing → Live
```
### Scheduled Summary
```
Agent: Support Agent
Trigger: Scheduler
Schedule: Weekdays at 9 AM
Mode: Testing → Live
```
## Next Steps
Understand live vs testing
Trigger agents from custom JSON events
Run an agent on a recurring schedule
Track your deployment
# Custom Webhooks
Source: https://docs.duckie.ai/deployments/custom-webhooks
Trigger an agent from a custom JSON webhook
Custom Webhooks let you trigger a Duckie agent from any system that can send a JSON `POST` request. Use them when your source system is not one of Duckie's built-in deployment channels, or when you need to shape a custom event payload into Duckie runs.
## How Custom Webhooks Work
A Custom Webhook deployment has two parts:
| Part | What it controls |
| -------------------- | -------------------------------------------------------------------------------- |
| **Webhook endpoint** | The generated URL, endpoint name, and request verification method |
| **Payload mappings** | How fields from the incoming JSON payload become the run, messages, and metadata |
When Duckie receives a valid request, it checks the deployment's event filtering, extracts the mapped fields, creates a run, inserts the mapped run messages, and queues the selected agent.
## Create a Custom Webhook Deployment
Go to **Deploy**, click **Create Deployment**, and choose the agent that should handle the webhook.
In the trigger selector, choose **Custom Webhook**.
Enter an **Endpoint Name**. This name identifies the webhook endpoint in Duckie.
Select how Duckie should verify incoming requests.
Paste a sample JSON payload, parse the fields, and map the payload into run fields, run messages, and optional metadata.
Save the deployment. Duckie shows the generated webhook URL after the endpoint is created.
## Webhook URL
After you save the deployment for the first time, Duckie shows a generated URL:
```text theme={null}
https://app.useduckie.ai/api/webhooks/custom/{endpointSlug}
```
Send JSON `POST` requests to this URL. Duckie reads the request body as JSON, so non-JSON payloads are rejected.
## Verification Methods
Choose a verification method before sending production traffic.
| Method | How it works |
| ------------------ | ----------------------------------------------------------------------------------------------------------------- |
| **HMAC Signature** | Duckie computes an HMAC over the raw request body with your signing secret and compares it to a signature header. |
| **Bearer Token** | Duckie checks that the configured header value exactly matches the token you entered. |
| **None** | Duckie skips request verification. Use only for local testing or trusted temporary traffic. |
For HMAC verification, configure the signature header and algorithm. Duckie supports the algorithms available in the selector, including SHA-256, SHA-1, and SHA-512.
For token verification, the default header is `X-Webhook-Token`. Send the token as the header value:
```bash theme={null}
curl -X POST "https://app.useduckie.ai/api/webhooks/custom/{endpointSlug}" \
-H "Content-Type: application/json" \
-H "X-Webhook-Token: YOUR_TOKEN" \
-d '{"id":"evt_123","ticket_id":"T-123","title":"Billing question","message":"Can you help me update my invoice?"}'
```
## Payload Mappings
Payload mappings tell Duckie how to turn your JSON payload into a run.
Most mapping fields accept either:
| Mapping type | Example |
| ------------ | ------------------------------------------ |
| **JSONPath** | `$.ticket.id` |
| **Template** | `Ticket {{ticket.id}}: {{ticket.subject}}` |
JSONPath reads a value from the payload. Templates combine literal text with dot-path placeholders from the payload.
### Parse a Sample Payload
Paste a sample JSON payload into **Sample JSON Payload** and click **Parse Fields**. Duckie discovers scalar fields, suggests common mappings such as IDs and messages, and makes discovered fields available in mapping dropdowns.
The parser accepts normal JSON, fenced JSON snippets, and common pasted object-literal formatting such as single quotes, unquoted keys, and trailing commas.
### Run Fields
Run fields are required fields written to the run.
| Field | Required | Description |
| --------------------- | -------- | --------------------------------------------------------------------------------- |
| **Event ID** | Yes | Unique ID for this webhook event. |
| **Ticket ID** | Yes | Stable ID for the customer issue, conversation, ticket, or object. |
| **Ticket Title** | Yes | Short title shown in run history. |
| **Ticket URL** | No | Link back to the source system. |
| **Source Message ID** | No | Source message ID used for tracking. If omitted, Duckie uses the mapped Event ID. |
Example mappings:
```json theme={null}
{
"event_id": "$.event.id",
"ticket_id": "$.ticket.id",
"ticket_title": "Ticket {{ticket.id}}: {{ticket.subject}}",
"ticket_url": "https://example.com/tickets/{{ticket.id}}",
"source_message_id": "$.message.id"
}
```
### Run Messages
Run messages provide the conversation content the agent should respond to.
Use **Single message** when each webhook payload contains one new message:
| Field | Required | Description |
| --------------------- | -------- | ------------------------------------------------------------------- |
| **Message Body** | Yes | The text the agent should process. |
| **Role** | No | Fixed role or a role mapped from the payload. Defaults to customer. |
| **User Name** | No | Name shown for the message author. Defaults to `Customer`. |
| **Source Message ID** | No | Message ID from the source system. |
| **Timestamp** | No | Message timestamp from the source system. |
Use **Conversation array** when the payload contains an array of messages or comments. Set **Array Path** to the array, then map message fields relative to each item in that array.
Example payload:
```json theme={null}
{
"event": { "id": "evt_123", "type": "ticket.created" },
"ticket": { "id": "T-123", "subject": "Billing question" },
"comments": [
{
"id": "c_1",
"body": "Can you help me update my invoice?",
"sender_type": "end_user",
"sender_name": "Alice",
"created_at": "2026-05-29T16:30:00Z"
},
{
"id": "c_2",
"body": "Sure, I can help.",
"sender_type": "admin",
"sender_name": "Support",
"created_at": "2026-05-29T16:31:00Z"
}
]
}
```
Example conversation array mappings:
| Field | Mapping |
| --------------------- | --------------- |
| **Array Path** | `$.comments` |
| **Message Body** | `$.body` |
| **Role** | `$.sender_type` |
| **User Name** | `$.sender_name` |
| **Source Message ID** | `$.id` |
| **Timestamp** | `$.created_at` |
When role is mapped from the payload, Duckie normalizes common values:
| Payload values | Duckie role |
| --------------------------------------------------- | ----------- |
| `customer`, `user`, `end_user`, `contact` | Customer |
| `agent`, `admin`, `support`, `teammate`, `operator` | Agent |
| `duckie`, `assistant`, `bot` | Duckie |
If the mapped role is missing or unrecognized, Duckie uses the fallback role selected in the deployment.
### Run Metadata
Run Metadata stores optional fields on the run for context. Use it for source-specific attributes such as account ID, priority, product area, locale, plan, or tags.
You can add fields manually, or click **Add Parsed Fields** after parsing a sample payload.
Do not send secrets, credentials, or unnecessary sensitive fields in webhook payloads. Duckie stores the raw payload and mapped metadata with the run.
## Event Filtering
Event filtering lets one webhook endpoint receive multiple event types while a deployment only processes the ones you allow.
| Field | Description |
| ----------------------- | ------------------------------------------------------------------------------------------ |
| **Event Type Path** | JSONPath to the field that identifies the event type, such as `$.event.type`. |
| **Allowed Event Types** | Comma-separated list of exact event type values, such as `ticket.created, ticket.updated`. |
If you leave the allowed event types blank, Duckie accepts all event types for that deployment.
## Request Outcomes
Duckie validates the request before it starts asynchronous processing.
| Outcome | Meaning |
| --------------------------- | ----------------------------------------------------------------- |
| `200` with `{ "ok": true }` | The request was accepted and processing continues asynchronously. |
| `400` | The request body was not valid JSON. |
| `401` | Request verification failed. |
| `404` | The webhook endpoint slug was not found. |
| `429` | The endpoint rate limit was exceeded. |
If filtering does not match, Duckie accepts the request but does not create a run for that deployment. If required mappings resolve to empty values, Duckie does not create a run for that deployment.
## Test Before Going Live
1. Create the deployment in **Testing** mode.
2. Send a representative sample payload to the webhook URL.
3. Open **Analyze > Runs** and review the created run.
4. Confirm the title, ticket ID, messages, role mapping, and metadata look correct.
5. Switch to **Live** mode after the mapping is validated.
## Troubleshooting
| Problem | What to check |
| -------------------------- | -------------------------------------------------------------------------------------------------------------- |
| No run appears | Confirm the deployment is active and the event type filter matches the payload. |
| Mapping failure | Check that required mappings resolve to non-empty values: Event ID, Ticket ID, Ticket Title, and Message Body. |
| Wrong message role | Check the role mapping and fallback role. |
| `401 Unauthorized` | Confirm the signature or token header name and secret match the deployment. |
| `400 Invalid JSON payload` | Send a JSON request body with `Content-Type: application/json`. |
## Next Steps
Set up a deployment
Test before live traffic
Review webhook-triggered runs
Let a customer-owned orchestration agent call Duckie with a webhook.
# Deployment Modes
Source: https://docs.duckie.ai/deployments/deployment-modes
Control how your agent interacts with customers
Deployment modes control whether an agent responds directly to customers or runs with testing safeguards.
## Available Modes
### Live Mode
The agent responds **directly to customers**.
| Aspect | Behavior |
| -------------- | ----------------------------- |
| **Responses** | Sent immediately to customers |
| **Actions** | Executed in real systems |
| **Visibility** | Customers see agent responses |
**Use when:**
* Agent has been validated in testing mode
* You're confident in response quality
* Ready for production traffic
### Testing Mode
The agent processes matching deployment events with testing safeguards.
| Aspect | Behavior |
| -------------- | --------------------------------------------------------- |
| **Responses** | Can be forced to internal notes instead of public replies |
| **Actions** | Write actions can be skipped during execution |
| **Visibility** | Runs are visible in Duckie run history |
**Use when:**
* Testing a new agent or deployment
* Validating on real traffic before going live
* Debugging a specific channel, trigger, or filter
* Checking behavior after major configuration changes
## Testing Options
When a deployment is in testing mode, you can enable additional safeguards.
### Internal Notes Only
Duckie response tools use internal notes instead of public responses.
Use this when you want the agent to process real messages without sending public customer replies.
### No Write Actions
Tools marked as write actions are skipped during execution.
Use this when you want to validate reasoning, retrieval, and response quality without modifying external systems.
## Choosing the Right Mode
### New Deployment
```
Playground Testing → Testing Mode → Live Mode
```
1. Test in the playground until confident
2. Deploy in testing mode
3. Review test runs and internal notes
4. Switch to live when quality is consistent
### Existing Deployment with Major Changes
```
Pause → Update → Testing → Validate → Live
```
1. Pause the deployment
2. Make configuration changes
3. Switch to testing mode
4. Validate the changes
5. Return to live
### Minor Change
For minor, low-risk changes:
* Update directly in live mode
* Monitor closely afterward
## Change Modes
Go to **Deploy** and click on your deployment.
Click **Edit** to modify settings.
Select **Live** or **Testing**.
Save to apply the change.
## Review Testing Runs
### In Run History
1. Go to **Analyze > Runs**
2. Filter by deployment
3. Review agent responses
4. Check execution steps and tool calls
### In the Source System
When **Internal Notes Only** is enabled, responses are written as internal notes on channels that support them.
### Quality Checks
When reviewing testing runs, ask:
* Is the response accurate?
* Is the tone appropriate?
* Did the agent find the right knowledge?
* Did guardrails work correctly?
* Would you send this to a customer?
## Go Live
Before switching from testing to live:
Review a representative sample of testing runs.
Verify escalation rate and response quality are acceptable.
Fix any problems found in review.
Change mode to **Live**.
Watch performance for the first few hours or days.
## Best Practices
### Start in Testing
New deployments and major changes should go through testing mode:
* Catches issues before public customer responses
* Builds confidence in the configuration
* Provides run data for validation
### Set Review Expectations
In testing mode:
* Decide how many runs to review before going live
* Set a timeline, such as testing for a few days
* Define quality criteria for switching to live
### Keep a Testing Deployment
Consider maintaining a testing deployment for ongoing validation:
* Test new configurations safely
* Catch regressions
* Compare behavior before updating a live deployment
## Next Steps
Set up a deployment
Review agent activity
# Deployments Overview
Source: https://docs.duckie.ai/deployments/overview
Connect agents to real customer channels
Deployments connect your agents to real customer channels, defining when and how agents respond to incoming messages.
## What is a Deployment?
A deployment is the connection between:
* **An agent** — What responds
* **A trigger** — When to respond
* **A mode** — How to respond
## Deployment Components
### Agent
The configured AI that handles conversations. Includes:
* Start mode and instructions
* Knowledge access
* Guidelines and guardrails
* Tool access
* Classification settings
### Trigger
What causes the agent to activate:
| Component | Examples |
| --------------------------- | --------------------------------------------------------------- |
| **Channel or trigger type** | Zendesk, Slack, Intercom, Discord, Custom Webhook, Scheduler |
| **Event or schedule** | New ticket, message received, comment added, recurring schedule |
| **Filters** | Specific channels, groups, tags |
### Mode
How the agent interacts with customers:
| Mode | Behavior |
| ----------- | -------------------------------------------------------------------------- |
| **Live** | Responds directly to customers |
| **Testing** | Runs with testing options such as internal notes only and no write actions |
### Status
* **Active** — Deployment is running
* **Paused** — Temporarily disabled
## Deployment Lifecycle
```
Create → Configure → Test → Activate → Monitor → Iterate
```
Define the agent and trigger
Set mode, filters, and options
Validate in playground or testing mode
Enable for real traffic
Watch performance metrics
Adjust based on results
## Multiple Deployments
You can create multiple deployments for flexibility:
### Same Agent, Different Channels
```
Support Agent → Zendesk tickets
Support Agent → Slack messages
Support Agent → Intercom conversations
```
### Different Agents, Same Channel
```
Billing Agent → Zendesk (billing group)
Technical Agent → Zendesk (technical group)
```
### Different Events
```
Support Agent → New tickets only
Triage Agent → All ticket updates
```
### Recurring Work
```
Support Agent → Weekday morning queue summary
SLA Agent → Hourly escalation check
```
## Deployment Cards
Each deployment card shows:
* **Agent name** — Which agent is deployed
* **Trigger** — Channel and events
* **Mode** — Live or Testing
* **Status** — Active or Paused
* **Metrics** — Recent activity
## Best Practices
### Start in Testing Mode
New deployments should start in testing mode:
1. Agent processes real messages
2. Responses can be saved as internal notes
3. You review before going live
4. Build confidence, then switch to live
### Monitor Closely Initially
After going live:
* Check run history frequently
* Watch for unexpected behavior
* Review escalation rates
* Gather customer feedback
### Use Filters Strategically
Start narrow and expand:
1. Deploy to one channel first
2. Expand to more channels when confident
3. Use tag filters to control scope
## Next Steps
Deploy your first agent
Understand live vs testing
Trigger agents from custom JSON events
Run agents on a recurring schedule
Configure when agents respond
# Scheduled Deployments
Source: https://docs.duckie.ai/deployments/scheduled-deployments
Run an agent on a recurring schedule
Scheduled deployments run an agent automatically on a recurring schedule. Use them for recurring work such as daily summaries, SLA checks, periodic account reviews, or scheduled follow-ups.
Unlike channel deployments, a scheduled deployment does not wait for an event from Zendesk, Slack, Intercom, or another integration. Duckie starts a run when the schedule fires.
## Create a Scheduled Deployment
Go to **Deploy**, click **Create Deployment**, and choose the agent that should run on a schedule.
In the trigger selector, choose **Scheduler**.
Choose a preset schedule or select **Custom...**.
Presets include hourly, daily at 9 AM, weekdays at 9 AM, and weekly on Monday at 9 AM.
For a custom schedule, describe the schedule in plain language and click **Convert**, or enter a five-field cron expression directly.
Select the timezone Duckie should use when evaluating the schedule.
Choose **Live** or **Testing**, save the deployment, and keep it **Active** when you want the schedule to run.
## Schedule Options
| Option | Use it when |
| -------------------------- | ------------------------------------------------------------------------------------------ |
| **Preset** | You want a common schedule such as hourly, daily, weekdays, or weekly. |
| **Describe your schedule** | You want Duckie to convert text such as `every weekday at 9am EST` into a cron expression. |
| **Cron expression** | You already know the exact five-field cron schedule you want. |
Custom cron expressions use the standard five-field format:
```text theme={null}
minute hour day-of-month month day-of-week
```
For example:
```text theme={null}
0 9 * * 1-5
```
This runs at 9:00 AM on weekdays in the selected timezone.
Scheduled deployments must run at least five minutes apart. Duckie rejects schedules that fire more frequently.
## Timezones
The selected timezone controls when the schedule runs. Duckie shows a preview of the next scheduled run times after you choose a schedule and timezone.
Use the timezone where the work should happen, not necessarily the timezone where you are configuring the deployment. For example, choose `America/New_York` for a weekday 9 AM East Coast check-in.
## Deployment Mode
Scheduled deployments use the same deployment modes as other deployments:
| Mode | Behavior |
| ----------- | ------------------------------------------------------------- |
| **Testing** | Runs with testing safeguards before you rely on the schedule. |
| **Live** | Runs the selected agent on each scheduled fire. |
Start new scheduled deployments in **Testing** mode, then switch to **Live** after you review the run output.
## Monitoring Scheduled Runs
Active scheduled deployments show the next run time on the deployment card. When you open an active scheduled deployment, Duckie also shows schedule timing details for that deployment.
Scheduled runs appear in **Analyze > Runs** with the source **Scheduler**. Use this view to confirm that the schedule fired, inspect the agent's output, and compare scheduled runs with other deployment traffic.
## Best Practices
* Give the agent clear instructions for what recurring work it should perform.
* Choose an interval that gives the agent enough time to finish the expected work.
* Use Testing mode before relying on a scheduled deployment.
* Keep schedules narrow and intentional; create separate scheduled deployments for unrelated recurring jobs.
## Next Steps
Set up a deployment
Test before live scheduled runs
Review scheduled run history
# Triggers and Events
Source: https://docs.duckie.ai/deployments/triggers-and-events
Configure when your agent responds
Triggers define when your agent is activated — which events from which channels cause the agent to run.
## What is a Trigger?
A trigger combines:
* **Integration** — The source platform (Zendesk, Slack, etc.)
* **Event** — The action that occurred (new ticket, message, etc.)
* **Filters** — Conditions that must be met
## Available Events by Integration
### Zendesk
| Event | Description | Common Use |
| ------------------ | ------------------------ | ----------------------- |
| **Ticket created** | New ticket submitted | Respond to new requests |
| **Comment added** | Public comment on ticket | Continue conversations |
| **Internal note** | Private note added | React to agent notes |
### Slack
| Event | Description | Common Use |
| ------------------- | -------------------- | ------------------------ |
| **Channel message** | Message in a channel | Monitor support channels |
| **Direct message** | DM to the bot | Private support |
| **App mention** | Bot is @mentioned | Explicit requests |
| **Thread reply** | Reply in a thread | Continue conversations |
### Intercom
| Event | Description | Common Use |
| ------------------------ | ------------------------ | ---------------------- |
| **Conversation created** | New conversation started | Respond to new chats |
| **Customer replied** | Customer sends message | Continue conversations |
| **Assigned to Duckie** | Routed to Duckie | Handle assigned work |
### Discord
| Event | Description | Common Use |
| ------------------- | ---------------------- | ----------------- |
| **Message created** | New message in channel | Community support |
| **Bot mentioned** | Bot is @mentioned | Explicit requests |
### HubSpot
| Event | Description | Common Use |
| ------------------------ | ---------------------- | ------------------ |
| **Conversation replied** | Customer sends message | Respond to tickets |
### Plain
| Event | Description | Common Use |
| -------------------- | -------------------- | ---------------------- |
| **Thread created** | New thread started | New support requests |
| **Thread replied** | Customer replies | Continue conversations |
| **Duckie mentioned** | @mentioned in thread | Explicit requests |
### Pylon
| Event | Description | Common Use |
| ----------------- | ------------------- | ---------------------- |
| **Issue created** | New issue submitted | New support requests |
| **Issue replied** | Customer replies | Continue conversations |
### Custom Webhook
Custom Webhook deployments accept JSON events from your own systems. You map payload fields into Duckie runs and can optionally filter by an event type field.
Configure a custom webhook trigger
### Scheduler
Scheduler deployments run on a recurring schedule instead of an integration event. Choose a preset schedule, describe a schedule in plain language, or enter a five-field cron expression.
Configure a recurring scheduled trigger
## Event Filters
Narrow which events trigger your agent:
### Channel Filters
Respond only in specific channels:
**Slack:**
```
#support
#customer-questions
#sales-inquiries
```
**Zendesk:**
```
Support group
VIP Support group
Enterprise group
```
### @Mention Only
Only respond when the bot is explicitly mentioned:
**When to use:**
* Shared channels where bot shouldn't respond to everything
* When you want customers to explicitly invoke the bot
* Preventing unwanted responses
### Tag Filters (Zendesk)
Respond only to tickets with specific tags:
```
Tags to include: ai-enabled, duckie-support
Tags to exclude: human-only, sensitive
```
### Group/Queue Filters
Respond only when assigned to specific groups:
```
Groups: Level 1 Support, General Inquiries
```
## Configuring Triggers
Choose the platform (Zendesk, Slack, etc.).
Only connected integrations appear as options.
Select which events should trigger the agent.
You can select multiple events for a single deployment.
Optionally narrow with channel, tag, or mention filters.
Save to activate the trigger configuration.
## Multiple Events
A single deployment can respond to multiple events:
**Example: Complete Zendesk Coverage**
```
Events:
- Ticket created ✓
- Comment added ✓
- Internal note (optional)
Filters:
- Group: Support Team
- Tags: ai-enabled
```
This agent responds to new tickets AND follow-up comments, but only in the Support Team group.
## Multiple Deployments
For complex needs, create separate deployments:
**Example: Different Agents for Different Events**
| Deployment | Agent | Events | Filters |
| ---------- | ------------- | -------------- | ------------- |
| Triage | Triage Agent | Ticket created | All |
| Support | Support Agent | Comment added | Support group |
| VIP | VIP Agent | All events | VIP group |
## Event Flow
```
External Event (new message/ticket)
│
▼
Webhook Received
│
▼
┌─────────────────────┐
│ Find Matching │
│ Deployments │
└─────────────────────┘
│
▼
┌─────────────────────┐
│ Check Filters │
│ (channel, tags, │
│ mention) │
└─────────────────────┘
│
▼
┌─────────────────────┐
│ Trigger Agent Run │
└─────────────────────┘
```
## Best Practices
### Start Narrow
Begin with specific filters, then expand:
1. One channel, @mention only
2. Add more channels
3. Remove @mention requirement
4. Add more events
### Use @Mention for Shared Spaces
In channels where not every message needs a response:
```
Slack #general → @mention only
Slack #support → All messages
```
### Prevent Loops
Ensure filters prevent the agent from responding to its own messages:
* Duckie automatically filters bot messages
* Don't respond to internal notes you created
* Check for bot user IDs in custom integrations
### Test Before Going Live
1. Configure trigger
2. Send test messages
3. Verify only intended messages trigger the agent
4. Adjust filters as needed
## Next Steps
Build a deployment with triggers
See available integrations
Run agents on a schedule
# Customer Follow-Up Loop
Source: https://docs.duckie.ai/examples/bug-intake-to-engineering/customer-follow-up-loop
Send engineering questions and resolutions back through the original customer conversation
The customer follow-up loop is what makes the bug intake system two-way. Duckie should continue the original conversation when engineering needs more information, when a workaround is available, or when the engineering issue is resolved.
## What It Does
The customer follow-up loop:
* Receives engineering questions from Slack or Linear/Jira comments
* Decides whether the question should go to the customer, support owner, or an internal lookup
* Rewrites technical questions into customer-friendly language
* Posts the question to the original support ticket or customer channel
* Waits for the customer's answer
* Summarizes the answer for engineering
* Updates the issue and Slack thread
* Detects issue completion and drafts the final customer update
* Records whether the customer conversation should stay open, pause, or close
## Recommended Components
| Need | Duckie component |
| --------------------------------- | ----------------------------------------- |
| Route questions back to customers | Customer follow-up workflow |
| Draft customer-safe language | Autonomous communication agent |
| Update original ticket | Ticketing or messaging app tools |
| Sync answers to engineering | Linear, Jira, and Slack tools |
| Detect issue completion | Issue update deployment or custom webhook |
| Final response gating | Workflow branch and optional human review |
## Question Loop
```mermaid theme={null}
flowchart TD
EngQuestion["Engineering question"]
EngQuestion --> Route["Question routing workflow"]
Route --> Draft["Customer-friendly question draft"]
Draft --> Review["Safety and clarity check"]
Review --> Ticket["Original customer ticket"]
Ticket --> CustomerAnswer["Customer answer"]
CustomerAnswer --> Summarize["Summarize answer for engineering"]
Summarize --> Issue["Update Linear or Jira issue"]
Summarize --> Slack["Update engineering Slack thread"]
Slack --> Continue["Continue engineering work"]
```
## Resolution Loop
```mermaid theme={null}
flowchart TD
IssueDone["Engineering issue completed"]
IssueDone --> UpdateDeployment["Issue update deployment"]
UpdateDeployment --> Resolution["Resolution workflow"]
Resolution --> Outcome["Determine customer-facing outcome"]
Outcome --> Draft["Draft customer update"]
Draft --> Approval["Optional support approval"]
Approval --> Ticket["Original customer ticket"]
Ticket --> Close["Close or continue conversation"]
Close --> Runs["Runs and analytics"]
```
## Customer-Facing Outcomes
| Outcome | Customer follow-up |
| ------------------------------- | ------------------------------------------------------------------------------------------------- |
| **Fix shipped** | Explain the fix, when it shipped, and any action the customer needs to take. |
| **Workaround available** | Share the workaround and keep the engineering issue linked internally. |
| **Duplicate of known issue** | Acknowledge the report and explain that the team is tracking it under an existing issue. |
| **Cannot reproduce** | Ask for the smallest missing detail, or explain what was tested if no further action is possible. |
| **Not planned** | Route to human review before sending a customer-facing response. |
| **Needs customer confirmation** | Ask the customer to confirm whether the issue is resolved on their side. |
## Response Guidelines
Customer updates should:
* Use the original support ticket or customer channel
* Avoid exposing internal issue tracker details that customers should not see
* Explain the state in plain language
* Include any workaround or requested next step
* Avoid promising ship dates unless approved
* Link internally to the engineering issue and Duckie run
* Preserve the support team's tone and escalation policy
Do not automatically tell customers that a bug is fixed just because an engineering issue moved to Done. Use the resolution workflow to check release status, workaround status, and support approval rules.
## Related Docs
Connect the original customer conversation.
Control customer-facing tone and response rules.
Gate sensitive customer communication.
Test customer follow-up before going live.
# Engineering Collaboration
Source: https://docs.duckie.ai/examples/bug-intake-to-engineering/engineering-collaboration
Route engineering questions through Slack and keep support in the loop
Engineering collaboration is handled by an autonomous internal agent deployed to Slack or another team channel. It posts concise summaries, captures engineer questions, and sends structured requests back to the originating workflow.
Use a Duckie Assistant agent for reporting, run review, and improving Duckie behavior. Do not use a Duckie Assistant agent as the real-time engineering collaboration agent.
## What It Does
The engineering collaboration function:
* Posts new bug summaries to an engineering triage channel
* Links the support ticket, engineering issue, and Duckie run
* Captures engineer questions from Slack replies or issue comments
* Converts engineering questions into structured requests
* Routes customer-facing questions back to the original support ticket
* Routes internal-only questions to the support owner or triage reviewer
* Syncs answers back to Slack and the Linear or Jira issue
* Records the collaboration trail for reporting
## Recommended Components
| Need | Duckie component |
| ------------------------------- | ---------------------------------------------- |
| Internal engineering discussion | Autonomous internal Slack agent |
| Issue tracker updates | Linear or Jira app tools |
| Question routing | Deterministic question routing workflow |
| Customer-safe wording | Customer follow-up agent called by workflow |
| Audit trail | Runs, issue comments, and support ticket notes |
## Flow
```mermaid theme={null}
flowchart TD
Issue["Linear or Jira issue"]
Issue --> SlackAgent["Engineering Slack agent"]
SlackAgent --> Channel["Engineering triage channel"]
Channel --> EngineerQuestion["Engineer asks question"]
EngineerQuestion --> Parse["Parse question and needed audience"]
Parse --> Internal["Ask support owner internally"]
Parse --> Customer["Route to customer follow-up workflow"]
Internal --> Answer["Structured answer"]
Customer --> Answer
Answer --> Issue
Answer --> Channel
```
## Question Types
| Question type | Route |
| --------------------------------- | ---------------------------------------------------------------- |
| **Customer can answer** | Original support ticket through the customer follow-up workflow. |
| **Support owner can answer** | Internal support Slack channel or ticket internal note. |
| **Requires logs or product data** | Product/log lookup workflow or support operations owner. |
| **Already answered in ticket** | Sync answer back to issue and Slack with source link. |
| **Sensitive or policy-related** | Manual support or engineering review before customer contact. |
## Slack Message Shape
Engineering summaries should be short and answerable.
```text theme={null}
New customer-reported bug
Issue: ENG-123
Support ticket: ticket_123
Product area: Dashboard
Impact: Priority customer cannot view project metrics
Repro status: Steps present, console logs missing
Suggested next action:
Review repro steps. If logs are required, reply with the exact question to send the customer.
```
## Structured Question Contract
```json theme={null}
{
"question_id": "q_123",
"engineering_issue_id": "ENG-123",
"support_ticket_id": "ticket_123",
"audience": "customer | support_owner | internal_data_lookup",
"question": "Can the customer share the browser console error after the dashboard goes blank?",
"why_needed": "Engineering needs the client-side error to identify the failing component.",
"sensitive": false
}
```
The Slack agent should keep engineering fast, but the workflow should decide where a question goes. That keeps customer contact, internal notes, and issue comments consistent.
## Related Docs
Connect Duckie to engineering channels.
Configure the internal engineering collaboration agent.
Define when engineering questions need human review.
Inspect the collaboration trail.
# Engineering Issue Workflow
Source: https://docs.duckie.ai/examples/bug-intake-to-engineering/engineering-issue-workflow
Create and sync Linear or Jira issues from support bug reports
The engineering issue workflow turns a repro-ready intake case into a Linear or Jira issue. It should be deterministic because issue fields, labels, links, and sync behavior need to stay consistent.
## What It Does
The engineering issue workflow:
* Receives a repro-ready bug intake record
* Checks for duplicate or related engineering issues
* Drafts a concise engineering issue description
* Sets team, project, labels, priority, severity, and customer impact fields
* Links the issue to the original support ticket and Duckie run
* Posts a summary to an engineering Slack channel when review is needed
* Syncs issue comments, questions, status changes, and resolution back to the workflow
## Recommended Components
| Need | Duckie component |
| ----------------------- | ---------------------------------------------------------- |
| Create or update issues | Linear or Jira app tools |
| Enforce field values | Engineering issue workflow |
| Draft issue content | Bug intake agent called by workflow |
| Detect duplicates | Issue tracker search tool and deterministic matching rules |
| Notify engineering | Slack engineering agent |
| Sync issue updates | Issue tracker deployment or custom webhook |
## Flow
```mermaid theme={null}
flowchart TD
Intake["Repro-ready bug intake case"]
Intake --> Duplicate["Duplicate issue check"]
Duplicate --> Existing["Link to existing issue"]
Duplicate --> Draft["Draft issue description"]
Draft --> Validate["Validate required issue fields"]
Validate --> Create["Create Linear or Jira issue"]
Existing --> Link["Update support ticket with issue link"]
Create --> Link
Create --> Slack["Post engineering summary to Slack"]
Slack --> Review["Engineering triage review"]
Review --> Sync["Record issue and thread links"]
```
## Issue Content
The created issue should include:
* Short title with product area and observed failure
* Customer impact and severity
* Affected customer or account link when allowed
* Reproduction steps
* Expected behavior
* Actual behavior
* Environment details
* Logs, screenshots, recordings, or trace links
* Known incident or duplicate references
* Original support ticket link
* Duckie run link
* Support owner or follow-up owner
## Suggested Issue Contract
```json theme={null}
{
"title": "[Dashboard] Blank state after login for priority customer",
"description": "Customer can log in, but the dashboard loads as a blank page.",
"product_area": "dashboard",
"severity": "high",
"priority": "urgent",
"labels": ["customer_reported", "dashboard"],
"team": "web app",
"customer_impact": "Priority customer cannot view project metrics.",
"steps_to_reproduce": ["log in as affected user", "open dashboard"],
"expected_behavior": "dashboard loads project metrics",
"actual_behavior": "dashboard is blank",
"support_ticket_url": "https://helpdesk.example/tickets/123",
"duckie_run_url": "https://duckie.example/runs/run_123"
}
```
## Sync Fields
Store the relationship between systems in workflow state or a durable record.
| Field | Purpose |
| ------------------------------ | ------------------------------------------------------------------------------ |
| `support_ticket_id` | Routes customer updates back to the original conversation. |
| `engineering_issue_id` | Updates the correct Linear or Jira issue. |
| `engineering_issue_url` | Links support and stakeholder updates. |
| `engineering_slack_thread_url` | Keeps engineering discussion tied to the issue. |
| `customer_follow_up_status` | Tracks whether Duckie is waiting on the customer. |
| `engineering_question_status` | Tracks whether engineering is waiting on support or customer input. |
| `resolution_status` | Tracks whether the fix is shipped, workaround-only, duplicate, or not planned. |
Do not let the issue workflow invent severity, priority, or customer commitments outside the team's rules. Let agents recommend values, then let the workflow enforce allowed fields and approval gates.
## Related Docs
Connect Duckie to Linear issues.
Connect Duckie to Jira issues.
Build deterministic issue creation and sync logic.
Trigger sync from issue tracker events.
# Intake and Repro Gathering
Source: https://docs.duckie.ai/examples/bug-intake-to-engineering/intake-and-repro-gathering
Turn messy customer bug reports into structured repro-ready cases
Bug reports usually arrive incomplete. The intake layer should preserve the original customer language, add context, and run a repeatable repro checklist before creating engineering work.
## What It Does
The intake and repro-gathering function:
* Receives customer reports from support tickets, chat, email, or webhook events
* Normalizes the customer report into a structured bug intake record
* Links the bug intake record to the original support conversation
* Fetches account, product, environment, version, incident, and recent activity context
* Checks for reproduction steps, expected behavior, actual behavior, impact, logs, screenshots, and affected objects
* Detects likely duplicates or known incidents
* Asks customer follow-up questions when required information is missing
* Passes repro-ready cases to the engineering issue workflow
## Recommended Components
| Need | Duckie component |
| ---------------------------------- | --------------------------------------------------- |
| Receive customer reports | Ticketing, messaging, email, or webhook deployment |
| Normalize and link records | Bug intake workflow |
| Fetch customer and product context | App tool, custom tool, or MCP tool |
| Interpret messy descriptions | Autonomous bug intake agent |
| Ask missing-context questions | Customer follow-up workflow or support ticket agent |
| Track repro completeness | Categories and attributes |
## Flow
```mermaid theme={null}
flowchart TD
Trigger["Customer support report"]
Trigger --> Intake["Bug intake deployment"]
Intake --> Normalize["Normalize report workflow"]
Normalize --> Link["Link to original support ticket"]
Link --> Context["Fetch customer and product context"]
Context --> Checklist["Run repro checklist"]
Checklist --> Ready["Repro readiness check"]
Ready --> Question["Draft customer follow-up question"]
Question --> Ticket["Post to original support ticket"]
Ticket --> Answer["Customer answer"]
Answer --> Checklist
Ready --> Draft["Draft engineering-ready report"]
```
## Repro Checklist
Start with a checklist that engineering actually uses.
| Field | Why it matters |
| --------------------------------- | --------------------------------------------------------------------------- |
| **Customer impact** | Helps engineering prioritize severity and urgency. |
| **Affected account or workspace** | Lets the team inspect the right record. |
| **Product area** | Routes the issue to the right owning team. |
| **Environment** | Captures browser, device, app version, region, integration, or API version. |
| **Steps to reproduce** | Turns a complaint into an actionable bug. |
| **Expected behavior** | Clarifies what the customer thought should happen. |
| **Actual behavior** | States the failure in observable terms. |
| **Frequency** | Distinguishes one-time confusion from reproducible defects. |
| **Logs or errors** | Gives engineering debugging material. |
| **Screenshot or recording** | Helps verify the state quickly. |
| **Known incident match** | Prevents duplicate escalation for active incidents. |
| **Duplicate issue match** | Links the customer to existing engineering work when possible. |
## Customer Follow-Up Questions
Ask only for information that changes engineering action.
Good follow-up questions are:
* Specific
* Short
* Written in customer-friendly language
* Tied to one missing field
* Sent in the original conversation
* Stored as part of the bug intake state
Example:
```text theme={null}
Thanks for reporting this. Could you send the exact steps you took right before the dashboard went blank, plus the browser and device you were using? That will help our engineering team reproduce it.
```
## Suggested Intake Contract
```json theme={null}
{
"support_ticket_id": "ticket_123",
"customer": {
"account_id": "acct_123",
"segment": "business",
"support_tier": "priority"
},
"bug_report": {
"product_area": "dashboard",
"impact": "cannot view project data",
"expected_behavior": "dashboard loads project metrics",
"actual_behavior": "dashboard is blank after login",
"steps_to_reproduce": ["log in", "open dashboard"],
"environment": {
"browser": "Chrome",
"device": "desktop"
},
"logs": [],
"screenshots": [],
"missing_fields": ["console logs"]
},
"links": {
"original_ticket_url": "https://helpdesk.example/tickets/123",
"known_incident_url": null,
"duplicate_issue_url": null
}
}
```
## What to Track
Track categories and attributes from the start:
* Product area
* Severity
* Customer segment
* Support tier
* Repro completeness
* Missing field type
* Duplicate issue match
* Known incident match
* Follow-up question status
* Time waiting on customer
## Related Docs
Create the customer-side intake deployment.
Use connected tools to read support, CRM, and product context.
Add internal lookups for logs, product events, or account data.
Track severity, completeness, and waiting states.
# MVP
Source: https://docs.duckie.ai/examples/bug-intake-to-engineering/mvp
The smallest useful bug intake system before full two-way support and engineering sync
Start with a narrow bug intake loop. Duckie should turn a messy customer report into a reproducible engineering issue, preserve the link back to the original support ticket, and ask for missing information only when the repro checklist is not ready.
This proves the system without starting with customer-facing automation, Slack question routing, resolution follow-up, and reporting all at once.
The MVP is the same architecture with fewer moving parts: one intake record, one repro checklist, one engineering issue, and one record map that links the support ticket, Duckie run, and engineering issue.
## MVP Goal
By the end of the MVP, Duckie should reliably answer:
* What did the customer report?
* What customer, account, product, and environment context is available?
* Is the bug reproducible enough for engineering?
* What single missing detail blocks the handoff?
* What engineering issue should Duckie create or update?
* Which support ticket, Duckie run, and engineering issue belong together?
## Minimal Flow
```mermaid theme={null}
flowchart TD
Customer["Customer bug report"]
Customer --> Intake["Bug intake deployment"]
Intake --> Normalize["Normalize report and link original ticket"]
Normalize --> Context["Fetch customer and product context"]
Context --> Checklist["Run repro checklist"]
Checklist --> Ready{"Ready for engineering?"}
Ready -->|No| Question["Draft one missing-info question"]
Question --> Ticket["Original support ticket"]
Ticket --> Checklist
Ready -->|Yes| Draft["Prepare engineering issue"]
Draft --> Issue["Create or update Linear/Jira issue"]
Issue --> RecordMap["Store support ticket, Duckie run, and issue links"]
```
## Build First
| Piece | What to build | Done when |
| ----------------- | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| Intake deployment | Trigger from support ticket, chat, email, or webhook. | Duckie receives new bug reports and stores the original ticket link. |
| Repro checklist | Check impact, product area, environment, steps, expected behavior, actual behavior, logs, and screenshots. | Each report gets a clear `ready`, `missing_info`, or `duplicate_or_known_issue` status. |
| Context lookup | Read customer, account, product usage, version, incident, and recent activity context. | Issue drafts include context without asking the customer for information the team can look up. |
| Bug intake agent | Interpret the messy report and draft repro steps or missing-info questions. | Repro-ready reports consistently produce useful issue content. |
| Issue creation | Create or update Linear or Jira issues for repro-ready reports. | Issues use consistent fields, labels, links, and ownership. |
| Record map | Store cross-system IDs in workflow state or a durable record. | The team can trace every issue back to the original ticket and Duckie run. |
## Defer Until the MVP Works
Do not start with every bridge automated. Add these after the first loop is trusted:
* Autonomous Slack engineering collaboration
* Engineering question routing back to customers
* Customer answer sync into Slack and Linear/Jira
* Automatic resolution follow-up
* Daily reporting and feedback agents
* Automatic high-severity issue creation
The first live win is not full automation. It is reliable context gathering, better issue drafts, and a record map that prevents support and engineering from losing the thread.
## When to Expand
Move beyond the MVP when:
* Missing-info questions are specific and useful
* Duplicate and known-incident checks are not creating noisy matches
* Severity, product area, and ownership recommendations are consistently correct
* Record links survive ticket updates, issue comments, and status changes
* The main remaining delays are handoffs that a two-way sync loop can remove
## Next Pages
After the MVP:
1. Read the [system map](/examples/bug-intake-to-engineering/system-map) to see the full architecture.
2. Build [intake and repro gathering](/examples/bug-intake-to-engineering/intake-and-repro-gathering).
3. Add the [engineering issue workflow](/examples/bug-intake-to-engineering/engineering-issue-workflow).
4. Use the [rollout plan](/examples/bug-intake-to-engineering/rollout-plan) before enabling live write paths.
# Overview
Source: https://docs.duckie.ai/examples/bug-intake-to-engineering/overview
A blueprint for turning customer bug reports into engineering-ready issues
This blueprint shows how to design a Duckie system that converts messy customer bug reports into reproducible engineering tickets, keeps engineering and support in sync, and routes engineering questions or fixes back to the original customer conversation.
The recommended design uses a deterministic workflow backbone for state, handoffs, and sync logic. Autonomous agents handle messy report interpretation, repro drafting, customer follow-up, and engineering summaries.
## Start With the MVP
You do not need to launch the full two-way system at once. Start with a narrow loop that gathers context, checks repro completeness, creates or updates an engineering issue, and stores the record map between the support ticket, Duckie run, and Linear or Jira issue.
Then add Slack collaboration, customer answer sync, resolution follow-up, reporting, and feedback after the first loop is trusted.
Use the [MVP](/examples/bug-intake-to-engineering/mvp) as the starting point if you are building this blueprint for the first time.
## What This System Does
The system helps a support team:
* Receive bug reports from support tickets, chat, email, or a custom webhook
* Gather customer context, environment details, logs, screenshots, and reproduction steps
* Ask the customer follow-up questions when the report is incomplete
* Draft a concise engineering-ready bug report
* Create or update a Linear or Jira issue
* Post engineering triage summaries and questions to Slack
* Route engineering questions back to the original support ticket
* Send the customer's answer back to the engineering issue or Slack thread
* Detect when the engineering ticket is resolved
* Draft and send a customer follow-up through the original conversation
* Report on bug intake volume, blocked issues, and feedback loops
This blueprint is two-way by design. Duckie should not just create engineering tickets. It should preserve a bridge between the customer conversation, the engineering issue, and the internal Slack thread until the loop is closed.
## Design at a Glance
| Function | Duckie component | Why |
| -------------------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| Bug intake | Ticketing, chat, email, or webhook deployment | Customer reports can start from multiple support channels. |
| Repro gathering | Deterministic repro-gathering workflow | The system needs a repeatable checklist before engineering handoff. |
| Report interpretation | Autonomous bug intake agent called by workflow | Customer descriptions are often vague, emotional, or missing technical detail. |
| Customer follow-up | Support ticket agent or workflow-called communication agent | Missing details should be requested in the original customer conversation. |
| Engineering issue creation | Linear or Jira issue workflow | Issue creation needs consistent fields, labels, links, and ownership. |
| Engineering collaboration | Internal Slack engineering agent | Engineers need a lightweight way to ask questions and review summaries. |
| Resolution follow-up | Issue update deployment and customer follow-up workflow | Resolved engineering work should route back to the originating ticket. |
| Daily reporting | Scheduler deployment running a Duckie Assistant reporting agent | Stakeholders need visibility into bug intake volume and blocked issues. |
| Feedback loop | Duckie Assistant feedback agent and analytics | Corrections should improve repro checklists, issue templates, and routing rules. |
## Blueprint Pages
Start with the smallest useful bug intake loop before adding two-way sync.
See the two-way support-to-engineering architecture.
Collect context, logs, steps, screenshots, and expected behavior.
Create and update Linear or Jira issues from customer reports.
Route engineering questions through Slack and back to support.
Continue the original customer conversation when engineers ask questions or complete fixes.
Report on bug intake health and improve the workflow over time.
Move from narrow bug intake to live two-way support and engineering sync.
## Recommended Reading Order
1. Start with the [MVP](/examples/bug-intake-to-engineering/mvp) to understand the smallest useful version.
2. Read the [system map](/examples/bug-intake-to-engineering/system-map) to see how the MVP expands into the full two-way architecture.
3. Read [intake and repro gathering](/examples/bug-intake-to-engineering/intake-and-repro-gathering) to understand the customer-side entry point.
4. Read the [engineering issue workflow](/examples/bug-intake-to-engineering/engineering-issue-workflow) to see how tickets are created and synced.
5. Read [engineering collaboration](/examples/bug-intake-to-engineering/engineering-collaboration) and [customer follow-up loop](/examples/bug-intake-to-engineering/customer-follow-up-loop) together when you are ready for the two-way bridge.
6. Add [reporting and feedback](/examples/bug-intake-to-engineering/reporting-and-feedback) before live deployment.
7. Follow the [rollout plan](/examples/bug-intake-to-engineering/rollout-plan) to expand safely.
## Related Docs
Learn the general workflow-plus-agent design pattern.
Connect Duckie to Linear issues.
Connect Duckie to Jira issues.
Connect internal engineering channels.
# Reporting and Feedback
Source: https://docs.duckie.ai/examples/bug-intake-to-engineering/reporting-and-feedback
Report on bug intake health and improve the support-to-engineering loop
Use Duckie Assistant agents for reporting and feedback. The reporting agent posts operational summaries. The feedback agent reviews runs, corrections, blocked issues, and outcome data to recommend improvements to Duckie configuration.
## What It Does
The reporting and feedback function:
* Posts a daily or weekly bug intake report to support and engineering stakeholders
* Tracks new bug reports, issue creation, duplicate rate, blocked issues, resolution outcomes, and customer follow-up status
* Highlights engineering questions waiting on customers or support
* Reviews rejected, rerouted, duplicate, or incomplete engineering issues
* Identifies weak repro checklists, missing context tools, bad issue templates, and routing problems
* Proposes updates to workflows, agents, guidelines, tools, categories, and reports
## Recommended Components
| Need | Duckie component |
| ------------------- | -------------------------------- |
| Recurring report | Scheduler deployment |
| Reporting logic | Duckie Assistant reporting agent |
| Inspect Duckie runs | Duckie Assistant MCP or Runs API |
| Read issue outcomes | Linear or Jira app tools |
| Destination | Slack app tools |
| Feedback review | Duckie Assistant feedback agent |
## Reporting Flow
```mermaid theme={null}
flowchart TD
Scheduler["Scheduler deployment"]
Scheduler --> Reporter["Duckie Assistant reporting agent"]
Runs["Runs and analytics"] --> Reporter
Issues["Linear or Jira issues"] --> Reporter
Tickets["Support tickets"] --> Reporter
Reporter --> Digest["Support and engineering digest"]
Digest --> Stakeholders["Stakeholder Slack channel"]
```
## Feedback Flow
```mermaid theme={null}
flowchart TD
Runs["Runs and tool traces"]
Issues["Issue outcomes"]
Corrections["Engineer and support corrections"]
CustomerReplies["Customer follow-up results"]
Runs --> Feedback["Duckie Assistant feedback agent"]
Issues --> Feedback
Corrections --> Feedback
CustomerReplies --> Feedback
Feedback --> Patterns["Recurring patterns and gaps"]
Patterns --> Improvements["Checklist, workflow, agent, tool, and template updates"]
Improvements --> Testing["Replay and batch testing"]
Testing --> Deploy["Updated bug intake deployments"]
```
## Report Contents
Include:
* New customer-reported bugs
* Bug reports converted to Linear or Jira issues
* Reports linked to duplicate or existing issues
* Reports blocked on missing customer information
* Engineering questions waiting on support or customer response
* Issues resolved, shipped, closed as duplicate, not planned, or cannot reproduce
* Customer follow-ups sent and waiting
* Average time from report to engineering issue
* Average time waiting on customer
* Top product areas and severity bands
* Tool failures and sync failures
* Recommended improvements
## Example Digest Shape
```text theme={null}
Bug intake summary
Window: Previous business day
Volume:
- New customer-reported bugs: 27
- Engineering issues created: 11
- Linked to existing issues: 6
- Waiting on customer details: 5
Engineering loop:
- 8 engineering questions routed back to support
- 5 customer answers synced to issues
- 3 issues resolved and ready for customer follow-up
Risk:
- 2 priority customers waiting on engineering questions
- 1 high-severity report missing logs
Automation health:
- 89% repro checklist completion before issue creation
- 2 issue sync retries
- 4 engineer edits to issue template fields
Follow-ups:
- Add API version lookup for integration bug reports
- Split dashboard bugs into loading, permissions, and data freshness categories
```
## Improvement Actions
Common improvements include:
* Add a missing repro checklist field
* Change the issue template
* Add an internal log or product event lookup tool
* Add duplicate detection against issue titles and labels
* Tighten the customer follow-up prompt
* Add a human review gate for sensitive bug categories
* Add a routing rule for a product area or engineering team
* Update the stakeholder report to show blocked customer loops
Measure the full loop, not only issue creation. A useful bug intake system should improve time to usable repro, time to engineering answer, and time to customer follow-up.
## Related Docs
Run reports on a recurring schedule.
Build reporting and feedback agents for Duckie system improvement.
Monitor performance and trends.
Test changes against historical bug reports.
# Rollout Plan
Source: https://docs.duckie.ai/examples/bug-intake-to-engineering/rollout-plan
Move bug intake from assisted drafting to live two-way support and engineering sync
Bug intake touches customer communication, engineering issue trackers, and internal escalation channels. Roll it out in stages so support and engineering trust the loop before Duckie writes across systems automatically.
## Rollout Stages
Align support and engineering on required repro fields, issue template fields, severity values, labels, owner rules, and customer follow-up expectations.
Enable read access to ticketing, CRM, product usage, logs, incident status, and issue tracker search. Keep write actions disabled at first.
Have Duckie summarize historical and live bug reports, score repro completeness, and suggest missing follow-up questions without posting to customers.
Let Duckie draft Linear or Jira issue content for human review. Compare against issues engineers would have written.
Allow Duckie to create issues only after support or engineering approval. Store links between the support ticket, issue, Slack thread, and Duckie run.
Post summaries to an internal engineering triage channel. Route engineer questions through the question routing workflow instead of ad hoc support pings.
Draft customer questions and resolution messages in the original support ticket, but require human approval before sending.
Automatically sync customer answers and resolved issue updates for approved product areas, severities, and support queues.
Schedule a Duckie Assistant reporting agent and a Duckie Assistant feedback agent to keep the loop visible and improving.
## Testing Plan
Use historical tickets and known bugs:
* Replay complete and incomplete bug reports
* Include duplicates, known incidents, cannot-reproduce reports, and high-priority customers
* Compare Duckie issue drafts against human-created issues
* Verify that issue fields use only allowed values
* Test engineering questions routed to support owner, customer, and internal lookup paths
* Confirm customer replies sync back to the correct issue and Slack thread
* Confirm issue completion routes to the original support ticket
* Run batch tests after issue template, routing, or follow-up prompt changes
## Success Metrics
Track:
* Percent of customer bug reports converted to engineering-ready issues
* Repro completeness before issue creation
* Duplicate issue detection rate
* Engineering rejection or reroute rate
* Time from customer report to engineering issue
* Time waiting on customer details
* Engineering questions answered
* Resolved issues followed up with customers
* Sync failures across ticket, issue, and Slack records
* Support and engineering satisfaction with summaries
## Launch Guardrails
Start conservatively:
* Require human approval before sending customer-facing messages
* Require human approval before creating high-severity engineering issues
* Use allowlists for issue teams, projects, labels, priorities, and statuses
* Keep not-planned and cannot-reproduce responses behind review
* Store all cross-system IDs before enabling two-way sync
* Post daily reports during rollout
* Review issue template edits and engineer corrections weekly
The first live win is usually not full automation. It is reliable context gathering, better issue drafts, and a record map that lets support and engineering stop losing the thread.
## Related Docs
Move from Testing to Live when each part of the loop is ready.
Evaluate changes across historical bug reports.
Gate sensitive customer and engineering actions.
Notify the team when sync failures or blocked loops appear.
# System Map
Source: https://docs.duckie.ai/examples/bug-intake-to-engineering/system-map
The two-way support-to-engineering architecture for bug intake
This system keeps three records connected: the original customer ticket, the engineering issue, and the internal engineering discussion. Workflows own state and synchronization. Agents handle interpretation, communication, and summaries.
## Two-Way Operational Flow
```mermaid theme={null}
flowchart TD
Customer["Customer bug report"]
Customer --> Intake["Support ticket deployment"]
Intake --> Normalize["Bug intake workflow"]
Normalize --> Context["Customer and product context workflow"]
Context --> Repro["Repro gathering workflow"]
Repro --> Readiness["Repro readiness check"]
Readiness --> FollowUp["Customer follow-up workflow"]
FollowUp --> OriginalTicket["Original support ticket"]
OriginalTicket --> CustomerAnswer["Customer answer"]
CustomerAnswer --> Repro
Readiness --> BugAgent["Bug intake agent"]
BugAgent --> Draft["Engineering-ready report draft"]
Draft --> IssueWorkflow["Engineering issue workflow"]
IssueWorkflow --> Issue["Linear or Jira issue"]
IssueWorkflow --> SlackAgent["Engineering Slack agent"]
SlackAgent --> EngChannel["Engineering triage channel"]
EngChannel --> Question["Engineering question"]
Question --> SlackAgent
SlackAgent --> QuestionWorkflow["Question routing workflow"]
QuestionWorkflow --> OriginalTicket
CustomerAnswer --> AnswerWorkflow["Answer sync workflow"]
AnswerWorkflow --> Issue
AnswerWorkflow --> EngChannel
Issue --> IssueUpdate["Issue update deployment"]
IssueUpdate --> Resolution["Resolution workflow"]
Resolution --> ResolutionDraft["Customer resolution draft"]
ResolutionDraft --> OriginalTicket
OriginalTicket --> Runs["Runs and analytics"]
```
## Reporting and Improvement Loop
```mermaid theme={null}
flowchart TD
Runs["Runs and analytics"]
Issues["Linear or Jira issue outcomes"]
Support["Support ticket outcomes"]
Runs --> Scheduler["Scheduler deployment"]
Issues --> Reporting["Duckie Assistant reporting agent"]
Support --> Reporting
Scheduler --> Reporting
Reporting --> Stakeholders["Support and engineering stakeholders channel"]
Runs --> Feedback["Duckie Assistant feedback agent"]
Issues --> Feedback
Support --> Feedback
Feedback --> Proposals["Improvement proposals"]
Proposals --> Review["Support operations and engineering review"]
Review --> Updates["Repro checklist, issue template, routing rules, and tools"]
Updates --> Testing["Replay and batch testing"]
Testing --> Deploy["Updated deployments"]
```
## Component Responsibilities
| Component | Responsibility |
| ----------------------------------------- | -------------------------------------------------------------------------------------------------- |
| **Support ticket deployment** | Starts the system from a customer support ticket, chat, email, or webhook. |
| **Bug intake workflow** | Normalizes the report, links records, and owns intake state. |
| **Customer and product context workflow** | Fetches account, environment, plan, product usage, incident, and version context. |
| **Repro gathering workflow** | Checks for steps, expected behavior, actual behavior, logs, screenshots, environment, and impact. |
| **Bug intake agent** | Interprets the messy customer report and drafts an engineering-ready summary. |
| **Engineering issue workflow** | Creates or updates Linear or Jira issues with consistent fields and links. |
| **Engineering Slack agent** | Posts summaries and questions to an internal engineering channel and returns structured decisions. |
| **Question routing workflow** | Sends engineering questions back to the original customer conversation. |
| **Answer sync workflow** | Sends customer answers back to the Linear or Jira issue and Slack thread. |
| **Resolution workflow** | Detects issue completion and routes the final customer update through support. |
| **Duckie Assistant reporting agent** | Posts scheduled summaries about bug intake volume, blockers, and resolutions. |
| **Duckie Assistant feedback agent** | Reviews runs and corrections to improve Duckie configuration. |
## Deterministic vs Autonomous
Use deterministic workflows for:
* Record linking between support ticket, issue, and Slack thread
* Required repro checklist checks
* Duplicate detection rules
* Allowed issue field values
* Linear or Jira issue creation and update
* Customer question routing
* Customer answer sync
* Issue status handling
* Final customer follow-up gating
Use autonomous agents for:
* Interpreting unclear customer reports
* Summarizing technical context
* Drafting reproduction steps
* Drafting engineering issue descriptions
* Translating engineering questions into customer-friendly language
* Drafting resolution messages
* Summarizing blocked issues and trends
The critical design choice is the record map. Store the support ticket ID, engineering issue ID, Slack thread link, customer follow-up status, and current owner in workflow state so every update can route back to the right place.
## Deployment Inventory
| Deployment | Trigger | Target | Mode to start |
| ----------------------------------- | ------------------------------------------------------------------- | ---------------------------------- | ------------- |
| **Bug intake** | Ticket created, message received, email received, or custom webhook | Bug intake workflow | Testing |
| **Engineering issue sync** | Linear or Jira issue created, updated, completed, or commented | Resolution or answer sync workflow | Testing |
| **Engineering Slack collaboration** | Internal Slack channel or workflow escalation request | Engineering Slack agent | Testing |
| **Daily bug intake report** | Scheduler, such as weekdays at 9 AM | Duckie Assistant reporting agent | Testing |
| **Bug intake feedback review** | Scheduler or manual internal request | Duckie Assistant feedback agent | Testing |
## Related Docs
Trigger Duckie from issue tracker or internal events.
Connect Duckie to Linear.
Connect Duckie to Jira.
Inspect linked support, engineering, and Slack activity.
# Designing Agent Systems
Source: https://docs.duckie.ai/examples/designing-agent-systems
Combine deterministic workflows with autonomous agents for reliable operations
Complex Duckie systems work best when deterministic process logic and autonomous reasoning are separated clearly.
Use **workflows** for repeatable state transitions, routing, approvals, retries, and audit-sensitive steps. Use **autonomous agents** for judgment, research, language, tool selection, and ambiguous work. Use **internal channel agents** for human approvals and escalations in Slack or another team channel. Use **Duckie Assistant agents** for reporting, run review, feedback loops, and improvements to Duckie configuration.
## The Design Model
```mermaid theme={null}
flowchart TD
Channels["Channels and schedules"] --> Deployments["Deployments"]
Deployments --> Workflows["Deterministic workflows"]
Deployments --> Agents["Autonomous agents"]
Workflows --> Subflows["Callable workflows"]
Workflows --> AgentTasks["Agent task nodes"]
Agents --> SpecialistAgents["Callable agents"]
Agents --> Tools["Tools and knowledge"]
AgentTasks --> Tools
Workflows --> EscalationAgent["Internal escalation agent"]
Agents --> EscalationAgent
EscalationAgent --> Humans["Human reviewers"]
Humans --> EscalationAgent
EscalationAgent --> Workflows
Workflows --> Runs["Runs and analytics"]
Runs --> DuckieAssistant["Duckie Assistant reporting and feedback agents"]
```
The orchestration layer should be explicit:
* A deployment starts a workflow or agent when an event, webhook, message, or schedule fires.
* A workflow owns known process states and branches.
* A workflow can call another workflow when a step is reusable across multiple processes.
* A workflow can call an agent when a step needs judgment or natural language work.
* An autonomous agent can call specialized agents when a task should be delegated.
* An internal escalation agent keeps human approvals and questions inside the operational loop.
* A Duckie Assistant agent reviews runs, reports on behavior, and proposes improvements to Duckie objects.
## What Each Component Owns
| Component | Owns | Avoid using it for |
| -------------------------- | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| **Deployment** | Trigger source, channel, mode, and schedule | Business logic that belongs in a workflow or agent |
| **Workflow** | Deterministic process state, branch logic, approvals, retries, and tool order | Open-ended reasoning or broad research |
| **Autonomous agent** | Judgment, language, investigation, and flexible tool use | Strict compliance branches that must run the same way every time |
| **Internal channel agent** | Human approvals, escalation questions, reviewer decisions, and structured handoffs | Duckie workspace maintenance or configuration updates |
| **Duckie Assistant agent** | Run inspection, workspace inspection, reporting, feedback loops, and configuration improvements | Direct customer support or real-time approval routing |
| **Callable agent** | A focused subtask with a clear contract | General orchestration of the full process |
| **Tool** | A specific read or write action | Policy decisions or process ownership |
A good design usually uses a workflow backbone with agents at the points where judgment, language, or tool choice matters.
## Design From the Business Process
Start by writing the process in normal operational language:
1. What starts the process?
2. What facts are always required?
3. Which branches are deterministic?
4. Which steps require judgment or language?
5. Which humans approve, review, or provide missing context?
6. What should be reported daily or weekly?
7. How should mistakes become improvements?
Then map each answer to a Duckie component.
## Common Patterns
### Workflow Backbone With Specialist Agents
Use this when the process has known stages but individual stages need judgment.
```mermaid theme={null}
flowchart TD
Trigger["Trigger"] --> Workflow["Main workflow"]
Workflow --> Classifier["Classification agent"]
Workflow --> Research["Research agent"]
Workflow --> Approval["Approval workflow"]
Approval --> Submit["Submission workflow"]
```
### Internal Channel Agent for Human Review
Use this when the system needs quick human input without moving people out of Slack or another internal channel.
```mermaid theme={null}
sequenceDiagram
participant Workflow as Workflow
participant Agent as Slack escalation agent
participant Reviewer as Human reviewer
participant Origin as Originating run
Workflow->>Agent: Ask for approval or missing context
Agent->>Reviewer: Post concise request
Reviewer->>Agent: Reply in thread
Agent->>Origin: Return structured decision
Origin->>Workflow: Continue next branch
```
### Scheduled Reporting Agent
Use this when stakeholders need recurring visibility into operational health.
```mermaid theme={null}
flowchart TD
Scheduler["Scheduler deployment"] --> Reporter["Duckie Assistant reporting agent"]
Reporter --> Runs["Runs and analytics"]
Reporter --> Systems["Operational systems"]
Reporter --> Slack["Stakeholder channel"]
```
## Design Checklist
* Put deterministic routing in workflows.
* Put uncertain interpretation in agents.
* Put repeated subprocesses in callable workflows.
* Put specialized judgment in callable agents.
* Put human approvals and escalations in internal channel agents.
* Put reporting, run review, and behavior improvement in Duckie Assistant agents.
* Put recurring operational review in scheduled deployments.
* Put powerful write actions behind clear scopes and approval gates.
* Track categories, attributes, and outcomes from the start.
## Related Docs
Build deterministic process logic.
Configure agents that reason and use tools flexibly.
Build agents for reporting, run review, and Duckie configuration improvements.
Run agents on recurring schedules.
# Account Communication Agent
Source: https://docs.duckie.ai/examples/disputes-and-chargebacks/account-communication-agent
Gather missing information from the account or merchant
The account communication agent handles messages to the account, merchant, or internal account owner connected to a dispute. It should be called by the dispute handling workflow when the case needs clarification, documents, or confirmation before evidence can be prepared.
## What It Does
The agent:
* Reviews the structured case record and missing-information checklist
* Drafts a concise message to the account or merchant
* Uses the right channel for the relationship, such as ticketing, email, CRM, or internal messaging
* Asks only for information that is needed for the current dispute branch
* Handles supported languages and tone requirements
* Returns a structured wait state to the workflow
## Recommended Components
| Need | Duckie component |
| --------------------------------------- | -------------------------- |
| Interpret what information is missing | Autonomous agent |
| Send account messages | App tool or responder tool |
| Look up account and transaction context | App, custom, or MCP tools |
| Apply communication rules | Guidelines and guardrails |
| Continue after a response arrives | Workflow state transition |
## Flow
```mermaid theme={null}
sequenceDiagram
participant Workflow as Dispute workflow
participant Agent as Account communication agent
participant Tools as Account and ticketing tools
participant Account as Account or merchant
Workflow->>Agent: Case context and missing facts
Agent->>Tools: Retrieve relevant account details
Agent->>Workflow: Draft message and wait state
Workflow->>Tools: Send message through approved channel
Account->>Tools: Reply with information
Tools->>Workflow: New response event
Workflow->>Agent: Ask agent to interpret response
Agent->>Workflow: Structured facts and remaining gaps
```
## Agent Instructions
The instructions should be narrow and operational:
```text theme={null}
You help gather information for payment dispute cases.
Use the case record, transaction details, and missing-information checklist to draft clear account-facing messages. Ask only for information needed to handle the current case. Do not promise an outcome. Do not ask for sensitive payment credentials. If the case requires legal, policy, or financial judgment outside the provided rules, escalate to the review channel.
Return structured output with:
- message_draft
- requested_information
- channel_recommendation
- language
- deadline
- remaining_risks
```
## Guardrails
Add guardrails for:
* No guarantees about dispute outcomes
* No collection of sensitive credentials
* No use of evidence that is not account-provided, transaction-backed, or customer-facing
* Escalate legal threats, account ownership disputes, regulatory questions, or high-value exceptions
* Escalate when the account asks to change historical records or fabricate evidence
Keep evidence quality rules outside the agent's judgment alone. The workflow should validate required evidence types before moving to approval.
## Deployment Options
This agent usually does not need its own public deployment. In most systems, the dispute handling workflow calls it as a focused agent task.
Use a direct channel deployment only when account messages come into a dedicated support queue and should be handled by this agent first.
## Related Docs
Configure the communication agent.
Control tone, formatting, and account-facing language.
Prevent unsafe account communications.
Send messages through connected systems.
# Daily Reporting Agent
Source: https://docs.duckie.ai/examples/disputes-and-chargebacks/daily-reporting-agent
Post a scheduled stakeholder digest for dispute operations
Use a scheduled deployment for recurring stakeholder reporting. The recommended agent type is a Duckie Assistant agent because the report should inspect Duckie runs, summarize behavior, and surface improvement items without requiring a custom cron job.
## What It Does
The daily reporting agent:
* Runs on a schedule, such as every weekday at 9 AM in the stakeholders' timezone
* Reads Duckie runs, classifications, and operational systems for the reporting window
* Summarizes new cases, pending approvals, submitted cases, outcomes, deadline risks, and failures
* Highlights follow-up work and owners
* Posts the digest to a stakeholder channel
* Links back to relevant runs, tickets, and cases
## Recommended Components
| Need | Duckie component |
| ------------------ | -------------------------------- |
| Recurring run | Scheduler deployment |
| Reporting logic | Duckie Assistant agent |
| Duckie run review | Duckie Assistant MCP or Runs API |
| Destination | Slack app tools |
| Follow-up tracking | Issue tracker or ticketing tools |
## Flow
```mermaid theme={null}
sequenceDiagram
participant Scheduler as Scheduler deployment
participant Reporter as Duckie Assistant reporting agent
participant Runs as Duckie runs and analytics
participant Systems as Case and processor systems
participant Slack as Stakeholder channel
Scheduler->>Reporter: Start daily report run
Reporter->>Runs: Read runs and classifications
Reporter->>Systems: Read case statuses and outcomes
Reporter->>Reporter: Summarize metrics, risks, and follow-ups
Reporter->>Slack: Post stakeholder digest
Reporter->>Runs: Record report run output
```
## Deployment Steps
Create a Duckie Assistant agent that can inspect Duckie runs, summarize system behavior, and report improvement items.
Enable read access to Duckie runs, analytics, ticketing, processor, and case systems needed for the report.
Use Slack app tools to post to a channel such as `#payments-ops` or `#disputes-daily`.
Choose **Scheduler** as the trigger and set a preset, plain-language schedule, or five-field cron expression.
Review the scheduled output before switching the deployment to **Live**.
## Report Contents
Include:
* New cases opened
* Cases accepted, countered, withdrawn, submitted, won, lost, or closed
* Cases waiting on account response
* Cases waiting on human approval
* Cases at deadline risk
* High-value or policy-sensitive cases
* Tool failures and retries
* Escalations sent and resolved
* Recommended follow-up work
* Links to runs, cases, tickets, and review threads
## Example Digest Shape
```text theme={null}
Daily dispute operations summary
Window: Previous business day
Volume:
- New cases: 18
- Submitted responses: 7
- Accepted or closed: 3
- Waiting on account: 5
- Waiting on approval: 2
Risk:
- 3 cases due in the next 48 hours
- 1 high-value case needs policy review
Automation health:
- 2 tool retries
- 1 escalation resolved by reviewer
Follow-ups:
- Review missing evidence pattern for reason category X
- Confirm owner for overdue account response cases
```
Scheduled runs appear in **Analyze > Runs** with source **Scheduler**, which gives the team an audit trail for every posted report.
## Related Docs
Run the report on a recurring schedule.
Build a reporting agent that can inspect Duckie runs.
Review scheduled report executions.
Post the report to a stakeholder channel.
# Dispute Handling Workflow
Source: https://docs.duckie.ai/examples/disputes-and-chargebacks/dispute-handling-workflow
Build the deterministic backbone for dispute case handling
The dispute handling workflow is the main orchestrator. It should own the case lifecycle and call agents only for the parts that need judgment.
## What the Workflow Owns
The workflow should control:
* Case state
* Deadline checks
* Branch routing
* Tool call order
* Retry and failure paths
* Human approval gates
* Handoffs to subflows
* Status updates back to the source system
Autonomous agents should not own these process states. They should return structured outputs that the workflow can validate and route.
## Main Flow
```mermaid theme={null}
flowchart TD
Start["Validated case"] --> Deadline["Check deadline and status"]
Deadline --> TooLate{"Can still respond?"}
TooLate -->|No| RecordLoss["Record closed or missed case"]
TooLate -->|Yes| Classify["Call reason classification agent"]
Classify --> Branch{"Recommended path"}
Branch -->|Accept| Accept["Acceptance workflow"]
Branch -->|Counter| Evidence["Evidence preparation workflow"]
Branch -->|Withdraw| Withdraw["Withdrawal workflow"]
Branch -->|Need info| Account["Account communication agent"]
Account --> Wait["Wait for account response"]
Wait --> Evidence
Evidence --> Approval["Human approval workflow"]
Approval --> Approved{"Approved?"}
Approved -->|Yes| Submit["Submission or recording workflow"]
Approved -->|Changes requested| Evidence
Approved -->|Rejected| Manual["Manual review queue"]
Submit --> Outcome["Outcome tracking workflow"]
```
## Subflows
Break repeated deterministic logic into callable workflows:
| Subflow | Purpose |
| --------------------------------- | --------------------------------------------------------------- |
| **Case validation workflow** | Normalize and validate required fields. |
| **Deadline workflow** | Calculate deadline risk and escalation priority. |
| **Acceptance workflow** | Record that the business accepts liability or will not contest. |
| **Evidence preparation workflow** | Gather evidence, draft packet, and prepare approval request. |
| **Human approval workflow** | Route packet to reviewers and wait for decision. |
| **Submission workflow** | Submit to processor or record manual submission. |
| **Outcome tracking workflow** | Check outcome, update source systems, and notify stakeholders. |
If two use cases need the same approval logic, make that logic a callable workflow instead of rebuilding it inside every blueprint.
## Agent Calls
Use focused agents with clear contracts:
| Agent | Called by | Expected output |
| ------------------------------- | ----------------- | ----------------------------------------------------------------- |
| **Reason classification agent** | Main workflow | Reason category, confidence, recommended path, explanation. |
| **Account communication agent** | Main workflow | Message draft, requested information, language, next wait state. |
| **Evidence drafting agent** | Evidence workflow | Draft narrative, evidence checklist, missing facts, confidence. |
| **Slack escalation agent** | Approval workflow | Reviewer decision, comments, required changes, approver identity. |
The workflow should validate the output shape before continuing.
## Branching Guidelines
Use deterministic branches for conditions such as:
* Response deadline has passed
* Case value is above approval threshold
* Required evidence is missing
* Account response is overdue
* Reviewer rejected the evidence packet
* Tool call failed
Use agent judgment for conditions such as:
* Whether the reason text maps to one or more categories
* What clarification to request from the account
* How to summarize evidence in a clear narrative
* Whether reviewer comments imply a specific correction
## Related Docs
Learn when to use deterministic workflows.
Build branches, tool nodes, and conditions.
Call focused agents from workflows and agents.
Add escalation and restriction rules.
# Escalation Agent
Source: https://docs.duckie.ai/examples/disputes-and-chargebacks/escalation-agent
Route human-in-the-loop decisions through an internal Slack channel
The escalation agent is an autonomous internal agent deployed to Slack or another team channel. It receives structured questions from workflows or agents, posts them to reviewers, and returns structured answers to the originating run.
Use a Duckie Assistant agent for reporting, run review, and improving Duckie behavior. Do not use a Duckie Assistant agent as the real-time escalation agent for this workflow.
## What It Does
The escalation agent:
* Receives approval requests, missing-context questions, or exception alerts
* Posts concise requests to an internal channel
* Keeps the original case link and deadline visible
* Collects reviewer responses
* Converts the response into structured output
* Sends the answer back to the workflow or agent that asked
* Records the escalation in the run history
## Recommended Components
| Need | Duckie component |
| ------------------------------- | ------------------------------------- |
| Human collaboration | Autonomous internal agent |
| Internal channel | Slack integration |
| Structured request and response | Workflow node or custom tool contract |
| Approval gate | Human approval workflow |
| Audit trail | Runs and source-system comments |
## Flow
```mermaid theme={null}
sequenceDiagram
participant Origin as Originating workflow
participant Agent as Slack escalation agent
participant Reviewer as Reviewer
participant Case as Case system
Origin->>Agent: Structured approval request
Agent->>Reviewer: Post request in Slack
Reviewer->>Agent: Reply with decision and comments
Agent->>Case: Add internal note or status update
Agent->>Origin: Return structured decision
Origin->>Origin: Continue approved, change-requested, rejected, or escalated branch
```
## When to Escalate
Escalate when:
* A human must approve external submission
* The agent has low confidence
* Required evidence is missing or conflicting
* The case value exceeds a threshold
* The deadline is at risk
* A tool fails repeatedly
* A reviewer must interpret policy
* The case includes legal, regulatory, or account ownership concerns
## Request Format
Each escalation should include:
* Case ID and source link
* Deadline and urgency
* Recommended action
* Reason for escalation
* Evidence summary or message draft
* Risks and missing facts
* Allowed responses
Example response contract:
```json theme={null}
{
"decision": "approved | changes_requested | rejected | escalate",
"reviewer": "name or identifier",
"comments": "short explanation",
"required_changes": ["item 1", "item 2"]
}
```
## Deployment Guidance
Use a dedicated internal channel, such as `#dispute-review` or `#payments-ops-review`.
Start in Testing mode and route only non-production or replayed cases through the channel until reviewers confirm that the message format is useful.
The escalation agent should be concise. Reviewers should be able to make a decision from the Slack message without opening multiple systems unless the case is complex.
## Related Docs
Configure the internal escalation agent.
Connect Duckie to Slack.
Define when cases should be routed to humans.
Test human-in-the-loop flows before live use.
# Evidence and Approval
Source: https://docs.duckie.ai/examples/disputes-and-chargebacks/evidence-and-approval
Draft evidence packets and route them for human review
Evidence preparation should combine deterministic collection with autonomous drafting. The workflow decides what evidence is allowed and required. The evidence drafting agent turns approved facts into a clear packet.
## What It Does
The evidence and approval function:
* Collects transaction, account, order, fulfillment, communication, and policy evidence from approved sources
* Checks which evidence types are required for the dispute reason
* Calls an evidence drafting agent to create a concise narrative
* Flags missing or weak evidence
* Sends the packet to a reviewer before submission
* Records the reviewer decision and required changes
## Recommended Components
| Need | Duckie component |
| ---------------------------- | ---------------------------------- |
| Evidence checklist by reason | Workflow or knowledge article |
| Evidence retrieval | App, custom, or MCP tools |
| Evidence narrative | Autonomous evidence drafting agent |
| Human review | Approval workflow |
| Reviewer collaboration | Slack escalation agent |
| Audit trail | Runs and source-system updates |
## Flow
```mermaid theme={null}
flowchart TD
Start["Case ready for evidence"] --> Checklist["Load evidence checklist"]
Checklist --> Collect["Collect approved evidence"]
Collect --> Complete{"Minimum evidence present?"}
Complete -->|No| Missing["Request missing information"]
Missing --> Account["Account communication agent"]
Account --> Collect
Complete -->|Yes| Draft["Evidence drafting agent"]
Draft --> Validate["Validate packet structure"]
Validate --> Approval["Human approval workflow"]
Approval --> Decision{"Reviewer decision"}
Decision -->|Approved| Submit["Submission workflow"]
Decision -->|Changes requested| Draft
Decision -->|Rejected| Manual["Manual handling queue"]
```
## Evidence Sources
Use sources that can be audited:
* Payment processor case details
* Transaction records
* Order or service records
* Account profile data
* Customer-facing policy pages
* Prior account communications
* Delivery, fulfillment, usage, or access logs when relevant
* Account-provided documents or statements
Avoid sources that are not tied to the account, transaction, or published policy.
## Approval Request Format
The approval workflow should send reviewers a structured request:
| Section | Contents |
| ------------------------------- | ----------------------------------------------------------------- |
| **Case summary** | Case ID, amount, deadline, reason, and recommended path. |
| **Evidence packet** | Draft narrative and evidence list. |
| **Risks** | Missing facts, weak evidence, policy uncertainty, or timing risk. |
| **Decision buttons or options** | Approve, request changes, reject, or escalate. |
| **Required response format** | Reviewer decision, comments, and approver identity. |
## Human Approval Rules
Require approval when:
* The packet will be submitted externally
* The case value is above a threshold
* The deadline is near
* The evidence drafting agent reports low confidence
* A guardrail or escalation rule triggers
* The account or cardholder raises a legal or regulatory issue
The reviewer should approve the final packet, not just the agent's reasoning. Keep the approval artifact close to what will be submitted or recorded.
## Related Docs
Build the evidence and approval workflow.
Retrieve evidence from internal systems.
Route sensitive cases to reviewers.
Audit every evidence and approval step.
# Feedback and Analytics
Source: https://docs.duckie.ai/examples/disputes-and-chargebacks/feedback-and-analytics
Use outcomes, run review, and stakeholder feedback to improve the system
The feedback loop uses a Duckie Assistant feedback agent to turn human review, case outcomes, and operational metrics into better workflows, agent instructions, tools, guidelines, and reporting.
## What It Does
The feedback function:
* Reviews runs with low confidence, tool failures, reviewer changes, or poor outcomes
* Groups recurring failures into categories
* Identifies missing knowledge, unclear guardrails, or weak workflow branches
* Proposes updates to agent instructions, workflows, tools, categories, or guidelines
* Reports improvement items to owners
* Measures whether changes improve future runs
## Recommended Components
| Need | Duckie component |
| ----------------------------------------- | ------------------------------- |
| Review run history | Analytics runs |
| Group recurring issues | Categories and attributes |
| Inspect and propose configuration changes | Duckie Assistant feedback agent |
| Track improvements | Issue tracker or ticketing tool |
| Monitor recurring failures | Alerts and daily reports |
## Feedback Loop
```mermaid theme={null}
flowchart TD
Runs["Runs and tool traces"] --> Review["Duckie Assistant feedback agent"]
Outcomes["Case outcomes"] --> Review
HumanEdits["Reviewer changes"] --> Review
StakeholderReports["Daily stakeholder reports"] --> Review
Review --> Patterns["Failure patterns and gaps"]
Patterns --> Improvements["Guidelines, workflows, agents, tools, and categories"]
Improvements --> Testing["Replay and batch testing"]
Testing --> Deploy["Updated deployments"]
Deploy --> Runs
```
## What to Track
Track categories and attributes that explain both business outcomes and system behavior:
| Tracking item | Example values |
| --------------------- | --------------------------------------------------------------------------------------- |
| **Reason category** | Fraud, duplicate, service not received, product not as described, credit not processed. |
| **Automation path** | Accepted, countered, needs account info, human review, manual handling. |
| **Escalation reason** | Low confidence, missing evidence, deadline risk, policy question, tool failure. |
| **Reviewer decision** | Approved, changes requested, rejected, escalated. |
| **Outcome** | Won, lost, accepted, withdrawn, closed, pending. |
| **Failure type** | Missing data, wrong classification, weak evidence, message quality, tool error. |
## Review Cadence
Use three loops:
| Loop | Cadence | Owner |
| --------------------------- | ------------------ | ---------------------------------------------------- |
| **Daily operations report** | Business days | Duckie Assistant reporting agent and operations lead |
| **Exception review** | As cases happen | Slack escalation agent and reviewer |
| **Improvement review** | Weekly or biweekly | Duckie Assistant feedback agent and system owner |
## Improvement Actions
Common improvements include:
* Add a branch to the dispute handling workflow
* Split a broad reason category into more specific categories
* Add a missing evidence checklist
* Tighten an agent instruction
* Add a guardrail for a risky response pattern
* Add a custom tool for repeated manual lookup work
* Update the daily report to surface a recurring issue
The Duckie Assistant feedback agent should propose changes, but sensitive workflow, guardrail, or tool updates should follow your normal review process before going live.
## Related Docs
Monitor performance and trends.
Inspect the details behind each case.
Notify the team when important patterns appear.
Test changes against historical cases.
# Intake and Triage
Source: https://docs.duckie.ai/examples/disputes-and-chargebacks/intake-and-triage
Deploy the entry point for new dispute and chargeback cases
The intake layer turns external events into a clean case record. It should be deterministic because downstream agents and workflows depend on consistent inputs.
## What It Does
The intake function:
* Receives a dispute case from a ticketing event, custom webhook, or payment processor event
* Creates or finds the internal case record
* Extracts required fields such as processor case ID, amount, currency, deadline, transaction ID, account ID, and reason text
* Validates that required fields are present
* Routes incomplete cases to an enrichment or escalation path
* Starts the main dispute handling workflow
## Recommended Components
| Need | Duckie component |
| -------------------------------- | ---------------------------------- |
| Receive ticket or webhook events | Deployment |
| Normalize case data | Case validation workflow |
| Fetch missing processor details | App tool, custom tool, or MCP tool |
| Classify ambiguous reason text | Reason classification agent |
| Track analytics | Categories and attributes |
## Flow
```mermaid theme={null}
flowchart TD
Trigger["Ticket, webhook, or processor event"] --> Intake["Intake deployment"]
Intake --> Validate["Case validation workflow"]
Validate --> Required{"Required data present?"}
Required -->|Yes| Main["Dispute handling workflow"]
Required -->|No| Enrich["Fetch missing details"]
Enrich --> Required
Required -->|Still missing| Escalate["Slack escalation agent"]
Main --> Classify["Reason classification agent"]
Classify --> Route["Route by reason, deadline, and value"]
```
## Deployment Steps
Use a ticketing deployment when cases originate in a support system. Use a custom webhook when the payment processor or internal system should start the run directly.
Create the deployment in **Testing** mode so you can review the extracted case record before live automation.
Route the deployment to a workflow that checks required fields, normalizes names, and records missing data.
Enable tools that can fetch transaction, account, processor, ticket, and CRM details.
Call a specialized classifier agent only after the case has enough context to classify reliably.
## Fields to Normalize
| Field | Purpose |
| ------------------- | ---------------------------------------------------------------------------------------- |
| `case_id` | Stable Duckie-side identifier for the dispute case. |
| `processor_case_id` | External processor identifier used for lookup and submission. |
| `transaction_id` | Payment or order reference used to gather evidence. |
| `account_id` | Account, merchant, or customer record connected to the case. |
| `reason_code` | Processor reason code, when available. |
| `reason_summary` | Human-readable reason text for routing and review. |
| `response_deadline` | Latest safe date to act on the case. |
| `case_value` | Amount at risk for prioritization. |
| `current_status` | Intake, waiting for account, approval needed, submitted, won, lost, accepted, or closed. |
The exact field names can match your internal data model. The important part is that the workflow produces a stable, structured case object before agents begin judgment-heavy work.
## What to Track
Use categories and attributes from the first deployment:
* Reason category
* Case value band
* Deadline risk
* Intake source
* Missing data type
* Automation path
* Final outcome
## Related Docs
Create the entry-point deployment.
Receive processor or internal events.
Track dispute reason categories.
Track deadline, value, and source attributes.
# MVP
Source: https://docs.duckie.ai/examples/disputes-and-chargebacks/mvp
The smallest useful autonomous dispute operations system before full submission, escalation, reporting, and feedback loops
Start with an autonomous case-handling loop. Duckie should receive a dispute case, normalize required fields, classify the reason, gather approved evidence, choose the next path from deterministic policy, and submit or record only the actions your policy allows without human approval.
This proves the system without putting every case through a reviewer or starting with full external submission automation.
The MVP is one case record, one validation workflow, one reason classifier, one decision policy workflow, one evidence packet, and one required-approval path for cases that cannot continue autonomously.
## MVP Goal
By the end of the MVP, Duckie should reliably answer:
* What case was opened, and what deadline applies?
* Which transaction, account, order, processor, and communication records matter?
* What is the likely dispute reason and recommended path?
* Is the case allowed to continue autonomously under policy?
* What evidence is required, present, missing, or weak?
* Should Duckie submit, record a decision, request account information, or route a required approval?
## Minimal Flow
```mermaid theme={null}
flowchart TD
Event["Dispute case or ticket"]
Event --> Intake["Dispute intake deployment"]
Intake --> Validate["Normalize and validate case"]
Validate --> Classify["Classify reason and deadline risk"]
Classify --> Policy["Apply decision policy"]
Policy -->|Accept or close allowed| Record["Record decision"]
Policy -->|Need account info| Account["Ask for missing account information"]
Account --> Validate
Policy -->|Prepare response| Evidence["Collect approved evidence"]
Evidence --> Draft["Draft evidence packet"]
Draft --> Gate{"Approval required by policy?"}
Gate -->|No| Submit["Submit or record response"]
Gate -->|Yes| RequiredApproval["Route required approval"]
Submit --> Outcome["Track outcome"]
Record --> Outcome
RequiredApproval --> Outcome
```
## Build First
| Piece | What to build | Done when |
| ---------------------- | --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| Intake deployment | Trigger from ticketing, custom webhook, or payment processor event. | Duckie creates or finds a stable case record. |
| Case validation | Normalize case ID, processor ID, transaction ID, account ID, amount, currency, deadline, and reason text. | Downstream agents always receive a structured case object. |
| Reason classifier | Classify reason category, confidence, deadline risk, and recommended path. | Messy processor text becomes structured workflow input. |
| Decision policy | Apply deterministic accept, close, counter, request-info, submit, and approval-required rules. | The workflow decides whether the case can continue autonomously. |
| Evidence packet | Collect approved evidence and draft the response narrative. | Evidence uses auditable sources tied to the case, account, transaction, or published policy. |
| Required approval path | Route only cases that policy requires to an internal approval or escalation channel. | High-risk cases leave the autonomous path with a clear packet and reason. |
| Outcome tracking | Record submitted, accepted, countered, won, lost, missed, or closed outcomes. | Each case can be audited from intake through outcome. |
## Defer Until the MVP Works
Add these after the first autonomous loop is trusted:
* Full external submission automation for every processor
* Broad multi-processor routing
* Complex appeal or second-presentment flows
* Automatic handling for high-value cases
* Legal, regulatory, or policy-exception automation
* Daily reporting and feedback agents
* Large evidence source catalogs that are not yet audited
## Required Human Handoffs
Keep humans in the loop only when policy, risk, or missing authority requires it:
| Condition | Handoff |
| ------------------------------------------------ | ---------------------------------------------------------------------- |
| External submission requires approval | Route the final packet and submission summary to the approved owner. |
| Case value is above threshold | Route to the finance, operations, or risk owner. |
| Evidence is weak or contradictory | Route the packet with the missing or conflicting facts called out. |
| Legal, regulatory, or policy exception appears | Route to the team that owns that decision. |
| Deadline or tool failure makes automation unsafe | Route to the manual handling queue with current state and next action. |
Do not remove required approval gates. The autonomous path should handle allowed cases end to end and hand off only the cases where policy, risk, or external submission rules require a person.
## When to Expand
Move beyond the MVP when:
* Case validation is reliable across live sources
* Reason classification is consistently correct for common categories
* Decision policy branches match operations rules
* Evidence packets are complete and sourced from auditable systems
* Required approval handoffs are specific and actionable
* Outcomes are tracked cleanly enough to improve the workflow
## Next Pages
After the MVP:
1. Read the [system map](/examples/disputes-and-chargebacks/system-map) to see the full architecture.
2. Build [intake and triage](/examples/disputes-and-chargebacks/intake-and-triage).
3. Add the [dispute handling workflow](/examples/disputes-and-chargebacks/dispute-handling-workflow).
4. Use the [rollout plan](/examples/disputes-and-chargebacks/rollout-plan) before expanding live scope.
# Overview
Source: https://docs.duckie.ai/examples/disputes-and-chargebacks/overview
A blueprint for automating payment dispute operations with Duckie
This blueprint shows how to design a Duckie system for payment disputes and chargebacks. It uses generic payment operations terminology so you can adapt it to your own ticketing system, payment processor, CRM, and required approval process.
The recommended design uses a deterministic workflow backbone with autonomous agents for the ambiguous parts of the work.
## Start With the MVP
You do not need to launch the full disputes system at once. Start with an autonomous loop that validates cases, classifies the reason, applies decision policy, gathers approved evidence, and routes only policy-required approvals or exceptions to humans.
Then add broader submission automation, escalation, reporting, and feedback after the first loop is trusted.
Use the [MVP](/examples/disputes-and-chargebacks/mvp) as the starting point if you are building this blueprint for the first time.
## What This System Does
The system helps a team:
* Receive dispute cases from a ticketing system, webhook, or payment processor
* Classify the case reason and deadline
* Gather missing information from the account or merchant
* Draft an evidence packet from approved data sources
* Route policy-required approvals or exceptions to humans
* Submit or record the final response when policy allows
* Track the outcome
* Report daily operational status to stakeholders
* Learn from escalations, failures, and operator corrections
Do not remove required approval gates. For financial or compliance-sensitive processes, automate allowed paths and route only policy-required approvals, high-risk cases, and exceptions to the right human owner.
## Design at a Glance
| Function | Duckie component | Why |
| ---------------------- | --------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| Case intake and triage | Workflow deployment from ticketing or webhook | Intake needs repeatable extraction, validation, and routing. |
| Reason classification | Autonomous classifier agent called by workflow | Dispute reasons can be messy and require judgment. |
| Account communication | Autonomous communication agent called by workflow | Messages need context, tone, and language handling. |
| Evidence preparation | Workflow plus evidence drafting agent | The process is deterministic, but drafting needs judgment. |
| Required approvals | Approval workflow plus Slack escalation agent | Policy-required approvals and exceptions need a structured internal request. |
| Daily reporting | Scheduler deployment running a Duckie Assistant reporting agent | Stakeholders need recurring visibility without a custom cron service. |
| Feedback loop | Duckie Assistant feedback agent and analytics | Corrections should improve guidelines, workflows, categories, and tools. |
## Blueprint Pages
Start with autonomous case handling before adding broader submission and escalation loops.
See the full multi-agent, multi-channel architecture.
Deploy the entry point that validates and routes new cases.
Build the deterministic backbone for the case lifecycle.
Gather missing information from the account or merchant.
Draft evidence packets and route required approvals.
Send questions and approvals to an internal Slack channel.
Post a scheduled stakeholder digest.
Turn run data, outcomes, and corrections into improvements.
Move from narrow case handling to broader live operations.
## Recommended Reading Order
1. Start with the [MVP](/examples/disputes-and-chargebacks/mvp) to understand the smallest useful autonomous loop.
2. Read the [system map](/examples/disputes-and-chargebacks/system-map) to see how the MVP expands into the full architecture.
3. Read [intake and triage](/examples/disputes-and-chargebacks/intake-and-triage) to understand the entry point.
4. Read the [dispute handling workflow](/examples/disputes-and-chargebacks/dispute-handling-workflow) to see how state is controlled.
5. Open the function page for the first component you want to build.
6. Use the [rollout plan](/examples/disputes-and-chargebacks/rollout-plan) before moving to live traffic.
## Related Docs
Learn the general workflow-plus-agent design pattern.
Test historical cases before live deployment.
# Rollout Plan
Source: https://docs.duckie.ai/examples/disputes-and-chargebacks/rollout-plan
Move the disputes blueprint from testing to live operations
Roll out the system in phases. Start with visibility and human review, then expand automation only after replay tests and live testing show reliable behavior.
## Phase 1: Model the Process
Define:
* Case states
* Required fields
* Reason categories
* Evidence checklists
* Deadline rules
* Approval thresholds
* Escalation reasons
* Final outcomes
Build the first version of the dispute handling workflow and case validation workflow.
## Phase 2: Connect Intake in Testing Mode
Create the intake deployment from the ticketing system, custom webhook, or processor event.
In Testing mode, verify:
* Case fields are extracted correctly
* Missing fields route to enrichment or escalation
* Deadlines are calculated correctly
* Classification output is structured
* Runs are easy to inspect
## Phase 3: Add Specialist Agents
Add agents one at a time:
1. Reason classification agent
2. Account communication agent
3. Evidence drafting agent
4. Slack escalation agent
5. Duckie Assistant feedback agent
Keep each agent narrow. Give each one a clear contract and validate its output in the workflow.
## Phase 4: Add Human Approval
Before any external submission or final case action:
* Route the evidence packet to a reviewer
* Capture approve, request changes, reject, and escalate decisions
* Record reviewer identity and comments
* Send changes back to the evidence workflow
Do not move final dispute submission to live automation until reviewers trust the evidence packet quality and the workflow handles edge cases reliably.
## Phase 5: Add Scheduled Reporting
Create a Scheduler deployment for the Duckie Assistant reporting agent.
Start with:
* Weekdays at 9 AM in the stakeholder timezone
* Testing mode
* Read-only tools
* A single stakeholder channel
Switch to Live after the team confirms that the digest is accurate and useful.
## Phase 6: Replay and Batch Test
Test historical cases before expanding automation:
* Straightforward accepted cases
* Straightforward counter cases
* Missing evidence cases
* Deadline-risk cases
* High-value cases
* Tool failure cases
* Cases requiring human review
* Cases with poor or incomplete source data
Use failures to update workflows, instructions, tools, and guardrails.
## Phase 7: Expand Live Scope
Move low-risk paths to Live first:
* Intake and classification
* Internal notes and status updates
* Account information requests
* Daily reporting
* Reviewer-ready evidence drafts
Keep high-risk actions gated:
* Final external submissions
* High-value cases
* Legal or regulatory cases
* Cases with weak evidence
* Tool failures that require manual interpretation
## Launch Checklist
* Intake deployment is in the correct mode
* Main workflow and subflows are published
* Agent tool access is scoped to the job
* Slack escalation channel has reviewer owners
* Daily reporting channel has stakeholder owners
* Categories and attributes are configured
* Runs are reviewed during the first live week
* Rollback plan is documented
## Related Docs
Control testing and live behavior.
Test historical cases before launch.
Evaluate many cases at once.
Scope sensitive actions safely.
# System Map
Source: https://docs.duckie.ai/examples/disputes-and-chargebacks/system-map
The multi-channel, multi-agent architecture for dispute operations
This system is built around a workflow backbone. Deployments bring work into Duckie, workflows hold deterministic state, and agents handle judgment-heavy steps.
## Operational Flow
```mermaid theme={null}
flowchart TD
Event["Payment processor event or ticket update"]
Event --> Intake["Intake deployment"]
Intake --> Validate["Case validation workflow"]
Validate --> Main["Dispute handling workflow"]
Main --> Classify["Reason classification agent"]
Classify --> Route{"Next action"}
Route -->|Accept or close| Close["Close or record decision"]
Route -->|Need account context| Account["Account communication agent"]
Route -->|Prepare response| Evidence["Evidence preparation workflow"]
Account --> Wait["Wait for account response"]
Wait --> Evidence
Evidence --> Draft["Evidence drafting agent"]
Draft --> Approval["Human approval workflow"]
Approval --> Escalation["Slack escalation agent"]
Escalation --> Reviewers["Operations reviewers"]
Reviewers --> Decision{"Reviewer decision"}
Decision -->|Approved| Submit["Submission or recording workflow"]
Decision -->|Changes requested| Evidence
Decision -->|Manual handling| Manual["Manual review queue"]
Submit --> Outcome["Outcome tracking workflow"]
Close --> Runs["Runs and analytics"]
Manual --> Runs
Outcome --> Runs
```
## Reporting and Improvement Loop
```mermaid theme={null}
flowchart TD
Runs["Runs and analytics"]
Runs --> Scheduler["Scheduler deployment"]
Scheduler --> Reporting["Duckie Assistant reporting agent"]
Reporting --> Stakeholders["Stakeholder Slack channel"]
Runs --> Feedback["Duckie Assistant feedback agent"]
Stakeholders --> Feedback
Feedback --> Proposals["Improvement proposals"]
Proposals --> Review["System owner review"]
Review --> Updates["Guidelines, workflows, tools, and categories"]
Updates --> Testing["Replay and batch testing"]
Testing --> Deploy["Updated deployments"]
```
## Component Responsibilities
| Component | Responsibility |
| ------------------------------------ | ---------------------------------------------------------------------------------------------- |
| **Intake deployment** | Starts the system from a ticket, webhook, or processor event. |
| **Dispute handling workflow** | Owns case state, deterministic branches, retries, and handoffs. |
| **Case validation workflow** | Normalizes the case record and checks required fields. |
| **Reason classification agent** | Interprets messy dispute text and chooses the most likely reason. |
| **Decision policy workflow** | Applies deterministic accept, counter, close, and escalation rules. |
| **Account communication agent** | Contacts the account or merchant for missing information. |
| **Evidence preparation workflow** | Calls tools and agents to assemble the draft evidence packet. |
| **Human approval workflow** | Requires a reviewer decision before final submission. |
| **Slack escalation agent** | Sends structured questions and returns structured answers through the internal review channel. |
| **Duckie Assistant reporting agent** | Reads runs and posts a scheduled digest for stakeholders. |
| **Duckie Assistant feedback agent** | Reviews runs and corrections to recommend improvements to Duckie configuration. |
## Deterministic vs Autonomous
Use deterministic workflows for:
* Required field checks
* Deadline calculation
* Branch routing
* Approval gates
* Submission status changes
* Retrying failed tool calls
* Calling reusable subflows
Use autonomous agents for:
* Classifying unclear reason codes
* Reading free-form dispute notes
* Drafting account messages
* Drafting evidence narratives
* Summarizing reviewer feedback
* Explaining daily operational trends
* Delegating narrow tasks to other agents
When a step must happen the same way every time, make it a workflow. When a step needs interpretation, make it an agent called by the workflow.
## Deployment Inventory
| Deployment | Trigger | Target | Mode to start |
| ---------------------------- | ---------------------------------------------------------- | -------------------------------- | ------------- |
| **Dispute intake** | Ticketing event, custom webhook, or processor webhook | Dispute handling workflow | Testing |
| **Slack escalation** | Internal Slack channel or responder behavior from workflow | Escalation agent | Testing |
| **Daily stakeholder report** | Scheduler, such as weekdays at 9 AM | Duckie Assistant reporting agent | Testing |
| **Feedback review** | Scheduler or manual internal request | Duckie Assistant feedback agent | Testing |
## Related Docs
Learn how deployments connect triggers to agents and workflows.
Trigger Duckie from external systems.
Run reporting and review loops on a schedule.
Inspect what happened during each case.
# Duckie as an External Subagent
Source: https://docs.duckie.ai/examples/duckie-as-external-subagent
Call a focused Duckie agent from a customer-owned orchestration agent
Use Duckie as an external subagent when a customer-owned [orchestration agent](/concepts/routing-and-orchestration-patterns) should keep ownership of the overall workflow, but Duckie should handle a focused support task such as searching [knowledge](/knowledge/overview), summarizing context, classifying a request, or drafting a customer-safe answer.
This pattern is intentionally small: the customer's agent sends Duckie a task, Duckie runs a specialized agent, and Duckie sends the result back to the customer's system.
## Example Flow
```mermaid theme={null}
sequenceDiagram
participant Orchestrator as Customer-owned orchestration agent
participant Webhook as Duckie custom webhook
participant Agent as Duckie search agent
participant Knowledge as Duckie knowledge and tools
participant Callback as Orchestrator callback API
Orchestrator->>Webhook: POST task payload
Webhook->>Agent: Start Duckie run
Agent->>Knowledge: Search docs and call allowed tools
Agent->>Callback: POST structured result
Callback->>Orchestrator: Continue orchestration
```
[Custom webhook deployments](/deployments/custom-webhooks) accept the request and process it asynchronously. If the orchestrator needs the result, have the Duckie agent call a [custom tool](/tools/custom-tools) configured with a fixed callback API and a correlation ID rather than expecting the webhook response to include the final answer.
## When to Use This Pattern
Use Duckie as an external subagent when:
* You already have a primary [orchestration agent](/concepts/routing-and-orchestration-patterns) outside Duckie.
* Duckie should own a narrow support capability, not the whole customer journey. For the Duckie-native version of this pattern, see [Sub-Agents](/agents/sub-agents).
* The task benefits from Duckie [knowledge search](/knowledge/overview), [runbooks](/runbooks/overview), [guidelines](/guidelines/overview), [guardrails](/guardrails/overview), or [support tools](/tools/duckie-tools).
* Your orchestrator can continue after receiving an async callback from Duckie.
Good first tasks include:
* Search internal support docs and return a sourced answer.
* Classify a customer request into your support taxonomy.
* Summarize a ticket, conversation, or account record.
* Draft a customer-facing response for the orchestrator to review or send.
* Check policy eligibility and return a recommendation.
## What to Build
| Component | Purpose |
| ------------------------------------------------------------- | ------------------------------------------------------------------ |
| **Customer-owned orchestration agent** | Owns the parent workflow and decides when Duckie should be called. |
| **[Custom webhook deployment](/deployments/custom-webhooks)** | Receives the task payload and starts the Duckie agent. |
| **[Focused Duckie agent](/agents/autonomous-agents)** | Performs one narrow task, such as search or classification. |
| **[Custom callback tool](/tools/custom-tools)** | Sends the final result back to your orchestrator API. |
| **Correlation ID** | Connects the Duckie result to the parent orchestration task. |
## Request Shape
Send the task to a Duckie [custom webhook](/deployments/custom-webhooks) as JSON.
```json theme={null}
{
"event": {
"id": "evt_123",
"type": "subagent.search.requested"
},
"task": {
"id": "task_456",
"type": "knowledge_search",
"question": "What is our refund policy for annual plans?"
},
"context": {
"customer_id": "cus_789",
"plan": "enterprise",
"region": "us"
}
}
```
Map the payload into:
| Duckie field | Example mapping |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **Event ID** | `$.event.id` |
| **Ticket ID** | `$.task.id` |
| **Ticket Title** | `Duckie subagent task {{task.id}}` |
| **Message Body** | `{{task.question}}` |
| **Run Metadata** | `task_id: $.task.id`, `task_type: $.task.type`, `customer_id: $.context.customer_id`, `plan: $.context.plan`, `region: $.context.region` |
Keep the webhook payload focused. Do not include secrets, credentials, API keys, or unnecessary sensitive data.
## Agent Setup
Create an [autonomous agent](/agents/autonomous-agents) with a narrow name and description, such as **External Knowledge Search Agent**.
Example instructions:
```text theme={null}
You are a focused research subagent for an external orchestration system.
Answer only the task provided in the current run. Search the available Duckie knowledge before answering. Use tools only when they are directly needed for the task.
Return a concise, structured result to the calling system by using the Send Subagent Result tool. Include the correlation ID from run metadata, the answer, relevant sources, confidence, and any caveats.
Do not send a customer-visible response unless explicitly instructed. If the task cannot be completed safely or confidently, return a low-confidence result with the missing information.
```
Give this agent access only to the [knowledge](/knowledge/overview), [runbooks](/runbooks/overview), [guidelines](/guidelines/overview), [guardrails](/guardrails/overview), and [tools](/tools/overview) required for the subtask. For a search agent, that usually means Duckie knowledge search and the callback custom tool.
## Callback Tool
Create a [custom tool](/tools/custom-tools) that posts the result back to your orchestrator API.
```text theme={null}
POST https://orchestrator.example.com/api/duckie/subagent-results
```
Example body parameters:
| Parameter | Source |
| ---------------- | ------------------------------------------------------------------------------- |
| `correlation_id` | Fixed value from `{{context.task_id}}` or another run metadata field |
| `status` | AI-generated enum-style string, such as `complete`, `needs_review`, or `failed` |
| `answer` | AI-generated result text |
| `sources` | AI-generated array of source references |
| `confidence` | AI-generated string, such as `high`, `medium`, or `low` |
| `notes` | AI-generated caveats or missing information |
Use a fixed callback endpoint. Pass task IDs, customer IDs, or routing keys as parameters instead of letting the agent choose a destination URL.
## Result Shape
The callback response to your orchestrator can look like this:
```json theme={null}
{
"correlation_id": "task_456",
"status": "complete",
"answer": "Annual plans are refundable within 30 days if the account has not exceeded the usage threshold.",
"sources": [
{
"title": "Refund Policy",
"url": "https://example.com/refund-policy"
}
],
"confidence": "high",
"notes": "The policy has an enterprise exception; confirm account-specific terms before issuing a refund."
}
```
Your orchestrator can then decide whether to continue the workflow, ask Duckie another focused task, send a customer response, or route to a human.
## Testing
1. Create the webhook deployment in [**Testing** mode](/deployments/deployment-modes).
2. Send a representative task payload with a correlation ID.
3. Open [**Analyze > Runs**](/analytics/runs) and verify the message, metadata, searched knowledge, and tool calls.
4. Confirm your callback API receives one result for the task.
5. Test missing context, low-confidence answers, and callback failures before switching the deployment to [**Live**](/deployments/deployment-modes).
## Related Docs
Trigger Duckie from your orchestration system.
Send the subagent result back to your API.
Configure the focused Duckie agent.
Review the Duckie run, tool calls, and callback result.
Place this pattern inside a larger agent architecture.
Compare internal delegation with external orchestration.
# Overview
Source: https://docs.duckie.ai/examples/overview
Example Duckie patterns and architectures for real customer operations
Examples show how Duckie components fit together for larger systems and integration patterns. Use the short pattern pages for focused implementation ideas, and use the blueprints when you want a fuller business-process design.
These pages are meant to be read alongside the product docs. They explain what to build and link back to the reference pages for how each Duckie component works.
Learn how to combine workflows, autonomous agents, internal channel agents, Duckie Assistant agents, tools, and deployments.
See how to call Duckie from your own orchestration agent and send structured results back.
See how to enrich support tickets with customer context, classify intent, apply tags, and route work.
See how to turn customer reports into engineering issues and route questions or fixes back to the customer.
See how to automate order-status support with proactive updates and specialist agents.
See how to automate payment dispute operations with deterministic workflows and specialized agents.
## How to Read Examples
Use focused pattern pages when you need one integration shape. Use blueprints when you need a full operational design organized by function rather than by product feature:
| Page type | What it answers |
| -------------------------- | -------------------------------------------------------------- |
| **Pattern pages** | How should one integration or agent pattern work? |
| **Overview** | What business process does this automate? |
| **System map** | How do channels, agents, workflows, tools, and humans connect? |
| **Function pages** | How should each deployable part be designed? |
| **Reporting and feedback** | How does the system improve after launch? |
| **Rollout plan** | How should the system move from testing to live traffic? |
Start with the system map, then open the function page for the part you want to build first.
## Related Docs
Review the main Duckie building blocks.
Connect agents and workflows to channels, webhooks, and schedules.
Build deterministic process logic.
Use agents for judgment, research, and flexible tool use.
# Escalation and Handoff
Source: https://docs.duckie.ai/examples/ticket-triage/escalation-and-handoff
Route unclear or high-risk tickets to human reviewers and specialist teams
The escalation agent is an autonomous internal agent deployed to Slack or another team channel. It receives structured triage questions from a workflow, posts them to reviewers, and returns a structured answer to the originating run.
Use a Duckie Assistant agent for reporting, run review, and improving Duckie behavior. Do not use a Duckie Assistant agent as the real-time escalation agent for ticket triage.
## What It Does
The escalation and handoff function:
* Sends low-confidence classification or routing questions to an internal channel
* Gives reviewers the ticket link, customer context, recommendation, and reason for escalation
* Collects reviewer decisions in thread
* Converts the reply into structured output for the workflow
* Writes a concise handoff note for the assigned team
* Records escalation reason, reviewer decision, and final route for analytics
## Recommended Components
| Need | Duckie component |
| ------------------------------------ | ------------------------------------- |
| Human collaboration | Autonomous internal agent |
| Internal channel | Slack integration |
| Structured request and response | Workflow node or custom tool contract |
| Review routing and tagging decisions | Support triage reviewers |
| Audit trail | Runs and ticket internal notes |
## Flow
```mermaid theme={null}
sequenceDiagram
participant Workflow as Triage workflow
participant Agent as Slack escalation agent
participant Reviewer as Support reviewer
participant Ticket as Helpdesk ticket
Workflow->>Agent: Structured triage question
Agent->>Reviewer: Post ticket summary and recommendation
Reviewer->>Agent: Reply with route, tags, and comments
Agent->>Ticket: Add internal note when needed
Agent->>Workflow: Return structured decision
Workflow->>Ticket: Apply reviewed tags, priority, queue, or handoff
```
## When to Escalate
Escalate when:
* Classifier confidence is below the threshold
* The ticket has multiple plausible intents
* A high-value or priority customer is involved
* The customer is angry, at churn risk, or repeatedly contacting support
* The ticket may involve security, privacy, legal, or trust and safety concerns
* The recommended route would trigger an expensive or sensitive downstream workflow
* Required context is missing or conflicting
* A helpdesk writeback tool fails repeatedly
## Request Format
Each escalation should include:
* Ticket ID and source link
* Customer segment and support tier
* Short ticket summary
* Recommended intent, tags, route, and priority
* Confidence score and reason for uncertainty
* Relevant recent context
* Allowed reviewer responses
Example response contract:
```json theme={null}
{
"decision": "approved | changes_requested | manual_review",
"primary_intent": "bug report",
"route": "technical support",
"priority": "high",
"tags": ["bug_report", "dashboard"],
"reviewer": "name or identifier",
"comments": "Route to technical support and ask for browser console logs."
}
```
## Specialist Handoff
The handoff should make the next team faster, not just move the ticket.
Include:
* One-sentence customer problem
* Customer context that affects handling
* Intent, product area, urgency, and route
* Missing information
* Relevant links to account, order, product event, logs, or prior tickets
* Why Duckie routed the ticket there
* Suggested next action
For most teams, a good handoff note is more valuable than a perfect tag. It lets specialists trust the route and continue without rereading the whole thread.
## Related Docs
Connect Duckie to the internal review channel.
Define when tickets should be routed to humans.
Test escalation behavior before live use.
Inspect the escalation trail for each ticket.
# Intake and Customer Context
Source: https://docs.duckie.ai/examples/ticket-triage/intake-and-customer-context
Normalize new tickets and attach the context needed for reliable triage
The intake layer turns a helpdesk event, email, chat, or webhook into a clean ticket record. The customer context layer adds the facts that make triage useful: who the customer is, what they have, what they recently did, and what support obligations apply.
## What It Does
The intake and context function:
* Receives new ticket or message events
* Normalizes source fields into a consistent ticket object
* Deduplicates obvious duplicate messages or ticket updates
* Looks up the requester, account, subscription, order, product usage, or workspace context
* Checks current incidents, open tickets, prior escalations, and support entitlement
* Produces a context bundle for the triage workflow and classifier agent
* Records missing context so the system can route safely
## Recommended Components
| Need | Duckie component |
| ---------------------------------------------- | ---------------------------------- |
| Receive ticket, chat, email, or webhook events | Deployment |
| Normalize and deduplicate tickets | Workflow |
| Fetch customer and account context | App tool, custom tool, or MCP tool |
| Check known incidents and prior tickets | App tools and knowledge sources |
| Store context for downstream steps | Workflow state and run output |
| Track missing context | Categories and attributes |
## Flow
```mermaid theme={null}
flowchart TD
Trigger["Ticket, email, chat, or webhook event"]
Trigger --> Intake["Ticket intake deployment"]
Intake --> Normalize["Normalize ticket workflow"]
Normalize --> Dedupe{"Duplicate or update?"}
Dedupe -->|New ticket| Lookup["Customer lookup tools"]
Dedupe -->|Existing ticket update| Merge["Merge with existing ticket state"]
Merge --> Lookup
Lookup --> Context["Build context bundle"]
Context --> Complete{"Required context present?"}
Complete -->|Yes| Triage["Triage workflow"]
Complete -->|No| Missing["Set missing context attributes"]
Missing --> Triage
```
## Context to Fetch
| Context | Why it matters |
| ------------------------- | ----------------------------------------------------------------------------------------------------------- |
| **Requester identity** | Connects the ticket to the correct customer, account, workspace, or organization. |
| **Customer segment** | Helps route enterprise, premium, trial, or self-serve customers correctly. |
| **Support entitlement** | Determines SLA, support tier, escalation path, and allowed actions. |
| **Product area** | Helps classify the issue and route to the right support or specialist queue. |
| **Recent activity** | Shows whether the ticket relates to a recent order, payment, login, configuration change, or product event. |
| **Open incidents** | Prevents duplicate investigation when a known outage or degradation already explains the ticket. |
| **Prior tickets** | Reveals repeated issues, unresolved threads, and customers that may need careful handling. |
| **Language and timezone** | Helps route by coverage and draft customer-facing messages later. |
Use the least sensitive context that can support the triage decision. Keep high-risk write actions and sensitive data behind explicit scopes and approval gates.
## Suggested Context Contract
The exact field names can match your systems. The important part is that downstream agents receive a stable context bundle.
```json theme={null}
{
"ticket": {
"id": "ticket_123",
"source": "helpdesk",
"channel": "email",
"subject": "Cannot access workspace",
"body_summary": "Customer says login succeeds but workspace is blank",
"requester_id": "user_123",
"created_at": "2026-06-09T16:20:00Z"
},
"customer": {
"account_id": "acct_123",
"segment": "business",
"support_tier": "priority",
"language": "en",
"timezone": "America/Los_Angeles"
},
"context": {
"active_incidents": [],
"recent_orders": [],
"recent_product_events": ["workspace permission changed"],
"open_ticket_count": 1,
"prior_escalations": []
},
"missing_context": []
}
```
## What to Track
Track categories and attributes from the start:
* Intake source
* Channel
* Customer segment
* Support tier
* Context completeness
* Missing context type
* Duplicate or update status
* Known incident match
* Prior-ticket count band
## Related Docs
Create the entry-point deployment.
Use connected tools to read ticketing, CRM, and product context.
Add internal lookups for account, entitlement, or product data.
Track context completeness and customer properties.
# Intent, Tagging, and Routing
Source: https://docs.duckie.ai/examples/ticket-triage/intent-tagging-and-routing
Classify support tickets and turn the classification into deterministic routing
Intent classification should interpret the customer's message. Routing should apply the support team's rules. Keeping those responsibilities separate makes the system easier to test, audit, and improve.
## What It Does
The intent, tagging, and routing function:
* Reads the normalized ticket and customer context bundle
* Classifies the primary intent and secondary topics
* Identifies product area, urgency, sentiment, language, and missing information
* Applies allowed categories, attributes, and helpdesk tags
* Calculates priority and SLA risk
* Routes the ticket to the right queue, owner, response workflow, or specialist team
* Escalates when confidence is low or the routing consequence is sensitive
## Recommended Components
| Need | Duckie component |
| --------------------------------- | ------------------------------------ |
| Interpret customer language | Autonomous triage classifier agent |
| Restrict tags to allowed values | Workflow branch logic and categories |
| Calculate priority and SLA | Routing workflow |
| Write tags and assignment | Helpdesk app tools or custom tools |
| Track confidence and routing path | Attributes and analytics |
| Review low-confidence cases | Slack escalation agent |
## Flow
```mermaid theme={null}
flowchart TD
Context["Ticket and customer context"]
Context --> Classifier["Intent and tag classifier agent"]
Classifier --> Output["Structured classification"]
Output --> Confidence{"Confidence threshold met?"}
Confidence -->|No| Escalate["Slack triage review"]
Confidence -->|Yes| Validate["Validate allowed tags"]
Escalate --> Reviewer["Reviewer decision"]
Reviewer --> Validate
Validate --> Priority["Priority and SLA workflow"]
Priority --> Route["Routing workflow"]
Route --> Writeback["Write tags, attributes, queue, and owner"]
Writeback --> Runs["Runs and analytics"]
```
## Suggested Taxonomy
Start small. A useful first taxonomy usually has broad intent, product area, urgency, and route dimensions.
| Dimension | Example values |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------- |
| **Intent** | access issue, billing question, bug report, how-to question, feature request, cancellation, complaint, account change |
| **Product area** | account, authentication, billing, dashboard, integration, notifications, API, mobile, data import |
| **Urgency** | low, normal, high, critical |
| **Sentiment** | neutral, confused, frustrated, angry, positive |
| **Customer segment** | enterprise, business, self-serve, trial, partner |
| **Route** | tier 1, billing support, technical support, account management, engineering triage, trust and safety |
| **Missing information** | no account match, unclear product area, missing screenshot, missing order ID, missing reproduction steps |
Avoid overfitting the first taxonomy. If reviewers cannot consistently explain the difference between two tags, start with one broader tag and split it after you have run data.
## Classifier Output Contract
Have the classifier return structured output. The routing workflow can then validate values and apply rules.
```json theme={null}
{
"primary_intent": "access issue",
"secondary_topics": ["authentication", "workspace permissions"],
"product_area": "account",
"urgency": "high",
"sentiment": "frustrated",
"missing_information": [],
"recommended_route": "technical support",
"confidence": 0.86,
"reasoning_summary": "Requester can log in but cannot access a workspace after a permission change."
}
```
## Routing Rules
Keep routing rules deterministic after classification.
| Rule | Example action |
| --------------------------------------- | ---------------------------------------------------------------------------- |
| Low confidence | Send to Slack triage review before writing assignment. |
| Known incident match | Tag as incident-related and route to incident macro or response workflow. |
| Priority customer and high urgency | Assign to priority queue and set elevated SLA. |
| Billing intent | Route to billing support unless account risk or refund approval is required. |
| Bug report with reproduction details | Route to technical support or engineering triage. |
| Bug report without reproduction details | Ask for missing details before routing to engineering. |
| Angry sentiment and repeated contact | Add management-review attribute or route to senior support. |
## Helpdesk Writeback
Common writebacks include:
* Tags
* Category or custom fields
* Priority
* SLA policy
* Queue or group
* Assignee
* Internal summary note
* Missing-information request
* Link to the Duckie run
Start with internal notes and shadow tags. Turn on assignment and priority writebacks only after replay testing and human review show that the routing rules are reliable.
## Related Docs
Define the allowed classification categories.
Track confidence, urgency, SLA risk, and route.
Configure the triage classifier agent.
Apply deterministic routing and writeback logic.
# MVP
Source: https://docs.duckie.ai/examples/ticket-triage/mvp
The smallest useful autonomous ticket triage system before broader escalation, reporting, and feedback loops
Start with an autonomous triage loop. Duckie should receive a ticket, attach customer context, classify intent and urgency, apply allowed tags or attributes, route high-confidence tickets, and send only required exceptions to an internal handoff channel.
This proves the system without starting with every escalation, reporting, and improvement loop at once.
The MVP is one intake record, one context bundle, one classifier output, one deterministic routing workflow, and one exception path for cases that should not be handled automatically.
## MVP Goal
By the end of the MVP, Duckie should reliably answer:
* What did the customer ask for?
* Which customer, account, product, and prior-ticket context matters?
* What intent, product area, urgency, sentiment, and route should be applied?
* Is the classification confident enough for autonomous routing?
* Which tags, attributes, queue, priority, or owner should be written?
* Which cases require a human handoff because policy, risk, or confidence requires it?
## Minimal Flow
```mermaid theme={null}
flowchart TD
Event["New ticket or message"]
Event --> Intake["Ticket triage deployment"]
Intake --> Normalize["Normalize ticket"]
Normalize --> Context["Fetch customer context"]
Context --> Classifier["Classify intent, tags, urgency, and route"]
Classifier --> Gate{"Autonomous path allowed?"}
Gate -->|Yes| Validate["Validate allowed values"]
Validate --> Priority["Calculate priority and SLA"]
Priority --> Writeback["Write tags, attributes, queue, or owner"]
Writeback --> Runs["Runs and analytics"]
Gate -->|No| Handoff["Send required exception handoff"]
Handoff --> Runs
```
## Build First
| Piece | What to build | Done when |
| ------------------ | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| Intake deployment | Trigger from helpdesk, inbox, chat, email, or webhook. | Duckie receives new tickets and stores the source ticket link. |
| Context enrichment | Fetch CRM, subscription, product, order, incident, and prior-ticket context. | Classifications use internal context instead of asking the customer for known information. |
| Triage classifier | Return intent, product area, urgency, sentiment, missing information, recommended route, and confidence. | The classifier produces structured output that the routing workflow can validate. |
| Routing workflow | Apply deterministic tag, priority, SLA, queue, and owner rules. | High-confidence tickets follow predictable support rules. |
| Helpdesk writeback | Write allowed tags, attributes, internal notes, queue, priority, or assignee. | Writebacks use only allowed values and link to the Duckie run. |
| Exception handoff | Route only required exceptions to an internal channel or specialist queue. | Low-confidence, sensitive, or high-risk tickets leave the autonomous path cleanly. |
## Defer Until the MVP Works
Add these after the first autonomous loop is trusted:
* Broad or highly granular taxonomies
* Multi-step specialist handoff automation
* Automatic sensitive category routing
* Assignment and SLA changes for low-confidence tickets
* Daily reporting and feedback agents
* Automated customer responses beyond simple missing-information requests
* Expansion to every support queue at once
## Required Human Handoffs
Keep humans in the loop only when the workflow cannot safely continue autonomously:
| Condition | Handoff |
| -------------------------------------------- | ----------------------------------------------------------------------------------- |
| Low classification confidence | Send the ticket, context, recommendation, and reason to an internal triage channel. |
| Sensitive or policy-bound category | Route to the team that owns the policy decision. |
| Expensive downstream action | Ask for confirmation before triggering the downstream workflow. |
| Missing account match or conflicting context | Route to support operations or the owning queue. |
| Tool failure blocks routing | Create an internal note and route to the fallback queue. |
The first live win is not a perfect taxonomy. It is consistent autonomous routing for known paths, with narrow exception handling for cases that actually need a person.
## When to Expand
Move beyond the MVP when:
* High-confidence routes are consistently correct
* Helpdesk writebacks use the expected tags, queues, priorities, and owners
* Exception handoffs are rare, specific, and answerable
* Support teams can explain the remaining reroutes and corrections
* The taxonomy has enough run data to justify splitting broad categories
* The main remaining delays are downstream handoffs that automation can remove
## Next Pages
After the MVP:
1. Read the [system map](/examples/ticket-triage/system-map) to see the full architecture.
2. Build [intake and customer context](/examples/ticket-triage/intake-and-customer-context).
3. Add [intent, tagging, and routing](/examples/ticket-triage/intent-tagging-and-routing).
4. Use the [rollout plan](/examples/ticket-triage/rollout-plan) before expanding live routing.
# Overview
Source: https://docs.duckie.ai/examples/ticket-triage/overview
A blueprint for support ticket triage with Duckie
This blueprint shows how to design a Duckie system for customer support ticket triage. It receives new tickets, adds customer context, classifies intent, applies tags and attributes, routes the work, and reports on triage health.
The recommended design uses deterministic workflows for the repeatable parts of triage and autonomous agents for the messy interpretation work.
## Start With the MVP
You do not need to launch the full triage system at once. Start with an autonomous loop that gathers context, classifies intent, applies allowed tags or attributes, routes high-confidence tickets, and sends only required exceptions to an internal handoff channel.
Then add broader escalation, reporting, feedback, and specialist handoff automation after the first loop is trusted.
Use the [MVP](/examples/ticket-triage/mvp) as the starting point if you are building this blueprint for the first time.
## What This System Does
The system helps a support team:
* Receive new tickets from a helpdesk, inbox, chat tool, or custom webhook
* Normalize the ticket into a consistent record
* Add customer context from CRM, subscription, order, product, or internal systems
* Detect customer intent, product area, urgency, sentiment, and missing information
* Apply tags, categories, and attributes for reporting and routing
* Route tickets to the right queue, owner, workflow, or specialist team
* Escalate low-confidence or high-risk tickets to an internal channel
* Post daily triage reporting to support stakeholders
* Use corrections and run data to improve tags, routing rules, and agent behavior
Ticket triage is a good first Duckie blueprint because it can start in shadow mode. Duckie can classify and recommend routing before it writes tags or changes ownership in the helpdesk.
## Design at a Glance
| Function | Duckie component | Why |
| ---------------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| Ticket intake | Helpdesk, inbox, chat, or webhook deployment | The system needs a clear entry point for new and updated tickets. |
| Customer context | Context enrichment workflow | Customer lookups should run in a repeatable order with clear fallbacks. |
| Intent and tagging | Autonomous triage classifier agent called by workflow | Customer language is messy and needs interpretation. |
| Priority and routing | Deterministic routing workflow | SLA, queue, owner, and priority rules should be auditable and consistent. |
| Escalation and handoff | Internal Slack escalation agent | Low-confidence or high-risk tickets need a required exception path without leaving the operational loop. |
| Daily reporting | Scheduler deployment running a Duckie Assistant reporting agent | Support leaders need recurring visibility into volume, risk, and automation health. |
| Feedback loop | Duckie Assistant feedback agent and analytics | Corrections should improve tags, workflows, guidelines, and tools. |
## Blueprint Pages
Start with autonomous routing for known ticket paths before adding broader loops.
See the full ticket triage architecture across channels, workflows, agents, and reports.
Normalize tickets and attach the context agents need to classify accurately.
Classify intent, apply tags, calculate priority, and route tickets.
Route unclear or risky tickets to an internal support channel.
Post daily triage reports and improve the system from corrections.
Move from shadow classification to live tagging and routing.
## Recommended Reading Order
1. Start with the [MVP](/examples/ticket-triage/mvp) to understand the smallest useful autonomous loop.
2. Read the [system map](/examples/ticket-triage/system-map) to see how the MVP expands into the full architecture.
3. Read [intake and customer context](/examples/ticket-triage/intake-and-customer-context) to understand what data the system needs.
4. Read [intent, tagging, and routing](/examples/ticket-triage/intent-tagging-and-routing) to see how classification turns into action.
5. Use [escalation and handoff](/examples/ticket-triage/escalation-and-handoff) only for required exception paths.
6. Add [reporting and feedback](/examples/ticket-triage/reporting-and-feedback) before live deployment.
7. Follow the [rollout plan](/examples/ticket-triage/rollout-plan) to expand safely.
## Related Docs
Learn the general workflow-plus-agent design pattern.
Configure categories, attributes, and resolution rules.
Connect Duckie to ticketing, messaging, webhook, and scheduled triggers.
Test historical tickets before live routing.
# Reporting and Feedback
Source: https://docs.duckie.ai/examples/ticket-triage/reporting-and-feedback
Use scheduled reports and run review to improve ticket triage
Ticket triage should improve as the support team corrects tags, reroutes tickets, and changes the taxonomy. Use Duckie Assistant agents for the reporting and feedback loops because they can inspect Duckie runs, summarize behavior, and propose improvements to Duckie configuration.
## What It Does
The reporting and feedback function:
* Posts a daily triage summary to a stakeholder channel
* Tracks ticket volume, intent mix, route distribution, SLA risk, and automation health
* Surfaces low-confidence classifications, reroutes, and tool failures
* Reviews human tag and routing corrections
* Proposes improvements to categories, attributes, workflows, guidelines, tools, and classifier instructions
* Measures whether updates improve future runs
## Recommended Components
| Need | Duckie component |
| ------------------- | ----------------------------------------- |
| Recurring report | Scheduler deployment |
| Reporting logic | Duckie Assistant reporting agent |
| Inspect Duckie runs | Duckie Assistant MCP or Runs API |
| Destination | Slack app tools |
| Feedback review | Duckie Assistant feedback agent |
| Track changes | Issue tracker or support operations queue |
## Reporting Flow
```mermaid theme={null}
sequenceDiagram
participant Scheduler as Scheduler deployment
participant Reporter as Duckie Assistant reporting agent
participant Runs as Duckie runs and analytics
participant Helpdesk as Helpdesk and CRM
participant Slack as Stakeholder channel
Scheduler->>Reporter: Start daily triage report
Reporter->>Runs: Read classifications, routes, and failures
Reporter->>Helpdesk: Read ticket outcomes and reroutes
Reporter->>Reporter: Summarize metrics, risks, and follow-ups
Reporter->>Slack: Post daily digest
Reporter->>Runs: Record report run output
```
## Feedback Flow
```mermaid theme={null}
flowchart TD
Runs["Runs and tool traces"]
Corrections["Human tag and routing corrections"]
Reroutes["Queue reroutes and reassignment"]
Runs --> Feedback["Duckie Assistant feedback agent"]
Corrections --> Feedback
Reroutes --> Feedback
Feedback --> Patterns["Recurring patterns and gaps"]
Patterns --> Proposals["Taxonomy, workflow, guideline, and tool updates"]
Proposals --> Review["Support operations review"]
Review --> Testing["Replay and batch testing"]
Testing --> Deploy["Updated triage deployment"]
Deploy --> Runs
```
## Report Contents
Include:
* New ticket volume by channel
* Intent and product-area breakdown
* Route and queue distribution
* Tickets at SLA risk
* Priority customer or high-risk tickets
* Classification confidence distribution
* Low-confidence escalations sent and resolved
* Missing context patterns
* Helpdesk writeback failures
* Reroutes after Duckie assignment
* Top recommended improvements
## Example Digest Shape
```text theme={null}
Daily ticket triage summary
Window: Previous business day
Volume:
- New tickets triaged: 412
- Routed automatically: 318
- Sent to triage review: 41
- Missing context: 28
Intent mix:
- Access issues: 24%
- Billing questions: 18%
- How-to questions: 17%
- Bug reports: 11%
Risk:
- 9 priority customers with high urgency
- 6 tickets at SLA risk
- 3 known-incident matches need customer updates
Automation health:
- 92% high-confidence classification
- 14 tickets rerouted by humans after assignment
- 5 helpdesk writeback retries
Follow-ups:
- Split "account issue" into access, permission, and profile-update tags
- Add product event lookup for integration setup tickets
```
## Improvement Actions
Common improvements include:
* Rename or merge confusing tags
* Add a new category for a repeated customer intent
* Change the classifier confidence threshold
* Add a routing rule for a customer segment or product area
* Add a missing context lookup tool
* Update the handoff note format
* Add a guardrail for sensitive tickets
* Update the daily report to show a metric the team actually uses
Use reporting to decide what to improve, then use replay testing to verify that the improvement helps before switching live routing behavior.
## Related Docs
Run the daily report on a schedule.
Build reporting and feedback agents for Duckie system improvement.
Monitor performance and trends.
Test triage changes against historical tickets.
# Rollout Plan
Source: https://docs.duckie.ai/examples/ticket-triage/rollout-plan
Move ticket triage from shadow mode to live tagging and routing
Ticket triage is a good candidate for staged rollout. Start by observing and recommending, then gradually turn on helpdesk writebacks as confidence improves.
## Rollout Stages
Start with a small set of intents, product areas, urgency levels, routes, and missing-context categories. Use historical tickets and support team feedback to define the initial values.
Connect read-only tools for helpdesk, CRM, subscription, product, order, incident, and prior-ticket context. Produce a stable context bundle before classification.
Create the ticket triage deployment in **Testing** mode. Have Duckie classify tickets and recommend tags without writing to the helpdesk.
Review a sample of tickets by intent, route, customer segment, and confidence band. Track where humans changed tags or routes.
Turn on internal notes, shadow tags, or custom fields first. Avoid assignment, priority, and SLA changes until the team trusts the routing rules.
Start with high-confidence intents that have simple deterministic routes, such as billing questions, access issues, or known-incident updates.
Route low-confidence or high-risk tickets to a Slack escalation agent, and schedule a Duckie Assistant reporting agent for stakeholder visibility.
Use a Duckie Assistant feedback agent to review corrections, reroutes, and failures. Expand the taxonomy and routing rules only after replay testing.
## Testing Plan
Use historical tickets before live routing:
* Replay tickets across all major intents and channels
* Include edge cases with missing account matches, angry customers, priority accounts, and known incidents
* Compare Duckie tags and routes against human-applied tags
* Review low-confidence cases separately
* Verify that helpdesk writebacks use only allowed values
* Confirm that escalation requests are concise and answerable
* Run batch tests after every taxonomy or routing change
## Success Metrics
Track:
* Percent of tickets triaged automatically
* Classification confidence by intent
* Human correction rate
* Reroute rate after initial assignment
* Time to first assignment
* SLA-at-risk tickets
* Missing context rate
* Escalation volume and resolution time
* Helpdesk writeback failures
* Support team satisfaction with handoff notes
## Launch Guardrails
Start conservatively:
* Require human review below a confidence threshold
* Keep sensitive categories out of live routing at first
* Use allowlists for helpdesk tags, queues, priorities, and custom fields
* Limit write tools to the smallest required scopes
* Keep assignment and SLA changes behind explicit workflow branches
* Post daily reports during rollout
* Review reroutes and corrections weekly
The safest first live action is usually an internal note with Duckie's suggested intent, tags, route, and reasoning. Assignment and SLA updates can come later.
## Related Docs
Move from Testing to Live when the triage path is ready.
Evaluate changes across groups of historical tickets.
Notify the team when triage failures or SLA risks appear.
Control risky or sensitive behavior.
# System Map
Source: https://docs.duckie.ai/examples/ticket-triage/system-map
The multi-channel, multi-agent architecture for support ticket triage
This system is built around a workflow backbone. Deployments bring tickets into Duckie, workflows control deterministic triage state, and agents handle interpretation, summarization, human review, and improvement loops.
## Operational Flow
```mermaid theme={null}
flowchart TD
Event["New ticket or message update"]
Event --> Intake["Ticket intake deployment"]
Intake --> Normalize["Normalize ticket workflow"]
Normalize --> Enrich["Customer context enrichment workflow"]
Enrich --> ContextCheck["Context completeness check"]
ContextCheck --> Triage["Triage workflow"]
ContextCheck --> Missing["Mark missing context"]
Missing --> Triage
Triage --> Classifier["Intent and tag classifier agent"]
Classifier --> Confidence["Confidence gate"]
Confidence --> Routing["Routing workflow"]
Confidence --> Escalation["Slack escalation agent"]
Escalation --> Leads["Support triage reviewers"]
Leads --> Decision["Structured routing decision"]
Decision --> Routing
Routing --> Tags["Apply tags and attributes"]
Tags --> Priority["Calculate priority and SLA"]
Priority --> Assignment["Assign queue or owner"]
Assignment --> NextStep["Choose next step"]
NextStep --> Response["Start response workflow or agent"]
NextStep --> Specialist["Specialist queue handoff"]
NextStep --> Clarify["Ask clarifying question"]
Response --> Update["Update ticket"]
Specialist --> Update
Clarify --> Update
Update --> Runs["Runs and analytics"]
```
## Reporting and Improvement Loop
```mermaid theme={null}
flowchart TD
Runs["Runs and analytics"]
Runs --> Scheduler["Scheduler deployment"]
Scheduler --> Reporting["Duckie Assistant reporting agent"]
Reporting --> Stakeholders["Support stakeholders channel"]
Runs --> Feedback["Duckie Assistant feedback agent"]
Corrections["Human tag and routing corrections"] --> Feedback
Stakeholders --> Feedback
Feedback --> Proposals["Improvement proposals"]
Proposals --> Review["Support operations review"]
Review --> Updates["Tags, workflows, guidelines, and tools"]
Updates --> Testing["Replay and batch testing"]
Testing --> Deploy["Updated deployments"]
```
## Component Responsibilities
| Component | Responsibility |
| ---------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| **Ticket intake deployment** | Starts the system from a helpdesk ticket, chat message, email, or webhook. |
| **Normalize ticket workflow** | Creates a clean ticket record with requester, channel, subject, body, attachments, and source links. |
| **Customer context enrichment workflow** | Fetches account, entitlement, product, order, incident, and prior-ticket context. |
| **Triage workflow** | Owns triage state, allowed branches, retries, and handoffs. |
| **Intent and tag classifier agent** | Interprets the ticket and returns intent, topic, urgency, sentiment, and confidence. |
| **Routing workflow** | Applies deterministic queue, owner, priority, and SLA rules from the classification result. |
| **Slack escalation agent** | Sends low-confidence or high-risk tickets to human reviewers and returns structured decisions. |
| **Duckie Assistant reporting agent** | Reads runs and operational data to post scheduled triage summaries. |
| **Duckie Assistant feedback agent** | Reviews corrections, reroutes, and failures to recommend system improvements. |
## Deterministic vs Autonomous
Use deterministic workflows for:
* Ticket normalization
* Required field checks
* Customer and account lookups
* Allowed tag value enforcement
* SLA and priority calculation
* Queue and owner assignment
* Helpdesk writebacks
* Retrying failed tools
* Calling reusable subflows
Use autonomous agents for:
* Understanding messy customer language
* Classifying ambiguous intent
* Summarizing customer context
* Identifying missing information
* Drafting handoff notes
* Explaining why a route was chosen
* Summarizing reporting trends
* Proposing taxonomy and workflow improvements
Keep final routing decisions deterministic. Let the classifier agent recommend intent and tags, then let a workflow apply the support team's routing rules.
## Deployment Inventory
| Deployment | Trigger | Target | Mode to start |
| -------------------------- | ------------------------------------------------------------------- | -------------------------------- | ------------- |
| **Ticket triage intake** | Ticket created, message received, email received, or custom webhook | Triage workflow | Testing |
| **Slack triage review** | Internal Slack channel or workflow escalation request | Escalation agent | Testing |
| **Daily triage report** | Scheduler, such as weekdays at 9 AM | Duckie Assistant reporting agent | Testing |
| **Triage feedback review** | Scheduler or manual internal request | Duckie Assistant feedback agent | Testing |
## Related Docs
Learn how deployments connect triggers to agents and workflows.
Run reporting and feedback loops on a schedule.
Track intent, topic, and route categories.
Track priority, confidence, SLA risk, and customer segment.
# Condition Routing and Agents
Source: https://docs.duckie.ai/examples/wismo-order-status/condition-routing-and-agents
Route WISMO cases to the right specialist agent or controlled workflow
Condition routing is the core of the WISMO system. The customer may ask the same question every time, but Duckie should not answer every order-status request the same way.
Use a workflow for the routing layer. Use specialist agents for the exception-specific investigation and response.
## Routing Workflow
```mermaid theme={null}
flowchart TD
Context["Canonical order context"]
Guard{"Guardrail triggered?"}
Normal{"ETA exists and within SLA?"}
Supplier{"Supplier backorder or allocation issue?"}
Warehouse{"Warehouse delay or handoff gap?"}
Split{"Multiple shipment states?"}
Carrier{"Carrier exception or stalled tracking?"}
DNR{"Delivered but customer disputes receipt?"}
Repeat{"Repeated contact?"}
Context --> Guard
Guard -->|Yes| Escalate["Priority escalation workflow"]
Guard -->|No| Normal
Normal -->|Yes| Standard["Standard status agent"]
Normal -->|No| Supplier
Supplier -->|Yes| SupplierAgent["Supplier backorder agent"]
Supplier -->|No| Warehouse
Warehouse -->|Yes| WarehouseAgent["Warehouse investigation agent"]
Warehouse -->|No| Split
Split -->|Yes| SplitAgent["Split shipment agent"]
Split -->|No| Carrier
Carrier -->|Yes| CarrierAgent["Carrier exception agent"]
Carrier -->|No| DNR
DNR -->|Yes| DNRAgent["Delivered-not-received agent"]
DNR -->|No| Repeat
Repeat -->|Yes| Escalate
Repeat -->|No| Standard
```
## Condition Matrix
| Condition | Trigger examples | Handler | Expected output |
| ------------------------------- | ------------------------------------------------------------------------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| Standard in transit | Carrier ETA exists, latest scan is current, no unresolved contacts | Standard status agent | Current status, ETA, tracking link, follow-up only if ETA changes. |
| Processing within SLA | OMS processing, WMS not started, still inside fulfillment SLA | Standard status agent | Expected ship-by date and clear next checkpoint. |
| Supplier backorder | Supplier ETA moved, allocation shortage, inbound PO delayed | Supplier backorder agent | Customer-safe explanation, wait/cancel/alternate options, next supplier check. |
| Allocation conflict | Inventory exists but is reserved or allocation failed | Supplier backorder agent | Explanation that availability changed before fulfillment, escalation if exception needed. |
| Warehouse pick delay | Pick pending beyond SLA, short pick, SKU quarantine, cycle-count mismatch | Warehouse investigation agent | Warehouse status, trace action, next checkpoint, escalation threshold. |
| Label created, no pickup | Label exists but no first physical scan after threshold | Carrier exception agent | Handoff explanation, trace action, follow-up checkpoint. |
| No tracking movement | No carrier scan for threshold period | Carrier exception agent | Carrier investigation status, expected investigation SLA, replacement/refund review if needed. |
| Delivery failed | Address issue, access issue, business closed, recipient unavailable | Carrier exception agent | Carrier reason, reattempt or pickup options, address-verification path. |
| Return-to-sender | Carrier status says return-to-sender or attempts exhausted | Carrier exception agent plus resolution workflow | Resolution choices and approval path. |
| Partial shipment | Some items shipped or delivered while others are pending | Split shipment agent | Itemized shipment map and per-shipment status. |
| Delivered not received | Carrier delivered, customer says not received | Delivered-not-received agent plus resolution workflow | Delivery proof review, investigation path, approval recommendation. |
| Fraud, payment, or address hold | OMS hold status, payment review, address verification | Guarded hold workflow plus communications agent | Approved verification request or internal escalation. |
| Repeated contact | Same order has 2+ WISMO contacts before resolution | Priority escalation workflow plus Slack agent | Summary of prior updates and human review request. |
## Specialist Agent Contracts
Each specialist agent should return the same output shape:
| Output | Description |
| ----------------------- | ----------------------------------------------------------------------------------------------------- |
| `condition_type` | The specific WISMO condition detected. |
| `customer_safe_summary` | Facts that can be shared with the customer. |
| `internal_summary` | Operational details for CX or operations only. |
| `recommended_action` | Answer, monitor, trace, investigate, replacement review, refund review, or escalate. |
| `customer_options` | Wait, cancel, alternate item, address correction, hold for pickup, replacement, or refund if allowed. |
| `follow_up_reason` | Why Duckie should check again later. |
| `next_follow_up_due_at` | The promised or internal follow-up time. |
| `confidence` | High, medium, or low. Low confidence should trigger review. |
## Agent Responsibilities
| Agent | Scope | Avoid |
| ----------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| Standard status agent | Normal processing, in-transit, delivered, and within-SLA states. | Inventing ETAs or using generic time windows. |
| Supplier backorder agent | Supplier ETA, allocation, preorder/backorder, and approved substitute paths. | Blaming suppliers or offering unapproved component alternatives. |
| Warehouse investigation agent | Pick/pack delay, short pick, SKU quarantine, label-created-no-handoff, and SLA breach. | Promising warehouse action that the WMS does not support. |
| Split shipment agent | Multi-shipment itemization and per-item status explanation. | Hiding that only part of the order shipped. |
| Carrier exception agent | No scan, no movement, delivery failure, return-to-sender, investigation status. | Treating label creation as physical carrier possession. |
| Delivered-not-received agent | Delivery proof, address, customer history, and replacement/refund review recommendation. | Approving high-value replacements without the resolution workflow. |
| Customer communications agent | Customer-facing replies and proactive updates. | Exposing internal risk signals or operational blame. |
## Keep the Workflow Small
Do not create a workflow branch for every carrier scan code, supplier note, warehouse exception, or SKU-specific rule. Keep the routing workflow focused on stable condition families, then update specialist agent instructions, runbooks, knowledge, and guardrails as operations change.
The routing workflow should decide who handles the case. The specialist agent should decide how to interpret the facts and what customer-safe explanation to draft within its scope.
## Next Pages
After routing and specialist agents:
1. Add [proactive follow-up](/examples/wismo-order-status/proactive-follow-up).
2. Add [escalation and resolution](/examples/wismo-order-status/escalation-and-resolution).
3. Use the [rollout plan](/examples/wismo-order-status/rollout-plan) before expanding live traffic.
# Escalation and Resolution
Source: https://docs.duckie.ai/examples/wismo-order-status/escalation-and-resolution
Route WISMO exceptions, approvals, and high-impact actions through a structured human loop
Escalation should be a structured decision path, not a loose side conversation. Every escalation should include a case ID, order facts, detected condition, customer impact, requested decision, options, deadline, and return path.
## Escalation Flow
```mermaid theme={null}
sequenceDiagram
participant Origin as Origin WISMO run
participant Bridge as Escalation bridge tool
participant Slack as Review Slack thread
participant Reviewer as CX, shipping, supply-chain, or fraud reviewer
participant Agent as Slack escalation agent
participant Case as WISMO case
Origin->>Bridge: create_escalation(case_id, question, options, deadline)
Bridge->>Slack: post review thread with order and shipment context
Reviewer->>Slack: reply with decision or missing info
Slack->>Agent: thread reply triggers run
Agent->>Bridge: record_escalation_answer(case_id, decision, rationale)
Bridge->>Case: add internal note and update saved values
Bridge-->>Origin: structured answer available
Origin->>Origin: continue workflow with reviewer decision
```
## Escalation Triggers
| Trigger | Why it escalates |
| ------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
| Customer contacted about the same order 2+ times | Repeated contact indicates stale or unsatisfying prior updates. |
| Order value exceeds action threshold | Replacement, refund, and reship decisions affect money and inventory. |
| Supplier has no ETA for a build-critical component | The customer needs a judgment-based choice, not a generic delay response. |
| Alternate component may be needed | Compatibility, price, and inventory rules may require human approval. |
| Carrier says delivered, but customer disputes receipt | Delivery proof, risk signals, and policy thresholds matter. |
| Fraud, payment, or address hold exists | Customer-facing language and next steps must be restricted. |
| Customer threatens chargeback, legal action, or manager escalation | Risk and relationship handling need a human owner. |
| Backend data conflicts across systems | Duckie should not choose a customer-visible answer from contradictory facts. |
## Resolution Eligibility Workflow
Use a workflow for deterministic action gates:
```mermaid theme={null}
flowchart TD
Start["Recommended action from specialist agent"]
Type{"Action type"}
Replacement["Check replacement eligibility"]
Refund["Check refund eligibility"]
Cancel["Check cancellation eligibility"]
Address["Check address-change eligibility"]
Threshold{"Approval required?"}
Draft["Create draft action and customer message"]
Approval["Ask human reviewer"]
Execute["Execute approved action"]
Deny["Record denial and next safe option"]
Notify["Customer communications agent"]
Start --> Type
Type -->|Replacement| Replacement --> Threshold
Type -->|Refund| Refund --> Threshold
Type -->|Cancellation| Cancel --> Threshold
Type -->|Address change| Address --> Threshold
Threshold -->|No| Draft --> Execute --> Notify
Threshold -->|Yes| Approval
Approval -->|Approved| Execute --> Notify
Approval -->|Denied or changed| Deny --> Notify
```
## Action Gates
| Action | Gate before execution |
| --------------------- | ---------------------------------------------------------------------------------------------------------- |
| Replacement order | Inventory availability, order value, customer history, item class, delivery proof, and approval threshold. |
| Refund | Refund eligibility, payment state, delivery state, return state, amount threshold, and approval threshold. |
| Cancellation | Fulfillment stage, carrier handoff status, policy eligibility, and refund timing. |
| Address correction | Identity verification, shipment stage, carrier support, fraud/address-hold state, and policy approval. |
| Alternate item | Compatibility, price difference, stock status, approved substitute list, and customer consent. |
| Carrier investigation | Carrier status, time since last scan, route threshold, and duplicate claim check. |
## Slack Review Request
Each Slack review thread should include:
* Case ID and Duckie run link
* Customer and order identifiers
* Order value band and relevant threshold
* Detected WISMO condition
* Current OMS, WMS, supplier, carrier, and support-history facts
* Prior customer updates and promised follow-ups
* Recommended action
* Allowed reviewer options
* Deadline for decision
## Reviewer Decision Shape
The Slack escalation agent should return a structured decision:
| Field | Example |
| ----------------------- | -------------------------------------------------------------------------- |
| `decision` | approve, deny, request\_changes, manual\_takeover |
| `approved_action` | replacement, refund, cancel, address\_change, carrier\_investigation, wait |
| `rationale` | Short internal explanation. |
| `customer_safe_message` | Optional wording or facts that can be shared. |
| `owner` | Reviewer or queue responsible for next step. |
| `deadline` | When the next action or follow-up is due. |
## Guardrails
* Never approve replacement or refund actions above threshold without human approval.
* Never expose fraud scores, payment-risk signals, supplier blame, margin, or internal allocation notes.
* Never update an address after shipment without required verification and policy approval.
* Escalate delivered-not-received cases when proof of delivery is ambiguous or value exceeds threshold.
* Escalate repeated contacts, angry customers, legal threats, chargeback threats, and data conflicts.
## Next Pages
After escalation and resolution:
1. Add [proactive follow-up](/examples/wismo-order-status/proactive-follow-up) for backend-triggered updates.
2. Use the [rollout plan](/examples/wismo-order-status/rollout-plan) before enabling high-impact write actions.
# Intake and Order Context
Source: https://docs.duckie.ai/examples/wismo-order-status/intake-and-order-context
Normalize customer WISMO requests and backend events into a consistent case context
WISMO quality depends on the context Duckie has before it responds. The intake layer should create or update a stable WISMO case, identify the order, and build a canonical context object that downstream workflows and agents can trust.
## Entry Points
| Entry point | Typical trigger | First action |
| --------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| Customer ticket | New ticket, public reply, or WISMO tag | Identify customer and likely order. |
| Chat message | Authenticated chat or widget intent | Use session identity and recent order data first. |
| Email reply | Customer replies to an existing thread | Reuse the existing WISMO case and order if possible. |
| OMS event | Order status, hold, cancellation, or fulfillment change | Find existing case or create proactive monitoring state. |
| WMS event | Pick, pack, short-pick, label, or handoff update | Update fulfillment state and decide whether a customer update is needed. |
| Supplier event | ETA, allocation, stockout, or inbound receiving update | Route to supplier backorder handling or proactive monitor. |
| Carrier event | Scan, no movement, delivery attempt, return-to-sender, or delivered update | Route to carrier handling or proactive monitor. |
| Scheduled sweep | Follow-up due, stale tracking, or missed webhook check | Rehydrate the WISMO case and compare current status to last update. |
## Intake Contract
Every WISMO run should produce a structured case object before it routes to a specialist:
| Field | Purpose |
| ------------------------- | ------------------------------------------------------------------------------- |
| `wismo_case_id` | Stable key for the customer/order issue. |
| `source_channel` | Ticket, chat, email, webhook, or scheduler. |
| `customer_id` | Customer identity from authenticated context, ticket metadata, or lookup. |
| `order_id` | Target order. Ask for this only when multiple orders are plausible. |
| `shipment_ids` | Shipment groups attached to the order. |
| `ticket_id` | Active support conversation, if one exists. |
| `prior_contact_count` | Number of WISMO contacts for the same order. |
| `last_customer_update_at` | Most recent public status message to the customer. |
| `last_status_sent` | Status facts already communicated. |
| `next_follow_up_due_at` | Promised next checkpoint, if any. |
| `restricted_state` | Fraud, payment, address, legal, VIP, high-value, or confidence guardrail flags. |
## Order Context Workflow
Build order context in a repeatable order. This keeps the downstream agents focused on interpretation instead of basic data plumbing.
```mermaid theme={null}
flowchart TD
Start["Start WISMO run"]
Customer["Lookup customer"]
Orders["Find candidate orders"]
Select{"One clear order?"}
Ask["Ask for order number or verification"]
OMS["Lookup OMS order detail"]
Shipments["Lookup shipments"]
WMS["Lookup WMS fulfillment state"]
Inventory["Lookup inventory and allocation"]
Supplier["Lookup supplier status"]
Carrier["Lookup carrier tracking"]
History["Lookup support history"]
Save["Save canonical order context"]
Next["Route to investigation or condition routing"]
Start --> Customer --> Orders --> Select
Select -->|No| Ask --> Orders
Select -->|Yes| OMS --> Shipments --> WMS --> Inventory --> Supplier --> Carrier --> History --> Save --> Next
```
## Required Context
| Source | Minimum fields |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------- |
| Customer profile | Customer ID, email, customer tier, contact preferences, risk-safe flags. |
| OMS | Order status, order date, promised ship date, promised delivery date, payment state, hold state, cancellation eligibility. |
| Order items | SKU, quantity, item value, item status, shipment mapping, replacement/refund eligibility. |
| WMS | Pick status, pack status, short-pick status, label state, handoff confirmation, warehouse queue. |
| Inventory | On-hand, reserved, inbound, allocation state, approved substitute availability. |
| Supplier | Purchase order, supplier ETA, allocation note, inbound receiving state, ETA confidence. |
| Carrier | Tracking number, carrier status, latest scan, exception reason, ETA, proof of delivery, investigation status. |
| Support history | Prior contacts, previous customer promises, internal notes, escalation status, open tickets. |
## When to Use an Investigation Agent
Call the order investigation agent when:
* OMS says shipped but WMS has no handoff confirmation
* Carrier tracking has a label but no first physical scan
* Inventory shows stock but allocation failed
* Supplier ETA and promised customer date conflict
* Multiple shipments contain overlapping or missing items
* The customer references an order that does not match account data
* The support history contains a newer human update than backend data
The investigation agent should return:
* Current best understanding of the order state
* Conflicting facts, if any
* Recommended WISMO condition
* Customer-safe facts
* Internal-only facts that must not be shown to the customer
* Recommended next action and confidence
## Guardrails
* Do not ask for an order number if authenticated metadata identifies one clear order.
* Do not expose fraud, payment-risk, supplier blame, margin, or internal allocation notes to customers.
* Do not proceed to a customer-visible answer when customer identity is ambiguous.
* Do not treat "label created" as carrier possession unless handoff or first scan is confirmed.
* Do not overwrite a newer human reply with an older backend status.
## Next Pages
After intake and context:
1. Build [condition routing and agents](/examples/wismo-order-status/condition-routing-and-agents).
2. Add [proactive follow-up](/examples/wismo-order-status/proactive-follow-up).
3. Add [escalation and resolution](/examples/wismo-order-status/escalation-and-resolution) for guarded cases.
# MVP
Source: https://docs.duckie.ai/examples/wismo-order-status/mvp
The smallest useful WISMO system before full exception handling, approvals, and proactive automation
Start with one autonomous WISMO loop that can identify the order, gather live context, detect a small set of common conditions, reply safely, and save a follow-up commitment.
This proves the core value without starting with every supplier, warehouse, carrier, and replacement/refund edge case.
The MVP is one intake path, one canonical order context, one routing workflow, three specialist handlers, one customer communications agent, and one follow-up monitor.
## MVP Goal
By the end of the MVP, Duckie should reliably answer:
* Which customer, order, shipment, and support case is this?
* What does the OMS, WMS, carrier, and support history say right now?
* Is the order normal, split, delayed in fulfillment, or stalled in carrier tracking?
* What can Duckie safely tell the customer without overpromising?
* Should Duckie answer, monitor, ask for more information, or escalate?
* When did Duckie promise the next update, and what event should trigger it?
## Minimal Flow
```mermaid theme={null}
flowchart TD
Message["Customer WISMO message"]
Message --> Intake["WISMO intake deployment"]
Intake --> Identify["Identify customer, order, shipment, and case"]
Identify --> Context["Build order context"]
Context --> Route["Condition routing workflow"]
Route -->|Normal ETA| Standard["Standard status agent"]
Route -->|Multiple shipments| Split["Split shipment agent"]
Route -->|No scan or no movement| Carrier["Carrier exception agent"]
Route -->|Low confidence or restricted state| Escalate["Escalate to human review"]
Standard --> Reply["Customer communications agent"]
Split --> Reply
Carrier --> Reply
Reply --> Followup["Save follow-up commitment"]
Escalate --> Internal["Internal note or Slack review"]
```
## Build First
| Piece | What to build | Done when |
| ----------------------------- | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| Intake deployment | Trigger from a WISMO tag, chat intent, email rule, or helpdesk group. | Duckie creates or finds a stable WISMO case ID. |
| Order lookup | Find the order from requester email, authenticated customer ID, ticket metadata, or order number. | Duckie asks for order ID only when identity or order selection is ambiguous. |
| Order context workflow | Pull canonical OMS, WMS, carrier, and support-history fields. | Downstream agents receive one structured context object. |
| Condition routing workflow | Route normal status, partial shipment, carrier stall, low-confidence, and restricted cases. | The branch label is saved as a WISMO condition. |
| Standard status agent | Explain normal processing, in-transit status, delivered status, and customer-safe ETA. | Replies include status, source, next action, and follow-up only when needed. |
| Split shipment agent | Itemize shipped, delivered, and pending items. | Customers can see which component maps to which shipment. |
| Carrier exception agent | Explain label-created-no-scan, no movement, delivery attempt, and tracking-resumed cases. | Duckie starts allowed traces or escalates when action is not allowed. |
| Customer communications agent | Draft and send customer replies using approved tone and facts. | Responses never invent ETAs or generic windows. |
| Follow-up state | Save `next_follow_up_due_at`, `last_status_sent`, and `follow_up_reason`. | Promised follow-ups can be audited and retriggered. |
## Defer Until the MVP Works
Add these after the first loop is trusted:
* Supplier allocation and backorder investigation
* Warehouse short-pick, quarantine, or cycle-count exceptions
* Delivered-not-received review
* Replacement, refund, cancellation, and address-change write actions
* Broad proactive outbound messaging for every backend event
* Advanced customer segmentation, VIP paths, or SKU-specific rules
* Automated alternate component recommendations
## Required Human Handoffs
Keep humans in the loop only when policy, risk, or missing authority requires it:
| Condition | Handoff |
| ----------------------------------------------------------- | ---------------------------------------------------------------------------- |
| Order value exceeds replacement/refund threshold | Route to the owner with order value, shipment facts, and recommended action. |
| Fraud, payment, or address hold is present | Route without exposing restricted risk signals to the customer. |
| Data conflicts across OMS, WMS, carrier, or support history | Route with the conflict called out clearly. |
| Same customer contacted support 2+ times for the same order | Route as priority review with prior replies summarized. |
| Duckie cannot identify one clear order | Ask the customer for verification or route to manual review. |
Do not use the MVP to automate high-impact write actions. Duckie can prepare drafts and recommendations, but replacement, refund, cancellation, and address-change actions should remain gated until the policy and approval path are tested.
## When to Expand
Move beyond the MVP when:
* Order identification works reliably for the selected channel
* The canonical context object is stable
* Normal, split-shipment, and carrier-stall replies pass QA
* Low-confidence and restricted cases escalate cleanly
* Follow-up commitments are saved and retriggered reliably
* Historical WISMO tickets pass replay and batch tests
## Next Pages
After the MVP:
1. Read the [system map](/examples/wismo-order-status/system-map) to see the full architecture.
2. Build [intake and order context](/examples/wismo-order-status/intake-and-order-context).
3. Add [condition routing and agents](/examples/wismo-order-status/condition-routing-and-agents).
4. Use the [rollout plan](/examples/wismo-order-status/rollout-plan) before expanding live scope.
# Overview
Source: https://docs.duckie.ai/examples/wismo-order-status/overview
A blueprint for automating WISMO order-status operations with Duckie
This blueprint shows how to design a Duckie system for WISMO ("Where Is My Order?") operations in e-commerce. The example is a retailer that sells high-value computer parts, but the same pattern works for any order-status operation with OMS, warehouse, supplier, carrier, and support-history data.
The recommended design uses deterministic workflows for the repeatable control points and autonomous specialist agents for ambiguous investigation, customer-safe explanation, and internal decision support.
## Start With the MVP
You do not need to launch the full WISMO system at once. Start with a narrow loop that identifies the customer and order, pulls live order context, detects the most common WISMO condition, answers allowed status questions, and schedules a proactive follow-up when the status may change.
Then add supplier backorders, warehouse exceptions, carrier investigations, delivered-not-received review, replacement/refund approval, and broader proactive event handling after the first loop is trusted.
Use the [MVP](/examples/wismo-order-status/mvp) as the starting point if you are building this blueprint for the first time.
## What This System Does
The system helps a CX and operations team:
* Receive WISMO questions from chat, email, ticketing, or backend events
* Identify the customer, order, shipment, and active support case
* Pull live OMS, WMS, supplier, inventory, carrier, and support-history context
* Route the same customer intent to the right specialist handler based on actual order state
* Send factual customer replies without generic status copy or unsupported ETA promises
* Proactively update customers when backend tracking, fulfillment, or supplier status changes
* Escalate high-value, repeated-contact, fraud/address-hold, or ambiguous cases to the right internal team
* Gate replacement, refund, cancellation, and address-change actions behind policy and approval
* Track conditions, outcomes, follow-up commitments, and automation quality
WISMO is not primarily an order lookup problem. The hard part is deciding what to say and do when the order state is stale, blocked, split across systems, or operationally ambiguous.
## Design at a Glance
| Function | Duckie component | Why |
| ------------------------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
| Customer and event intake | Deployments plus WISMO intake workflow or triage agent | WISMO can start from tickets, chat, email replies, carrier events, supplier updates, or scheduled checks. |
| Order context | Order context workflow | Canonical OMS, WMS, supplier, inventory, carrier, hold, and support-history fields should be pulled in a repeatable order. |
| Ambiguous investigation | Order investigation agent | Conflicting or incomplete system data needs flexible tool choice and summarization. |
| Condition routing | Condition routing workflow | Clear status rules, approval thresholds, and follow-up commitments should be auditable. |
| Specialist handling | Standard status, supplier, warehouse, split shipment, carrier, and delivered-not-received agents | The expensive variation belongs in agent instructions, runbooks, knowledge, and guardrails. |
| Proactive follow-up | Proactive monitor workflow plus customer communications agent | Backend changes should trigger customer updates before another ticket is opened. |
| Resolution and approval | Resolution eligibility workflow plus Slack escalation agent | Replacement, refund, cancellation, and address-change decisions need controlled gates. |
| Analytics | Categories, attributes, resolution rules, and run review | Teams need to see which WISMO conditions are resolved, monitored, escalated, or blocked. |
## Blueprint Pages
Start with the smallest useful WISMO loop before adding all exception handling.
See the workflow backbone, specialist agents, proactive follow-up, and human review path.
Normalize customer requests and backend events into a consistent WISMO case.
Route order states to the right specialist agent or controlled workflow.
Send updates when backend tracking, supplier, warehouse, or shipment status changes.
Route human decisions and approval-gated actions through a structured internal loop.
Move from shadow-mode WISMO handling to broader live proactive operations.
## Recommended Reading Order
1. Start with the [MVP](/examples/wismo-order-status/mvp) to understand the smallest useful version.
2. Read the [system map](/examples/wismo-order-status/system-map) to see how the components connect.
3. Read [intake and order context](/examples/wismo-order-status/intake-and-order-context) to understand the data contract.
4. Read [condition routing and agents](/examples/wismo-order-status/condition-routing-and-agents) to map order states to handlers.
5. Add [proactive follow-up](/examples/wismo-order-status/proactive-follow-up) once backend events are reliable.
6. Add [escalation and resolution](/examples/wismo-order-status/escalation-and-resolution) before enabling high-impact actions.
7. Follow the [rollout plan](/examples/wismo-order-status/rollout-plan) before expanding live traffic.
## Related Docs
Learn the general workflow-plus-agent design pattern.
Decide when to use workflows, agents, runbooks, and human review.
Connect Duckie to ticketing, messaging, webhook, and scheduled triggers.
Test historical WISMO tickets before live customer replies.
# Proactive Follow-Up
Source: https://docs.duckie.ai/examples/wismo-order-status/proactive-follow-up
Send WISMO updates when backend order, supplier, warehouse, or carrier status changes
Proactive follow-up is the primary differentiator for WISMO. The system should not wait for a customer to open another ticket when backend status changes.
The proactive monitor should remain deterministic: deduplicate events, load saved commitments, compare the new status to the last customer update, and decide whether any action is needed. When the change needs interpretation or wording, the monitor calls a specialist agent and the customer communications agent.
## Event Decision Flow
```mermaid theme={null}
flowchart TD
Event["Backend status event or scheduled sweep"]
Dedupe["Deduplicate by order, shipment, event type, and status"]
Case["Load WISMO case state"]
NewInfo{"New customer-relevant information?"}
OpenCase{"Active support case exists?"}
NeedsAgent{"Needs interpretation?"}
Specialist["Call relevant specialist agent"]
Draft["Customer communications agent drafts update"]
Existing["Update active ticket or conversation"]
Outbound["Create proactive outbound message"]
Escalate{"Human review required?"}
Slack["Create Slack escalation"]
Save["Save last_status_sent and next_follow_up_due_at"]
End["No-op or close monitoring"]
Event --> Dedupe --> Case --> NewInfo
NewInfo -->|No| End
NewInfo -->|Yes| Escalate
Escalate -->|Yes| Slack --> Save
Escalate -->|No| NeedsAgent
NeedsAgent -->|Yes| Specialist --> Draft
NeedsAgent -->|No| Draft
Draft --> OpenCase
OpenCase -->|Yes| Existing --> Save
OpenCase -->|No| Outbound --> Save
```
## Recommended Triggers
| Backend event | Proactive behavior |
| ------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| Supplier ETA moved later by more than threshold | Notify customer, explain the delay, offer allowed options, and save next supplier check. |
| Supplier ETA becomes available after unknown ETA | Notify customer with the new date and confidence caveat. |
| Warehouse pick exceeds SLA | Notify customer before they ask and commit to the next checkpoint. |
| Label created but no first carrier scan after threshold | Notify customer that handoff is being verified and start allowed trace path. |
| Carrier scan resumes after stalled tracking | Notify customer that movement resumed and provide updated ETA if available. |
| Delivery attempt failed | Notify customer with carrier reason and available reattempt, pickup, or address options. |
| Return-to-sender begins | Notify customer and route refund/replacement choices through approval thresholds. |
| Partial shipment created | Notify customer that items are shipping separately and itemize each shipment. |
| Delivered event received for an open WISMO case | Close the loop with delivery confirmation and reopen path if there is a problem. |
| Follow-up due and no backend change | Send a brief checkpoint if Duckie promised it, or escalate before the promise is missed. |
## Saved Values
| Saved value | Purpose |
| ---------------------------- | ------------------------------------------------ |
| `wismo_case_id` | Stable case key. |
| `order_id` and `shipment_id` | Prevent duplicate updates across related events. |
| `condition_type` | Current routed condition. |
| `last_backend_status_seen` | Webhook idempotency and dedupe key. |
| `last_customer_update_at` | Prevent over-messaging. |
| `last_status_sent` | Avoid repeating the same facts. |
| `next_follow_up_due_at` | Make customer promises auditable. |
| `follow_up_reason` | Explain why the next run should occur. |
| `customer_action_options` | Keep offered options consistent across runs. |
| `human_owner` | Track ownership for escalated cases. |
## Messaging Rules
* Do not send duplicate updates for the same backend status.
* Do not send a proactive update if a human support teammate sent a newer public reply with the same facts.
* Update an existing ticket or conversation when one is open.
* Create a proactive outbound conversation only when there is no active support thread and policy allows it.
* If the status is worse than the last update, say what changed and what Duckie is doing next.
* If the status improves, close the loop and reduce the chance of another inbound WISMO ticket.
* If Duckie promised a follow-up and there is no new backend update, send a brief checkpoint or escalate before the promised time is missed.
## Proactive Update Template
Use this structure for customer-facing updates:
1. What changed since the last update
2. What Duckie knows from the order, warehouse, supplier, or carrier systems
3. What Duckie is doing next
4. Any customer options, if policy allows them
5. When the customer will hear back again
Do not use proactive updates as generic marketing or reassurance copy. The update should contain a real status change, a promised checkpoint, or a useful action path.
## Test Cases
Before enabling live proactive messages, replay cases for:
* Duplicate carrier webhooks
* Supplier ETA moving later, then earlier
* Human reply after Duckie saved a follow-up
* Label created without pickup scan
* Partial shipment with one delivered item and one pending item
* Delivered-not-received case that should escalate
* Follow-up due with no backend change
## Next Pages
After proactive follow-up:
1. Add [escalation and resolution](/examples/wismo-order-status/escalation-and-resolution).
2. Use [rollout plan](/examples/wismo-order-status/rollout-plan) to expand event coverage safely.
# Rollout Plan
Source: https://docs.duckie.ai/examples/wismo-order-status/rollout-plan
Move the WISMO blueprint from testing to live customer-facing operations
Roll out WISMO automation in phases. Start with shadow-mode classification and internal notes, then expand customer-visible replies, proactive updates, specialist agents, and approval-gated write actions as quality stabilizes.
## Phase 1: Observe and Model
Goal: create the WISMO data contract and validate routing on historical tickets.
Build:
* Customer WISMO intake deployment in Testing mode
* Order context workflow
* Condition routing workflow
* Standard status agent
* Split shipment agent
* Carrier exception agent for simple no-scan and no-movement cases
* Initial categories, attributes, and resolution rules
Keep disabled:
* Customer-visible proactive outbound messages
* Replacement, refund, cancellation, and address-change writes
* Supplier and warehouse edge cases beyond internal notes
Exit criteria:
* Historical WISMO tickets map to the expected condition labels
* Order lookup works for the selected channel
* Internal-note drafts are factual and do not overpromise
* Restricted states escalate reliably
## Phase 2: Reactive WISMO on One Channel
Goal: answer allowed WISMO requests in one controlled live channel.
Build:
* Live deployment for a narrow chat or Zendesk WISMO group
* Read-only OMS, WMS, carrier, inventory, and support-history tools
* Customer communications agent for standard, split-shipment, and simple carrier replies
* Saved follow-up commitments
Guardrails:
* Keep replacement/refund/address/cancellation actions human-owned
* Escalate high-value, repeated-contact, fraud/address-hold, and low-confidence cases
* Suppress replies when a human teammate has sent a newer update
Exit criteria:
* CSAT or QA score is stable for covered conditions
* First-touch resolution improves for selected WISMO traffic
* Escalations contain enough context for fast review
* Follow-up commitments are saved correctly
## Phase 3: Proactive Event Handling
Goal: update customers before they open another ticket.
Build:
* OMS, WMS, supplier, and carrier webhook deployments in Testing mode
* Proactive follow-up monitor
* Duplicate suppression for backend events
* Customer-visible proactive updates for low-risk events
Start with:
* Partial shipment created
* Carrier tracking resumed
* Delivery attempt failed
* Label created with no first scan after threshold
* Follow-up due with no backend change
Exit criteria:
* Duplicate updates are suppressed
* Existing tickets are updated instead of creating unnecessary new conversations
* Proactive updates contain real status changes or promised checkpoints
* Missed follow-ups are visible in analytics
## Phase 4: Exception Agents and Slack Review
Goal: handle more ambiguous WISMO conditions while keeping risky decisions gated.
Build:
* Supplier backorder agent
* Warehouse investigation agent
* Delivered-not-received agent
* Resolution eligibility workflow
* Slack escalation agent and review channels
* Draft replacement, refund, cancellation, and address-change actions
Guardrails:
* High-impact actions require approval
* Alternate component recommendations require approved compatibility data or human review
* Fraud, payment, and address-hold cases always use restricted language and escalation paths
Exit criteria:
* Slack reviewers can approve, deny, request changes, or take over manually
* Reviewer decisions return to the WISMO case as structured values
* Draft actions match policy and thresholds
* Delivered-not-received cases escalate when proof is weak or value is high
## Phase 5: Expand Once Proven
Goal: scale coverage after the quality loop is stable.
Expand:
* From chat to email and broader ticket groups
* From low-risk proactive events to supplier and warehouse exceptions
* From draft-only actions to approved write actions where policy allows
* From a few condition labels to the full WISMO analytics taxonomy
Monitor:
* WISMO deflection rate by channel
* First-touch resolution for WISMO tickets
* Proactive no-ticket rate
* Time from backend exception to first customer update
* Percent of promised follow-ups sent before `next_follow_up_due_at`
* Repeated-contact rate per order
* Escalation rate by WISMO condition
* Tool failure rate by system
* CSAT or QA score by condition
## Batch Test Suite
Before expanding live scope, build tests for:
* Normal ETA within SLA
* Processing within SLA
* Split shipment with one delivered item and one pending item
* Supplier backorder with unknown ETA
* Supplier ETA update after unknown ETA
* Warehouse pick delay
* Label created but no carrier pickup scan
* Carrier no movement
* Delivery failed because of address issue
* Return-to-sender
* Delivered-not-received below threshold
* Delivered-not-received above threshold
* Fraud or address hold
* Repeated customer contact
* Tool failure or missing order data
## Launch Checklist
* Deployments start in Testing mode
* Write actions are disabled until approval paths are tested
* Guardrails are configured for restricted states
* Knowledge tags are scoped to WISMO policy, shipping SLAs, supplier backorders, warehouse fulfillment, carrier exceptions, and replacement/refund rules
* Saved values include case ID, condition, last status sent, and next follow-up time
* Analytics categories and attributes are configured before launch
* Replay and batch tests pass for the launch channel
## Next Steps
After rollout, review runs weekly for:
* Repeated human corrections
* Conditions with high escalation rate
* Tool failures or stale data sources
* Follow-up commitments that were late or missed
* Customer replies that indicate the update was unclear
* Conditions that should move from manual review to guarded automation
# System Map
Source: https://docs.duckie.ai/examples/wismo-order-status/system-map
The workflow backbone, specialist agents, and proactive loops for WISMO operations
This system is built around a deterministic workflow backbone. Deployments bring WISMO work into Duckie, workflows hold case state and approval gates, and autonomous agents handle investigation, interpretation, customer communication, and internal review.
## Operational Flow
```mermaid theme={null}
flowchart TD
Sources["Ticket, chat, email, OMS, WMS, supplier, carrier, or scheduler event"]
Sources --> Deployments["Deployments and filters"]
Deployments --> Intake["WISMO intake workflow or triage agent"]
Intake --> Orchestrator["WISMO orchestration workflow"]
Orchestrator --> Context["Order context workflow"]
Context --> Investigate["Order investigation agent"]
Investigate --> Router["Condition routing workflow"]
Router --> Standard["Standard status agent"]
Router --> Supplier["Supplier backorder agent"]
Router --> Warehouse["Warehouse investigation agent"]
Router --> Split["Split shipment agent"]
Router --> Carrier["Carrier exception agent"]
Router --> DNR["Delivered-not-received agent"]
Router --> Hold["Guarded hold workflow"]
Standard --> Comms["Customer communications agent"]
Supplier --> Comms
Warehouse --> Comms
Split --> Comms
Carrier --> Comms
DNR --> Resolution["Resolution eligibility workflow"]
Hold --> Comms
Resolution --> Approval["Human approval workflow"]
Approval --> Slack["Slack escalation agent"]
Slack --> Reviewers["CX, shipping, supply-chain, or fraud reviewer"]
Reviewers --> Decision{"Reviewer decision"}
Decision -->|Approved| Execute["Execute approved action or create final draft"]
Decision -->|Needs change| Orchestrator
Decision -->|Manual takeover| Manual["Manual handling queue"]
Comms --> Followup["Proactive follow-up monitor"]
Execute --> Comms
Followup --> Orchestrator
Manual --> Runs["Runs and analytics"]
Comms --> Runs
```
## Proactive Event Loop
```mermaid theme={null}
sequenceDiagram
participant Backend as OMS, WMS, supplier, or carrier
participant Deployment as Duckie event deployment
participant Monitor as Proactive follow-up monitor
participant Case as WISMO case state
participant Specialist as Specialist agent
participant Comms as Customer communications agent
participant Channel as Ticketing or messaging channel
Backend->>Deployment: status_changed(order_id, shipment_id, event_type)
Deployment->>Monitor: start proactive run
Monitor->>Case: load last customer update and saved follow-up
Monitor->>Monitor: dedupe and decide whether action is needed
Monitor->>Specialist: interpret ambiguous status change if needed
Specialist-->>Monitor: recommended action and customer-safe facts
Monitor->>Comms: draft proactive update
Comms->>Channel: update active case or send outbound message
Comms->>Case: save last_status_sent and next_follow_up_due_at
```
## Component Responsibilities
| Component | Responsibility |
| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| **Customer WISMO deployment** | Starts from a support ticket, chat, email reply, or customer message. |
| **Backend event deployments** | Start from OMS, WMS, supplier, inventory, carrier, or scheduled exception events. |
| **WISMO orchestration workflow** | Owns case state, deterministic branches, approvals, retries, follow-up timing, and closure. |
| **Order context workflow** | Pulls canonical order, shipment, fulfillment, inventory, supplier, carrier, hold, and support-history fields. |
| **Order investigation agent** | Resolves missing or conflicting facts before routing. |
| **Condition routing workflow** | Applies auditable condition labels and routes to the right specialist or controlled workflow. |
| **Specialist agents** | Handle standard status, supplier backorder, warehouse delay, split shipment, carrier exception, and delivered-not-received paths. |
| **Customer communications agent** | Sends replies and proactive updates with approved tone, current facts, next action, and follow-up timing. |
| **Resolution eligibility workflow** | Applies deterministic eligibility and approval rules before replacement, refund, cancellation, or address-change actions. |
| **Slack escalation agent** | Asks targeted internal questions, collects reviewer decisions, and writes structured answers back to the case. |
| **Proactive follow-up monitor** | Deduplicates backend events, compares them to prior customer updates, and triggers the right next action. |
## Deterministic vs Autonomous
Use deterministic workflows for:
* Customer/order identity checks
* Canonical data gathering
* Condition routing when backend statuses are clear
* Saved values and follow-up commitments
* Duplicate suppression
* Approval gates
* High-impact writes
* Closure and classification
Use autonomous agents for:
* Interpreting conflicting order data
* Choosing which read-only tools to call next
* Explaining supplier, warehouse, and carrier exceptions
* Drafting customer-safe language
* Summarizing prior support history
* Asking internal teams focused questions
* Turning reviewer replies into structured case updates
When a WISMO step must happen the same way every time, make it a workflow. When it needs interpretation, make it an agent called by the workflow.
## Deployment Inventory
| Deployment | Trigger | Target | Mode to start |
| -------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------- | ------------- |
| **Customer WISMO intake** | Ticket tag, chat intent, email rule, or support group | WISMO intake workflow or triage agent | Testing |
| **OMS order event** | Order status, hold status, cancellation, payment, or fulfillment change | OMS event workflow | Testing |
| **WMS fulfillment event** | Pick delay, short pick, label creation, pack completion, or handoff event | Warehouse event workflow or agent | Testing |
| **Supplier and inventory event** | Supplier ETA, allocation, stockout, or inbound receiving change | Supplier backorder agent | Testing |
| **Carrier tracking event** | First scan, no movement, delivery attempt, RTS, delivered, or investigation update | Carrier event workflow or agent | Testing |
| **Scheduled exception sweep** | Hourly or business-hours schedule | Proactive follow-up monitor | Testing |
| **Slack escalation** | Internal review thread reply or app mention | Slack escalation agent | Testing |
## Related Docs
Choose the right mix of deployments, workflows, agents, and human review.
Trigger Duckie from OMS, WMS, supplier, inventory, and carrier systems.
Run exception sweeps and follow-up monitors.
Inspect each WISMO run and tool call.
# Escalation Rules
Source: https://docs.duckie.ai/guardrails/escalation-rules
Define when your agent should hand off to humans
Escalation rules define conditions under which your agent should stop and hand off the conversation to a human agent.
## What are Escalation Rules?
Escalation rules identify situations where human judgment is needed:
* Customer is upset or threatening
* Question involves legal, compliance, or security
* Issue is too complex for automation
* Customer explicitly requests a human
* VIP or high-value customer needs attention
## Creating Escalation Rules
Go to **Train → Guardrails** and select the **Escalation Rules** tab.
Click **Create Escalation Rule**.
Give it a descriptive name:
* Good: "Angry Customer Escalation", "Legal Question Detection"
* Avoid: "Rule 1", "Escalation"
Configure what causes this rule to trigger.
Define what happens when triggered:
* Message to send to customer
* Internal note content
* Routing rules
Use the built-in playground to verify detection.
Save and activate the rule.
## Detection Methods
### AI-Based Detection
Use natural language to describe when to escalate:
**Example prompts:**
```
Escalate when the customer expresses significant frustration
or anger about the service, especially if they mention:
- Wanting to cancel their account
- Threatening negative reviews
- Repeated issues without resolution
- Being a long-time customer who is disappointed
```
```
Escalate when the conversation involves legal topics including:
- Contract terms or disputes
- Liability questions
- Threats of legal action
- Requests for legal documentation
```
**Strengths:**
* Handles nuanced situations
* Adapts to context
* No need to predict every phrase
### Keyword Detection
Trigger on specific words or phrases:
**Example keywords:**
```
cancel, cancellation, lawsuit, lawyer, attorney,
speak to human, talk to person, manager, supervisor,
unacceptable, furious, terrible service, worst experience
```
**Strengths:**
* Fast and predictable
* Easy to understand and audit
* Good for specific trigger words
### Regex Detection
Match complex patterns:
**Example patterns:**
```
# Phone numbers
\b\d{3}[-.]?\d{3}[-.]?\d{4}\b
# Credit card numbers (trigger for security)
\b\d{4}[\s-]?\d{4}[\s-]?\d{4}[\s-]?\d{4}\b
# Email addresses in specific domains
\b[\w.-]+@competitor\.com\b
```
**Strengths:**
* Precise pattern matching
* Good for structured data
* Catches variations
### Combining Methods
Use multiple detection methods together:
```
Trigger escalation when:
- AI detects customer frustration AND
- (Keywords include "cancel" OR "refund") AND
- Conversation is longer than 5 messages
```
## Configuring Escalation Response
### Customer Message
What the agent sends to the customer when escalating:
**Example:**
```
I understand this is important to you, and I want to make sure
you get the best help possible. I'm connecting you with a
member of our team who can assist you directly.
You can expect to hear from them within [timeframe].
Thank you for your patience!
```
### Internal Note
Context for the human agent:
```
## Escalation Summary
**Reason:** Customer expressed frustration about repeated billing issues
**Context:**
- Customer has contacted support 3 times about this issue
- Previous resolutions did not work
- Customer mentioned considering cancellation
**Conversation Summary:**
[Auto-generated summary]
**Recommended Action:**
Review billing history and consider goodwill gesture
```
### Routing (if applicable)
Where to route the escalated conversation:
* Specific team or queue
* Priority level
* Assignment rules
## Example Escalation Rules
### Angry Customer
| Setting | Value |
| ------------- | ------------------------------------------------------------------------------------------------- |
| **Name** | Angry Customer Escalation |
| **Detection** | AI-based |
| **Prompt** | Escalate when customer expresses significant frustration, anger, or threatens to leave |
| **Message** | "I can see this has been frustrating. Let me connect you with someone who can help resolve this." |
### Legal Questions
| Setting | Value |
| ------------- | --------------------------------------------------------------------------- |
| **Name** | Legal Question Detection |
| **Detection** | Keyword + AI |
| **Keywords** | lawyer, attorney, lawsuit, legal, contract dispute |
| **Prompt** | Escalate questions about legal matters, liability, or contract terms |
| **Message** | "For legal matters, I'll connect you with someone who can properly assist." |
### VIP Customer
| Setting | Value |
| ------------- | ------------------------------------------------------------------------------------------------ |
| **Name** | VIP Customer Handling |
| **Detection** | Attribute-based |
| **Condition** | Customer tier = "Enterprise" |
| **Message** | "Thank you for being a valued customer. I'm connecting you with your dedicated support contact." |
### Human Request
| Setting | Value |
| ------------- | -------------------------------------------------------------------- |
| **Name** | Explicit Human Request |
| **Detection** | Keyword |
| **Keywords** | speak to human, talk to person, real person, human agent, live agent |
| **Message** | "Of course! I'm connecting you with a member of our team now." |
## Testing Escalation Rules
Use the built-in playground:
1. Open the escalation rule
2. Enter test messages
3. See if the rule triggers
4. Adjust detection criteria as needed
**Test scenarios to try:**
* Messages that should clearly trigger
* Messages that should clearly not trigger
* Edge cases and borderline situations
## Assigning to Agents
Go to **Build → Agents** and click on an agent.
Select the **Guardrails** tab.
Check the rules that should apply to this agent.
Save the agent configuration.
## Best Practices
* **Test thoroughly** before activating
* **Start broader, then refine** — better to escalate too much initially
* **Review regularly** — analyze which rules trigger most
* **Balance sensitivity** — too sensitive = too many escalations
* **Provide context** — good internal notes help human agents
## Next Steps
Set hard limits on agent behavior
Back to overview
# Guardrails Overview
Source: https://docs.duckie.ai/guardrails/overview
Keep your agent safe and compliant
Guardrails are safety constraints that protect your customers and brand by defining what your agent cannot do and when it should escalate to humans.
## What are Guardrails?
Guardrails are the safety net for your AI agents. They define boundaries and trigger actions when those boundaries are approached.
### Two Types
| Type | Purpose | When Triggered |
| -------------------- | ----------------------------- | ---------------------------------------------------- |
| **Escalation Rules** | Hand off to humans | Customer is upset, legal question, VIP, complexity |
| **Restrictions** | Block specific actions/topics | Forbidden topics, unsafe promises, confidential info |
## Escalation Rules
Define when the agent should stop and hand off to a human:
**Examples:**
| Rule | Description |
| -------------- | ---------------------------------------------------- |
| Angry Customer | Customer expresses frustration or mentions canceling |
| Legal Question | Questions about contracts, liability, or legal terms |
| VIP Customer | Conversations from enterprise or high-value accounts |
| Complex Issue | Agent cannot confidently resolve after attempts |
| Human Request | Customer explicitly asks to speak with a person |
When an escalation rule triggers:
1. Agent stops processing
2. Sends an appropriate message to the customer
3. Creates an internal note with context
4. Routes to human queue
## Restrictions
Define absolute limits on what the agent cannot do:
**Examples:**
| Restriction | Response When Triggered |
| ------------------------ | ---------------------------------------------------------------------------------------------------- |
| No refund promises | "I'd love to help! Let me connect you with our billing team who can review refund requests." |
| No competitor discussion | "I'm focused on how we can help you. Let me tell you about what makes us great." |
| No internal pricing | "For custom pricing, please contact our sales team at [sales@example.com](mailto:sales@example.com)" |
| No medical/legal advice | "I can't provide medical/legal advice, but I can help you find appropriate resources." |
Restrictions are the highest priority — they're checked before anything else.
## Priority Order
Guardrails are evaluated in this order:
```
1. Restrictions (highest priority)
↓
If triggered → Block/Redirect
↓
2. Escalation Rules
↓
If triggered → Escalate
↓
3. Normal Processing
↓
Generate response
```
## Detection Methods
Guardrails can detect triggers using:
| Method | Best For | Example |
| ------------ | ---------------------------------- | ---------------------------------------------- |
| **AI-based** | Complex context, sentiment, intent | "Customer is frustrated about repeated issues" |
| **Keyword** | Specific words or phrases | "cancel", "lawsuit", "speak to manager" |
| **Regex** | Structured patterns | Email addresses, order numbers |
## Testing Guardrails
Each guardrail includes a built-in playground:
1. Open the guardrail configuration
2. Enter test messages
3. See if the guardrail triggers
4. Refine detection criteria
## Guardrails vs Guidelines
| Guardrails | Guidelines |
| --------------------------------- | ------------------- |
| Safety constraints | Communication style |
| Hard limits | Soft guidance |
| Trigger actions (escalate, block) | Shape responses |
| Evaluated per-message | Always applied |
**Guardrail:** "Never discuss competitor pricing" → Blocks the topic
**Guideline:** "Be professional and helpful" → Shapes all responses
## Common Guardrail Patterns
### Safety Net
Catch situations that need human judgment:
* Angry or threatening language
* Legal or compliance topics
* Account security concerns
* Complex edge cases
### Brand Protection
Prevent brand damage:
* Competitor discussions
* Unauthorized promises
* Confidential information
* Off-brand responses
### Compliance
Meet regulatory requirements:
* Privacy requests (GDPR, CCPA)
* Financial advice disclaimers
* Medical/legal limitations
* Age-restricted content
## Next Steps
Define when to hand off
Set hard limits
# Restrictions
Source: https://docs.duckie.ai/guardrails/restrictions
Hard limits on what your agent cannot do
Restrictions are the highest-priority guardrails — absolute limits on what your agent cannot do or say.
## What are Restrictions?
Restrictions define forbidden actions or topics. Unlike escalation rules (which hand off to humans), restrictions typically redirect the conversation or provide an alternative response.
**Examples:**
* Cannot promise refunds without approval
* Cannot discuss competitor products
* Cannot share internal pricing
* Cannot provide medical or legal advice
## Restrictions vs Escalation
| Restrictions | Escalation Rules |
| ------------------------------ | --------------------------------- |
| Block and redirect | Hand off to human |
| Agent continues conversation | Agent stops |
| Prevents specific actions | Transfers responsibility |
| "I can't do X, but I can do Y" | "Let me connect you with someone" |
## Creating Restrictions
Go to **Train → Guardrails** and select the **Restrictions** tab.
Click **Create Restriction**.
Give it a clear name:
* Good: "No Refund Promises", "No Competitor Discussion"
* Avoid: "Restriction 1", "Don't"
Describe what the agent cannot do.
Define how the agent should respond when this triggers.
Verify detection with the built-in playground.
Save and activate the restriction.
## Detection Methods
Same as escalation rules:
### AI-Based
Describe the forbidden topic:
```
Restrict any discussion or comparison of competitor products
or services, including:
- Naming competitor companies
- Comparing features or pricing
- Responding to "is X better than Y" questions
- Discussing why customers might choose competitors
```
### Keyword
Trigger on specific terms:
```
[competitor-name-1], [competitor-name-2],
refund guarantee, price match, free trial extension
```
### Regex
Match specific patterns:
```
# Block sharing of internal URLs
https?://internal\.[a-z]+\.com
# Block specific codes
PROMO-[A-Z]{3}-\d{4}
```
## Configuring Restriction Response
When a restriction triggers, the agent should:
1. **Acknowledge** the request (don't ignore it)
2. **Explain** it can't fulfill this specific request
3. **Redirect** to an appropriate alternative
4. **Continue** helping with other matters
### Good Response Templates
**No Refund Promises:**
```
I'd be happy to help with your refund request! While I can't
process refunds directly, I can connect you with our billing
team who can review your case and assist you. Would you like
me to do that?
```
**No Competitor Discussion:**
```
I'm focused on helping you get the most out of our product.
I'd love to tell you more about [specific feature] that might
address what you're looking for. What would be most helpful?
```
**No Internal Pricing:**
```
For custom pricing and enterprise plans, our sales team would
be the best resource. They can put together options tailored
to your needs. I can help you connect with them — would you
like me to set that up?
```
**No Medical/Legal Advice:**
```
I'm not qualified to provide medical/legal advice, and I want
to make sure you get accurate information. I'd recommend
consulting with a [doctor/lawyer] for this question. Is there
anything else I can help you with today?
```
## Example Restrictions
### No Unauthorized Discounts
| Setting | Value |
| --------------- | ---------------------------------------------------------------------------------------------------------------------- |
| **Name** | No Unauthorized Discounts |
| **Detection** | AI + Keyword |
| **Keywords** | discount, coupon, promo code, special price |
| **Description** | Cannot offer discounts or promotional pricing |
| **Response** | "I don't have the ability to offer special pricing, but our sales team might be able to help. Want me to connect you?" |
### No Competitor Comparison
| Setting | Value |
| --------------- | ---------------------------------------------------------------------------------------------------- |
| **Name** | No Competitor Discussion |
| **Detection** | Keyword + AI |
| **Keywords** | \[list of competitor names] |
| **Description** | Cannot discuss or compare competitor products |
| **Response** | "I'm focused on helping you succeed with our product. What specific need are you trying to address?" |
### No Security Information
| Setting | Value |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Name** | No Security Details |
| **Detection** | AI |
| **Description** | Cannot share internal security architecture, vulnerabilities, or detailed implementation |
| **Response** | "For security questions, please contact [security@example.com](mailto:security@example.com) or request our security documentation through your account manager." |
### No Data Deletion Promises
| Setting | Value |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Name** | No Data Deletion Promises |
| **Detection** | Keyword + AI |
| **Keywords** | delete my data, GDPR, right to be forgotten, data removal |
| **Description** | Cannot promise or perform data deletion without proper process |
| **Response** | "Data deletion requests need to go through our privacy team to ensure we handle them properly. I can submit a request on your behalf — would you like me to do that?" |
## Testing Restrictions
Use the built-in playground:
1. Open the restriction
2. Enter messages that might trigger it
3. Verify detection works correctly
4. Test edge cases
**Test scenarios:**
* Direct requests (e.g., "Give me a refund")
* Indirect requests (e.g., "I'm unhappy with my purchase")
* False positives (e.g., "What's your refund policy" should NOT trigger "No Refund Promises")
## Priority
Restrictions are the highest priority in the guardrail system:
```
Message arrives
│
▼
Check Restrictions ← Highest priority
│
├─ If triggered → Use restriction response
│
▼
Check Escalation Rules
│
├─ If triggered → Escalate
│
▼
Normal Processing
```
## Assigning to Agents
Go to **Build → Agents** and click on an agent.
Select the **Guardrails** tab.
Check the restrictions that should apply.
Save the agent configuration.
## Best Practices
* **Be specific** about what's forbidden
* **Provide helpful alternatives** in responses
* **Test for false positives** — don't over-restrict
* **Review regularly** — update as policies change
* **Keep responses friendly** — restrictions shouldn't feel like rejections
## Next Steps
Define when to hand off to humans
Back to overview
# Creating Guidelines
Source: https://docs.duckie.ai/guidelines/creating-guidelines
Write effective guidelines for your agents
This guide helps you create guidelines that shape your agent's communication effectively.
## Creating Guidelines
Go to **Train → Guidelines** in your dashboard.
Click **Create Section** to start a new guideline section.
Give it a descriptive name:
* Good: "Tone & Voice", "Response Format", "Technical Support"
* Avoid: "Guidelines 1", "Rules"
Use the rich text editor to write your guidelines.
Click **Save** to save your guidelines.
## Writing Effective Guidelines
### Be Specific
**Vague:**
> Be nice to customers.
**Specific:**
> Acknowledge the customer's situation in your first sentence. Use their name if available. Express understanding before jumping into solutions.
### Use Examples
Show what good looks like:
```
## Examples of Good Responses
✅ "Hi Sarah! I understand how frustrating it is when your password
won't work. Let me help you get back into your account."
✅ "Thanks for reaching out! I can see why that error message
would be confusing. Here's what it means and how to fix it..."
❌ "Your password reset request has been received. Please check
your email for further instructions."
❌ "Unfortunately, I cannot assist with that request at this time."
```
### Be Actionable
Give instructions the agent can follow:
```
## Response Structure
1. Acknowledge the question (1 sentence)
2. Provide the direct answer (1-2 sentences)
3. Give context or explanation if needed (1-2 sentences)
4. Offer next steps or additional help (1 sentence)
5. End with a friendly closing
```
### Use Positive Framing
Instead of rules about what *not* to do, describe what *to* do:
**Negative:**
> Don't use corporate jargon or technical terms.
**Positive:**
> Use simple, everyday language. If you must use a technical term, explain what it means.
## Organizing Sections
### By Purpose
Create separate sections for different aspects:
| Section | Content |
| --------------------- | ------------------------------------ |
| **Tone & Voice** | Personality, empathy, language style |
| **Response Format** | Structure, length, lists |
| **Brand Standards** | Terminology, phrases, voice |
| **Technical Writing** | How to explain technical topics |
### By Scenario
Create sections for different contexts:
| Section | Content |
| --------------------- | ------------------------------- |
| **Complaints** | How to handle unhappy customers |
| **Billing Questions** | Specific billing language |
| **Technical Issues** | Troubleshooting approach |
## Assigning Guidelines to Agents
Once created, assign guidelines to agents:
Go to **Build → Agents** and click on an agent.
Select the **Guidelines** tab.
Check the sections that apply to this agent.
Save the agent configuration.
### Combining Sections
Selecting multiple sections combines their guidelines. The agent follows all selected guidelines together.
**Example:**
* General Agent: Tone + Format + Brand
* Technical Agent: Tone + Format + Brand + Technical Writing
* Billing Agent: Tone + Format + Brand + Billing Specifics
## Testing Guidelines
### In the Playground
1. Assign guidelines to an agent
2. Open **Test → Playground**
3. Select the agent
4. Send test messages
5. Check that responses follow guidelines
### What to Test
* **Tone:** Does it sound right?
* **Format:** Is the structure correct?
* **Terminology:** Are brand terms used correctly?
* **Length:** Are responses the right length?
### Iterating
Guidelines often need refinement:
1. Test → Identify issues
2. Update guidelines with clearer instructions
3. Test again
4. Repeat until satisfied
## Common Patterns
### The Friendly Professional
```
## Tone
- Be warm and personable, like a knowledgeable friend
- Use contractions (it's, you're, we'll)
- Keep sentences short and readable
- Express empathy without being overly apologetic
## Language
- Use "I" when possible for personal touch
- Avoid jargon — if you must use it, explain it
- Never say "unfortunately" — find positive alternatives
- End conversations with genuine offers to help more
```
### The Technical Expert
```
## Approach
- Be clear and precise
- Explain the "why" not just the "what"
- Use technical terms when helpful, but define them
- Provide step-by-step instructions with numbered lists
## Format
- Use code blocks for commands or technical content
- Break complex explanations into digestible sections
- Include relevant links to documentation
- Anticipate follow-up questions
```
### The Support Specialist
```
## Structure
Every response should:
1. Acknowledge the customer's situation
2. Provide a clear solution or next step
3. Confirm understanding or success
4. Offer additional assistance
## Escalation
If you cannot fully resolve:
- Clearly explain what you've done
- Set expectations for next steps
- Provide a timeline if possible
- Thank them for their patience
```
## Best Practices
### Do
* **Keep it concise** — Agents need clear, actionable guidance
* **Include examples** — Show what good looks like
* **Be consistent** — Use the same terminology throughout
* **Test thoroughly** — Verify guidelines work in practice
* **Update regularly** — Refine based on actual results
### Don't
* **Don't contradict** — Ensure sections don't conflict
* **Don't over-specify** — Leave room for context adaptation
* **Don't forget edge cases** — Consider unusual scenarios
* **Don't set and forget** — Review and update periodically
## Next Steps
Learn more about guidelines
Test your guidelines
# Guidelines Overview
Source: https://docs.duckie.ai/guidelines/overview
Shape how your agent communicates
Guidelines are instructional rules that define how your agent communicates — its voice, tone, format, and style.
## What are Guidelines?
Guidelines tell your agent *how* to write responses. They cover:
| Area | Examples |
| -------------------- | ------------------------------------------ |
| **Voice & Tone** | Friendly, professional, casual, empathetic |
| **Response Format** | Length, structure, use of lists |
| **Brand Standards** | Terminology, phrases to use or avoid |
| **Domain Knowledge** | Product-specific instructions |
## How Agents Use Guidelines
When generating a response, agents:
1. **Gather context** from knowledge search
2. **Apply guidelines** to shape the response
3. **Format** according to your specifications
4. **Validate** against guardrails before sending
Guidelines act as instructions that influence every response the agent generates.
## Guideline Sections
Guidelines are organized into sections for easier management. Common sections:
### Tone & Voice
How the agent should sound:
```
## Tone
- Be warm and friendly, but professional
- Use "I" instead of "we" for a personal touch
- Acknowledge the customer's situation before solving
- Avoid corporate jargon — write like a helpful human
```
### Response Format
How responses should be structured:
```
## Formatting
- Keep responses concise (under 200 words when possible)
- Use bullet points for lists of options or steps
- Use numbered lists for step-by-step instructions
- Break up long responses with clear sections
- Include relevant links when available
```
### Brand Guidelines
Your company's specific standards:
```
## Brand Voice
- Always refer to the product as "Acme Platform", not "the platform"
- Never use the word "unfortunately" — reframe positively
- Sign off with "Happy to help!" not "Best regards"
- Avoid mentioning competitors by name
```
### Domain-Specific
Instructions for particular topics:
```
## Technical Support
- Ask for error messages or screenshots when relevant
- Include the error code in responses about technical issues
- Link to relevant documentation when explaining features
- If suggesting a workaround, explain why it works
```
## Example Guidelines
### Customer Support Agent Guidelines
```
## Objective
Help customers resolve their issues quickly while providing a friendly, supportive experience.
## Tone
- Be empathetic and patient
- Acknowledge frustration without being apologetic
- Stay positive and solution-focused
- Use conversational language, not corporate speak
## Response Structure
- Start by acknowledging the customer's question
- Provide the answer or solution clearly
- Offer additional help or next steps
- End with an invitation for follow-up
## What to Include
- Relevant links to documentation
- Specific instructions, not vague suggestions
- Confirmation of what was done (if actions taken)
## What to Avoid
- Technical jargon without explanation
- Promising things we can't deliver
- Discussing internal processes
- Mentioning competitors
```
## Testing Guidelines
Use the playground to test how guidelines affect responses:
1. Configure guidelines on your agent
2. Open **Test → Playground**
3. Send test messages
4. Review responses for tone and format
5. Adjust guidelines and retest
## Guidelines vs Guardrails
| Guidelines | Guardrails |
| ---------------------- | ---------------------------- |
| Shape *how* to respond | Define *what not* to do |
| Soft guidance | Hard constraints |
| Affect tone and format | Trigger escalation or blocks |
| Always applied | Only activated when matched |
**Guidelines:** "Be friendly and use the customer's name"
**Guardrail:** "Never promise refunds without approval"
## Next Steps
Write effective guidelines
Set safety constraints
# How Duckie Works
Source: https://docs.duckie.ai/how-duckie-works
Understanding the flow from message to response
This page explains what happens when a customer message arrives and how Duckie processes it to generate a response.
## The Message Flow
When a customer sends a message, Duckie follows an intelligent workflow:
## Step-by-Step Breakdown
### 1. Receive & Route
When a message arrives from a connected channel (Zendesk, Slack, Intercom, etc.):
1. **Webhook handler** receives the event from the external platform
2. **Signature verification** ensures the request is authentic
3. **Deployment matching** finds which agent should handle this message
4. **Run record** is created to track the execution
Each message creates a "run" — a complete record of how Duckie handled the conversation, including all reasoning and tool calls.
### 2. Check Guardrails
Before processing, Duckie evaluates safety constraints:
* **Restrictions** are checked first (highest priority)
* **Escalation rules** are evaluated against the conversation context
* If a guardrail triggers, the conversation may be escalated to a human
### 3. Execute the Agent
The agent follows its configured start mode:
* **Autonomous agents** decide which resources and tools to use
* **Workflow agents** follow a visual workflow
* **Runbook agents** follow a selected runbook
* **Knowledge search** retrieves relevant information
* **Tool calls** perform actions (query external systems, update records, etc.)
* **Context gathering** builds understanding of the customer's situation
### 4. Generate Response
Using all gathered context:
* **Guidelines** shape the tone, format, and content
* **Response generation** creates a draft reply
* **Validation** ensures the response doesn't violate any guardrails
### 5. Deliver & Classify
Finally:
* **Response delivery** sends the message back through the source channel
* **Classification** assigns categories and attributes
* **Resolution evaluation** determines if the issue is resolved
## Visibility & Transparency
Every step is logged and visible in the Duckie dashboard:
* **Run history** shows all executions
* **Step details** reveal reasoning and tool calls
* **Timeline view** shows the full conversation flow
Learn how to analyze agent execution
## Deployment Modes
How responses are delivered depends on the deployment mode:
| Mode | Behavior |
| ----------- | --------------------------------------------------- |
| **Live** | Agent responds directly to customers |
| **Testing** | Agent runs with testing options before live traffic |
Choose the right mode for your use case
## Next Steps
Build your first agent
Configure safety constraints
Connect agents to customers
Track and improve results
# GitHub
Source: https://docs.duckie.ai/integrations/issues/github
Connect GitHub to access repositories and issues with Duckie
Connect GitHub to let your agents create issues, search code, and reference pull requests.
## Capabilities
| Capability | Supported |
| ---------------------- | ----------------------------- |
| **Knowledge Source** | ✓ Search code and issues |
| **Deployment Trigger** | ✓ Respond to issues/PRs |
| **Tool Actions** | ✓ Create issues, add comments |
## Setup
### Connect via OAuth
1. Go to **Settings → Connections** in Duckie
2. Find **GitHub** and click **Connect**
3. You'll be redirected to GitHub
4. Choose which repositories to grant access to
5. Authorize Duckie
6. You'll be redirected back to Duckie
### Repository Access
You can grant access to:
* **All repositories**: Full access to your account/org
* **Select repositories**: Choose specific repos
For organization repositories, an org admin may need to approve the OAuth app.
## Using as a Deployment Trigger
Trigger agents based on GitHub activity:
1. Go to **Deploy**
2. Click **Create Deployment**
3. Select your agent
4. Choose **GitHub** as the trigger
5. Configure events:
* **Issue opened** — New issue filed
* **Issue comment** — Comment on an issue
* **PR opened** — New pull request
* **PR review** — Review submitted
### Use Cases
* **Auto-triage**: Label and assign new issues
* **Answer questions**: Respond to questions in issues
* **PR assistance**: Help with pull request questions
## Available Tools
| Tool | Description |
| ---------------------- | ---------------------- |
| `github_create_issue` | Create a new issue |
| `github_add_comment` | Comment on issue/PR |
| `github_search_code` | Search repository code |
| `github_search_issues` | Search issues and PRs |
| `github_get_issue` | Get issue details |
| `github_add_labels` | Add labels to issue |
## Tool Examples
### Create Issue from Support Ticket
```
When a customer reports a bug that needs engineering attention:
1. Use @github_create_issue:
- Repo: your-org/your-repo
- Title: Bug report: {summary}
- Body: Include reproduction steps and customer context
- Labels: ["bug", "support-reported"]
2. Link the GitHub issue in your response
```
### Search for Related Issues
```
When a customer asks about a known issue:
1. Use @github_search_issues: "is:issue {keywords}"
2. If found, share the issue link and status
3. If not found, offer to create one
```
## Using as Knowledge Source
Index GitHub content:
1. Go to **Train → Knowledge**
2. Click **Add Source**
3. Select **GitHub**
4. Choose repositories and content types:
* **Issues**: Bug reports and discussions
* **README/Docs**: Documentation files
* **Code**: Source code (for technical support)
## Best Practices
### For Open Source Projects
Deploy Duckie to help with community support:
* Answer common questions in issues
* Point to documentation
* Help triage new issues
### For Internal Repositories
Use Duckie to bridge support and engineering:
* Create issues from support tickets
* Search for existing bugs
* Track resolution status
### Use Labels Effectively
Create labels for Duckie-related issues:
* `support-reported`
* `needs-triage`
* `documentation`
## Troubleshooting
### "Repository not accessible"
* Verify you granted access to the repository
* For org repos, check if admin approval is needed
* Re-authenticate if permissions changed
### "Cannot create issue"
* Verify you have write access to the repository
* Check that issues are enabled for the repo
### "Search not returning results"
* GitHub search has rate limits
* Try more specific search queries
* Verify the repository is indexed
# Jira
Source: https://docs.duckie.ai/integrations/issues/jira
Connect Jira to manage issues and track work with Duckie
Connect Jira to let your agents create, update, and reference Jira issues.
## Capabilities
| Capability | Supported |
| ---------------------- | ------------------------------------ |
| **Knowledge Source** | ✓ Search issues for context |
| **Deployment Trigger** | ✓ Respond to issue updates |
| **Tool Actions** | ✓ Create/update issues, add comments |
## Setup
### Connect via OAuth
1. Go to **Settings → Connections** in Duckie
2. Find **Jira** and click **Connect**
3. You'll be redirected to Atlassian
4. Select the Jira site to connect
5. Authorize Duckie's access
6. You'll be redirected back to Duckie
Duckie requests read and write access to Jira issues, plus webhook management for real-time updates.
## Using as a Deployment Trigger
Trigger agents based on Jira activity:
1. Go to **Deploy**
2. Click **Create Deployment**
3. Select your agent
4. Choose **Jira** as the trigger
5. Configure events:
* **Issue created** — When a new issue is filed
* **Issue updated** — When an issue changes
* **Comment added** — When someone comments
### Use Cases
* **Auto-triage**: Classify and route new bugs
* **Auto-respond**: Answer questions in issue comments
* **Status updates**: Notify stakeholders of changes
## Available Tools
| Tool | Description |
| ------------------- | ------------------------- |
| `jira_create_issue` | Create a new issue |
| `jira_update_issue` | Update issue fields |
| `jira_add_comment` | Add a comment to an issue |
| `jira_get_issue` | Retrieve issue details |
| `jira_search` | Search issues with JQL |
| `jira_transition` | Change issue status |
## Tool Examples
### Create an Issue from Support Ticket
In a runbook:
```
When a customer reports a bug:
1. Use @jira_create_issue to file a bug report
- Project: SUPPORT
- Type: Bug
- Summary: Customer-reported issue
- Description: Include customer details and steps to reproduce
2. Share the Jira link with the customer
```
### Search for Related Issues
```
Before answering, check if there's a known issue:
1. Use @jira_search with JQL: project = BUGS AND status != Done AND text ~ "{{customer_issue}}"
2. If found, reference the existing issue
3. If not, create a new one
```
## Using as Knowledge Source
Search Jira issues for context:
1. Go to **Train → Knowledge**
2. Click **Add Source**
3. Select **Jira**
4. Choose which projects to index
5. Click **Start Sync**
This helps agents:
* Reference existing bugs when customers report issues
* Find related feature requests
* Access resolution history
## Best Practices
### Use Specific Projects
Don't sync all projects — focus on:
* Customer-facing bug trackers
* Feature request projects
* Support-related projects
### Create Templates
Set up issue templates in your runbooks:
* Consistent bug report format
* Required fields always populated
* Proper labels and components
### Link Issues to Conversations
When creating issues from support tickets, include:
* Link back to the support ticket
* Customer contact info (if appropriate)
* Conversation context
## Troubleshooting
### "Cannot access Jira"
* Re-authenticate the connection
* Verify your Atlassian account has Jira access
* Check project permissions
### "Issue creation failed"
* Verify all required fields are provided
* Check that the project and issue type exist
* Ensure your account can create issues
### "Webhook not triggering"
* Verify webhooks are enabled in Jira
* Check webhook configuration in Jira settings
* Ensure the webhook URL is correct
# Linear
Source: https://docs.duckie.ai/integrations/issues/linear
Connect Linear to manage issues and projects with Duckie
Connect Linear to let your agents create, update, and reference Linear issues.
## Capabilities
| Capability | Supported |
| ---------------------- | ------------------------------------ |
| **Knowledge Source** | ✓ Search issues for context |
| **Deployment Trigger** | ✓ Respond to issue activity |
| **Tool Actions** | ✓ Create/update issues, add comments |
## Setup
### Connect via OAuth
1. Go to **Settings → Connections** in Duckie
2. Find **Linear** and click **Connect**
3. You'll be redirected to Linear
4. Authorize Duckie to access your workspace
5. You'll be redirected back to Duckie
Duckie requests read and write access to issues in your Linear workspace.
## Using as a Deployment Trigger
Trigger agents based on Linear activity:
1. Go to **Deploy**
2. Click **Create Deployment**
3. Select your agent
4. Choose **Linear** as the trigger
5. Configure events:
* **Issue created** — When a new issue is filed
* **Issue updated** — When an issue changes
* **Comment added** — When someone comments
## Available Tools
| Tool | Description |
| --------------------- | ------------------- |
| `linear_create_issue` | Create a new issue |
| `linear_update_issue` | Update issue fields |
| `linear_add_comment` | Add a comment |
| `linear_get_issue` | Get issue details |
| `linear_search` | Search issues |
## Tool Examples
### Create Bug Report
In a runbook:
```
When a customer reports a bug:
1. Use @linear_create_issue:
- Team: Engineering
- Title: Bug report from customer
- Description: Include reproduction steps
- Priority: Based on severity
- Labels: ["bug", "customer-reported"]
2. Share the issue link with the customer
```
### Find Related Issues
```
Before creating a new issue:
1. Use @linear_search to check for existing issues
2. If found, link to it instead of creating duplicate
```
## Using as Knowledge Source
Index Linear issues for context:
1. Go to **Train → Knowledge**
2. Click **Add Source**
3. Select **Linear**
4. Choose which teams/projects to index
5. Click **Start Sync**
## Best Practices
### Use Labels for Classification
Create labels for support-related issues:
* `customer-reported`
* `support-escalation`
* `documentation-needed`
### Set Up Issue Templates
Configure Linear templates that match your support workflow:
* Bug report template
* Feature request template
* Support escalation template
### Link Back to Conversations
Always include context when creating issues:
* Link to support ticket
* Customer information
* Conversation summary
## Troubleshooting
### "Cannot access Linear"
* Re-authenticate the connection
* Verify your Linear account is active
* Check workspace permissions
### "Issue creation failed"
* Verify the team exists
* Check that required fields are provided
* Ensure your account has create permissions
# Confluence
Source: https://docs.duckie.ai/integrations/knowledge/confluence
Sync Confluence spaces and pages to your Duckie knowledge base
Connect Confluence to sync your team's documentation and knowledge base.
## Capabilities
| Capability | Supported |
| ---------------------- | ----------------------- |
| **Knowledge Source** | ✓ Sync spaces and pages |
| **Deployment Trigger** | ✗ |
| **Tool Actions** | ✗ |
## Setup
### Connect via OAuth
1. Go to **Settings → Connections** in Duckie
2. Find **Confluence** and click **Connect**
3. You'll be redirected to Atlassian
4. Select the Confluence site to connect
5. Authorize Duckie's access
6. You'll be redirected back to Duckie
Duckie requests read-only access to your Confluence content.
## Selecting Content to Sync
After connecting:
1. Go to **Train → Knowledge**
2. Click **Add Source**
3. Select **Confluence**
4. Choose what to sync:
* **Entire spaces**: Sync all pages in selected spaces
* **Specific pages**: Pick individual pages or page trees
### What Gets Synced
* Page content (text, formatted content)
* Page attachments (PDFs, images)
* Blog posts
* Page labels (used for tagging)
* Nested/child pages
### What Doesn't Sync
* Comments
* Page history
* Restricted pages (based on your permissions)
## Best Practices
### Sync Support-Relevant Spaces
Focus on spaces that help answer customer questions:
* Product documentation
* How-to guides
* FAQ pages
* Troubleshooting guides
### Use Space Permissions
Your Confluence permissions apply — Duckie only sees what you can see. Connect with an account that has access to relevant spaces.
### Leverage Labels
Use Confluence labels to organize content:
* Label pages by topic or product
* Use labels to filter what gets synced
* Helps with knowledge organization in Duckie
## Sync Frequency
* **Automatic sync**: Every few hours
* **Manual sync**: Click "Sync Now" in Knowledge sources
* **Change detection**: Duckie detects when pages are updated
## Example Setup
### Documentation Space
```
📖 Product Docs Space
├── Getting Started
│ ├── Installation Guide
│ └── Quick Start
├── User Guide
│ ├── Feature Documentation
│ └── Best Practices
└── API Reference
├── Authentication
└── Endpoints
```
### Knowledge Base Space
```
❓ Support KB Space
├── Common Issues
├── How-To Articles
├── Release Notes
└── FAQs
```
## Troubleshooting
### "Cannot access Confluence"
* Re-authenticate the connection
* Verify your Atlassian account has Confluence access
* Check that the site is accessible
### "Space not appearing"
* Ensure you have permission to view the space
* Try reconnecting with an account that has access
### "Content outdated"
* Click **Sync Now** to force refresh
* Check that the page wasn't recently moved or deleted
# Fireflies
Source: https://docs.duckie.ai/integrations/knowledge/fireflies
Connect Fireflies to capture meeting transcripts for Duckie
Connect Fireflies to sync meeting transcripts and recordings as knowledge for your agents.
## Capabilities
| Capability | Supported |
| ---------------------- | -------------------------- |
| **Knowledge Source** | ✓ Sync meeting transcripts |
| **Deployment Trigger** | ✗ |
| **Tool Actions** | ✗ |
## Setup
Fireflies uses an API key + webhook setup.
### Step 1: Get API Credentials
1. Go to Fireflies settings
2. Navigate to **Developer Settings** or **API**
3. Generate or copy your API key
### Step 2: Connect in Duckie
1. Go to **Settings → Connections** in Duckie
2. Find **Fireflies** and click **Connect**
3. You'll receive a webhook URL
4. Enter your:
* **API Key**: From Fireflies
* **Webhook Secret**: Generated when you set up the webhook
### Step 3: Configure Webhook
1. Copy the webhook URL from Duckie
2. Go to Fireflies developer settings
3. Add the webhook URL
4. Copy the generated webhook secret back to Duckie
5. Click **Connect**
## Using as Knowledge Source
Once connected, meeting transcripts sync automatically:
1. Go to **Train → Knowledge**
2. Click **Add Source**
3. Select **Fireflies**
4. Configure which meetings to sync:
* All meetings
* Specific participants
* By date range
5. Click **Start Sync**
### What Gets Synced
* Full meeting transcripts
* Speaker identification
* Meeting summaries
* Action items (if generated)
* Meeting metadata (date, participants)
## How Agents Use Meeting Data
Agents can reference meeting transcripts to:
* **Answer "what was discussed"** — Find specific topics from calls
* **Recall decisions** — Surface decisions made in meetings
* **Follow up on action items** — Reference committed actions
* **Provide context** — Understand customer conversations
### Example Use Cases
**Customer Success:**
> "What did we discuss in the last call with Acme Corp?"
Agent searches Fireflies → Finds transcript → Summarizes key points
**Sales Support:**
> "What features did the prospect ask about?"
Agent finds sales call → Lists discussed features and concerns
## Best Practices
### Organize by Customer
Tag meetings with customer names for easy retrieval:
* Agents can find all calls with a specific customer
* Better context for support conversations
### Regular Sync
Ensure transcripts sync promptly:
* New calls available to agents quickly
* Set up webhook for real-time updates
### Privacy Considerations
Meeting transcripts may contain sensitive info:
* Consider which meetings to sync
* Use knowledge tags to control agent access
## Troubleshooting
### "Transcripts not syncing"
* Verify the webhook is configured correctly
* Check that Fireflies is processing your meetings
* Confirm API key is valid
### "Webhook not receiving events"
* Verify the webhook URL in Fireflies
* Check the webhook secret matches
* Test the webhook from Fireflies settings
### "Missing meetings"
* Check date range filters
* Verify the meeting was processed by Fireflies
* Force a manual sync
# Google Drive
Source: https://docs.duckie.ai/integrations/knowledge/google-drive
Sync Google Drive documents to your Duckie knowledge base
Connect Google Drive to sync documents, sheets, and slides as knowledge for your agents.
## Capabilities
| Capability | Supported |
| ---------------------- | ------------------------ |
| **Knowledge Source** | ✓ Sync files and folders |
| **Deployment Trigger** | ✗ |
| **Tool Actions** | ✗ |
## Setup
### Connect via OAuth
1. Go to **Settings → Connections** in Duckie
2. Find **Google Drive** and click **Connect**
3. Sign in with your Google account
4. Grant Duckie read access to Drive
5. You'll be redirected back to Duckie
Duckie requests read-only access to your Google Drive files.
## Selecting Content to Sync
After connecting:
1. Go to **Train → Knowledge**
2. Click **Add Source**
3. Select **Google Drive**
4. Browse and select folders or files
5. Click **Start Sync**
### Supported File Types
| File Type | How It's Processed |
| --------------------- | --------------------------- |
| **Google Docs** | Full text content extracted |
| **Google Sheets** | Data converted to text |
| **Google Slides** | Text from slides extracted |
| **PDFs** | Text extracted via OCR |
| **Word docs (.docx)** | Text content extracted |
| **Text files** | Direct content |
### What Doesn't Sync
* Images (unless they contain text via OCR)
* Videos
* Audio files
* Binary files
## Best Practices
### Create a Dedicated Folder
Organize knowledge content in a dedicated folder:
```
📁 Duckie Knowledge
├── 📁 Product Docs
│ ├── User Guide.gdoc
│ └── API Reference.gdoc
├── 📁 Support Materials
│ ├── FAQs.gdoc
│ └── Troubleshooting.gdoc
└── 📁 Policies
├── Refund Policy.gdoc
└── Terms of Service.gdoc
```
### Use Google Docs for Easy Updates
Google Docs are ideal because:
* Easy to edit and update
* Changes sync automatically
* Team collaboration built-in
### Leverage Shared Drives
For team knowledge, use Shared Drives:
* Content persists even if employees leave
* Clear ownership and permissions
* Better organization
## Sync Behavior
* **Automatic sync**: Files checked for updates periodically
* **Folder recursion**: Subfolders are included
* **Permission-based**: Only files you can access are synced
## Example Use Cases
### Product Documentation
Sync your product documentation folder so agents can answer product questions.
### Policy Documents
Sync HR policies, terms of service, and legal documents for accurate policy-related responses.
### Training Materials
Sync onboarding and training docs to help answer procedural questions.
## Troubleshooting
### "File not syncing"
* Verify you have access to the file
* Check that the file type is supported
* Ensure the file isn't in trash
### "Content seems outdated"
* Click **Sync Now** to force refresh
* Check when the source was last synced
### "Cannot connect Google account"
* Try signing out and back into Google
* Clear browser cookies and try again
* Ensure you're using the correct Google account
# Guru
Source: https://docs.duckie.ai/integrations/knowledge/guru
Connect Guru to sync knowledge cards with Duckie
Connect Guru to sync your team's knowledge cards and documentation.
## Capabilities
| Capability | Supported |
| ---------------------- | ---------------------- |
| **Knowledge Source** | ✓ Sync knowledge cards |
| **Deployment Trigger** | ✗ |
| **Tool Actions** | ✗ |
## Setup
### Prerequisites
* Guru account with API access
* Admin permissions to create API tokens
### Step 1: Get API Credentials
1. Go to **Guru Settings → API Access**
2. Generate an API token
3. Copy the token and note your email address
### Step 2: Connect in Duckie
1. Go to **Settings → Connections** in Duckie
2. Find **Guru** and click **Connect**
3. Enter your details:
* **Email Address**: Your Guru account email
* **API Token**: The token you generated
4. Click **Connect**
## Using as Knowledge Source
Sync your Guru cards:
1. Go to **Train → Knowledge**
2. Click **Add Source**
3. Select **Guru**
4. Choose which boards/collections to sync
5. Click **Start Sync**
### What Gets Synced
* Card content (rich text, images)
* Card titles and descriptions
* Board/collection organization
* Tags and categories
* Verification status
## How Agents Use Guru Content
Guru cards are ideal for:
* **Policies and procedures** — Standard processes
* **FAQs** — Common questions and answers
* **Product information** — Features and specifications
* **Troubleshooting guides** — Step-by-step fixes
### Example
Customer asks: "What's your refund policy?"
Agent searches Guru → Finds "Refund Policy" card → Provides accurate answer with policy details
## Best Practices
### Keep Cards Updated
Guru's verification feature helps ensure accuracy:
* Set verification schedules
* Duckie uses the latest verified content
### Use Tags for Organization
Tag cards by:
* Topic area
* Product line
* Customer tier
### Structure for AI Readability
Format cards for easy understanding:
* Clear headings
* Bullet points for lists
* Separate concerns into multiple cards
## Sync Behavior
* **Automatic sync**: Cards checked periodically for updates
* **Verification aware**: Duckie can prioritize verified cards
* **Archive handling**: Archived cards are excluded
## Troubleshooting
### "Cannot connect to Guru"
* Verify email and API token are correct
* Check that API access is enabled for your account
* Ensure the token hasn't expired
### "Cards not syncing"
* Verify you have access to the boards
* Check that cards aren't archived
* Force a manual sync
### "Outdated content"
* Click **Sync Now** to refresh
* Check if the card was recently updated in Guru
# Notion
Source: https://docs.duckie.ai/integrations/knowledge/notion
Sync Notion pages and databases to your Duckie knowledge base
Connect Notion to sync your documentation, wikis, and databases as knowledge for your agents.
## Capabilities
| Capability | Supported |
| ---------------------- | -------------------------- |
| **Knowledge Source** | ✓ Sync pages and databases |
| **Deployment Trigger** | ✗ |
| **Tool Actions** | ✗ |
## Setup
### Connect via OAuth
1. Go to **Settings → Connections** in Duckie
2. Find **Notion** and click **Connect**
3. You'll be redirected to Notion
4. Select which pages/databases to share with Duckie
5. Click **Allow Access**
6. You'll be redirected back to Duckie
You control exactly which pages Duckie can access. Only shared pages will be synced.
## Selecting Content to Sync
When connecting, Notion asks you to select pages:
### Option 1: Select Specific Pages
Choose individual pages or databases to share. This is the most secure approach.
### Option 2: Select Parent Pages
Share a parent page to include all its children. Useful for entire documentation sections.
### Option 3: Use Templates
If you have a documentation workspace, share the top-level template pages.
## Syncing to Knowledge Base
After connecting:
1. Go to **Train → Knowledge**
2. Click **Add Source**
3. Select **Notion**
4. Choose from your shared pages
5. Click **Start Sync**
### What Gets Synced
* Page content (text, headings, lists)
* Database entries (as individual items)
* Nested pages (if parent is shared)
* Images (referenced, not embedded)
### What Doesn't Sync
* Comments
* Page history/versions
* Permissions (all synced content is available to agents)
## Keeping Content Updated
Duckie automatically re-syncs Notion content:
* **Incremental sync**: Changes detected and updated
* **Sync frequency**: Every few hours by default
* **Manual sync**: Click "Sync Now" to force update
## Best Practices
### Organize for AI Readability
Structure your Notion pages for clear understanding:
* Use descriptive headings
* Keep pages focused on single topics
* Link related pages together
### Use Databases for Structured Info
Databases work great for:
* FAQs (question + answer properties)
* Product catalogs
* Process documentation
### Create a "Duckie Knowledge" Section
Consider creating a dedicated section in Notion:
* Curated content specifically for support
* Easy to maintain and update
* Clear separation from internal docs
## Example Structures
### Support Documentation
```
📚 Support Docs (share this)
├── Getting Started
│ ├── Quick Start Guide
│ └── Installation
├── Features
│ ├── Feature A
│ └── Feature B
└── Troubleshooting
├── Common Issues
└── Error Messages
```
### FAQ Database
Create a database with:
* **Question** (Title)
* **Answer** (Text)
* **Category** (Select)
* **Last Updated** (Date)
## Troubleshooting
### "Page not syncing"
* Verify the page is shared with Duckie in Notion
* Check that it's selected in Knowledge sources
* Try removing and re-adding the source
### "Content out of date"
* Click **Sync Now** to force a refresh
* Check the last sync time in source details
### "Missing nested pages"
* Ensure the parent page is shared
* Nested pages inherit sharing from parents
# Sentry
Source: https://docs.duckie.ai/integrations/knowledge/sentry
Connect Sentry to monitor errors and provide context to Duckie
Connect Sentry to give your agents visibility into application errors and exceptions.
## Capabilities
| Capability | Supported |
| ---------------------- | --------------------------- |
| **Knowledge Source** | ✓ Search errors for context |
| **Deployment Trigger** | ✗ |
| **Tool Actions** | ✗ |
## Setup
### Connect via OAuth
1. Go to **Settings → Connections** in Duckie
2. Find **Sentry** and click **Connect**
3. You'll be redirected to Sentry
4. Select the organization to connect
5. Grant Duckie read access
6. You'll be redirected back to Duckie
Duckie requests read-only access to projects and events.
## Using as Knowledge Source
Once connected, Duckie can search Sentry for relevant errors:
1. Go to **Train → Knowledge**
2. Click **Add Source**
3. Select **Sentry**
4. Choose which projects to index
5. Click **Start Sync**
### What Gets Indexed
* Error messages and stack traces
* Error frequency and trends
* Affected users count
* First/last seen timestamps
* Tags and metadata
## How Agents Use Sentry Data
When customers report issues, agents can:
1. **Search for related errors** — Find if there's a known bug
2. **Check error status** — See if it's resolved or ongoing
3. **Get context** — Understand the technical details
4. **Estimate impact** — See how many users are affected
### Example Workflow
In a runbook:
```
When a customer reports a technical issue:
1. Search Sentry for errors matching their description
2. If found:
- Acknowledge the known issue
- Share expected resolution timeline
- Offer workaround if available
3. If not found:
- Collect reproduction steps
- Escalate to engineering
```
## Best Practices
### Index Production Projects
Focus on production environments:
* Customer-facing errors
* Backend services
* API errors
### Use Sentry Tags
Well-tagged errors are easier to search:
* User ID
* Feature area
* Error category
### Combine with Issue Tracking
Link Sentry errors to Jira/Linear issues:
* Agents can reference the tracking ticket
* Provide status updates to customers
## Use Cases
### Technical Support
Help support agents understand customer-reported bugs:
* Verify if error is known
* Get technical context
* Estimate resolution
### Proactive Communication
Identify affected users for proactive outreach:
* Major outages
* Widespread bugs
## Troubleshooting
### "Cannot access Sentry"
* Re-authenticate the connection
* Verify your Sentry account has project access
* Check organization permissions
### "Errors not syncing"
* Verify the project is selected
* Check that there are recent events
* Force a sync refresh
# Skilljar
Source: https://docs.duckie.ai/integrations/knowledge/skilljar
Connect Skilljar to sync courses and training content with Duckie
Connect Skilljar to sync your training courses, lessons, and educational content.
## Capabilities
| Capability | Supported |
| ---------------------- | -------------------------- |
| **Knowledge Source** | ✓ Sync courses and lessons |
| **Deployment Trigger** | ✗ |
| **Tool Actions** | ✗ |
## Setup
### Prerequisites
* Skilljar admin account
* API access enabled
### Step 1: Get API Credentials
1. Go to **Skilljar Admin → Settings → API**
2. Generate or copy your API key
3. Note your Skilljar domain (e.g., `university.yourcompany.com`)
### Step 2: Connect in Duckie
1. Go to **Settings → Connections** in Duckie
2. Find **Skilljar** and click **Connect**
3. Enter your details:
* **Skilljar Domain**: Your university domain (without https\://)
* **API Key**: The key you generated
4. Click **Connect**
## Using as Knowledge Source
Sync your Skilljar content:
1. Go to **Train → Knowledge**
2. Click **Add Source**
3. Select **Skilljar**
4. Choose which courses to sync
5. Click **Start Sync**
### What Gets Synced
* Course descriptions and outlines
* Lesson content
* Quiz questions and answers
* Learning paths
* SCORM content (if accessible)
## How Agents Use Skilljar Content
Training content helps agents with:
* **Product education** — How features work
* **Onboarding questions** — Getting started guides
* **Certification info** — Training program details
* **Best practices** — Recommended workflows
### Example Use Cases
**Customer asks about a feature:**
Agent finds the relevant training lesson and explains the feature based on official training material.
**User needs onboarding help:**
Agent references the getting started course to guide them through setup.
**Certification questions:**
Agent provides info about available certifications and requirements.
## Best Practices
### Sync Customer-Facing Courses
Focus on courses relevant to support:
* Product training
* Getting started guides
* Feature deep-dives
### Keep Training Updated
Training content should reflect current product:
* Agents give accurate information
* Reduces confusion from outdated material
### Use Course Metadata
Leverage Skilljar's organization:
* Course categories help with search
* Learning paths provide context
## Troubleshooting
### "Cannot connect to Skilljar"
* Verify domain format (no https\://)
* Check API key is correct
* Ensure API access is enabled
### "Courses not syncing"
* Verify the courses are published
* Check you have admin access
* Force a manual sync
### "Missing content"
* Some content types may not sync (videos, interactive elements)
* Text-based content syncs fully
# Discord
Source: https://docs.duckie.ai/integrations/messaging/discord
Add the Duckie bot to your Discord server
Add Duckie to your Discord server to provide AI-powered support in your community.
## Capabilities
| Capability | Supported |
| ---------------------- | ------------------------ |
| **Knowledge Source** | ✓ Search message history |
| **Deployment Trigger** | ✓ Respond to messages |
| **Tool Actions** | ✓ Send messages, react |
## Setup
### Add Bot to Server
1. Go to **Settings → Connections** in Duckie
2. Find **Discord** and click **Connect**
3. You'll be redirected to Discord
4. Select the server to add Duckie to
5. Review and approve the bot permissions
6. You'll be redirected back to Duckie
You need **Manage Server** permission on the Discord server to add bots.
### Bot Permissions
Duckie requests these permissions:
* Read messages and message history
* Send messages
* Add reactions
* Read member information
## Using as a Deployment Trigger
Deploy an agent to Discord:
1. Go to **Deploy**
2. Click **Create Deployment**
3. Select your agent
4. Choose **Discord** as the trigger
5. Configure the trigger:
### Trigger Options
| Option | Description |
| ----------------- | -------------------------------------- |
| **Channels** | Specific channels to monitor |
| **@mention only** | Only respond when @Duckie is mentioned |
| **All messages** | Respond to every message |
### Channel Permissions
Ensure Duckie has access to the channels:
1. Go to channel settings in Discord
2. Check that the Duckie role can view and send messages
3. Adjust permissions if needed
## Available Tools
| Tool | Description |
| ---------------------- | --------------------------- |
| `discord_send_message` | Send a message to a channel |
| `discord_add_reaction` | React to a message |
| `discord_get_user` | Get user information |
## Best Practices
### Create a Dedicated Support Channel
Set up a `#support` or `#help` channel specifically for Duckie:
* Users know where to ask questions
* Keeps other channels clean
* Easy to manage and monitor
### Use @mention in Busy Channels
For active community channels, use **@mention only** mode so Duckie doesn't respond to every message.
### Set Up Roles
Create a Duckie role in Discord with appropriate permissions:
* Can see support channels
* Cannot see private/admin channels
## Example Use Cases
### Community Support
Deploy Duckie to answer common questions in your community server — product questions, troubleshooting, how-tos.
### Developer Documentation Bot
Let developers ask questions about your API or SDK in a `#dev-help` channel.
### Gaming Community
Answer questions about game mechanics, server rules, or events.
## Troubleshooting
### "Bot not responding"
* Verify Duckie has permission to view the channel
* Check if the deployment is in **Live** mode
* Ensure the trigger matches (@mention vs all messages)
### "Missing permissions"
* Go to Server Settings → Roles
* Find the Duckie role and grant needed permissions
* Make sure channel-specific permissions don't override
### "Can't add bot to server"
* You need **Manage Server** permission
* Ask a server admin to add the bot
# Gmail
Source: https://docs.duckie.ai/integrations/messaging/gmail
Connect Gmail to send and receive emails with Duckie
Connect Gmail to let Duckie handle email-based support conversations.
## Capabilities
| Capability | Supported |
| ---------------------- | ------------------- |
| **Knowledge Source** | ✗ |
| **Deployment Trigger** | ✓ Respond to emails |
| **Tool Actions** | ✓ Send emails |
## Setup
### Connect via OAuth
1. Go to **Settings → Connections** in Duckie
2. Find **Gmail** and click **Connect**
3. Sign in with your Google account
4. Grant Duckie permission to read and send emails
5. You'll be redirected back to Duckie
Duckie requests permission to read incoming emails and send replies on your behalf.
## Using as a Deployment Trigger
Deploy an agent to handle emails:
1. Go to **Deploy**
2. Click **Create Deployment**
3. Select your agent
4. Choose **Gmail** as the trigger
5. Configure which emails trigger responses:
* **All emails** — Respond to every incoming email
* **Specific senders** — Only emails from certain addresses
* **Labels** — Only emails with specific Gmail labels
### Filter Examples
* Support emails: Filter by label `support` or sender domain
* Customer inquiries: Filter by subject containing "question" or "help"
## Available Tools
| Tool | Description |
| ------------------ | --------------------------- |
| `gmail_send` | Send an email reply |
| `gmail_get_thread` | Get full email conversation |
| `gmail_search` | Search emails |
## Best Practices
### Use a Dedicated Support Email
Set up a dedicated email like `support@yourcompany.com`:
* Clear separation from personal emails
* Easy to manage and monitor
* Can be shared across team
### Set Up Gmail Filters
Use Gmail filters to organize incoming emails:
* Auto-label support requests
* Skip spam before it reaches Duckie
### Include Thread Context
Duckie automatically reads the email thread for context, so it understands the full conversation history.
## Example Use Cases
### Email Support Inbox
Deploy Duckie to handle your `support@` inbox:
* Answer common questions
* Acknowledge receipt of complex issues
* Route to human agents when needed
### Sales Inquiries
Handle initial sales emails:
* Provide product information
* Answer pricing questions
* Schedule demos
## Troubleshooting
### "Cannot send emails"
* Re-authenticate the Gmail connection
* Verify your Google account is in good standing
* Check that you approved send permissions
### "Not receiving emails"
* Verify the deployment is in Live mode
* Check Gmail filters aren't blocking emails
* Ensure the email address is correctly configured
# Slack
Source: https://docs.duckie.ai/integrations/messaging/slack
Connect Slack for real-time messaging with Duckie
Connect Slack to let Duckie respond to messages in channels and DMs.
## Capabilities
| Capability | Supported |
| ---------------------- | ------------------------------ |
| **Knowledge Source** | ✓ Search message history |
| **Deployment Trigger** | ✓ Respond to messages |
| **Tool Actions** | ✓ Send messages, react, search |
## Setup
### Connect via OAuth
1. Go to **Settings → Connections** in Duckie
2. Find **Slack** and click **Connect**
3. You'll be redirected to Slack to authorize
4. Select the workspace to connect
5. Review and approve the permissions
6. You'll be redirected back to Duckie
### Permissions Granted
Duckie requests these bot permissions:
* Read messages in channels it's added to
* Send messages and reactions
* Read user profiles
* Access files shared in conversations
## Using as a Deployment Trigger
Deploy an agent to Slack:
1. Go to **Deploy**
2. Click **Create Deployment**
3. Select your agent
4. Choose **Slack** as the trigger
5. Configure the trigger:
### Trigger Options
| Option | Description |
| ----------------- | --------------------------------------- |
| **Channels** | Specific channels to monitor |
| **@mention only** | Only respond when @Duckie is mentioned |
| **All messages** | Respond to every message in the channel |
| **DMs** | Respond to direct messages |
### Channel Setup
After creating a deployment, invite Duckie to the channels:
1. Go to the Slack channel
2. Type `/invite @Duckie` or add from channel settings
3. Duckie will now receive messages in that channel
## Available Tools
| Tool | Description |
| ----------------------- | ----------------------------------- |
| `slack_send_message` | Send a message to a channel or user |
| `slack_add_reaction` | Add an emoji reaction |
| `slack_search_messages` | Search message history |
| `slack_get_user` | Get user profile information |
| `slack_upload_file` | Share a file |
## Using as Knowledge Source
Search your Slack history for context:
1. Go to **Train → Knowledge**
2. Click **Add Source**
3. Select **Slack**
4. Choose which channels to index
5. Click **Start Sync**
Slack message history requires a paid Slack plan for full access.
## Best Practices
### Use @mention Mode for Busy Channels
In high-traffic channels, set the trigger to **@mention only** so Duckie only responds when directly asked.
### Create Dedicated Support Channels
Consider creating channels like `#ask-duckie` where customers or team members can ask questions.
### Thread Responses
Duckie responds in threads by default to keep channels organized.
## Example Use Cases
### Internal IT Helpdesk
Deploy an agent to `#it-help` that answers common IT questions using your internal documentation.
### Customer Support (Slack Connect)
If you use Slack Connect for customer support, deploy Duckie to those shared channels.
### Team Knowledge Bot
Create a `#ask-anything` channel where employees can ask questions about company policies, processes, and tools.
## Troubleshooting
### "Duckie not responding"
* Verify Duckie is invited to the channel
* Check if the deployment is in **Live** mode
* Ensure the trigger matches (@mention vs all messages)
### "Missing message history"
* Duckie can only see messages after it was added to the channel
* Historical search requires the Slack knowledge source to be synced
### "Permission denied"
* The workspace admin may need to approve Duckie
* Re-authenticate if permissions changed
# Microsoft Teams
Source: https://docs.duckie.ai/integrations/messaging/teams
Connect Microsoft Teams for enterprise messaging with Duckie
Connect Microsoft Teams to let Duckie respond to messages in your Teams workspace.
## Capabilities
| Capability | Supported |
| ---------------------- | --------------------- |
| **Knowledge Source** | ✗ |
| **Deployment Trigger** | ✓ Respond to messages |
| **Tool Actions** | ✓ Send messages |
## Setup
### Prerequisites
* Microsoft 365 admin access or approval
* Teams workspace with bot permissions enabled
### Connect via OAuth
1. Go to **Settings → Connections** in Duckie
2. Find **Microsoft Teams** and click **Connect**
3. Sign in with your Microsoft 365 account
4. Grant the requested permissions
5. You'll be redirected back to Duckie
Your Microsoft 365 admin may need to approve the Duckie app before you can connect.
## Using as a Deployment Trigger
Deploy an agent to Teams:
1. Go to **Deploy**
2. Click **Create Deployment**
3. Select your agent
4. Choose **Microsoft Teams** as the trigger
5. Configure the trigger:
### Trigger Options
| Option | Description |
| ----------------- | -------------------------------------- |
| **Channels** | Specific channels to monitor |
| **@mention only** | Only respond when @Duckie is mentioned |
| **1:1 chats** | Respond to direct messages |
### Adding to Channels
After deployment, add Duckie to Teams channels:
1. Go to the Teams channel
2. Click **+** to add a tab or app
3. Search for "Duckie" and add it
4. Configure which messages trigger responses
## Available Tools
| Tool | Description |
| -------------------- | ----------------------------------- |
| `teams_send_message` | Send a message to a channel or chat |
| `teams_get_user` | Get user profile information |
## Best Practices
### Enterprise Approval Process
Work with your IT team to approve Duckie:
1. Submit Duckie for admin approval
2. IT reviews requested permissions
3. Once approved, all users can add Duckie
### Use Dedicated Channels
Create channels like "IT Support" or "HR Questions" specifically for Duckie interactions.
### Integrate with Existing Workflows
Teams users often have established workflows — position Duckie as a helper in channels they already use.
## Example Use Cases
### IT Helpdesk
Deploy to an IT support channel to answer common questions about software, VPN, passwords, etc.
### HR Questions
Let employees ask about PTO policies, benefits, and company procedures.
### Sales Enablement
Help sales teams quickly find product information and competitive intel.
## Troubleshooting
### "App not approved"
* Contact your Microsoft 365 admin
* Request approval for the Duckie app
* Admin can approve in the Teams Admin Center
### "Bot not responding"
* Verify Duckie is added to the channel
* Check deployment mode (Live vs Testing)
* Ensure trigger is configured correctly
### "Permission denied"
* Re-authenticate the connection
* Verify your account has access to the channels
# Website Widget
Source: https://docs.duckie.ai/integrations/messaging/widget
Embed a Duckie chat widget on your website
Add an AI-powered chat widget directly to your website for instant customer support. To deploy the widget for support agents without embedding code on a site, see [Chrome Extension](/integrations/messaging/widget-chrome-extension).
## Capabilities
| Capability | Supported |
| ---------------------- | -------------------- |
| **Knowledge Source** | ✗ |
| **Deployment Trigger** | ✓ Chat conversations |
| **Tool Actions** | ✓ Send messages |
## Setup
### Step 1: Create a Widget Deployment
1. Go to **Deploy**
2. Click **Create Deployment**
3. Select your agent
4. Choose **Website Widget** as the trigger
5. Configure appearance and behavior
6. Click **Create**
### Step 2: Get the Embed Code
After creating the deployment:
1. Click on the deployment to open settings
2. Go to the **Widget** tab
3. Copy the embed code
### Step 3: Add to Your Website
Add the embed code before the closing `` tag:
```html theme={null}