Build your first agent
Build your first agent
10 min
Gaëlle Caplier1. How to build a custom AI agent?
1.1. The components of a custom AI agent
A custom agent is made of several components:
- A name, which you will use to call it in your conversations
- ⚠️ The name needs to be unique on the workspace
- ⚠️ Your company may have some specific naming standards for your agents: check out the name formats in your agent library!
- Custom instructions, where you define exactly what the agent should do, which role it should take, which output it should produce, etc.
- The underlying AI model, which you can pick in a large list of available LLMs.
- Knowledge sources, where you will select which data sources your agent can leverage to answer user queries.
- Capabilities, which are the “superpowers” of your agent. You can allow it to take actions for you - like browsing the web, drafting emails in your inbox, updating fields in your CRM, and more!
- Triggers, which determine when an agent is going to be called automatically.
1.2. The agent builder
When you start creating a new agent, you will be brought to the agent builder interface. You access it by clicking Create from the Dust homepage. It is made of five main sections, which map to the main components of a custom agent. This is also where you will interact with Sidekick, your agent building helper!
In the Instructions section, you will write your custom instructions.
Instructions are the core of your agent. They define, in natural language, what the agent should do: its role, the process it should follow, the tone it should use, the output format it should produce, and any constraints it should respect.
- 📚 Instructions are written in natural language, but there are some best practices to follow to write effective custom instructions. Check them out!
- The most important element of good instructions is a step-by-step process. Agents with a clear "Step 1, do X; Step 2, do Y; Step 3, do Z" structure will produce consistent, repeatable results every time you call them. Without this structure, your agent improvises, and the quality of its output will vary from one conversation to the next.
Pro tip: You don't need to write perfect instructions from day one. Sidekick (covered in the next section) can draft them for you, and you can iterate over time.
The model - The Advanced button above the Instructions box will let you change the underlying AI model used by your agent, if you wish. Different models have different strengths: some are faster, others handle complex reasoning better. It is not often possible to know beforehand which AI model will be the best for your specific task, so test it out with different options!
Below instructions, you have the Spaces section.
This section will only be relevant if you are a member of a restricted space, e.g. a space that contains private data that your administrator has decided to only open to a specific set of Dust users. How do you know if that's your case? Simply click on Manage: if there's nothing to select here, then you don't have access to any restricted space, and you don't need to change anything in your agent!
Below, you have the Capabilities and Knowledge section. This is where you define what your agent can actually do. Instructions tell the agent what it should do; knowledge and tools give it the ability to do it. These two must work hand in hand.
- Knowledge sources connect your agent to your company data: Notion pages, Google Drive or Sharepoint folders, support tickets, CRM records, spreadsheets, and more.
- Capabilities extend your agent's capabilities beyond reading data. They let your agent take actions: searching the web, drafting emails via Gmail or Outlook, creating calendar events, generating visualizations (Frames), running other agents, and more.
Knowledge and capabilities are covered in depth in following Chapters. For now, just know that they exist and that Sidekick will help you pick the right ones.
Then, you'll find the Triggers section, where you can choose to automate your agent.
We will cover this in the next course, so we'll just ignore this section for now.
Finally, the last section in the agent builder is the Settings, where you'll choose a name for your agent, a description, and you'll define its sharing parameters. An Unpublished agent is only available to you, its creator. Keep your agents unpublished during their testing phase. Once an agent is ready to be released and used by your colleagues, switch it to Published to open it to everyone on the workspace.
You can also add some tags to organize your agent library, and make other colleagues editors of your agent.
1.2 Agent building with Sidekick
Sidekick is your AI helper for building agents. It lives directly inside the agent builder and turns building agents into a guided conversation.
1.2.1 Introducing Sidekick
In the agent builder, you'll see a conversational panel on the right side of the screen. That's Sidekick. You simply describe what you want your agent to do in plain language, and Sidekick handles the rest.
How it works:
- You describe your goal in natural language: what the agent should do, what data it needs access to, what actions it should take.
- Sidekick translates your description into a concrete agent configuration: it drafts instructions, recommends tools and knowledge sources, and suggests the right model.
- Every suggestion appears as an inline redline that you can accept or reject with a single click. Nothing changes in your agent until you approve it.
- You iterate: ask Sidekick to adjust, add new capabilities, refine the process, or visualize the agent's workflow.
Sidekick is workspace-aware. It knows what tools, knowledge sources, and skills are available on your workspace, so its suggestions are grounded in what you can actually use.
Sidekick for existing agents
Sidekick isn't just for building new agents. When you open an existing agent in the builder, Sidekick automatically analyzes the current configuration and any user feedback (thumbs up/down reactions from conversations). It will proactively surface suggestions to improve your agent without you having to ask.
Visualizing your agent's workflow
For more complex agents with branching logic, you can ask Sidekick to "visualize the process" or "show me a diagram of this agent's workflow." It will generate a visual flowchart of your agent's step-by-step process, making it easy to verify that the logic matches what you had in mind.
1.2.2 Building an agent from scratch
Check it out in action!
Step 1: Create a new agent
Click Create from the Dust homepage, then select Start from scratch. The agent builder opens with empty fields on the left and Sidekick's conversation panel on the right. Sidekick's first question: "What should this agent do?"
Step 2: Describe your intent
Be specific. The more context you give Sidekick, the better its suggestions will be. A vague prompt like "help me with clients" will produce a vague agent. Instead, describe the use case in detail.
For example, imagine you want an agent that prepares you for client meetings by pulling together everything you need to know about a given client:
"I want to create an agent that generates client summaries before my meetings. For any client I name, it should pull relevant information from our internal data sources: recent interactions in Notion, documents in Google Drive, open support tickets in Zendesk, recent emails in Gmail, and upcoming meetings in Google Calendar. It should synthesize everything into a structured briefing."
Step 3: Review and approve suggestions
Sidekick will produce a plan: drafted instructions with a step-by-step process, recommended tools (Gmail, Google Calendar, Notion, Zendesk, etc.), and potentially a model upgrade. Each suggestion appears as an inline diff. Review them one by one:
- Accept suggestions that look right.
- Reject suggestions that don't fit. For example, Sidekick might suggest adding a tool you don't need. That's fine; just decline it.
- Iterate by telling Sidekick what to change. You can always come back and ask for adjustments.
Step 4: Save, test, and iterate
Save your agent (published or unpublished), then open a new conversation and call it by name. Test it with a real scenario. If the output isn't quite right, return to the agent builder, let Sidekick analyze your feedback, and iterate.
1.2.3 Building an agent from a template
Templates provide a head start when you know the type of agent you want but aren't sure how to configure it.
Check it out in action!
How to access templates: Click Create, then select Start from a template. Browse the template library by category (Sales, Support, Marketing, Writing, etc.) and pick one that matches your use case.
How templates work with Sidekick: Selecting a template opens the agent builder with Sidekick pre-loaded with that template's context. Sidekick then asks you targeted follow-up questions to tailor the agent to your specific needs, producing a customized version rather than a generic one.
For example, selecting a "Slide Deck Creator" template will prompt Sidekick to ask what presentation tool you use (Google Slides, PowerPoint, etc.), what kind of decks you typically create, and where your templates live. Based on your answers, it configures the agent accordingly.
This approach gives you the best of both worlds: the discoverability and inspiration of templates combined with the personalization of a Sidekick-guided build.
Pro tip: Even if no template perfectly matches your use case, browsing the library is a great way to discover what's possible with Dust agents.
1.2.4 Building an agent from a conversation (Convert to Agent)
Sometimes, the best way to discover an agent is by accident. You have a long, productive conversation with an agent like
@deep-dive, iterating back and forth until you get a workflow that works beautifully. Then you realize: "I want to do this exact thing again next week, without having to re-explain everything from scratch."That's what Convert to agent is for. It lets you turn a successful conversation into a reusable agent in one click.
How to use Convert to agent:
- In any conversation where you've built up a workflow you want to keep, click the three-dot menu (⋯) at the top of the conversation.
- Select the Convert to agent option (identified by the Sidekick icon).
- The agent builder opens with Sidekick pre-loaded with the full context of your conversation. Sidekick analyzes the tools used, the knowledge accessed, the instructions you gave, and the workflow that emerged.
- Sidekick produces a complete agent configuration based on that conversation. Review, adjust, and save.
This is especially powerful for complex workflows that evolved organically over a long conversation. Instead of trying to recreate them manually, Convert to agent captures the essence of what worked and packages it into a standalone agent.
2. When should you create a custom agent?
As you've seen in previous courses, there are a lot of use cases you can address simply with the @dust agent or the @deep-dive agent, which are available by default on your Dust workspace. If you need those agents to have extra capabilities, you can always add them manually in the context of your conversation.
So when do you actually need to create a custom agent? The key word here is recurrence.
- For any kind of recurring task, you will want to create a custom agent, because it will always know what to do and how to address your specific needs thanks to its custom instructions. You will not need to provide context again and again with each new conversation.
- For any kind of one-time task, simply talking to
@dustor a similar agent is more than enough!
And how about the case when you started from a one-time task, had a long discussion with
@dust that evolved into a more and more complex and high-value use case, and you would like to package that one into a new custom agent? In this case, you can simply ask @dust at the end of your conversation to give you recommendations on how to transform the conversation into a new custom agent!3. Hands-on: build your @askHR agent
The objective of this hands-on is to build an agent to answer simple HR questions from coworkers. It presupposes that you have a source of truth for HR processes connected to Dust, that you can use as a knowledge source for your agent. If that's not your case, you can adapt the use case to build@askProduct,@askCustomerSuccess,@askLegal, or anything else relevant to you!There might already be an@askHR(or equivalent) agent on your workspace: this hands-on is just for practice, it's not to replace your existing agents, so don't forget to archive your agent if you have no further use for it after this tutorial!
3.1. Create a new agent
From the Dust homepage, click on "Create", then create an agent from scratch. This will bring you to the Agent builder interface.
3.2. Sidekick
Explain your goal to Sidekick. What should this agent do? Which data sources should it pull from? Who will interact with it? What process should it follow? The more specific and detailed you are, the better the result will be.
Sidekick will suggest some instructions and some capabilities for the agent. Review them and update them until your agent configuration makes sense for you!
3.3. Spaces
You probably don't have to change anything in the Spaces section. This is only for agents dealing with confidential data!
3.4. Settings
Skip the "Triggers" section - your agent doesn't need one! If you're intrigued by this feature, we'll cover it in-depth in a follow-up course.
Give a name to your agent (or approve the auto-generated one). If
@askHR is already taken, you'll need to pick something else!The description should be auto-generated, but you may want to review and update it if needed.
You can add more editors and choose to publish your agent, and use tags to classify it.
When everything is ready, just save your agent!
3.5. Try it out!
Try out your agent directly in the Dust homepage. Ask any question about HR processes you want :)
Good job on building your first agent! 🤖
Test Your Knowledge
Answer 5 questions — score 3 or more to pass
Ready to test your understanding of this chapter?