ACP Capability Negotiation
Before writing code
Fetch live docs:
- Web-search
site:github.com agentic-commerce-protocol rfcs capability_negotiation for the capability negotiation RFC
- Fetch
https://developers.openai.com/commerce/specs/checkout/ for how capabilities appear in checkout requests/responses
- Web-search
site:github.com agentic-commerce-protocol spec json-schema capabilities for the capabilities JSON schema
Conceptual Architecture
What Capability Negotiation Does
ACP agents and merchants may support different features. Capability negotiation allows them to dynamically discover what they both support, so the session uses only mutually available features.
How It Works
- Agent sends capabilities — In the
create request, the agent includes a capabilities object listing what it supports
- Merchant responds with capabilities — The merchant intersects with its own capabilities and returns what's active for this session
- Intersection governs the session — Only mutually supported features are used
Capabilities Object Structure
The capabilities object contains:
capabilities — Major features (checkout, orders, etc.)
extensions[] — Optional add-ons (discount, intent traces, affiliate attribution)
payment_handlers[] — Supported payment methods
interventions — Structured object with sub-fields: supported, required, enforcement, display_context, redirect_context, max_redirects, max_interaction_depth
Extension Pruning
Extensions declare a parent capability via extends. If the parent capability is not in the negotiated intersection, the extension is automatically pruned — no extra logic needed.
Interventions
Interventions are actions that require human involvement. They are represented as a structured object (not a flat array) with sub-fields including supported, required, enforcement, display_context, redirect_context, max_redirects, and max_interaction_depth.
Intervention types include:
- 3D Secure — Card authentication challenge
- Biometric — Fingerprint/face verification
- Address Verification — Address confirmation flow
- Other authentication or verification flows
The agent advertises which interventions it can handle. If the merchant requires an intervention the agent can't handle, the checkout may not proceed.
Versioning in Negotiation
- Each capability has its own version
- Extensions are versioned independently (
discount@2026-01-27)
- Payment handlers have their own version
- Version mismatches are resolved by intersection (both must support a compatible version)
Use Cases
- Merchants that support different feature sets for different plans
- Agents that gradually adopt new protocol features
- Graceful degradation when features aren't mutually supported
- Multi-merchant agents that adapt per-merchant
Best Practices
- Always include capabilities in the create request
- Advertise all capabilities you support — don't under-report
- Handle the case where the merchant supports fewer features than expected
- Log negotiated capabilities for debugging
- Test with minimal capability sets to ensure graceful degradation
- Update advertised capabilities as you adopt new spec features
Fetch the capability negotiation RFC for the exact capabilities object schema, extension pruning rules, and negotiation semantics before implementing.
1---2name: acp-capability-negotiation3description: Implement ACP capability negotiation — dynamic discovery of mutually supported capabilities, extensions, payment handlers, and interventions. Use when building multi-feature merchant servers or agents that adapt to merchant capabilities.4allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch5metadata:6 source: https://skillmd.com/skills/orcaqubits/acp-capability-negotiation7---89# ACP Capability Negotiation1011## Before writing code1213**Fetch live docs**:141. Web-search `site:github.com agentic-commerce-protocol rfcs capability_negotiation` for the capability negotiation RFC152. Fetch `https://developers.openai.com/commerce/specs/checkout/` for how capabilities appear in checkout requests/responses163. Web-search `site:github.com agentic-commerce-protocol spec json-schema capabilities` for the capabilities JSON schema1718## Conceptual Architecture1920### What Capability Negotiation Does2122ACP agents and merchants may support different features. Capability negotiation allows them to **dynamically discover** what they both support, so the session uses only mutually available features.2324### How It Works25261. **Agent sends capabilities** — In the `create` request, the agent includes a `capabilities` object listing what it supports272. **Merchant responds with capabilities** — The merchant intersects with its own capabilities and returns what's active for this session283. **Intersection governs the session** — Only mutually supported features are used2930### Capabilities Object Structure3132The capabilities object contains:33- **`capabilities`** — Major features (checkout, orders, etc.)34- **`extensions[]`** — Optional add-ons (discount, intent traces, affiliate attribution)35- **`payment_handlers[]`** — Supported payment methods36- **`interventions`** — Structured object with sub-fields: `supported`, `required`, `enforcement`, `display_context`, `redirect_context`, `max_redirects`, `max_interaction_depth`3738### Extension Pruning3940Extensions declare a parent capability via `extends`. If the parent capability is not in the negotiated intersection, the extension is automatically pruned — no extra logic needed.4142### Interventions4344Interventions are actions that require human involvement. They are represented as a structured object (not a flat array) with sub-fields including `supported`, `required`, `enforcement`, `display_context`, `redirect_context`, `max_redirects`, and `max_interaction_depth`.4546Intervention types include:47- **3D Secure** — Card authentication challenge48- **Biometric** — Fingerprint/face verification49- **Address Verification** — Address confirmation flow50- Other authentication or verification flows5152The agent advertises which interventions it can handle. If the merchant requires an intervention the agent can't handle, the checkout may not proceed.5354### Versioning in Negotiation5556- Each capability has its own version57- Extensions are versioned independently (`discount@2026-01-27`)58- Payment handlers have their own version59- Version mismatches are resolved by intersection (both must support a compatible version)6061### Use Cases6263- Merchants that support different feature sets for different plans64- Agents that gradually adopt new protocol features65- Graceful degradation when features aren't mutually supported66- Multi-merchant agents that adapt per-merchant6768### Best Practices6970- Always include capabilities in the create request71- Advertise all capabilities you support — don't under-report72- Handle the case where the merchant supports fewer features than expected73- Log negotiated capabilities for debugging74- Test with minimal capability sets to ensure graceful degradation75- Update advertised capabilities as you adopt new spec features7677Fetch the capability negotiation RFC for the exact capabilities object schema, extension pruning rules, and negotiation semantics before implementing.