feat(nemo-agent): add mcp calculator example

docs/agents/index.mdx

@@ -81,40 +81,39 @@ An agent's behavior is described by the platform-managed `agent.yaml`:
 |---------|---------|---------|
 | `config_format` | Selects the versioned Platform agent contract. Use `nemo-agents-spec-v1`. | `nemo-agents-spec-v1` |
 | `name` | Provides the agent name used in runtime metadata. | `calculator-agent` |
-| `description` | Summarizes the agent's purpose for users and image metadata. | `Calculator agent executed with Codex` |
+| `description` | Summarizes the agent's purpose for users and image metadata. | `Calculator agent executed with DeepAgents` |
 | `instructions` | Defines shared instructions for every harness. `instructions.system.content` contains the system prompt. | `system.content: You are a concise calculator agent.` |
-| `default_harness` | Selects the entry under `harnesses` that runs by default. | `codex` |
-| `harnesses` | Declares the supported harness adapters and their harness-specific model or runtime settings. | `codex.kind: codex`, `codex.settings.sandbox: read-only` |
+| `default_harness` | Selects the entry under `harnesses` that runs by default. | `deepagents` |
+| `harnesses` | Declares the supported harness adapters and their harness-specific model or runtime settings. | `deepagents.kind: deepagents` |
 | `models` | Declares shared named model bindings. A harness uses `models.default` unless it defines its own model. | `default.provider: nvidia`, `default.model: nvidia-nemotron-3-nano-30b-a3b` |
 | `skills` | Lists skill directories, relative to `agent.yaml`, that are made available to the harness. | `paths: [./skills/math]` |
 | `mcp` | Configures shared MCP servers that expose tools and resources to the harness. | `servers.github.transport: streamable-http`, `servers.github.url: ${GITHUB_MCP_URL}` |
 | `tools` | Defines shared tool policy, such as tool names that the harness must block. | `blocked: [shell, browser]` |
 | `environment` | Configures the agent's runtime workspace, artifacts directory, provider, and provider-specific settings. | `workspace: ./workspace`, `artifacts: ./artifacts` |
 | `telemetry` | Configures telemetry collection and output, including Relay, ATIF, and ATOF settings. | `provider: relay`, `atif.enabled: true`, `atof.enabled: true` |
 
-The calculator agent uses Codex as its harness and the Platform Inference
+The calculator agent uses DeepAgents as its harness and the Platform Inference
 Gateway for model access. It answers arithmetic and numeric comparison
 requests and records ATIF and ATOF telemetry with NeMo Relay:
 
 ```yaml
 config_format: nemo-agents-spec-v1
 name: calculator-agent
-description: Calculator agent executed with Codex
+description: Calculator agent executed with DeepAgents
 
 instructions:
   system:
     content: |
       You are a concise calculator agent. Solve arithmetic and numeric
       comparison requests yourself and return only the answer.
 
-default_harness: codex
+default_harness: deepagents
 
 harnesses:
-  codex:
-    kind: codex
+  deepagents:
+    kind: deepagents
     settings:
-      sandbox: read-only
-      reasoning_effort: high
+      deepagents: {}
 
 models:
   default:
@@ -145,7 +144,7 @@ telemetry:
     filename_template: trajectory-{session_id}.atif.json
     storage:
       - type: http
-        endpoint: http://127.0.0.1:8080/apis/intake/v2/workspaces/default/ingest/atif
+        endpoint: http://localhost:8080/apis/intake/v2/workspaces/default/ingest/atif
         timeout_millis: 3000
   atof:
     enabled: true

plugins/nemo-agents/README.md

@@ -79,67 +79,42 @@ nemo-relay --version
 
 ---
 
-### Calculator agent demo — Codex + Relay
+### Calculator agent demo — DeepAgents + Relay
 
 [`examples/nemo-agent-config/calculator-agent/agent.yaml`](examples/nemo-agent-config/calculator-agent/agent.yaml)
-uses Codex as its harness and routes `nvidia-nemotron-3-nano-30b-a3b`
+uses DeepAgents as its harness and routes `nvidia-nemotron-3-nano-30b-a3b`
 through the Platform Inference Gateway. The agent answers arithmetic and
 numeric comparison requests and records ATIF and ATOF telemetry with NeMo
 Relay.
 
-#### Step 1 — Start the platform
+#### Step 1 — Configure and start the platform
 
-Run this in a **dedicated terminal** from the repository root. Use a separate
-terminal for the remaining steps.
+Set the NVIDIA API key and local Platform URL from the repository root:
 
 ```bash
