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

# Build an Agent

> Create an agent in the Agent Builder, upload one, fork a template, or connect a GitHub repo, and configure every setting

There are three ways to start an agent: build it from scratch in the Agent Builder, fork a template, or connect a GitHub repository that already holds one. All three produce the same thing -- a folder whose `CLAUDE.md` is the agent's prompt -- and use the same runtime settings.

| Start from | Button on the **Agents** page | Where the files live | How you edit |
| - | - | - | - |
| Scratch | **Create New** | Workspace storage | Agent Builder |
| Files you already have | **Upload** | Workspace storage | Agent Builder, or **Update files** |
| A GitHub repository | **Connect repo** | Your repository | Push to the repo |
| A template | **Start from a Template** during onboarding | A fork in your GitHub account | Push to the fork |

<Note>
  Each workspace keeps agents in one place, chosen when the workspace is created (**Context Mode**: **STORAGE (object store)** or **GIT (connected repo)**). **Create New** and **Upload** appear in storage workspaces; **Connect repo** appears in workspaces on DataGen Cloud. Self-hosted installations always use storage.
</Note>

***

## Create an agent from scratch

<Steps>
  <Step title="Open Create New">
    Go to **Agents** and click **Create New**.
  </Step>

  <Step title="Name it">
    **Agent name** becomes the agent's file root and its URL slug (for example in the Agent API path `/api/agents/<name>/v1/messages`). It cannot be changed later. Add an optional **Description**.
  </Step>

  <Step title="Pick its runtime">
    Under **Runtime**, choose the **Vault**, **Tool bundle**, **Default model** and **Sandbox environment**. Leave any of them on the default to use the workspace default. You can change all of them later in the builder.
  </Step>

  <Step title="Open the builder">
    Click **Create & open builder**. DataGen creates the agent and opens it in the Agent Builder.
  </Step>
</Steps>

***

## The Agent Builder

The Agent Builder lives at `/signalgen/agents/<agentId>/build`. Open it from **Create New**, or click **Edit** on any storage agent's page.

| Column | What it holds |
| - | - |
| **Left** | Tabs: **Chats** (your builder conversations), **Config** (every setting below), **Versions** (published versions and rollback) |
| **Center** | The **Chat** with the agent's sandbox, any files you open, and the **Test run** tab |
| **Right** | **Sandbox files**: the agent's working tree, the **Changes** tab, and **Shared files (read-only)** for the knowledge bases it can read |

The builder keeps one long-lived sandbox per agent. Everything you and the chat change happens in that sandbox's working tree; nothing reaches the live agent until you publish.

### Build with the chat

Ask the chat to write or change the agent. It edits files in the sandbox and you see them update on the right. The empty chat offers starter prompts:

* **Write my CLAUDE.md** -- document what the agent does, its inputs and outputs, and how to work with its files
* **Add a skill that…** -- scaffold a skill for a task you describe
* **Review this agent** -- suggest improvements to its instructions, skills and structure
* **Set up a weekly schedule** -- plan a recurring run for the agent

### Edit files directly

Click a file to open it in the center column, edit it, and click **Apply** (Cmd/Ctrl-S) to write it to the sandbox. Use **New** to scaffold a **New skill**, **New command** or **New sub-agent** with valid frontmatter, and **Upload** to add files or a whole folder. Entries in the tree can also be renamed, downloaded, reverted or deleted.

### Test before you publish

Click **Test run** to run the agent on your current draft in its own tab. Starter prompts include **Run a smoke test**, **What can you do?** and **Run an example task**. Click **New run** to start fresh on the latest draft.

<Tip>
  Test runs work even while the agent is disabled, so you can build and test without anyone else reaching it.
</Tip>

### Publish

The **Changes** tab lists every file that differs from the live agent. Click **Publish** (the button shows the number of changes), add optional **Release notes**, and confirm. Publishing:

* Syncs the sandbox files to the agent's storage
* Records a new version, including the agent's settings, that you can roll back to
* Enables the agent if it was disabled

Click **Discard** to throw away all unpublished changes, or **Revert** a single file. See [Versions and Logs](/agents/versions-and-logs) for rollback.

### Restart the sandbox

Vault, tool bundle, harness and model changes apply on your next message. A changed or rebuilt **sandbox environment** only applies to a fresh sandbox: click **Restart sandbox** in the header. Unsaved files are checkpointed and restored; anything installed by hand inside the sandbox is lost.

