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

# Agents

> Git-backed agents for document tasks that are hard to express as a fixed step graph.

An **agent** is the alternative to a [workflow](/concepts/workflows) when the
task does not fit a fixed graph of typed steps. An agent runs in a sandbox,
reads inputs, and produces structured output using a Git-backed source package
you maintain over time.

Use a workflow by default. Its steps run the same way every time, which makes it
easier to evaluate, debug, and review. Use an agent when the task is open-ended
or changes shape per input. Both are evaluated the same way; an agent changes how
the output is produced, not how quality is measured.

## When to use which

|             | Workflow                                 | Agent                                         |
| ----------- | ---------------------------------------- | --------------------------------------------- |
| Shape       | Fixed DAG of typed steps                 | Autonomous coding agent in a sandbox          |
| Authoring   | YAML you edit (or the builder generates) | Git-backed source package, trained via chat   |
| Determinism | Deterministic, same path every run       | Model-driven, adapts per input                |
| Best for    | Known pipelines, strict reproducibility  | Open-ended extraction, per-document variation |

Both run from the same places, are evaluated against datasets the same way, and
are inspected with the same `eigenpal runs` commands.

## Two ways an agent runs

* **Inference run** provisions a sandbox, mounts the agent's source, sends one
  prompt, collects results, and tears the sandbox down. This is what the Run
  button, the API, and eval batches use. Each run starts fresh, with no
  conversation history, and its output is validated against the agent's output
  schema.
* **Builder session** is interactive: a persistent sandbox with a coding agent
  in the training UI. You describe the change, the agent edits the Git-backed
  source, and you commit and push those changes through the `eigenpal agents`
  commands. Use it to update the source package, then run it via inference.

## Source lives in Git

An agent's source is a package in your organization's Git repository, not a
single file. Use `eigenpal agents` commands to clone, validate, commit, push,
release, and sync it:

```bash theme={null}
eigenpal agents clone --out tmp/org-repos/acme-prod   # clone the org repo
eigenpal agents validate                              # check source locally
eigenpal agents commit -m "teach invoice totals"      # commit changes
eigenpal agents push                                  # push to the org remote
eigenpal agents release                               # cut a release tag
eigenpal agents sync                                  # apply the release to the platform
```

See the [`eigenpal agents`](/cli/agents) reference for the full command surface.

## Running an agent

Start a run from the dashboard Run button, the CLI, or the API. Pass the agent
target in the JSON body alongside the input object:

```bash theme={null}
curl -X POST https://studio.eigenpal.com/api/v1/runs \
  -H "Authorization: Bearer eig_live_..." \
  -F 'target=agents.extract-invoice' \
  -F 'input={"language":"en","vendor":"Acme"}' \
  -F 'files.document=@invoice.pdf'
```

Send scalar fields in the `input` JSON part and each upload as `files.<fieldName>`.
See the [API reference](/api-reference) for run status,
review, and corrected-output endpoints.

## Inspecting and improving runs

Every run produces output, a trace of what the agent did, and a place to attach
reviews and corrected outputs. Inspect them with the same commands you use for
workflow runs:

```bash theme={null}
eigenpal runs list
eigenpal runs get <run-id>
eigenpal runs trace <run-id>
eigenpal runs reviews <run-id> ...
```

Reviews and expected artifacts are available to builder sessions, so future
source changes can account for past failures. See [Reviews](/concepts/reviews)
for the verdict/status model and [Review production runs](/guides/review-runs)
for the full review-and-rerun workflow.