-nemo services run
+export NVIDIA_API_KEY="<your NVIDIA API key>"
+export NMP_BASE_URL=http://localhost:8080
 ```
 
-#### Preflight — Verify Platform readiness
-
-In the second terminal, set the local Platform URL and confirm that an existing
-instance is running and ready before continuing:
+Start ClickHouse for Intake, then set up NeMo Platform without deploying the
+default demo agent:
 
 ```bash
-export NMP_BASE_URL=http://localhost:8080
+services/intake/scripts/spans/run_clickhouse.sh
+nemo setup --auto --start-services --install-skills --no-deploy-agent
+```
+
+Confirm that the Platform is ready before continuing:
 
+```bash
 curl -fsS --connect-timeout 2 --max-time 5 \
   "$NMP_BASE_URL/health/ready" >/dev/null || {
   echo "NeMo Platform is not ready at $NMP_BASE_URL"
   exit 1
 }
 ```
 
-#### Step 2 — Configure the model provider and harness
-
-Set the NVIDIA API key, then verify that Codex and NeMo Relay are ready:
-
-```bash
-export NVIDIA_API_KEY="<your NVIDIA API key>"
-
-codex login
-nemo-relay --version
-```
-
-Create the local NVIDIA Build provider and wait for its models to be
-registered:
-
-```bash
-nemo secrets create ngc-api-key \
-  --value "$NVIDIA_API_KEY"
-
-nemo inference providers create nvidia-build \
-  --host-url https://integrate.api.nvidia.com \
-  --api-key-secret-name ngc-api-key
-
-nemo wait inference provider nvidia-build
-```
-
-In production, the `system/nvidia-build` provider is normally created by the
-Platform seed job, so this local provider setup is not required.
-
-#### Step 3 — Create and deploy the agent
+#### Step 2 — Create and deploy the agent
 
 ```bash
 nemo agents create \
@@ -155,7 +130,7 @@ nemo agents deploy \
 `create` validates the config and registers the agent. `deploy` waits for the
 deployment to reach `running` by default.
 
-#### Step 4 — Invoke through the gateway
+#### Step 3 — Invoke through the gateway
 
 ```bash
 nemo agents invoke \
@@ -165,22 +140,17 @@ nemo agents invoke \
 
 The response content should be `12`.
 
-#### Step 5 — Verify Relay telemetry
+#### Step 4 — Verify Relay telemetry
 
-The config writes ATIF and ATOF files beneath the deployment's artifacts
-directory:
+The config writes ATOF events beneath the deployment's artifacts directory:
 
 ```bash
 find ~/.local/share/nemo/agents/system/default \
   -path "*calculator-agent-deployment*/artifacts/*" \
-  \( -name "*atif*" -o -name "*atof*" \) \
+  -name "*.atof.jsonl" \
   -exec ls -lh {} \;
 ```
 
-Its ATIF configuration also sends trajectories to the local Platform Intake
-API at `http://127.0.0.1:8080`. Ensure Intake is running if you want to use that
-HTTP sink.
-
 ### Packaging agents as container images
 
 `nemo agents package` automatically detects `nemo-agents-spec-v1` and selects

plugins/nemo-agents/examples/nemo-agent-config/calculator-agent/README.md

