Covers the caller (agent) side. The repository’s
docs/internal/connectors/CONNECTING_AN_AGENT.md points here. For what
happens after approval (gateway, connector, the real business system), see
Connect any external system, the
Connector Development Guide.The mental model
What you need, and why
Step by step
1. Read the policy file directly.cat policies/customer-refund/1.2.0/policy.json; don’t guess
field names from a description. Ask the server which version is in effect:
GET /policies/in-effect?capability=erp:invoice-pay.
2. Pick the exact capability string. Case- and character-exact. This single detail is the most
common integration failure in practice.
3. Mint a scoped API key:
SERVICE, never "AGENT", that value doesn’t exist in AuthorityType. Never grant "*" to a
single-purpose agent; /callers/me’s unrestrictedCapabilities is literally
allowedCapabilities.includes("*").
4. Verify the key before writing agent code:
signalsSchema. Not a
placeholder to fix later, from day one.
6. Build the request:
policy.name/policy.version is never inferred from intent.action: name it explicitly, or a
caller could pair a real capability with an unrelated policy. Under customer-refund 1.2.0 every
refund needs a signed manager approval; without one the request is refused with 403 POLICY_DENIED, whatever your agent declares about eligibility and fraud.
7. Send it, handle the response, see the complete reference table below.
8. Confirm a connector is registered for your capability on this deployment. A 200 means
the action was released and executed and its Trust Record signed; with no connector the answer is
503 CONNECTOR_NOT_REGISTERED and nothing ran. To practise end to end, run a local server with the
Quickstart. To connect your own system
without code, see Connect any external system.
9. Verify independently: GET /refusal/:businessTransactionId + POST /refusal/verify for a rejection,
GET /trust-records/:businessTransactionId (only once a connector is wired) for an execution, or fully offline with
verifyExecutionTrustRecordOffline.
Complete response reference
Every row is what the server returns today (2026-10-02); the Error catalog has every code.Common mistakes
- Capability string mismatch between
intent.actionand your key’sallowedCapabilities. authorityType: "AGENT", invalid; use"SERVICE".- A signal inferred from the customer’s words instead of an independent business system.
- Treating
POLICY_DENIEDas a bug instead of a correct decision. - Treating a timeout as a failure and sending the action again under a new id.
- Granting
"*"“to get it working” and never narrowing it. - Hand-editing
PARMANA_API_KEYSby pasting a single entry instead of the complete array. - Assuming a bare
500means your request was wrong: ask for the server log first.
Reference implementation
Add a connector
What happens after APPROVED: Execution Gateway, connector dispatch,
execution evidence.
Live API and Demos
Call the real, deployed Parmana API directly and see what’s and isn’t wired
on it today.