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