Agent Playbook

How agents should discover, choose, invoke, and audit Xenodia marketplace capabilities.

Most capability failures come from agents skipping the descriptor. Treat the descriptor as the live contract: it contains the current operation list, prices, availability, input hints, and agent-specific instructions.

Selection Flow

Search the catalog with GET /v1/capabilities?q=....
Filter out descriptors where availability.invoke_allowed is false unless you only need a read-only helper operation that remains allowed.
Prefer capabilities whose agent_doc_what exactly matches the task.
Read agent_doc_how and the operations array before paying for a call.
Use flow_step order when operations expose it.
Prefer read-only helper operations before expensive retrieval, creation, or action operations.

Invocation Rules

Agents should always keep these fields in memory before calling:

Field	Why it matters
`slug`	Route and audit identifier.
`default_version`	Runtime contract snapshot.
`default_operation_slug`	The operation used by `/invoke`.
`operation.pricing.unit_price_micro_usdc`	Maximum expected fixed price for that operation.
`operation.input_fields`	Required and optional input shape.
`operation.trust_signals`	Evidence, freshness, health, and idempotency hints.
`operation.availability.invoke_allowed`	Whether the specific operation can currently run.

Generate a new Idempotency-Key for each new paid intent. Keep the same key only when retrying the same payload.

Budget Behavior

Agents should not guess cost from prose. Read pricing from the descriptor immediately before a price-sensitive call. If a call returns 402, use the returned payment object and retry with the same idempotency key after funding succeeds.

For owner-agent setups, the response billing object identifies:

actor: the account that made the call.
payer: the account whose credit was charged.
owner: the owner account when separate from the actor.

Evidence Behavior

When a capability returns external evidence, an agent should preserve enough context to explain its answer:

request_id
capability
operation
capability_version
key filter values
confidence or warning fields when returned
billing outcome

Do not store secrets, bearer tokens, or raw private credentials in task memory or user-facing logs.

Availability Behavior

Availability can block listing, detail, or invoke separately. Typical states include:

State	Agent action
`active`	Invoke is allowed.
`suppressed`	New traffic is temporarily blocked; retry only if `retryable` is true. Helper operations may remain allowed.
`not_configured`	Runtime adapter is not ready; do not keep retrying.
`contract_unpublished`	Version snapshot has not been published; wait for operator review.
`contract_drift`	Runtime contract changed after the frozen version; do not call until fixed.
`disabled`	Capability is intentionally unavailable.

Agent Checklist

Before calling a capability:

I have the descriptor from the current session.
I know the operation and mode.
I checked availability.
I checked price.
I generated or reused the correct idempotency key.
I can explain why this capability is better than a model-only answer.
I know what evidence or result field I need from the response.