Download the PHP package mahesh-rajawat/module-agentic-ucp without Composer
On this page you can find all versions of the php package mahesh-rajawat/module-agentic-ucp. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download mahesh-rajawat/module-agentic-ucp
More information about mahesh-rajawat/module-agentic-ucp
Files in mahesh-rajawat/module-agentic-ucp
Package module-agentic-ucp
Short Description Universal Commerce Protocol (UCP) base module for Magento 2 — Agentic commerce
License MIT
Homepage https://github.com/mahesh-rajawat/magento2-ucp-agentic
FAQ
Example:
In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
- Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
- To use Composer is sometimes complicated. Especially for beginners.
- Composer needs much resources. Sometimes they are not available on a simple webspace.
- If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
- Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Informations about the package module-agentic-ucp
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
| Feature | Where |
|---|---|
| Agent 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
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
| Requirement | Version |
|---|---|
| Magento | 2.4.4+ |
| PHP | 8.1 or 8.2 |
| OpenSSL PHP extension | enabled |
| Redis (recommended) | 6.0+ for rate limiting |
Installation
Step 1 — Copy the module
Step 2 — Enable and compile
Step 3 — Add token secret to env.php
Open app/etc/env.php and add:
Step 4 — Register your first agent in admin
Go to Stores → Configuration → MSR → Agentic UCP → Agent registry.
Click Add agent and fill in:
| Field | Example value | Notes |
|---|---|---|
| Agent name | My Shopping Agent | Human label |
| DID | did:web:yourdomain.com |
From the agent owner |
| Trust level | Trusted | |
| Capability profile | Shopping agent | From dropdown |
| Active | Yes | |
| Max order value | 500 | Blank = use default |
| Rate limit/min | 30 | Blank = use default |
| Allowed payments | checkmo | Blank = all methods |
Step 5 — Verify
DID — what to put in the admin config
| Situation | DID value |
|---|---|
| You 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 provider | Whatever DID they give you |
Generate a did:key instantly (no server needed):
Host a did:web on your domain — create and serve at
https://yourdomain.com/.well-known/did.json:
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
| Profile ID | What 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
| Code | Label | Risk |
|---|---|---|
catalog.browse |
Browse catalog | Low |
catalog.search |
Search catalog | Low |
inventory.query |
Check inventory | Low |
cart.manage |
Manage cart | Medium |
order.track |
Track orders | Medium |
customer.read |
Read customer data | Medium |
order.place |
Place orders | High |
payment.initiate |
Initiate payments | High |
negotiation.price |
Negotiate pricing | High |
High-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
Every /V1/ucp/* request (except /V1/ucp/auth) passes through five checks:
| Check | Failure |
|---|---|
| Valid Bearer token | 401 |
| Capability granted for this route | 403 |
| Rate limit not exceeded | 429 |
| Order value within limit (order routes only) | 422 |
| Human confirmation present (mutating requests) | 400 |
Admin panel sections
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
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
Global defaults that apply to all agents unless overridden per-agent: human confirmation, rate limit, max order value, audit log, token TTL.
Security
Allowed DID methods, DID resolution timeout, and token secret status indicator (shows configured/not configured without exposing the value).
Recent audit log
Inline view of the last 20 agent requests showing agent, path, capability (human label), outcome (colour-coded), and timestamp.
Decision ownership
| What | Owned by | Changed via |
|---|---|---|
| Capability profiles | Code | ucp.xml + deploy |
| New capability codes | Code | di.xml injection + deploy |
| Agent identity (name, DID, trust level) | Database | Admin panel |
| Which agents are active | Database | Admin panel |
| Per-agent permissions | Database | Admin panel |
| Global default policies | Database | Admin panel |
| Token secret | Server | env.php |
Nothing about who the agents are or what their limits are should ever require a code deployment.
Extending from another module
Add a new agent at runtime
Admin panel → Agent registry → Add agent. No code, no deployment.
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
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.
When does a child module need ucp.xml?
Add a custom policy check
Hook into auth events
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.
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
| Error | Cause | Fix |
|---|---|---|
404 on /.well-known/ucp.json |
routes.xml has dot in frontName, or Router not registered | Check frontName="ucpwellknown" and etc/frontend/di.xml sortOrder=22 |
| "Agent not registered" | DID mismatch between admin config and request | Check 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 field |
Decode JWT with cut -d'.' -f2 \| base64 -d and check iss |
| "UCP token signature invalid" | Token secret mismatch | Check ucp/token_secret in env.php matches test script |
| 404 instead of 401 on policy test | Checkout module not installed | Install MSR_AgenticUcpCheckout |
| "More than one node" XML merge error | Repeating elements missing merge key | Check $_idAttributes in UcpReader.php covers all list elements |
| New capability not in admin dropdown | di.xml injection not compiled |
Run setup:di:compile && cache:flush |
| Rate limit not triggering | Redis not configured as cache backend | Check env.php cache section uses Redis |
