Schema Reference

Complete field reference for agent.json. Three fields are required: awp_version, domain, and intent. Everything else is optional but recommended for full agent interoperability.

Field	Type	Status	Description
awp_version	string	required	Spec version conformance using MAJOR.MINOR format (e.g. "0.1").
domain	string	required	Canonical domain reference. Must match the serving domain.
intent	string	required	Plain language surface description of what the service does and how agents should interact with it.
capabilities	object	optional	Optional feature indicators for agent evaluation.
└streaming	boolean	optional	Endpoint streaming response support.
└batch_actions	boolean	optional	Concurrent action submission capability.
└webhooks	boolean	optional	Asynchronous result delivery via webhook.
└pagination	"cursor" \| "offset" \| "page" \| "none"	optional	Pagination style.
└idempotency	boolean	optional	Idempotency key support.
auth	object	optional	Specifies authentication obligations.
└required_for	array[string]	optional	Action IDs demanding authentication.
└optional_for	array[string]	optional	Action IDs where authentication is discretionary.
└type	"oauth2" \| "api_key" \| "bearer" \| "none"	optional	Authentication category.
└token_expiry	string	optional	Lifespan notation (e.g. "24h", "7d").
└refresh_endpoint	string	optional	Token renewal endpoint.
entities	object	optional	Named, schema-defined models referenced by actions. Entity references in action parameters use object[entity_name] or array[entity_name] notation.
└{entity_name}.fields	object	optional	Field name → type mapping. Types: string, integer, float, boolean, ISO8601, url, enum[...], array[type], object[entity].
actions	array	required	Core element — declared executable operations. Each action represents an API endpoint agents can invoke.
└id	string	required	Unique action identifier.
└description	string	required	Plain language for agent reasoning.
└auth_required	boolean	required	Authentication necessity.
└inputs	object	required	Typed parameters — each with type, required, default, options, description.
└outputs	object	required	Typed results (e.g. "flights": "array[flight]").
└endpoint	string	required	API path.
└method	"GET" \| "POST" \| "PUT" \| "DELETE" \| "PATCH"	required	HTTP verb.
└rate_limit	string	optional	Throttle specification (e.g. "30/minute").
└idempotency	object	optional	Idempotency contract with supported, key_field, window.
└execution_model	"sync" \| "async"	optional	Execution model. Default: sync.
└poll_endpoint	string	optional	Job status check URL (for async actions).
└sensitivity	"standard" \| "destructive" \| "irreversible"	optional	Operation sensitivity level.
└requires_human_confirmation	boolean	optional	Agent SHOULD prompt user before executing.
└reversible	boolean	optional	Undo capability.
errors	object	optional	Maps error identifiers to remediation pathways. Recovery guidance must be executable by software.
dependencies	object	optional	Prerequisite relationships. Maps action ID → array of prerequisite action IDs. Agents MUST execute prerequisites before attempting dependent actions.
agent_hints	object	optional	Semantic guidance enhancing planning decisions. Free-form key-value pairs. Agents should incorporate hints but must not treat them as binding.
agent_status	object	optional	Optional operational state signal.
└operational	boolean	optional	Service availability.
└degraded_actions	array[string]	optional	Impaired action identifiers.
└status_endpoint	string	optional	Real-time status location.

File location

The agent.json file must be served at the root of your domain with Content-Type: application/json:

https://yourdomain.com/agent.json

Validation

Use the validator to check your agent.json against the schema, or download the JSON Schema for local validation.