Loki_AgenticCommerceBridge

What this module does

Loki_AgenticCommerceBridge lets an AI agent prepare a quote via Loki_AgenticCommerce (for instance with ACP or UCP) and then ask a human to finish it within the Loki Checkout:

1. The agent creates and updates an agentic checkout session (items, address, shipping method).
2. The agent requests a handoff URL via POST /V1/loki/agentic/handoff.
3. The human opens the URL: the quote is loaded into the regular checkout session and the Loki Checkout is shown, together with a link back to the agent.
4. Once the human places the order, the agentic checkout session is marked as completed with the order ID, so that the agent sees the result when polling the session. The success page shows a link back to the agent.

Endpoint

The endpoint uses the router, the API keys (Authorization: Bearer <key>) and the idempotency handling (Idempotency-Key header) of Loki_AgenticCommerce. The path is relative to the store base URL (there is no /rest prefix).

POST /V1/loki/agentic/handoff
Authorization: Bearer <api key>
Content-Type: application/json

{
  "quote_id": "12345",
  "agent_session_id": "session_abc",
  "return_url": "https://agent.example/return"
}

• quote_id (required): the Magento quote ID or the public agentic session ID (lac_...). The quote needs to belong to an agentic checkout session of the current store that is not completed or canceled yet.
• agent_session_id (optional): a reference of the agent (A-Z, a-z, 0-9, ., _, :, -, max 255 characters).
• return_url (optional): needs to be HTTPS and its host needs to be listed under Allowed Return URL Hosts.

Response 201:

{
  "handoff_url": "https://shop.example/lokiagentic/handoff/index/?session=lac_...&token=...",
  "expires_at": "2026-10-17T12:00:00+00:00",
  "session_id": "lac_...",
  "quote_id": "12345",
  "agent_session_id": "session_abc",
  "return_url": "https://agent.example/return",
  "status": "ready_for_payment"
}

Errors: 400 (invalid input), 401 (no valid API key), 404 (no agentic session for this quote), 409 (session is already completed or canceled, or human handoff is disabled).

The return link sends the human to return_url with the query parameters agent_session_id, session_id, status (open or completed) and order_increment_id (after placing the order).

Configuration

In Stores > Configuration > Loki > Loki Agentic Commerce:

• General > Enabled and General > API Keys (from Loki_AgenticCommerce) need to be configured.
• Human Handoff > Enabled (from Loki_AgenticCommerce) needs to be enabled.
• Bridge > Enabled: enables the handoff endpoint.
• Bridge > Allowed Return URL Hosts: comma-separated hosts, like agent.example, *.agent.example. When empty, no return_url is accepted.

Events

| Event | Data | |---|---| | loki_agentic_commerce_bridge_handoff_create_after | checkout_session, request, response (mutable) |

Installation

Install this package via composer:

composer require loki/magento2-agentic-commerce-bridge

Next, enable this module:

bin/magento module:enable Loki_AgenticCommerceBridge

Current status

Support

For getting support, create an Issue under the following project URL:

https://gitlab.yireo.com/loki-extensions/Loki_AgenticCommerceBridge.git