@@ -0,0 +1,123 @@
+# Calculator Agent
+
+This example provides two Platform-managed `nemo-agents-spec-v1` configurations
+for comparing a DeepAgents calculator agent with and without tools:
+
+| Config | Calculator server |
+| --- | --- |
+| `agent.yaml` | Disabled |
+| `agent-with-mcp.yaml` | Enabled through MCP |
+
+Both variants use the Platform Inference Gateway and record ATOF telemetry
+through NeMo Relay.
+
+## Prerequisites
+
+Run these commands from the repository root:
+
+```bash
+export NVIDIA_API_KEY="<your NVIDIA API key>"
+export NMP_BASE_URL=http://localhost:8080
+
+make bootstrap-python
+source .venv/bin/activate
+
+command -v calculator-server
+```
+
+Start ClickHouse for Intake:
+
+```bash
+services/intake/scripts/spans/run_clickhouse.sh
+```
+
+Set up NeMo Platform without deploying the default demo agent:
+
+```bash
+nemo setup --auto --start-services --install-skills --no-deploy-agent
+```
+
+Use `nemo setup` without `--auto` for interactive provider and model selection.
+Confirm the Platform is ready before continuing:
+
+```bash
+curl -fsS --connect-timeout 2 --max-time 5 \
+  "$NMP_BASE_URL/health/ready" >/dev/null
+```
+
+## Run without MCP
+
+Create and deploy the basic calculator agent:
+
+```bash
+nemo agents create \
+  --name calculator-agent \
+  --agent-config plugins/nemo-agents/examples/nemo-agent-config/calculator-agent/agent.yaml
+
+nemo agents deploy \
+  --agent calculator-agent \
+  --name calculator-agent-deployment \
+  --mode subprocess
+```
+
+Invoke it:
+
+```bash
+nemo agents invoke \
+  --agent-deployment calculator-agent-deployment \
+  --input "What is 12 multiplied by 8?"
+```
+
+The response should report `96`. This configuration has no calculator server,
+so its ATOF events should contain no calculator tool call.
+
+## Run with MCP
+
+Create and deploy the tool-enabled variant:
+
+```bash
+nemo agents create \
+  --name calculator-agent-with-mcp \
+  --agent-config plugins/nemo-agents/examples/nemo-agent-config/calculator-agent/agent-with-mcp.yaml
+
+nemo agents deploy \
+  --agent calculator-agent-with-mcp \
+  --name calculator-agent-with-mcp-deployment \
+  --mode subprocess
+```
+
+Invoke it:
+
+```bash
+nemo agents invoke \
+  --agent-deployment calculator-agent-with-mcp-deployment \
+  --input "Use the calculator multiply tool to calculate 12 multiplied by 8. Do not calculate it yourself."
+```
+
+The response should report `96` after calling the calculator's `multiply`
+tool.
+
+## Verify telemetry
+
+List the local ATOF artifacts for both deployments:
+
+```bash
+find ~/.local/share/nemo/agents/system/default \
+  -path "*calculator-agent*-deployment*/artifacts/*" \
+  -name "*.atof.jsonl" \
+  -exec ls -lh {} \;
+```
+
+Inspect calculator tool calls in the MCP deployment's ATOF events:
+
+```bash
+find ~/.local/share/nemo/agents/system/default \
+  -path "*calculator-agent-with-mcp-deployment*/artifacts/*" \
+  -name "*.atof.jsonl" \
+  -exec jq -c \
+    'select(.category == "tool" and .scope_category == "start")
+     | {name, arguments: .data}' {} +
+```
+
+The MCP deployment should include a `multiply` call. Running the same command
+against the basic deployment should print no calculator tool calls.

plugins/nemo-agents/examples/nemo-agent-config/calculator-agent/agent-with-mcp.yaml

@@ -0,0 +1,50 @@
+config_format: nemo-agents-spec-v1
+name: calculator-agent-with-mcp
+description: Calculator agent executed with DeepAgents and a calculator MCP server
+
+instructions:
+  system:
+    content: |
+      You are a concise calculator agent. You must use the appropriate
+      calculator MCP tool for every arithmetic or numeric comparison request
+      and base your answer on its result.
+
+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
+
+skills:
+  paths: []
+
+mcp:
+  servers:
+    calculator:
+      transport: stdio
+      url: calculator-server
+
+tools:
+  blocked: []
+
+environment:
+  workspace: ./workspace
+  artifacts: ./artifacts
+
+telemetry:
+  enabled: true
+  provider: relay
+  output_dir: ./artifacts/relay
+  project: calculator-agent-with-mcp
+  atof:
+    enabled: true
+    filename: events.atof.jsonl
+    mode: append

plugins/nemo-agents/examples/nemo-agent-config/calculator-agent/agent.yaml

@@ -1,21 +1,20 @@
 config_format: nemo-agents-spec-v1
 name: calculator-agent
-description: Calculator agent executed with Codex
+description: Calculator agent executed with DeepAgents
 
 instructions:
   system:
     content: |
       You are a concise calculator agent. Solve arithmetic and numeric
       comparison requests yourself and return only the answer.
 
-default_harness: codex
+default_harness: deepagents
 
 harnesses:
-  codex:
-    kind: codex
+  deepagents:
+    kind: deepagents
     settings:
-      sandbox: read-only
-      reasoning_effort: high
+      deepagents: {}
 
 models:
   default: