> ## Documentation Index
> Fetch the complete documentation index at: https://docs.duckie.ai/llms.txt
> Use this file to discover all available pages before exploring further.

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

<Info>
  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.
</Info>

## Creating a New Agent

<Steps>
  <Step title="Navigate to Agents">
    Go to **Build → Agents** in your Duckie dashboard.

    {/* Screenshot: Agents page with Create Agent button highlighted */}
  </Step>

  <Step title="Click Create Agent">
    Click the **Create Agent** button to open the creation drawer.
  </Step>

  <Step title="Enter Basic Information">
    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)

    {/* Screenshot: Create agent form with name and description fields */}
  </Step>

  <Step title="Select a Mode">
    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
  </Step>

  <Step title="Configure the Mode">
    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.
  </Step>

  <Step title="Save">
    Click **Create** to save your new agent. The agent detail view will open.
  </Step>
</Steps>

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

{/* Screenshot: Agent detail - Knowledge tab showing tag filters */}

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

<Tip>
  **Start broad, then narrow.** It's often easier to leave tags empty first, then restrict based on testing results.
</Tip>

### Guidelines

{/* Screenshot: Agent detail - Guidelines tab showing guideline section selection */}

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

{/* Screenshot: Agent detail - Guardrails tab showing escalation rules and restrictions */}

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:

<Steps>
  <Step title="Open Playground">
    Go to **Test → Playground**.
  </Step>

  <Step title="Select Your Agent">
    Choose your newly created agent from the dropdown.
  </Step>

  <Step title="Send Test Messages">
    Try various scenarios:

    * Common questions your customers ask
    * Edge cases and unusual requests
    * Messages that should trigger escalation
  </Step>

  <Step title="Review and Iterate">
    Check responses and execution steps. Adjust configuration as needed.
  </Step>
</Steps>

{/* Screenshot: Playground with test conversation and execution steps visible */}

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

<CardGroup cols={2}>
  <Card title="Agent Configuration" icon="sliders" href="/agents/configuration">
    Deep dive into all settings
  </Card>

  <Card title="Autonomous Agents" icon="wand-magic-sparkles" href="/agents/autonomous-agents">
    Configure flexible agents for open-ended conversations
  </Card>

  <Card title="Test in Playground" icon="flask" href="/testing/playground">
    Validate before deploying
  </Card>

  <Card title="Create a Deployment" icon="rocket" href="/deployments/creating-deployments">
    Connect to a customer channel
  </Card>
</CardGroup>