### One editor at a time

Only one person can be active in an agent's builder. If someone else is using it, choose **Take over** to become the active user, or **View only** to browse the files and chat history.

***

## Agent file layout

```text theme={null}
my-agent/
├── CLAUDE.md                     # The agent's prompt
├── .claude/
│   ├── skills/<name>/SKILL.md    # Skills the agent loads when relevant
│   ├── commands/<name>.md        # Slash commands
│   └── agents/<name>.md          # Sub-agents the main agent can delegate to
└── scripts/, data/, ...          # Anything else the agent uses
```

Skills, commands and sub-agents belong to the agent. They are not run on their own: only the agent is enabled, automated and reached through channels.

<AccordionGroup>
  <Accordion title="Skill: .claude/skills/<name>/SKILL.md">
    ```markdown theme={null}
    ---
    name: enrich-lead
    description: Enrich a company lead with web research. Use when given a company name or domain.
    ---

    # enrich-lead

    Given a company name and domain, find:
    1. Company size, industry and funding
    2. Recent news and product launches
    3. Key decision makers and their titles

    Return structured JSON with all findings.
    ```

    A skill folder can hold supporting files next to `SKILL.md`, such as reference notes or helper scripts.
  </Accordion>

  <Accordion title="Command: .claude/commands/<name>.md">
    ```markdown theme={null}
    ---
    description: Summarize this week's new leads.
    argument-hint: "[region]"
    ---

    Summarize the leads created in the last 7 days for $ARGUMENTS,
    grouped by source, and flag anything unusual.
    ```
  </Accordion>

  <Accordion title="Sub-agent: .claude/agents/<name>.md">
    ```markdown theme={null}
    ---
    name: report-writer
    description: Delegate here to turn analysis results into a short report.
    ---

    You are a focused sub-agent. You receive analysis results and return
    a concise report with a summary, three key findings and next steps.
    ```
  </Accordion>
</AccordionGroup>

***

## Configuration reference

The builder's **Config** tab holds the settings below; click **Save config** after changing them. The agent page has the same settings spread across its **Settings**, **Tools** and **Data access** tabs, plus a few that only live there. Changes apply from the agent's next turn.

### Identity

| Field | Notes |
| - | - |
| **Agent name** | Fixed after creation. It is the agent's file root and URL slug. |
| **Description** | What the agent does. |

### Model and runtime

| Field | Where | Notes |
| - | - | - |
| **Default model** | Config, Settings | The model the agent runs on when neither an API call nor an automation names one. Leave it blank for the system default, shown as the placeholder. DataGen checks the model against the provider when you save. |
| **Harness** | Settings tab, **Harness & model** | The harness preset that runs the agent. **Default (built-in SDK, stock Anthropic)** uses the built-in Claude Agent SDK. If the preset pins a provider model, the agent always runs on that model and the default-model field is hidden. See [Harness](/foundation/harness). |
| **Sandbox environment** | Config, Settings | The baked image and packages the agent's sandbox starts from. **Default (standard image)** uses the standard image. Appears when sandbox environments are enabled for your account. See [Sandbox Environments](/foundation/sandbox-environments). |

### Tools and credentials

