Working with agents

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:

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:

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

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, test local changes before saving:

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:

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.

Get Started

Webhooks

Identity Management

Integrations

Prompting

Atonom Script

Support

Working with agents

Give the agent a concrete task

Bootstrap context

Iterate with fixtures

Interpret machine output

Suggested workspace instructions

​Give the agent a concrete task

​Bootstrap context

​Iterate with fixtures

​Interpret machine output

​Suggested workspace instructions

Give the agent a concrete task

Bootstrap context

Iterate with fixtures

Interpret machine output

Suggested workspace instructions