> ## Documentation Index
> Fetch the complete documentation index at: https://docs.generalrobotics.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Work with the GRID agent

> Write and review robot tasks in the terminal, or call the agent from your own application.

The GRID agent calls your robot's available methods, reads documentation, and
writes and runs Python skills through your GRID development session. You review
actions before they run. A saved script, a finished call and a verified task are
three different results.

## Start a conversation

Set `ANTHROPIC_API_KEY` in the shell that starts GRID and sign in to GRID as usual.
Inside the GRID terminal, run:

```text theme={null}
agent --robot <robot-name> help me write and test a task
```

Use `agent --no-robot` to write code without connecting to hardware. Running
`agent` without either option reuses your current live robot connection. If
there is no live connection, it offers an online-robot picker. Use `--no-robot`
when you want to author code without attaching to that connection.

Recent tool calls stay visible while the agent works. Press Tab for the full
trace, and use arrow keys or Page Up / Page Down to scroll. Saved filenames are
terminal hyperlinks. Escape cancels and closes the conversation after cleanup.
Conversation history is retained between turns, but cannot be resumed after a
CLI restart.

## Navigate with the agent

Ask for a destination, for example: `Take me to the nearest chair`.
When Nav is available, the agent checks its active map. If no map is active and
you have not specified one, it asks which to use before starting navigation and
searching for matching objects. Setup and planning do not require approval. It plans a route and opens the
viewer before asking you to approve movement. Review the destination and route,
then press `y` followed by Enter to run it. If the map or starting position
changes during approval, the agent must plan again.

The agent uses the robot's mission result to report completion or failure.
Press Ctrl+X to request a stop during an action. Status and stop controls remain
available while the action runs. A stop request alone does not confirm that the
robot has stopped; follow the terminal's stop question before another action.

Press Ctrl+L to inspect agent events, then Tab to switch to the robot's mission
log. Inspected robot logs are saved under the session's `robot-logs` directory;
the terminal shows the file location. Logs remain available after a tool call.

## Review, run and check

1. The agent reads the docs, then saves a draft in your skill library,
   `~/.grid/skills/`, the same wherever you start GRID. **Draft saved**
   means the code has not run. The agent can also revise an existing skill after
   reading it; if someone changed the file meanwhile, GRID refuses the save.
2. Before an action, review its target, source, arguments, limits and success
   condition. Press `y` then Enter to approve, or Enter / `n` to deny. Changes to
   the approved program or inputs require another approval. Read-only tools do
   not need approval.
3. GRID runs approved Python through the same runner as `skill run`, captures
   its output and reports the process result. After a completed run, an unchanged
   program may retry within its approved trial limit. A run that fails, times out
   or is cancelled needs a new approval.
4. After the process ends, GRID asks you to check the robot, stop it if needed,
   and confirm it has stopped. It then asks whether the approved task succeeded,
   failed, or remains unclear. An exit code or the model's answer does not prove
   task success.

The person testing remains responsible for the prepared robot and its motion
limits. Python runs with your host's permissions; this is process supervision,
not an OS sandbox. Connecting establishes a GRID session; it does not check
physical readiness. For direct robot actions, cancellation requests the robot's
stop control. For generated Python programs, cancellation ends the task process;
that alone does not stop the hardware. You remain responsible for checking the
robot, and GRID blocks another action while stopping is unconfirmed.

## Call the agent without the terminal UI

Create a request file. `query` and all three `limits` fields are required; omit
`robot` to work without a selected robot.

```json theme={null}
{
  "robot": "lab-robot",
  "query": "Inspect the setup and write a task. Try at most twice.",
  "limits": {
    "maxActions": 60,
    "maxSeconds": 900,
    "maxTrials": 2
  },
  "approvalDirectory": "/private/grid-approvals",
  "approvalTimeoutSeconds": 600,
  "answers": []
}
```

```sh theme={null}
grid --json --exec "agent --request /absolute/path/request.json"
```

The final JSON result goes to stdout. Live approval notices go to stderr as JSON
lines, so your application can watch for decisions while keeping stdout parsable
as one document. Omitting `approvalDirectory` denies actions, but still permits
read-only work and authoring.

For each approval, the notice gives `proposalPath`, `decisionPath`,
`approvalHash`, `requestId` and `decideBy`. Your application or an operator must:

1. Read the complete proposal and decide whether to allow it.
2. Write this decision to a temporary file beside `decisionPath`.
3. Atomically rename that file to the exact `decisionPath` from the notice.

```json theme={null}
{"approvalHash": "<hash from this proposal>", "approved": true}
```

Use `false` to deny. Every request has new paths, including retries. An expired,
used or mismatched decision cannot approve a later request. The directory must
belong to the current user and must not be writable by other users. The default
wait is 600 seconds; `approvalTimeoutSeconds` accepts 60–3600 seconds. File
approvals are unavailable on Windows; program execution requires POSIX process
groups.

`answers` supplies replies to the agent's ordinary questions. It cannot approve
execution or confirm a task outcome or a stopped robot. Headless runs can
execute approved robot actions or Python and return logs, but physical task
outcomes stay `unknown`.
Without live operator confirmation, another run stays blocked until someone
checks the robot and reconciles stopping in an interactive session.

The final result's `data.host` reports denials, action failures, cancellation,
stop confirmation and task verification. Check the overall `ok` and `code` as
well as the model's text. `needs_attention` means a host check prevented success;
`invalid_request` means the input was rejected, and `setup_failed` includes a
missing model key. A model failure may supply its own error code.

## Limits and recovery

Interactive defaults are 60 tool calls, 900 seconds of working time and 10
execution trials. Model usage is recorded in session logs without a spending
limit. A trial counts a program or robot action start, not each robot movement
within it. Waiting for a person is excluded from working time. Headless requests
supply these limits explicitly.

Session evidence is saved in `~/.grid/agent/sessions/<id>/events.jsonl`. Keep any
unresolved stop record: deleting it bypasses the block without establishing that
the robot stopped. Check the robot and follow GRID's recovery message in an
interactive session. Recovery also checks that the old process has ended; it
does not pre-approve another task.

Documentation comes from the hosted GRID docs MCP. `GRID_DOCS_MCP_URL` overrides
that endpoint for a custom deployment. See the [CLI reference](/v2.4/cli/reference)
for the other GRID commands.


## Related topics

- [Training Workflow](/v2.4/simulation/isaac/reinforcement-learning/training-workflow.md)
- [Workflow Config](/v2.4/simulation/isaac/session_configuration/workflow.md)
- [Agent Config](/v2.4/simulation/isaac/session_configuration/agent.md)
- [Get started](/v2.4/get-started/installation.md)
- [GRID Cortex Client](/v2.4/models/cortex.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.