Summary

An AI agent in DAVE is a named, versioned, reusable component that wraps an AI provider with a system prompt and behavior parameters. This guide walks through creating one from scratch, configuring its first version, and making it ready to use in a workflow.

The steps

1
Navigate to Agents and open the creation form
Navigate to Agents in the left sidebar. The Agents page has two tabs: Agents and Prompt Library. You land on the Agents tab by default, which shows a table of all agents in your tenant.
If this is a new workspace, you will see an empty-state message: "No agents yet. Create one to get started." Click New Agent in the top-right corner of the page. A form panel expands below the header.
Do this
- Click Agents in the left sidebar.
- Confirm you are on the Agents tab (not Prompt Library).
- Click New Agent in the top-right corner.
- The creation form expands below the header. If the button is missing, your role does not include agent creation: see the FAQ section below.
Example
A content team lead opens DAVE, clicks Agents in the sidebar, and sees an empty table with the message "No agents yet. Create one to get started." They click New Agent and the form appears.
Best practice
Only users with the Admin or Create role can create agents. The Curate role can view agents but not create or edit them. The Use and Reporting roles cannot access the Agents section at all. DAVE ships with six default tenant roles (Admin, Create, Curate, Use, Reporting, and Financial), all editable by your administrator.
2
Name the agent and add a description and tags
Fill in the three fields on the creation form:
- Name (required): the display name shown in the agent list, the agent detail page, and every workflow node that references this agent. Choose a name that describes what the agent does, not which model it uses.
- Description (optional): a brief explanation of the agent's purpose. Shown in the agent list and at the top of the detail page. Write it for the person who will reference this agent in a workflow six months from now.
- Tags (optional): a comma-separated list of labels for filtering and organization. For example: content, review, summarizer. Each tag is trimmed of whitespace; empty entries are ignored.
Click Create Agent to save. To cancel without saving, click Cancel. The new agent appears in the table with zero versions and an initial status.
Do this
- Enter a descriptive Name that communicates the agent's function, for example: Content Summarizer or Compliance Checker.
- Optionally enter a Description, for example: Produces concise summaries of long-form content for editorial review.
- Optionally enter Tags as a comma-separated list, for example: content, summarizer, review.
- Click Create Agent.
Example
The content team lead names the agent Blog Post Summarizer, writes the description Summarizes long-form blog drafts into two-sentence abstracts for the editorial dashboard., and adds the tags content, summarizer. They click Create Agent. The agent appears in the table with a gray status badge and zero versions.
Best practice
Name agents by function, not by model. Content Summarizer is a better name than GPT-4 Agent because the model may change in a future version while the function stays the same. Adopt a consistent tagging scheme across your team (for example: content, review, safety, translation) so agents are easy to find as the list grows.
3
Open the agent detail page
After creating the agent, click its name in the agent list table to open the agent detail page. The detail page shows the agent's name and description at the top, a status badge in the top-right corner, tags displayed as labeled chips below the header, and a Versions section listing all versions for this agent.
At this point the Versions section is empty. An agent with zero versions cannot be used in a workflow: you must create at least one version before the agent appears in the workflow editor's agent selection dropdown.
A Back to Agents link at the top-left returns you to the agent list at any time.
Do this
- In the agent list table, click the agent name you just created.
- Confirm the detail page shows the correct name, description, and tags.
- Note that the Versions section is empty. You will add a version in the next step.
Example
The team lead clicks Blog Post Summarizer in the table. The detail page opens showing the name, description, and the tag chip content and summarizer. The Versions section shows no versions yet.
Best practice
Bookmark the agent detail page URL for any agent your team uses frequently. The detail page is the single source of truth for an agent's version history, configuration, and status. Sharing the URL with a colleague is faster than asking them to search the list.
4
Create the first version with a Config JSON
On the agent detail page, click Create Version in the Versions section header. A form panel expands with a single field: the Config (JSON) editor, a monospaced textarea for structured configuration.
Enter a valid JSON object that defines the agent's behavior. The most important fields are:
- systemPrompt: the instructions that define the agent's behavior and persona. This is the most consequential field. Write it precisely.
- model: the specific model to use, for example gpt-4o or claude-3-5-sonnet-20241022. The model must be available in the provider's model catalog.
- temperature: controls randomness (0.0 is deterministic, 1.0 is creative). For summarization and structured output, use a low value such as 0.2 or 0.3.
- maxTokens: the maximum number of tokens in the generated response.
- topP: nucleus sampling parameter for controlling output diversity.
Click Create Version to save. The system automatically assigns the next version number (v1 for the first version). Version numbers are auto-incremented integers: you cannot choose or skip them.
Do this
- Click Create Version in the Versions section header.
- Enter a valid JSON object in the Config (JSON) editor. Use the example below as a starting point.
- Double-check your JSON is valid: all keys and string values must use double quotes, no trailing commas after the last property, and all braces must be balanced.
- Click Create Version to save.
- Confirm the version row appears in the Versions section labeled v1 with the creation date and a Retire button.
Example
The team lead enters the following Config JSON for their summarizer agent:
```
{
 "systemPrompt": "You are an editorial summarizer. Given a long-form blog post, produce a concise two-sentence abstract suitable for an editorial dashboard. Be factual and neutral in tone. Do not add information not present in the source text.",
 "model": "gpt-4o",
 "temperature": 0.2,
 "maxTokens": 256,
 "topP": 1.0
}
```
They click Create Version. The version row appears labeled v1 with today's date and a Retire button on the right.
Best practice
Keep Config JSON minimal: only include fields your provider actually uses. Extra fields are ignored but add noise that makes the configuration harder to read and maintain. Write the system prompt as precisely as you would write a specification: vague prompts produce inconsistent output. If you are unsure of the right model identifier, check the provider's model catalog under Admin → API Management → Providers before creating the version.
5
Test the agent in a draft workflow before using it in production
An agent with a saved version is now available in the workflow editor's agent selection dropdown. Before referencing it in a production workflow, test it in a draft or staging workflow instance to verify the system prompt, model, and parameters produce the expected output.
Create a minimal test workflow: a Start node, an Agent Interaction node referencing your new agent at v1, and an End node. Run a test instance with representative input and review the output. If the output is not what you expected, return to the agent detail page, create a new version (v2) with adjusted Config JSON, and test again. Do not retire v1 until v2 is confirmed to work correctly.
Once the agent produces the expected output consistently, it is ready to reference in production workflows.
Do this
- Navigate to Workflows in the sidebar and open or create a draft workflow.
- Add an Agent Interaction node and select your new agent and version v1 from the configuration dropdowns.
- Run a test instance with representative input.
- Review the output. If it meets your standard, the agent is ready for production use.
- If the output needs adjustment, return to Agents, open the agent, create a new version with revised Config JSON, and retest.
Example
The team lead creates a minimal test workflow with a Start node, a User Interaction node to collect a sample blog post, an Agent Interaction node referencing Blog Post Summarizer v1, and an End node. They run a test instance, paste in a 1,200-word draft, and review the two-sentence abstract the agent produces. It is accurate and neutral in tone. The agent is ready for production.
Best practice
Never test a new agent version directly in a production workflow. A misconfigured version can cause running instances to fail or produce incorrect output that reaches reviewers or downstream systems. Use a draft workflow with a clearly labeled test instance. Only promote the agent to production workflows after confirming the version works correctly in isolation.

What an agent is and why it matters

In DAVE, an agent is a named, reusable AI component that performs a specific task within a workflow. It wraps an AI provider with a versioned configuration: a system prompt, a model selection, and behavior parameters such as temperature and max tokens. Once created, an agent can be referenced by any workflow in the tenant. Update the agent's behavior by creating a new version; the old version remains available and unchanged.

The alternative to agents is inline configuration: embedding a system prompt and model choice directly inside each workflow node that calls an AI service. Inline configuration works for a single workflow, but it does not scale. If you want the same summarization behavior in three workflows, you have to duplicate the configuration in each one and keep them in sync manually. When the prompt needs updating, you update it in three places, and you have no version history to fall back on if an update goes wrong.

Agents solve this by centralizing AI behavior definitions. One agent, one place to update, one version history, referenced by any number of workflows. They also give your team a single place to audit and control how AI is being used across the organization: every agent operation is logged, and every version is immutable once created.

The full execution chain in DAVE is: Providers (the AI service connection) supply models to Agents (the versioned behavior definition), which are referenced by Workflows (the orchestration graph), which run as Instances (the live execution), which may generate Tasks (the human checkpoints). An agent sits at the second link in that chain: it is the bridge between a raw AI provider connection and the workflow logic that uses it.

Before you start: what you need

Confirm the following before following the steps in this guide:

