PHPackages mahesh-rajawat/module-agentic-ucp - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Framework](/categories/framework) 4. / 5. mahesh-rajawat/module-agentic-ucp ActiveMagento2-module[Framework](/categories/framework) mahesh-rajawat/module-agentic-ucp ================================= Universal Commerce Protocol (UCP) base module for Magento 2 — Agentic commerce 1.0.1(3mo ago)0411MITPHPPHP >=8.1.0 Since Apr 20Pushed 3mo agoCompare [ Source](https://github.com/mahesh-rajawat/magento-module-agentic-commerce-base)[ Packagist](https://packagist.org/packages/mahesh-rajawat/module-agentic-ucp)[ Docs](https://github.com/mahesh-rajawat/magento2-ucp-agentic)[ RSS](/packages/mahesh-rajawat-module-agentic-ucp/feed)WikiDiscussions master Synced 1w ago READMEChangelog (3)Dependencies (1)Versions (3)Used By (1) MSR\_AgenticUcp — UCP Agentic Commerce Base Module ================================================== [](#msr_agenticucp--ucp-agentic-commerce-base-module) Adds Universal Commerce Protocol (UCP) support to Magento 2, enabling AI agents to discover, authenticate, and transact on your storefront in a structured, policy-controlled way. This is the **base module**. It handles identity, authentication, policy enforcement, and admin configuration. The companion module `MSR_AgenticUcpCheckout` provides the catalog, cart, checkout, and order REST endpoints. --- What this module provides ------------------------- [](#what-this-module-provides) FeatureWhereAgent capability manifest`GET /.well-known/ucp.json`Agent authentication (DID + JWT)`POST /rest/V1/ucp/auth`Policy middleware (all `/V1/ucp/*` routes)`Plugin/Webapi/AgentPolicyGuard.php`Capability profiles (what agents can do)`etc/ucp.xml`Admin configuration UI`Stores → Configuration → MSR → Agentic UCP`Extensible capability registry`Model/Config/Source/Capabilities.php`Audit trail`ucp_audit_log` database table--- Architecture overview --------------------- [](#architecture-overview) ``` Admin panel (Stores → Config → MSR → Agentic UCP) │ ├── Agent registry — WHO the agents are │ name, DID, trust level, profile, active, per-agent overrides │ stored in: core_config_data (database) │ no file editing ever needed │ ├── Default policies — global limits │ rate limit, max order value, human confirmation, TTL │ stored in: core_config_data (database) │ └── ucp.xml — capability profiles only what each profile CAN do stored in: module files (version controlled) changed only when: a new feature module is installed ``` ### Design principles [](#design-principles) **Single source of truth** — agent identity and policies live in the database (admin panel). Capability profiles live in code (ucp.xml). Never both. **Open/Closed** — child modules add capabilities by injecting into Capabilities source model via di.xml. Base module files are never modified. **No hardcoded agents** — ucp.xml contains only profile-\* entries. Real agents (DIDs) are registered in the admin panel at runtime. --- Requirements ------------ [](#requirements) RequirementVersionMagento2.4.4+PHP8.1 or 8.2OpenSSL PHP extensionenabledRedis (recommended)6.0+ for rate limiting--- Installation ------------ [](#installation) ### Step 1 — Copy the module [](#step-1--copy-the-module) ``` unzip MSR_AgenticUcp.zip -d /var/www/html/app/code/ ``` ### Step 2 — Enable and compile [](#step-2--enable-and-compile) ``` cd /var/www/html php bin/magento module:enable MSR_AgenticUcp php bin/magento setup:upgrade php bin/magento setup:di:compile php bin/magento cache:flush ``` ### Step 3 — Add token secret to env.php [](#step-3--add-token-secret-to-envphp) ``` php -r "echo bin2hex(random_bytes(32)) . PHP_EOL;" ``` Open `app/etc/env.php` and add: ``` 'ucp' => [ 'token_secret' => 'paste-generated-secret-here', ], ``` ### Step 4 — Register your first agent in admin [](#step-4--register-your-first-agent-in-admin) Go to `Stores → Configuration → MSR → Agentic UCP → Agent registry`. Click **Add agent** and fill in: FieldExample valueNotesAgent nameMy Shopping AgentHuman labelDID`did:web:yourdomain.com`From the agent ownerTrust levelTrustedCapability profileShopping agentFrom dropdownActiveYesMax order value500Blank = use defaultRate limit/min30Blank = use defaultAllowed paymentscheckmoBlank = all methods### Step 5 — Verify [](#step-5--verify) ``` curl -sk https://yourstore.com/.well-known/ucp.json | python3 -m json.tool ``` --- DID — what to put in the admin config ------------------------------------- [](#did--what-to-put-in-the-admin-config) SituationDID valueYou host the agent`did:web:yourdomain.com`Agent on a subdomain`did:web:agent.yourdomain.com`Agent at a path`did:web:yourdomain.com:agents:shopper`Local dev / Warden`did:web:default.freshm2.test:agents:test`No server available`did:key:z6Mk...` (generate below)Third-party providerWhatever DID they give youGenerate a `did:key` instantly (no server needed): ``` npm install -g @digitalbazaar/did-key-cli npx did-key generate --type Ed25519 ``` Host a `did:web` on your domain — create and serve at `https://yourdomain.com/.well-known/did.json`: ``` { "@context": ["https://www.w3.org/ns/did/v1"], "id": "did:web:yourdomain.com", "verificationMethod": [{ "id": "did:web:yourdomain.com#key-1", "type": "JsonWebKey2020", "controller": "did:web:yourdomain.com", "publicKeyPem": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----" }], "authentication": ["did:web:yourdomain.com#key-1"], "assertionMethod": ["did:web:yourdomain.com#key-1"] } ``` --- Capability profiles ------------------- [](#capability-profiles) Profiles are defined in `etc/ucp.xml`. They are templates — real agents are assigned to a profile in the admin panel. ### Built-in profiles [](#built-in-profiles) Profile IDWhat it allows`profile-readonly`Browse, search, check inventory, track orders`profile-shopping`Everything in readonly + manage cart, place orders`profile-full-access`Everything including customer data and payment initiation### Built-in capability codes [](#built-in-capability-codes) CodeLabelRisk`catalog.browse`Browse catalogLow`catalog.search`Search catalogLow`inventory.query`Check inventoryLow`cart.manage`Manage cartMedium`order.track`Track ordersMedium`customer.read`Read customer dataMedium`order.place`Place ordersHigh`payment.initiate`Initiate paymentsHigh`negotiation.price`Negotiate pricingHighHigh-risk capabilities always require human confirmation regardless of the default policy setting. Capability code format: `namespace.action` — lowercase, dot-separated. The XSD validates this pattern. Any code matching the pattern is valid — no central registry needed. --- Policy middleware ----------------- [](#policy-middleware) Every `/V1/ucp/*` request (except `/V1/ucp/auth`) passes through five checks: CheckFailureValid Bearer token401Capability granted for this route403Rate limit not exceeded429Order value within limit (order routes only)422Human confirmation present (mutating requests)400--- Admin panel sections -------------------- [](#admin-panel-sections) ### Agent registry [](#agent-registry) Dynamic grid — one row per AI agent. Profile dropdown is sourced from `profile-*` entries in `ucp.xml` across all installed modules. Adding a new module with a new profile automatically adds it to this dropdown. ### Capability profiles reference [](#capability-profiles-reference) Read-only table showing what each profile means in plain English. Store owner sees "Browse catalog — View product listings", not `catalog.browse`. Grouped by risk level. ### Default policies [](#default-policies) Global defaults that apply to all agents unless overridden per-agent: human confirmation, rate limit, max order value, audit log, token TTL. ### Security [](#security) Allowed DID methods, DID resolution timeout, and token secret status indicator (shows configured/not configured without exposing the value). ### Recent audit log [](#recent-audit-log) Inline view of the last 20 agent requests showing agent, path, capability (human label), outcome (colour-coded), and timestamp. --- Decision ownership ------------------ [](#decision-ownership) WhatOwned byChanged viaCapability profilesCode`ucp.xml` + deployNew capability codesCode`di.xml` injection + deployAgent identity (name, DID, trust level)DatabaseAdmin panelWhich agents are activeDatabaseAdmin panelPer-agent permissionsDatabaseAdmin panelGlobal default policiesDatabaseAdmin panelToken secretServer`env.php`Nothing about who the agents are or what their limits are should ever require a code deployment. --- Extending from another module ----------------------------- [](#extending-from-another-module) ### Add a new agent at runtime [](#add-a-new-agent-at-runtime) Admin panel → Agent registry → Add agent. No code, no deployment. ### Add a new capability profile [](#add-a-new-capability-profile) Drop a `ucp.xml` with a `profile-*` entry. Appears in admin dropdown after `cache:flush`. No base module changes. ``` ``` ### Add new capability codes [](#add-new-capability-codes) Inject into `Capabilities` source model via `di.xml`. No base module files touched. New capabilities appear in the admin reference table and are available in profile definitions. ``` quote.request Request a quote Agent can request B2B price quotes medium YourVendor_YourModule ``` ### When does a child module need ucp.xml? [](#when-does-a-child-module-need-ucpxml) ``` New REST endpoints only → NO (no ucp.xml needed) New capability codes → YES (new profile-* entry + di.xml injection) Only permissions/policies → NO (use admin panel) Only identity/DID changes → NO (use admin panel) ``` ### Add a custom policy check [](#add-a-custom-policy-check) ``` ``` ### Hook into auth events [](#hook-into-auth-events) ``` ``` Companion module ---------------- [](#companion-module) `MSR_AgenticUcpCheckout` provides catalog, cart, checkout, and order endpoints. It does **not** need its own `ucp.xml` — it only adds REST routes for capabilities already defined in base module profiles. ``` unzip MSR_AgenticUcpCheckout.zip -d /var/www/html/app/code/ php bin/magento module:enable MSR_AgenticUcpCheckout php bin/magento setup:upgrade php bin/magento setup:di:compile php bin/magento cache:flush ``` --- Local dev setup (Warden) ------------------------ [](#local-dev-setup-warden) Apply dev mode patches Manually patch `Model/Did/Resolver.php` to bypass HTTP DID resolution and return a local key (see `UCP_Testing_Guide.md` for full instructions). --- Troubleshooting --------------- [](#troubleshooting) ErrorCauseFix404 on `/.well-known/ucp.json`routes.xml has dot in frontName, or Router not registeredCheck `frontName="ucpwellknown"` and `etc/frontend/di.xml` sortOrder=22"Agent not registered"DID mismatch between admin config and requestCheck admin panel DID matches POST body exactly"Could not resolve DID document"Resolver patch not applied (dev) or DID document unreachable (prod)Apply dev patch or verify `https://yourdomain.com/.well-known/did.json`"JWT issuer mismatch"JWT `iss` claim doesn't match the `did` fieldDecode JWT with `cut -d'.' -f2 | base64 -d` and check `iss`"UCP token signature invalid"Token secret mismatchCheck `ucp/token_secret` in `env.php` matches test script404 instead of 401 on policy testCheckout module not installedInstall `MSR_AgenticUcpCheckout`"More than one node" XML merge errorRepeating elements missing merge keyCheck `$_idAttributes` in `UcpReader.php` covers all list elementsNew capability not in admin dropdown`di.xml` injection not compiledRun `setup:di:compile && cache:flush`Rate limit not triggeringRedis not configured as cache backendCheck `env.php` cache section uses Redis ### Health Score 37 — LowBetter than 81% of packages Maintenance82 Actively maintained with recent releases Popularity4 Limited adoption so far Community11 Small or concentrated contributor base Maturity44 Maturing project, gaining track record Bus Factor1 Top contributor holds 87.5% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~1 days Total 2 Last Release 94d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/32479280?v=4)[Mahesh Singh](/maintainers/mahesh-rajawat)[@mahesh-rajawat](https://github.com/mahesh-rajawat) --- Top Contributors [![mahesh-singh-pinja](https://avatars.githubusercontent.com/u/136575595?v=4)](https://github.com/mahesh-singh-pinja "mahesh-singh-pinja (14 commits)")[![mahesh-rajawat](https://avatars.githubusercontent.com/u/32479280?v=4)](https://github.com/mahesh-rajawat "mahesh-rajawat (2 commits)") --- Tags magentoecommercemagento2ai-agentsagentic commerceucpdiducp-protocol ### Embed Badge ![Health badge](/badges/mahesh-rajawat-module-agentic-ucp/health.svg) ``` [![Health](https://phpackages.com/badges/mahesh-rajawat-module-agentic-ucp/health.svg)](https://phpackages.com/packages/mahesh-rajawat-module-agentic-ucp) ``` ### Alternatives [magewirephp/magewire A framework that makes building reactive and dynamic interfaces simple in Magento 2 2621.4M45](/packages/magewirephp-magewire)[smile/elasticsuite Magento 2 merchandising and search engine built on ElasticSearch 8064.7M50](/packages/smile-elasticsuite)[run-as-root/magento2-prometheus-exporter Magento2 Prometheus Exporter 68357.9k](/packages/run-as-root-magento2-prometheus-exporter)[myparcelnl/magento A Magento 2 module that creates MyParcel labels 1860.2k](/packages/myparcelnl-magento)[opengento/module-category-import-export This module add the capability to import and export the categories from the back-office. 1310.9k2](/packages/opengento-module-category-import-export) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)