Gtstudio_Ucp

Magento 2 module implementing Google's Universal Commerce Protocol (UCP) — an open standard that allows AI shopping agents to discover and drive checkout sessions on any compliant merchant.

What It Does

• Exposes /.well-known/ucp profile discovery endpoint so AI agents can locate the checkout API.
• Implements the five UCP checkout session endpoints (create, get, update, complete, cancel).
• Maps Magento quote state to UCP session state (incomplete → ready_for_complete → completed | cancelled).
• Registers five AiAgents tools so the ucp_checkout agent can drive sessions programmatically.
• Seeds a ucp_checkout agent with a UCP-aware system prompt via data patch.

Installation

composer require gtstudio/module-ucp
bin/magento module:enable Gtstudio_Ucp
bin/magento setup:upgrade

Endpoints

Method	Path	Description
GET	/.well-known/ucp	Profile discovery
POST	/ucp/checkout-sessions	Create session
GET	/ucp/checkout-sessions/:id	Get session
PUT/PATCH	/ucp/checkout-sessions/:id	Update session
POST	/ucp/checkout-sessions/:id/complete	Place order
POST	/ucp/checkout-sessions/:id/cancel	Cancel session

Session Lifecycle

incomplete
  → (add buyer email)              requires_escalation | ready_for_complete
  → (complete with payment)        completed
  → (cancel at any point)          cancelled

Status is resolved dynamically from the linked Magento quote on every get or update call.

How It Works

1. Router (Controller/Router.php) — registered at sortOrder=20, intercepts /.well-known/ucp and /ucp/checkout-sessions/* before Magento's standard router.
2. Controllers — thin HTTP boundary classes extending AbstractCheckout; delegate to CheckoutSessionManagementInterface.
3. CheckoutSessionManagement — core business logic: creates/updates Magento quotes, maps UCP payloads to Magento API calls, persists UcpSession records.
4. SessionMapper — converts CartInterface to UCP JSON, resolves session state, surfaces recoverable validation messages.

Validation

Use the UCP conformance test suite or ucpchecker.com to validate the endpoints against the protocol spec.

Extensibility

• Swap the session mapper by declaring a <preference> for Gtstudio\Ucp\Api\CheckoutSessionManagementInterface.
• Add custom profile capabilities by replacing Gtstudio\Ucp\Api\ProfileBuilderInterface.
• The UcpSession model exposes standard Magento getter/setter methods for plugin attachment.

AI Studio Ecosystem

Module	Description
module-ai-connector	LLM provider abstraction (OpenAI, Anthropic, Gemini)
module-ai-agents	Agent orchestration, tools, and tool executor pool
module-ai-widgets	Admin chat widgets and Page Builder agent
module-ai-data-query	Natural-language store analytics tools
module-ai-knowledge-base	Vector search knowledge base
module-ai-dashboard	Admin AI dashboard with store assistant
module-ucp	(this module)

License

Business Source License 1.1 — see LICENSE.