At least one provider is configured. Agents call AI providers at runtime. Before creating an agent, at least one provider must be set up under Admin → API Management → Providers. If no provider is configured, the agent can be created and versioned, but it will fail with a "No providers configured" error when a workflow tries to run it. Check with your administrator if you are unsure whether a provider exists.
You know which model you want to use. The Config JSON requires a specific model identifier (for example gpt-4o or claude-3-5-sonnet-20241022). The model must be in the provider's model catalog. Check the catalog under Admin → API Management → Providers before writing your Config JSON.
You have the Admin or Create role. Only users with the Admin or Create role can create agents and create versions. The Curate role can view agents but not create or modify them. The Use and Reporting roles cannot access the Agents section. If the New Agent button is missing, your role does not include agent creation: ask your administrator to assign you the Admin or Create role under Admin → Settings → Users and Roles.

How versioning works and why it is not optional

Every agent in DAVE maintains an independent version history. Each version is a numbered, immutable snapshot of the agent's Config JSON. Version numbers are auto-incremented integers (v1, v2, v3) assigned by the system. You cannot edit a version after it is created, you cannot choose or skip version numbers, and you cannot delete a version.

This immutability is not a constraint: it is the mechanism that makes agents trustworthy in production. Because a version cannot be changed after creation, you always know exactly what configuration was running when a workflow instance produced a particular output. If an agent produces unexpected output, you can open the agent detail page, find the version that was active at the time, and read the exact Config JSON that drove the behavior.

Creating a new version

When you need to change an agent's behavior, create a new version. Do not attempt to work around versioning by creating a new agent with a modified name. New versions are created from the agent detail page using the Create Version button in the Versions section. The new version receives the next sequential number automatically.

Retiring an old version

Once you have confirmed a new version works correctly, retire the old one. Click the Retire button on the version row. Retiring marks the version with a retiredAt timestamp and displays an amber Retired badge. A retired version cannot be selected for new workflow assignments. Existing running instances that already reference it are not affected: they continue to use the configuration until they complete.

Retiring is a one-way action. You cannot un-retire a version. If you need the same configuration again, create a new version with the same JSON. This one-way constraint prevents silent rollbacks and keeps the version history honest.

The practical discipline

Create a new version, test it in a draft workflow, confirm it works, then retire the old version. Never leave multiple active versions of an agent in production unless you have a deliberate reason for each one to be available. An agent with multiple active versions is an agent with ambiguous behavior: different workflows may reference different versions and produce different output for the same input.

Frequently asked questions

The New Agent button is missing. What do I do?

Your user account does not have the Admin or Create role for this tenant. Ask your tenant administrator to assign you the appropriate role under Admin → Settings → Users and Roles.

My agent does not appear in the workflow editor's agent selection dropdown.

This happens for one of three reasons: the agent has zero versions (an agent with no versions cannot be used in a workflow), all of the agent's versions have been retired, or the agent belongs to a different tenant than the workflow. Open the agent detail page and confirm at least one non-retired version exists. If all versions are retired, create a new version.

I get a JSON validation error when creating a version. What is wrong?

The text in the Config (JSON) editor is not valid JSON. Common causes: trailing commas after the last property, single quotes instead of double quotes around keys or values, unquoted keys, or missing closing braces. Validate your JSON before submitting. All keys and string values must use double quotes, there must be no trailing commas, and all braces and brackets must be balanced.

I see a "No providers configured" error when the agent runs in a workflow.

No AI provider has been set up for your tenant, or the provider referenced by the agent's Config JSON is unavailable. Ask your administrator to configure a provider under Admin → API Management → Providers. Verify the provider is active and the model in your Config JSON is in the provider's model catalog.

Can I use the same agent in multiple workflows?

Yes. A single agent can be referenced by any number of workflows in the same tenant. This is one of the primary reasons to use agents rather than inline configuration: create the behavior definition once and reuse it everywhere. When you update the agent by creating a new version, each workflow that references the agent can be updated to use the new version independently, at its own pace.

What is the Prompt Library and should I use it?

The Prompt Library is a collection of reusable prompt templates accessible from the Prompt Library tab on the Agents page. Instead of writing a system prompt directly in the Config JSON, you can create a prompt in the library and assign it to the agent. Library prompts can be locked to an agent: when locked, the prompt selector for that agent is greyed out in the workflow editor, so workflow designers cannot override it. Use the Prompt Library when you want to manage prompts independently of agent versions, share prompts across multiple agents, or enforce consistent prompts across all workflows that use a given agent.