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

# Working with agents

> Give a coding agent a clear task and a repeatable Lua development workflow.

A coding agent can develop Atonom tools using the same CLI as a person. Give it the intended behavior, an environment, the target tool, and explicit success cases. Keep the Atonom agent (the tool owner) distinct from the coding agent editing the file.

## Give the agent a concrete task

Copy this brief into your coding agent and replace the bracketed values:

```text theme={null}
Develop the Lua tool [tool ID] in [workspace] for [environment].
Goal: [describe the behavior and the JSON result].
Inputs: [keys, types, required fields, and defaults].
Examples: [normal case, missing inputs, edge case, host failure].

Read `atonom guide` and the existing script and input schema.
Use --json for supported command output. Never print credentials.
Pull only the target tool and inspect the returned path and sync action.
Edit the Lua file and prepare explicit test inputs and expected results.
If sandbox access is configured, test with eval --transform and fixtures.
For tool calls, test canned success and failure responses in the sandbox.
If sandbox access is unavailable, report which tests remain unverified.
Review `atonom diff --json` and report any remote changes.
Do not use --force to resolve a conflict automatically.

For this task, stop after local tests and a reviewed diff.
Report the file, tool ID, test inputs, outputs, and remaining platform setup.
```

If you want the agent to save and execute changes, replace the last paragraph with:

```text theme={null}
After diff review and any available sandbox tests, push normally and execute
the stored script with run --no-save using the prepared inputs. Report whether
it was saved and whether execution passed. Do not enable the tool or change
its schema.
```

These are suggested task boundaries; adapt them to your team's workflow.

## Bootstrap context

```sh theme={null}
atonom guide
atonom config show --json
atonom status --json
atonom list --json
atonom get 42 --json
atonom pull 42 --json
```

`guide` prints plain text even with `--json`. It is the compact authoring contract shipped with the executable. `get --json` returns the script and input schema. Read `pull`'s per-file `action`: exit code zero can include `skipped-local-edits`.

An agent should use the returned path, not invent a filename from the tool name. Pass explicit `--comm-agent-id` when creating tools noninteractively.

## Iterate with fixtures

With [sandbox access](/atonom-script/cli/install#connect-the-sandbox-optional), test local changes before saving:

```sh theme={null}
atonom eval .atonom/scripts/order-total.lua \
  --transform '{"qty":2,"unit_price":12.5}' --json
atonom diff 42 --json
```

Use `eval` with the full workspace-relative file path. Unlike `push`, `diff`, and `run`, it does not resolve a bare filename relative to the scripts directory.

Compare the output to the expected value, rather than treating exit code `0` as proof of correctness. A script returning `{ ok = false }` is still a successful Lua execution unless it raises an error.

## Interpret machine output

* **Exit 0:** command or script succeeded. Check values and per-file sync actions.
* **Exit 1:** configuration, authentication, transport, or command failure. Read stderr; it may be plain text even in JSON mode.
* **Exit 2:** `run` returned an error status, or `eval` produced `FAIL`. Fix the script or input. Argument-parser errors also use code 2, so check whether JSON was emitted.
* **Exit 3:** an eval trap was unanswered, or the trap limit was reached. Inspect `unanswered_trap` and supply a suitable mock or correct the loop.

For `run`, inspect top-level `status`, `value`, `error`, and `saved`. For `eval`, inspect `outcome.status`, `outcome.value` or `outcome.error`, `traps`, and `exit_code`.

`diff` returns zero even when content differs. Parse `identical` and `remote_changed_since_pull`. A `null` remote-change field means there is no synced entry to compare against.

## Suggested workspace instructions

Place these conventions in your script repository's agent instructions if useful:

```text theme={null}
Lua tools use transform(context) and return JSON-compatible values.
Read atonom guide before changing scripts.
Use tool IDs from atonom list, not internal script IDs.
Preserve the input contract unless the task includes schema changes.
Test missing fields, empty results, and host failures.
Use atonom.json.array() for empty arrays and atonom.json.null for nulls.
Never assume require, os, io, or direct network access are available.
Keep credentials out of source, fixtures, logs, and prompts.
Check diff before a remote write; resolve conflicts without blind force.
Remember: run saves by default; run --no-save tests the stored body.
```

Keep fixtures and scripts in version control according to your repository policy. Keep environment-specific tool mappings separate when moving between environments; see [Sync & release](/atonom-script/cli/sync).


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