> ## 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 reads documentation, writes Python skills and runs approved code
through your robot's GRID development session. You review the proposed action before it runs. A saved script, a finished
process 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.

## 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. V0 does not automatically inspect the robot or send a hardware
stop. Cancellation ends the task process. You remain responsible for stopping
the hardware, and GRID blocks another agent run until you confirm it stopped.

## Call the agent without the terminal UI

Create a request file. `query` and all four `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,
    "maxCostUsd": 3,
    "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. V0 headless runs can
execute approved Python and return logs, but physical 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, 10 Python
starts and a \$3 model budget. Waiting for a person is excluded from working time.
A trial counts a Python start, not each robot movement inside the program.
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.3/cli/reference)
for the other GRID commands.


## Related topics

- [Training Workflow](/v2.3/simulation/isaac/reinforcement-learning/training-workflow.md)
- [Workflow Config](/v2.3/simulation/isaac/session_configuration/workflow.md)
- [Agent Config](/v2.3/simulation/isaac/session_configuration/agent.md)
- [GRID Cortex Client](/v2.3/models/cortex.md)
- [CLI reference](/v2.3/cli/reference.md)


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