Provider Guide

What a provider must prepare before a capability can be listed and safely invoked through Xenodia.

A capability must be more than a title and URL. It needs a machine-readable contract that an agent can inspect without private context, plus enough operational metadata for billing, logging, review, and support.

Publication Model

Capability publication is review-gated:

Define the capability contract.
Define each operation and input shape.
Provide agent-readable usage instructions.
Set pricing and funding modes.
Pass runtime readiness and health checks.
Publish a frozen version snapshot.
Make the capability consumer-visible.

The public catalog should only list capabilities that are runtime-ready, versioned, and safe for agents to call.

Required Descriptor Fields

Field	Requirement
`slug`	Stable lowercase identifier. Do not rename after publication.
`name`	Human-readable capability name.
`type`	Capability type, usually `api` for the current runtime.
`category`	High-level grouping such as `intelligence`, `data`, or `automation`.
`short_description`	One-sentence value proposition.
`provider_name`	Public provider display name.
`default_version`	Published runtime contract version such as `v1`.
`funding_modes`	Allowed billing relationships.
`invoke_path`	Default operation route.
`operations`	Complete operation contracts.
`agent_doc_what`	When an agent should use the capability.
`agent_doc_how`	Safe operation sequence and constraints.
`trust_signals`	Evidence, freshness, health, idempotency, or audit signals.

Operation Contract

Each operation should include:

Field	Requirement
`slug`	Stable operation identifier.
`name`	Human-readable operation name.
`method`	Public method, usually `GET` or `POST`.
`path`	Public Xenodia route for the operation.
`summary`	One-sentence operation purpose.
`read_only`	Whether the operation only reads external state.
`flow_step`	Recommended order when the capability has a staged flow.
`pricing`	Billing kind, mode, currency, and unit price in micro USDC.
`input_fields`	Required and optional inputs.
`request_example`	Minimal valid example.
`output_highlights`	Response fields an agent should inspect.
`agent_doc_how`	Operation-specific usage instructions.
`idempotency_key_required`	Required for paid, async, or policy-sensitive operations.
`supports_sync` / `supports_async`	Supported execution modes.

Agent Docs Standard

Write agent_doc_what as a decision rule:

Use this capability when an agent needs ...

Write agent_doc_how as an execution rule:

Call Status first, then List Monitors, then Query only when coverage and freshness are acceptable.

Good agent docs are short, imperative, and operational. They should not rely on marketing language or provider-only context.

Versioning

Published capability versions are contract snapshots. Breaking changes require a new version. A breaking change includes:

Removing or renaming an operation.
Changing required input fields.
Changing output meaning in a way that breaks agent interpretation.
Changing sync versus async support.
Changing the default operation.

Non-breaking catalog edits, such as better descriptions, tags, and agent docs, may evolve without changing the runtime snapshot.

Pricing Rules

Prices are expressed in unit_price_micro_usdc, where 1000000 equals 1 USDC. For multi-operation capabilities, set price per operation. Helper reads can be free, while the main operation can be paid.

Agents must be able to read price before calling. Do not hide required paid steps in prose.

Listing Checklist

Before requesting publication, confirm:

The capability has a stable slug and version.
Every operation has a route, input fields, example, and price.
Paid operations require idempotency.
Helper operations are marked read-only when appropriate.
Agent docs explain when and how to call.
Availability and health failures do not lock funds.
The response includes enough data for audit and user explanation.
Logs can identify capability slug, operation, version, actor, payer, and request ID.