| Field | Where | Notes |
| - | - | - |
| **Vault** | Config, Settings | The credential set the agent's tools and code authenticate with. **Workspace default** uses the workspace's default vault. See [Vault](/foundation/vault). |
| **Tool bundle** | Config, Settings | The allowlist of tools the agent can call, chosen from bundles in the selected vault. Changing the vault resets the bundle. See [Tools](/agents/tools). |
| **Enable DataGen MCP for this agent** | Config, Settings | Attaches the DataGen MCP gateway (`searchTools`, `getToolDetails`, `executeToolCall`) to the agent's runs. Off by default. |
| **Enable workspace data tools for this agent** | Config, Data access | Lets the agent list and read the workspace's raw files, its own earlier outputs and its connected knowledge bases on demand. Read-only. On by default. |
| **Skills** | Tools tab | Install approved skills from the workspace registry. See [Skills](#skills). |

### Knowledge and data

| Field | Where | Notes |
| - | - | - |
| **Connected contexts** | Config (**Knowledge bases**), Data access | Knowledge bases the agent reads, mounted read-only at `/mnt/context/contexts/<slug>/`. Each run reads the live version. A knowledge base attached **Read & write** also serves as the agent's memory. Read vs. read & write is set on each knowledge base's own **Agents** tab. See [Use Context](/context/use). |
| **Exposure** | Data access | **Connected only** (the default): the sandbox holds exactly the connected knowledge bases; raw workspace files are fetched on demand through the workspace data tools. **Whole workspace** is a compatibility mode for older agents: once switched to **Connected only**, it cannot be switched back. |
| **Analytic models** | Config, Data access | Published materialized models the agent can query with the `datagen-data` CLI. Each query reads the live version's current data. See [Use Data](/data/use). |
| **Data scope** | Data access | Which raw workspace data the agent may read: **Unrestricted**, or **Selected folders only** with the folders and files you add. A hard boundary: anything outside it is refused. The builder shows a summary with a link to change it. |

### Behaviour and memory

| Field | Where | Notes |
| - | - | - |
| **Show working details in chat** | Config, Settings (**Chat display**) | On: chat shows tool calls and reasoning beside the answer. Off: answer only. Builder chat and run logs always keep full detail. |
| **Auto-record learnings** | Config, Data access | Adds DataGen's default memory-maintenance guidance to the system prompt, so the agent records what it learned into any knowledge base it can write to. Off by default, and only takes effect with a writable knowledge base. See [Memory](/context/memory). |
| **Agents it can call** | Data access | Other agents this agent can start a turn on with `datagen-assets invoke`, as the person it is running for. A called agent cannot call further agents. |

### Skills

Skills from the workspace registry are installed per agent on the **Tools** tab:

1. Approve the skill under **Skills** in the sidebar. See [Skills](/context/skills).
2. On the agent's **Tools** tab, search for it in the **Skills** card and install it.

An installed skill is copied into the agent's own `.claude/skills/` and ships with its files on every run. When a newer approved version exists, the card offers to update it.

***

## Upload an agent

If you already have an agent folder, upload it instead of building from scratch.

<Steps>
  <Step title="Click Upload">
    On the **Agents** page, click **Upload**.
  </Step>

  <Step title="Choose a file or folder">
    Pick **Single file** or **Folder**, and enter the **Agent name**. Files are written under `<name>/`, and the dialog lists exactly where each one lands.
  </Step>

  <Step title="Upload">
    DataGen creates the agent. Its `CLAUDE.md` is the prompt.
  </Step>
</Steps>

On the agent page, **Update files** uploads a new version of the folder, and **Export ZIP** downloads the agent so you can use it anywhere.

***

## Connect a GitHub repository

Use this when your agent already lives in a repository, or you prefer to author it locally in Claude Code and push.

<Steps>
  <Step title="Click Connect repo">
    On the **Agents** page, click **Connect repo**.
  </Step>

  <Step title="Install the GitHub App">
    Click **Install GitHub App** and install the DataGen GitHub App on your organization or personal account. You return to the dialog when it finishes.
  </Step>

  <Step title="Select the repository">
    Choose it under **Select a repository**, or use **Advanced: Enter URL manually** for a repository that is not listed. Click **Connect**.
  </Step>
</Steps>

DataGen creates one agent per repository. The repository's `CLAUDE.md` is the prompt, and the skills, commands and sub-agents under `.claude/` are listed on the agent page under **Skills & commands**. Every run loads the sandbox from the repository's checkout.

To change a repository agent, push to the repository. The runtime settings (vault, tool bundle, model, harness, sandbox environment, knowledge and data) are set on the agent page the same way as for any other agent.

<Tip>
  Using Claude Code locally? The DataGen plugin's `/datagen:build-agent` command walks you through designing an agent, and `/datagen:deploy-agent` connects the repository. See [Claude Code Plugin](/developers/plugin-quickstart).
</Tip>

***

## Fork a template

New DataGen Cloud accounts are offered **Start from a Template** during onboarding. **Use Template** forks the template's repository into your GitHub account and connects it, so it behaves like any other repository agent. See [Templates](/agents/templates).

***

## Next

<CardGroup cols={2}>
  <Card title="Give it tools" icon="wrench" href="/agents/tools">
    Vaults, tool bundles, MCP servers, custom tools and the DataGen MCP gateway
  </Card>

  <Card title="Trigger it" icon="bolt" href="/agents/triggers">
    Run now, schedules and webhooks with automations
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.