Skip to content

Guide for agents

Automate without scraping the terminal

Agents should use documented JSON contracts, not parse colored tables or human-oriented status boxes. The CLI keeps the designed output for people and provides --json for scripts. The SDK returns typed objects and raw contract data where needed.

Use JSON and exit codes

Ask the CLI for JSON on every command used by an agent. Check the process exit code before reading fields. On success, inspect state, request ID, provenance, and usage. On failure, parse the error field and retain the request ID if supplied.

set -o pipefail
palo infra status --json > status.json
status_code=$?
if [ "$status_code" -ne 0 ]; then
  jq -r '.error // "unknown failure"' status.json
  exit "$status_code"
fi
jq '{state: .monitoring.state, provider, model_version}' status.json

For long event histories, page with --limit and --offset. Never assume the default 100 rows is the complete history.

Separate read, write, and destructive actions

ClassExamplesAgent rule
Readpalo auth, palo infra status, palo mind keys listSafe to automate with scoped credentials and bounded timeouts.
Writepalo memory write, palo mind keys createSupply stable identity and idempotency where supported. Capture the response.
Destructivepalo memory delete, key revoke, storage deleteRequire explicit resource identity and a separate approval decision.
Operator simulationpalo infra smoke-test with simulation controlsUse only with an authorized operator capability. It cannot override consent or production policy.

Make monitoring actionable

A good agent does not report a green badge alone. It compares the current status to the requested window, checks whether data exists, identifies the provider and deployment version, enumerates anomalies, and states whether billing data was measured.

palo infra metrics --lookback-minutes 15 --json
palo infra anomalies --json
palo infra usage --lookback-minutes 15 --json

Treat no_data as an information state. It is not proof that the system had zero historical usage outside the requested window.

Use authoritative context sources

llms.txt

Short routing context, status boundary, and page links.

llms-full.txt

Plain-text page content for retrieval and offline agent context.

docs-index.json

Stable metadata, URLs, audiences, and page status.
Credential rule.

Documentation is public. Credentials are not. Never ask a user to paste a live API key into a documentation prompt, never echo one in output, and never store one in agent memory.