automating with agents

Claude, Codex, and other shell-capable agents can operate the implemented Castia surface by invoking castia. They do not need the UI or a model-specific Castia SDK. They still cannot exceed the service token's Organization, role, scopes, or the server's advertised capabilities.

1. Inject scoped credentials

   Inject CASTIA_URL, CASTIA_ORG, and a least-privilege CASTIA_TOKEN from a secret manager.

2. Discover before assuming

   Run castia capabilities list --json; never assume a capability exists from prose or CLI syntax.

3. Read before mutating

   Read the exact resource and its revision before mutation.

4. One deterministic idempotency key

   Generate one deterministic idempotency key and preserve it for any exact replay.

5. Submit JSON through stdin

   Submit JSON through stdin or a protected file, not a command argument.

6. Parse the envelope

   Parse the versioned JSON envelope and durable operation receipt.

7. Stop for the human

   Stop on needs_human, held, outcome_uncertain, stale revision, or fingerprint mismatch. Route approval to a human.

8. Follow to a terminal state

   Follow the operation to a terminal state; do not infer success from request acceptance.

export CASTIA_URL=https://app.castia.ai
export CASTIA_ORG=ORGANIZATION_ID
export CASTIA_TOKEN="$(your-secret-manager read castia/codex-token)"

castia capabilities list --json
castia show company:COMPANY_ID --json

castia do company.followup.schedule@v1 company:COMPANY_ID \
  --input - \
  --expected-revision 2026-08-12T08:00:00.000Z \
  --idempotency-key agent-followup-COMPANY_ID-20260812 \
  --json <<'JSON'
{"followUpDate":"2026-08-20T09:00:00.000Z","followUpReason":"Budget cycle","temperature":"warm"}
JSON

castia wait OPERATION_ID --follow --jsonl

• --json writes one { "schemaVersion": 1, "ok": ... } envelope to stdout.

• --jsonl writes one envelope per NDJSON line for follow/watch flows.

• Diagnostics and device codes go to stderr.

• Exit 0 is success; 4 needs human approval; 5 is held, stale, conflicting, or uncertain; 6 is retryable transport/dependency failure. See the complete table in Troubleshooting.

• Tokens and secret-shaped fields are redacted from output.

An accepted action normally returns an operation receipt, not proof that the effect completed. Use --wait or castia wait when the workflow needs the terminal result.

The CLI never automatically retries an execute request. Automation must always supply --idempotency-key. If transport fails after submission, first inspect the resulting work where possible; if an exact re-submit is necessary, use the same action, target, input, expected revision, and idempotency key. A changed payload with the same key is rejected as an idempotency conflict.

There is no generic operation requeue command. castia operation retry ... returns capability_unavailable and performs no network fallback.

castia work --needs-human --json
castia operation show OPERATION_ID --json
castia approve OPERATION_ID --fingerprint FINGERPRINT --json
# or
castia reject OPERATION_ID --reason "Not approved" --json

Campaign launch remains a preparation/approval exercise: even after exact human approval it starts zero delivery.

capability:read,company:read,icp:read,playbook:read,operation:read,campaign:read

Add a write scope only for a concrete workflow: company:write, company:research, company:archive, campaign:write, campaign:launch, operation:control, or human-only operation:approve. Avoid * for service identities.

An agent can fully control the capabilities returned by its server within its granted authority. It cannot control UI-only features that remain planned, read another Organization, bypass Delivery Policy, create human approval, access raw provider payloads, or start real Campaign delivery. The command reference is the checked availability boundary.

Castia can generate a no-store OpenAPI 3.1 document at:

GET /api/operator/v1/adapters/microsoft-copilot/openapi

It exposes adapter-specific routes that delegate to the shared Operator handlers:

POST /api/operator/v1/adapters/microsoft-copilot/inspect
POST /api/operator/v1/adapters/microsoft-copilot/execute
GET /api/operator/v1/adapters/microsoft-copilot/follow

The gateway enforces a server-derived Microsoft allowlist before the shared Operator executes. Currently it contains capability discovery, Company list/show, published ICP and Segment Playbook Version list/show, work list, and operation show/follow/cancel. Human-only approve/reject, planned capabilities, Campaign launch, Company archive, and retries are excluded even when the underlying Castia credential has broader scopes. Approve/reject can be added only after Entra/OBO maps the signed Microsoft user to a revalidated Castia human actor.

The Copilot adapter does not use or require the CLI executable. Both adapters reuse the same schemas, tenant checks, durable receipts, and approval gates.

• Microsoft app/plugin registration and tenant-admin consent;

• an authenticated public gateway/host and final HTTPS domains;

• Entra SSO or on-behalf-of token exchange mapped to a Castia Organization and actor;

• a decision on delegated-user versus application authority;

• secret rotation, Conditional Access, audit export, retention, support, and incident procedures;

• Microsoft validation/submission or private organizational distribution.

The current Castia request resolver authenticates Castia human or service credentials. The checked-in OpenAPI metadata describes a scoped Castia service-token bearer boundary plus the enforced adapter allowlist. It does not implement Microsoft tenant registration, Entra SSO, or an on-behalf-of exchange service. Do not expose a long-lived Castia service token to an end user's browser, Copilot prompt, or plugin response.

the cli guide →the command reference →troubleshooting →docs home →