Loki_AgenticCommerce

What this module does

Loki_AgenticCommerce is a protocol-neutral framework that lets AI agents shop in Magento. It maps an agentic checkout session to a Magento quote, and offers extension points for protocol modules, PSP modules and Loki Checkout extensions. Protocols live in thin submodules:

• Loki_AgenticCommerceAcp: Agentic Commerce Protocol (OpenAI / Stripe)
• Loki_AgenticCommerceUcp: Universal Commerce Protocol (Google)
• Loki_AgenticCommerceAp2: Agent Payments Protocol mandate verification (works with any protocol)

See BENEFITS.md for how this approach compares to other modules.

Configuration

In Stores > Configuration > Loki > Loki Agentic Commerce:

• General > Enabled: enables the router for all enabled protocols.
• General > API Keys: comma-separated bearer tokens. Without a key, every authenticated endpoint is closed.
• Human Handoff: return a signed continue_url that loads the session quote into the regular checkout.
• Payment > Fallback Payment Method: optional Magento payment method for the handler magento.configured_method.

Architecture

Agent ─HTTP─> Router ─> Controller\Endpoint\Dispatch ─> EndpointDispatcher
                                                        ├─ AuthenticatorListing (closed by default)
                                                        ├─ IdempotencyStore
                                                        └─ EndpointInterface::getHandler()
                                                             └─ core handler + protocol CheckoutMapperInterface
                                                                  └─ CheckoutSessionManager
                                                                       ├─ QuoteUpdater
                                                                       ├─ CheckoutStateBuilder ─ CapabilityResolver
                                                                       ├─ PaymentHandlerListing
                                                                       └─ PaymentAuthorizationValidatorListing

Extension points

DI listings

| Listing | Item interface | Purpose | |---|---|---| | Protocol\ProtocolListing (protocols) | Api\ProtocolInterface | Register a protocol (use the generic Protocol\Protocol) | | Endpoint\EndpointListing (endpoints) | Api\EndpointInterface | Register HTTP endpoints (use virtualTypes of Endpoint\Endpoint) | | Authentication\AuthenticatorListing (authenticators) | Api\AuthenticatorInterface | Add authentication schemes (bearer token is built in) | | Capability\CapabilityListing (capabilities) | Api\AgenticCheckoutCapabilityInterface | Declare whether a feature allows agentic checkout | | Payment\PaymentHandlerListing (paymentHandlers) | Api\PaymentHandlerInterface | Map agent credentials to a Magento payment method | | Payment\PaymentAuthorizationValidatorListing (validators) | Api\PaymentAuthorizationValidatorInterface | Verify a payment before ordering (like AP2) |

Preference: Api\HandoffUrlProviderInterface (default Handoff\HandoffUrlProvider).

Events

| Event | Data | |---|---| | loki_agentic_commerce_session_create_before / _after | checkout_session, quote, protocol, checkout_request (state in after) | | loki_agentic_commerce_session_update_before / _after | same as above | | loki_agentic_commerce_session_complete_before | checkout_session, quote, checkout_request, payment_request, payment_handler | | loki_agentic_commerce_session_complete_after | checkout_session, quote, order, payment_request, payment_handler, state | | loki_agentic_commerce_session_cancel_after | checkout_session, quote, state | | loki_agentic_commerce_quote_update_before_collect | quote, checkout_request | | loki_agentic_commerce_checkout_state_build_after | state (mutable), quote, checkout_session, handoff_result | | loki_agentic_commerce_capabilities_resolve_after | quote, result (mutable HandoffResult) | | loki_agentic_commerce_request_dispatch_before | request, endpoint, protocol | | loki_agentic_commerce_response_render_before | request, response (mutable), protocol | | loki_agentic_commerce_handoff_before | checkout_session, quote |

Example: a Loki Checkout extension declaring its capability

use Loki\AgenticCommerce\Api\AgenticCheckoutCapabilityInterface;
use Loki\AgenticCommerce\Capability\HandoffRequirement;

class AgeVerificationCapability implements AgenticCheckoutCapabilityInterface
{
    public function supportsAgenticCheckout(): bool
    {
        return true;
    }

    public function requiresHumanInteraction(): bool
    {
        return true;
    }

    public function getHandoffRequirements(): array
    {
        return [
            new HandoffRequirement('age_verification', 'The buyer needs to verify their age', HandoffRequirement::TYPE_VERIFICATION),
        ];
    }
}

<type name="Loki\AgenticCommerce\Capability\CapabilityListing">
    <arguments>
        <argument name="capabilities" xsi:type="array">
            <item name="age_verification" xsi:type="object">Vendor\Module\Agentic\AgeVerificationCapability</item>
        </argument>
    </arguments>
</type>

Example: a new protocol

Implement Api\CheckoutMapperInterface, then wire it in di.xml with virtualTypes of the core handlers (Endpoint\Handler\CreateCheckoutSession and similar) and Endpoint\Endpoint. See Loki_AgenticCommerceAcp/etc/di.xml.

Installation

Install this package via composer:

composer require loki/magento2-agentic-commerce

Next, enable this module:

bin/magento module:enable Loki_AgenticCommerce

Current status

Support

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

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