> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nemo-helix/v0.9/documentation/agents/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nemo-helix/_mcp/server.

# About Agents

> Register, deploy, observe, and optimize agents on NeMo Helix.

An agent on NeMo Helix is an `agent` entity in a workspace. Once registered, the
platform can deploy it, route requests to it, collect its traces, evaluate it,
and optimize it. Agents run through
[NeMo Fabric](https://docs.nvidia.com/nemo/fabric/about-nemo-fabric/overview/),
which gives every supported harness (DeepAgents, Claude Code, Codex, Hermes,
Mini-SWE-Agent, NOOA, or a remote agent endpoint) the same configuration, lifecycle, and
telemetry.

## How It Works

```mermaid
flowchart LR
 Client --> GW["Agents gateway"]
 GW --> D["Agent deployment"]
 D --> IGW["Inference Gateway"]
 IGW --> Models
 D -. traces .-> Intake
```

1. **Register.** `nemo agents register` creates an agent identity. With `--agent-config`,
   it also stores the agent's config and uploads the files beside a Fabric config to
   the agent's `<name>-ethos` fileset.
2. **Deploy.** `nemo agents deploy` runs the agent as a local subprocess, a Docker
   container, or a Kubernetes Deployment.
3. **Invoke.** The Agents gateway routes each request to the agent's active deployment
   and exposes it as an OpenAI-compatible endpoint, whatever the runtime.
4. **Call models.** Model traffic from the agent goes through the
   [Inference Gateway](/documentation/models-and-inference), which resolves model and
   [virtual model](/documentation/models-and-inference/virtual-models) names and attaches
   provider credentials. Agent configs never carry provider API keys for platform-routed models.
5. **Trace.** Deployed agents export trajectories to Intake under the agent's name by default, which
   feeds [Insights](/documentation/agents/traces-and-insights/insights-from-traces),
   evaluation, and [optimization](/documentation/agents/optimize-agents).

## Upgrade and adapter setup

For NeMo Helix 0.9, start with
[Fabric 0.5 Upgrade and Adapter Support](/documentation/agents/fabric-upgrade): it
covers the registration-command rename, host/task package compatibility,
persisted Relay observability, gateway telemetry routing, and the difference
between a shipped descriptor and an installed harness. Pi is an opt-in packaged
integration, not an end-to-end release-gated harness in the 0.9 CI matrix.

For Mini-SWE-Agent 2.x, follow
[Run Mini-SWE-Agent](/documentation/agents/mini-swe-agent) for a complete
install → register → deploy → invoke → session → cleanup journey.

## Agent Lifecycle

| Stage             | Command                                                                  |
| ----------------- | ------------------------------------------------------------------------ |
| Register          | `nemo agents register --name <name> [--agent-config <path>]`             |
| Deploy            | `nemo agents deploy --agent <name>`                                      |
| Invoke            | `nemo agents invoke --agent <name> --input "..."`                        |
| Chat              | `nemo agents chat --agent-deployment <deployment>`                       |
| Run once as a job | `nemo agents execute --agent <name> --input "..."`                       |
| Analyze traces    | `nemo compass analysis-runs create --agent <name>`                       |
| Optimize          | `nemo agents optimize run-strategy --strategy <strategy> --agent <name>` |
| Update in place   | `nemo agents redeploy --agent <name> --agent-config <path>`              |
| Tear down         | `nemo agents undeploy --agent <name>`, then `nemo agents delete <name>`  |

To try an `agent.yaml` without registering it, run `nemo agents invoke --agent-config <path> --input "..."`.

## Next Steps

* [Register Agents](/documentation/agents/register-agents): from code, a container image, a
  remote endpoint, or traces.
* [Deploy Agents](/documentation/agents/deploy-agents): choose a runtime, and build and publish
  agent images.
* [Execute Agents as Jobs](/documentation/agents/execute-agents-as-jobs): run an agent once, to
  completion.
* [Collect Agent Traces](/documentation/agents/traces-and-insights/collect-agent-traces) and
  [Insights from Traces](/documentation/agents/traces-and-insights/insights-from-traces): find out
  what your agent does and where it fails.
* [Optimize Agents](/documentation/agents/optimize-agents): generate, evaluate, and compare
  candidate agents.
* [Agent Governance](/documentation/agents/governance): attack a sandboxed copy of an agent, then
  generate and validate guardrail and sandbox-policy fixes.

> Register, deploy, observe, and optimize agents on NeMo Helix.

## Docs

- [Register Agents](https://docs.nvidia.com/nemo-helix/v0.9/documentation/agents/register-agents.md): Register an agent on NeMo Helix from code, a container image, a remote endpoint, or its traces.
- [Fabric 0.5 Upgrade and Adapter Support](https://docs.nvidia.com/nemo-helix/v0.9/documentation/agents/fabric-upgrade.md): Agent migration, telemetry compatibility and adapter installation for NeMo Helix 0.9.
- [Run Mini-SWE-Agent](https://docs.nvidia.com/nemo-helix/v0.9/documentation/agents/mini-swe-agent.md): Install, deploy and use Mini-SWE-Agent 2.x with NeMo Helix.
- [Deploy Agents](https://docs.nvidia.com/nemo-helix/v0.9/documentation/agents/deploy-agents.md): Run a registered agent as a subprocess, Docker container, or Kubernetes Deployment, and build and publish agent images.
- [Sandboxed Deployments](https://docs.nvidia.com/nemo-helix/v0.9/documentation/agents/deploy-agents/sandboxed-deployments.md): Deploy a prepared Fabric agent through OpenShell and verify inference and network policy.
- [Execute Agents as Jobs](https://docs.nvidia.com/nemo-helix/v0.9/documentation/agents/execute-agents-as-jobs.md): 
- [Collect Agent Traces](https://docs.nvidia.com/nemo-helix/v0.9/documentation/agents/traces-and-insights/collect-agent-traces.md): Ingest, store, and query agent telemetry with NeMo Intake, including supported ingest paths, annotations, evaluator results, and review in NeMo Studio.
- [Insights from Traces](https://docs.nvidia.com/nemo-helix/v0.9/documentation/agents/traces-and-insights/insights-from-traces.md): Run NeMo Compass over an agent's traces to file evidence-backed Insights, on demand or on a schedule.
- [Optimize Agents](https://docs.nvidia.com/nemo-helix/v0.9/documentation/agents/optimize-agents.md): Generate candidate agents with plugin-provided optimization strategies, then evaluate and compare them against the original.
- [Agent Governance](https://docs.nvidia.com/nemo-helix/v0.9/documentation/agents/governance.md): 
- [Run a War-Game](https://docs.nvidia.com/nemo-helix/v0.9/documentation/agents/governance/run-a-war-game.md): 
- [Review and Apply Mitigations](https://docs.nvidia.com/nemo-helix/v0.9/documentation/agents/governance/apply-mitigations.md): 
- [Agent Hardening CLI Reference](https://docs.nvidia.com/nemo-helix/v0.9/documentation/agents/governance/cli-reference.md): 
- [Troubleshooting](https://docs.nvidia.com/nemo-helix/v0.9/documentation/agents/governance/troubleshooting.md):