Skip to main content
An agent is the alternative to a workflow when the task does not fit a fixed graph of typed steps. An agent uses model requests and tools to produce structured output from a Git-backed TypeScript definition. Normal agents run without a filesystem sandbox; add .withFilesystem() when they need files or shell scripts. 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

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

​
Execution and authoring

An inference run executes a released agent and validates its final output. Normal agents use structured inputs, custom tools and portable resources without a filesystem sandbox. Filesystem agents also receive a workspace and sandbox read/write/shell tools. Both modes capture the selected source commit and definition. A builder session is an optional sandbox-backed editing session in Studio. It edits the Git source; it is separate from running a normal agent. Deployments without enabled sandboxes can still author through Git/CLI and run normal agents. Use the agent authoring SDK to define capabilities and callback guide to understand custom tool limits. Use the API client to start and inspect runs from application code.

​
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:
See the eigenpal 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:
This file-upload example requires a filesystem agent. Send scalar fields in the input JSON part and each upload as files.<fieldName>. For a normal agent, send its structured input without file uploads. See the 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:
Reviews and expected artifacts are available to builder sessions, so future source changes can account for past failures. See Reviews for the verdict/status model and Review production runs for the full review-and-rerun workflow.