Execute Agents as Jobs

An execute-agent job (agents.execute) runs an agent once, to completion, as a scheduled platform job. You give it an agent and a prompt; the platform schedules a container, runs the agent until it finishes or times out, saves everything the run produced, and exits.

This is the bounded counterpart to Deploy Agents. A deployment is a service that stays up waiting for requests. An execute job is a single unit of work with a beginning and an end — you are asking an agent to do one thing, not to be available.

When to Use a Job Instead of a Deployment

Reach for a job when the work is long enough that holding an HTTP connection open is the wrong shape, when the run produces files rather than a reply, or when the agent only needs to exist for the duration of one task.

# Configure CLI (if not already done)
nemo config set --base-url "$NMP_BASE_URL" --workspace default

How It Works

1. Submission resolves and snapshots everything. When the job is created, the platform resolves the agent reference, resolves and merges the agent environment, and validates any working-directory references. A bad agent name, a missing secret, or a nonexistent fileset fails your create request rather than the run. The resolved config, compute, and secret references are snapshotted onto the job, so a later edit to the underlying entities does not change what an already-submitted job runs.
2. The job runs the agent once. The scheduled step stages the working directory, invokes the agent through Fabric with your prompt, and waits up to timeout_seconds for a result.
3. Everything is saved as job results. The input working directory, the output working directory, the run’s artifacts, and Fabric’s own run record are all saved and downloadable after the job finishes — including when it fails.

Submit a Job

The examples below use the calculator agent that ships with the source checkout. Register it first if you have not already:

nemo agents create \
  --name calculator-agent \
  --agent-config plugins/nemo-agents/examples/nemo-agent-config/calculator-agent/agent.yaml

nemo agents execute \
  --agent calculator-agent \
  --input "What is 12 multiplied by 8?"

Job Spec Fields

The CLI generates one flag per spec field (--agent, --input, --environment, --workdir.base-workdir, --timeout-seconds, --auto-telemetry). Fields that do not reduce to a single flag — an inline agent, an inline environment, workdir.artifact_mounts — are supplied with --spec (a JSON string) or --spec-file (a YAML or JSON file). Individual flags override values from the supplied spec.

Track a Job and Fetch Its Results

An execute job is an ordinary platform job, so the nemo jobs commands work on it by name (e.g. "calc-run-1" in the example commands below).

# Block until the job reaches a terminal status, streaming logs
nemo jobs watch calc-run-1
# Or poll it yourself
nemo jobs get-status calc-run-1
nemo jobs tail calc-run-1 -n 200
# List what the run produced, then download one result
nemo jobs results list --job calc-run-1
nemo jobs results download output_workdir --job calc-run-1 -o output_workdir.tar.gz

Result Names

Results download as gzipped tarballs of a directory, or as a single JSON file.

Working Directories

An agent that reads and writes files needs somewhere to do it. workdir builds that directory from the Files service before the agent starts.

Mounts are applied after the base tree, so a mount at the same path wins. Mount paths must be relative and must not overlap each other.

# run.yaml
agent: research-agent
input: Review the config and summarize the risks.
workdir:
  base_workdir: default/project-source
  artifact_mounts:
    - ref: default/config-artifact#config.yaml
      mount_path: app/config.yaml
    - ref: default/notes-artifact#notes.txt
      mount_path: notes/notes.txt

nemo agents execute --spec-file run.yaml

Whatever the agent leaves behind in that directory comes back as output_workdir.

Environments, Secrets, and Compute

Execute jobs use the same environment model as deployments. Pass --environment default/research and the environment’s spec is merged into the agent config, its secret references become secret-backed environment variables on the job step, and its compute spec sizes the container.

nemo agents execute \
  --agent research-agent \
  --environment default/research \
  --input "Summarize this repo's dependencies and risks."

Compute is expressed the Kubernetes way on the compute spec. Execute jobs support cpu, memory, and nvidia.com/gpu; any other resource key is rejected at submission rather than silently dropped.

See Agent Environments for how to create the environment, environment spec, and compute spec.

Inline Agents

agent also accepts a full agent definition instead of a reference. The config is validated at submission and snapshotted onto the job, but it is never stored as an Agent entity. This suits an agent composed per request — models chosen by the caller, harness settings scoped to a single run — where there would be nothing to keep in sync afterward.

{
  "agent": {
    "config_format": "nemo-agents-spec-v1",
    "config": {
      "config_format": "nemo-agents-spec-v1",
      "name": "one-off-analyst",
      "default_harness": "deepagents",
      "harnesses": {"deepagents": {"kind": "deepagents", "settings": {"deepagents": {}}}},
      "models": {
        "default": {
          "provider": "nvidia",
          "model": "nvidia-nemotron-3-nano-30b-a3b",
          "api_key_env": "NVIDIA_API_KEY"
        }
      }
    }
  },
  "input": "Summarize yesterday's failures."
}

Supply it with --spec/--spec-file from the CLI, or as the spec body from the SDK.

Execute Extensions

A plugin can register a trusted extension that runs after a successful invocation and turns the agent’s output into something the plugin owns — for example, the Insights plugin’s analysis runs attach an extension that saves an analysis-report result and files the insights it found.

Extensions are named by extension.kind and configured by extension.config. Only kinds registered by an installed plugin are accepted; an unknown kind fails the create request. If you are using a feature built on execute jobs, its own commands set this for you.

Requirements and Limits

• Config format. Only nemo-agents-spec-v1 agents can run as execute jobs. Legacy NAT workflow configs are rejected; use nemo agents evaluate or a deployment for those.
• Fabric environment. The merged agent config must select the local Fabric environment provider. Because an environment spec can override the provider, this is checked after the merge.
• Timeout. timeout_seconds bounds the wait for a Fabric result and defaults to one hour. A run that exceeds it fails with a saved fabric_error rather than hanging.
• Reserved environment variables. A secret cannot be bound to an environment variable name the platform injects itself (the NEMO_JOB_* family, NMP_BASE_URL, AGENT_CONFIG_PATH, and similar). The collision is rejected at submission.

Clean Up

Job records and their results persist until you remove them.

nemo jobs cancel calc-run-1   # stop a running job
nemo jobs delete calc-run-1   # remove the record and its results