> This page is for version 0.8.
> For other versions, use one of these documentation indexes:
> - Latest (default): https://docs.nvidia.com/nemo-helix/latest/llms.txt
> - 0.9: https://docs.nvidia.com/nemo-helix/v0.9/llms.txt
> - 0.8: https://docs.nvidia.com/nemo-helix/v0.8/llms.txt
> - 0.7: https://docs.nvidia.com/nemo-helix/v0.7/llms.txt
> - 0.6: https://docs.nvidia.com/nemo-helix/v0.6/llms.txt
> - 0.5: https://docs.nvidia.com/nemo-helix/v0.5/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nemo-helix/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,
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 create` stores the agent's `agent.yaml` and uploads the
   files beside it 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](/nemo-helix/v0.8/documentation/models-and-inference), which resolves model and
   [virtual model](/nemo-helix/v0.8/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](/nemo-helix/v0.8/documentation/agents/traces-and-insights/insights-from-traces),
   evaluation, and [optimization](/nemo-helix/v0.8/documentation/agents/optimize-agents).

## Agent Lifecycle

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