UCP Development Patterns

Before writing code

Fetch live reference: Web-search site:ucp.dev specification reference for the latest data model definitions and enum values. Also check https://ucp.dev/2026-01-23/documentation/core-concepts/ for architectural guidance.

Pattern: Capability Negotiation

Every request/response pair involves negotiation:

1. Platform sends UCP-Agent header with its profile URI
2. Business fetches the platform profile (cache it — don't fetch on every request)
3. Business computes the intersection: capabilities both support
4. Orphaned extensions are pruned (extensions whose parent capability is not in the intersection)
5. Business returns the negotiated ucp object

Caching: Cache the platform profile with a TTL (e.g., 5 minutes). Don't re-fetch on every request.

Version compatibility: If platform version > business version, return version_unsupported. If platform version <= business version, process using the platform's version semantics.