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

# Agents Overview

> What a DataGen agent is made of, how a run works, and where people reach it

An agent is a folder of instructions that DataGen runs for you in the cloud. Its `CLAUDE.md` is the prompt; skills, slash commands and sub-agents sit next to it under `.claude/`. Every time the agent runs, DataGen starts a sandbox from the agent's environment, loads its files, gives it the credentials, tools, knowledge and data you connected, and lets a harness drive the conversation.

## What an agent is made of

An agent combines the three foundation components with the building blocks you attach to it.

| Part | What it decides | Where you set it |
| - | - | - |
| **Harness** | The runtime that drives each turn (Claude Agent SDK by default, or Codex), its exact version, and an optional Anthropic-compatible gateway | **Settings** tab, **Harness & model** |
| **Sandbox environment** | The image, packages and resources each run's sandbox starts from | Builder **Config**, or **Settings** tab |
| **Vault** | Which credentials the agent's tools and code authenticate with | Builder **Config**, or **Settings** tab |
| **Tools** | The tool bundle (allowlist of default, MCP and custom tools in that vault), plus the DataGen MCP gateway and workspace data tools | Builder **Config**, **Tools** tab |
| **Context** | The knowledge bases connected to the agent, read-only or read & write | Builder **Config**, **Data access** tab |
| **Data** | Published analytic models the agent can query, and which raw workspace files it may read | Builder **Config**, **Data access** tab |
| **Files** | `CLAUDE.md`, `.claude/skills/`, `.claude/commands/`, `.claude/agents/` and any scripts or reference files | Builder sandbox files, **Files** tab, or a GitHub repo |

Anything you leave unset uses the workspace default: the default vault and tool bundle, the default sandbox environment, and the built-in harness with the system default model.

<Tip>
  You can set up an agent without touching the foundation pages first. When you need a custom package, a different credential set or an LLM gateway, see [Vault](/foundation/vault), [Sandbox Environments](/foundation/sandbox-environments) and [Harness](/foundation/harness).
</Tip>

## Where an agent's files live

An agent's files come from one of two sources. The source decides how you edit them.

<CardGroup cols={2}>
  <Card title="Workspace storage" icon="folder-tree">
    Agents you create with **Create New** or **Upload**. Edit them in the [Agent Builder](/agents/build), where every **Publish** creates a version you can roll back to.
  </Card>

  <Card title="GitHub repository" icon="github">
    Agents you add with **Connect repo**. One repository is one agent; you edit by pushing to the repo, and DataGen reads the checkout on each run.
  </Card>
</CardGroup>

## How a run works

<Steps>
  <Step title="Something triggers the agent">
    A chat message, an Agent API call, an automation's schedule or webhook, a message on a channel such as Slack or email, a public chat link, or another agent.
  </Step>

  <Step title="DataGen picks the model">
    If the harness pins a provider model, that model always wins. Otherwise the first one set is used: the model named in the API call, the automation's model, the agent's default model, then the system default.
  </Step>

  <Step title="The sandbox starts">
    The sandbox boots from the agent's sandbox environment. The agent's files are loaded, each connected knowledge base is mounted read-only at `/mnt/context/contexts/<slug>/`, and vault credentials are made available to tools and code.
  </Step>

  <Step title="The harness runs the turn">
    The harness follows `CLAUDE.md`, loads skills as needed, and calls the tools in the agent's tool bundle. Connected analytic models are queried with the `datagen-data` CLI.
  </Step>

  <Step title="The reply goes back">
    The answer returns to where the run started: the chat, the API response, the Slack or Teams thread, the email reply, or the automation's destinations. Every run is recorded in **Agent Logs**.
  </Step>
</Steps>

Configuration changes such as vault, tool bundle, model, connected context and data apply from the agent's next turn. File changes go live when you publish them.

## Enabled and disabled

An agent answers only while it is **Enabled**. Turning it off with the status pill on the agent page stops it everywhere: chat, API calls, public links, email, chat apps, rooms and automations. **Test run** in the builder keeps working, so you can keep building a disabled agent. Publishing from the builder enables the agent.

## Who can do what

| Workspace role | Can do |
| - | - |
| **Admin**, **Builder** | Create agents, change configuration, publish, enable or disable |
| **Operator** | Everything a Viewer can, plus **Run now** on automations |
| **Viewer** | Read the agent's configuration, files and logs |

## Next

<CardGroup cols={2}>
  <Card title="Build an agent" icon="hammer" href="/agents/build">
    Create an agent in the Agent Builder, fork a template, or connect a GitHub repo
  </Card>

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


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