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

# Agents

> Naming, splitting, renaming, and configuring per-agent evaluation. The Agent is the unit of identity that ties every other DecimalAI concept together.

The **Agent** is DecimalAI's unit of identity. Every trace is attributed to one agent. Every manifest version belongs to one agent. Every regression check, dataset, evaluator, and skill assignment is per-agent.

If you only have one agent, this page is mostly informational. If you have many — or you're deciding whether to split one — these are the decisions that affect everything downstream.

## What an Agent is (and isn't)

**An agent is a name**. Pick a string, pass it to `decimalai.init(agent_name="support-agent")` (or your framework adapter's equivalent), and every subsequent trace is bucketed under that name.

That name is the join key for six things at once — sever it, and every spoke loses its history:

```mermaid theme={null}
%%{init: {'theme':'base','themeVariables':{'primaryColor':'#f5f5f4','primaryBorderColor':'#a8a29e','primaryTextColor':'#44403c','lineColor':'#a8a29e'}}}%%
graph TD
  A["agent_name"]
  A --- T["Manifest timeline<br/>(one per agent)"]
  A --- B["Regression baseline<br/>(one active manifest per agent)"]
  A --- F["Trace filters<br/>(agent_name=...)"]
  A --- E["Per-agent evaluators"]
  A --- D["Per-agent dataset scope"]
  A --- S["Skill-effectiveness analytics"]
```

It is **not** a string you should change casually. Renaming an agent is fine; you just lose continuity if you do it.

## Naming agents — what to pick

Three rules:

1. **Lowercase, hyphenated, no spaces.** `support-agent`, not `Support Agent` or `SupportAgent`. Names appear in URLs (`/agents/support-agent`), CLI commands, and webhook payloads.
2. **Describe the role, not the implementation.** `support-agent` is good. `langchain-react-bot` is bad — when you switch frameworks next year, the name lies.
3. **Use a stable prefix if you'll have many.** `triage-frontline`, `triage-escalation`, `triage-billing` make filtering, ACLs, and dashboards easier than three unrelated names.

Names you should avoid:

* `agent`, `bot`, `assistant` (collide with default examples)
* Anything containing your company name (you'll never type it consistently)
* Anything containing the model name (gets stale on every model swap)

## When to use one agent vs. multiple

This is the most consequential decision because it affects every other concept downstream. Two questions:

<AccordionGroup>
  <Accordion title="Q1: Do they share the same manifest surfaces (tools, system prompt, model)?">
    If yes → **one agent**. They're behaviorally the same thing, just routed differently. You can still distinguish them in trace metadata (`session_id`, custom tags, the `route_decision` span) without splitting.

    If no → **multiple agents**. Splitting now means every manifest change to one doesn't pollute the regression report for the other.
  </Accordion>

  <Accordion title="Q2: Would you ever want a different regression policy for them?">
    Example: a `support-agent` serving customers needs strict pre-deploy regression checks; an `internal-research-agent` you and three engineers use can deploy looser changes.

    If they need different policies → **split them**. Evaluators and compatibility policies are per-agent.

    If they share the policy → keeping them as one agent is fine.
  </Accordion>
</AccordionGroup>

The common shape: **one agent per "product surface"** that gets shipped independently. A chat agent and a voice agent are two products even if they share most of the backend.

### When NOT to split

| Scenario                                     | Split? | Do instead                                                                                                                        |
| -------------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------- |
| Different prompts for different users        | No     | Same agent — vary the prompt via the `rendered_input`.                                                                            |
| A/B testing two variants                     | No     | Same agent — log both via `manifest_id` (the active variant is the baseline; run a regression check on the experimental variant). |
| Multiple tools sometimes called sequentially | No     | Same agent — tools are part of the manifest, not separate agents.                                                                 |

## Renaming an agent without losing history

Agent names are stable identifiers — they aren't first-class entities you rename in place. To rebrand:

<Steps>
  <Step title="Choose the new name">
    Pick a name that follows the [naming rules](#naming-agents-what-to-pick). Confirm it doesn't already exist — check the **Agents** list in the dashboard or `GET /api/v1/agents`.
  </Step>

  <Step title="Pass it via `decimalai.init()` in your next deploy">
    Update your initialization code. The next trace ingested under the new name creates the agent fresh.

    ```python theme={null}
    # before
    decimalai.init(agent_name="support-bot")

    # after
    decimalai.init(agent_name="support-agent")
    ```
  </Step>

  <Step title="Rename the agent record">
    Call `POST /api/v1/agents/<old-name>/rename` with `{"new_name": "<new-name>"}`. Because it's the same agent record, all existing manifests, traces, and datasets stay attached — nothing is copied or merged. The old name keeps resolving via a forwarding alias, so existing URLs and `agent_name=` filters don't break.

    <Note>
      This renames in place; it is not a merge. To fold two distinct agents together, re-ingest under the surviving name instead.
    </Note>
  </Step>

  <Step title="Update references">
    Search your repo + workflow files for the old name. Common places: `.github/workflows/decimal.yml` (the regression-check action), evaluator names, dataset filters.
  </Step>
</Steps>

If you forget step 3, the old agent stays in the sidebar with its frozen history — annoying but not destructive.

## Per-agent evaluation

How strictly an agent's traces are scored is controlled by the **evaluators** attached to it, not a standalone policy object. Create and manage them via the evaluators surface:

```bash theme={null}
# List evaluators (optionally scoped to one agent)
decimalai evaluators list --agent support-agent

# See available templates, then attach one to a single agent
decimalai evaluators templates
decimalai evaluators add --template helpfulness_judge --agent support-agent
```

The older per-agent `EvalPolicy` (and the `/api/v1/agents/{name}/eval-policy` route) is deprecated — configure evaluators via `/api/v1/evaluators` instead.

See [Evaluations](/guides/evaluations) for how built-ins, `@eval` functions, and LLM judges combine, and [Compatibility Policies](/guides/compatibility-policies) for the separate per-manifest compatibility rules.

## Sub-agents and orchestrators

If your system has an orchestrator that delegates to specialist sub-agents, register each one as its own DecimalAI agent. The orchestrator gets one manifest (tracking *which* sub-agents it can call); each sub-agent gets its own (tracking *what each does*). Cross-agent traces are linked via `parent_trace_id`, so the dashboard shows the full call graph.

This is covered in depth in the [Multi-agent guide](/guides/multi-agent).

## What's next

<CardGroup cols={2}>
  <Card title="Tracing" icon="route" href="/guides/tracing">
    Instrument your agent code so traces start landing under the agent's name.
  </Card>

  <Card title="Manifests" icon="layer-group" href="/guides/manifests">
    How agent versions are tracked and what gets hashed into a manifest.
  </Card>

  <Card title="Multi-agent" icon="users" href="/guides/multi-agent">
    Orchestrator / sub-agent patterns and how cross-agent traces link up.
  </Card>

  <Card title="Evaluations" icon="check-double" href="/guides/evaluations">
    Define what "good" means for each agent — built-ins, @eval functions, and LLM judges.
  </Card>
</CardGroup>