Thyris ACP Engine Documentation

This documentation supports customer implementations of Thyris Agentic Commerce.

Thyris Agentic Commerce powers controlled agent experiences where assistants understand customer intent, use approved business capabilities, and return normalized responses to customer applications.

These documents are written for integration, solution architecture, frontend, security, and operations teams. They describe supported public contracts, readiness expectations, and operational responsibilities without exposing internal implementation details.

Recommended Reading Order

Step	Document	Purpose
1	Platform Overview	What Thyris Agentic Commerce is, what it is not, and which capabilities it exposes.
2	Integration Overview	Integration model, actors, authentication flow, and recommended onboarding sequence.
3	Frontend and SDK Guide	Frontend/backend integration pattern, session handling, runtime chat, and response rendering.
4	Automatic Flow Routing	Optional flow_id, domain-neutral Flow capability modules, bounded AI decisions, session ownership, rollout, and rollback.
4a	Runtime Sessions, Chat IDs, and Recovery	Session TTL, refresh, recovery, status, chat labels, and BFF ownership.
5	Enterprise API Documentation	Public REST and MCP endpoints, authentication, payloads, errors, and integration sequence.
6	Control Plane Guide	Configure identities, providers, prompts, agents, flows, MCP servers, and routing in Manager.
7	Merchant, Store, Catalog, and Enrichment Guide	Configure independent merchants, stores, teams, developer keys, Catalog, and merchant-scoped Enrichment.
8	Manager CLI Guide	Inspect realm identities, runtime AI, MCP, sessions, and usage from the embedded read-only terminal.
9	Runtime Resource Lifecycle	Create, validate, activate, observe, roll back, and retire runtime resources safely.
10	MCP Integration Guide	Unified MCP service, Catalog tools, server registration, testing, and controlled execution.
11	Security and Data Handling	Credential handling, customer data boundaries, and integration responsibilities.
12	Operational Guide	QA, UAT, go-live, monitoring, support handoff, and troubleshooting.
13	Reference Frontend and MCP Patterns	Optional implementation reference using generic frontend and MCP patterns.
14	Production Readiness and Validation	Release gates, routing evidence, failure and capacity tests, and project-specific acceptance.
15	Examples	Explained request, response, and frontend state examples.

Glossary and Building Blocks

This section explains the main terms used across the documentation.

Platform Components

ACP Engine : The central orchestration API. It receives authenticated requests from customer applications, manages runtime context, uses configured assistant behavior and approved tools, records usage, and returns normalized responses.

Frontend Application : The customer-facing web, mobile, kiosk, or support UI. It should send user intent to ACP Engine and render the returned response. It should not contain service secrets or call downstream MCP servers directly.

Frontend Backend : A server-side adapter or backend-for-frontend layer used by the frontend application. It can perform token exchange, call ACP Engine, normalize responses, and keep secrets out of browser code.

MCP Server : A downstream tool server that exposes business capabilities through the Model Context Protocol. Examples include product search, product details, cart operations, checkout preparation, order lookup, CRM lookup, support ticket creation, or custom customer actions.

ACP MCP Facade : The public JSON-RPC surface of the unified mcp-service. Realm service identities authenticate Engine tools; merchant API keys authenticate merchant/store Catalog tools.

Manager CLI : A read-only terminal embedded in Manager. It exposes an allowlisted command set for inspecting realm-scoped operational data and is not an operating-system shell.

Merchant : An independent commerce account with its own team, developer keys, stores, and enrichment providers. A merchant is not a child of a realm.

AI Provider : A text and/or image provider. Realm providers serve runtime agents; merchant providers serve Enrichment and are isolated in a separate registry.

Tenant and Identity Terms

Realm : A customer tenant or workspace. Runtime resources such as agents, AI providers, MCP servers, flows, behavior templates, themes, and usage records are scoped to a realm.

User : A human or system identity that can authenticate and access allowed resources.

Agent : A runtime assistant identity. Agent configuration controls which AI provider, behavior template, flow, and MCP servers the assistant can use.

Service Identity : A backend-to-backend identity used by server-side integrations, automation, or frontend backend adapters.

Access Key : A long-lived identifier used together with a secret key to request a short-lived bearer token.

Secret Key : A sensitive credential paired with an access key. It is shown only when created and must be stored securely.

Bearer Token : A short-lived JWT used in the Authorization header for authenticated API requests.

Runtime Terms

Session : A subject-bound conversation or workflow context. Keep its session ID and protected resume token across chat and structured Flow execution to preserve continuity.

Flow : A named runtime journey. A flow can define which behavior template, AI provider, MCP servers, and execution steps should be used for a scenario such as product discovery, checkout support, or order tracking.

Behavior Template : A managed instruction template that controls assistant behavior, tone, tool usage rules, and domain constraints.

Runtime Chat : The primary API path for customer interaction. The frontend sends messages to ACP Engine, and ACP Engine handles assistant behavior, tools, and tool selection, and response generation.

Action : A response instruction returned by the runtime. Examples include RESPOND, CLARIFY, RENDER_PRODUCTS, ORDER_SUMMARY, or ACTION_REQUIRED.

Trace ID : A correlation identifier used for support and diagnostics. Include it when reporting issues.

MCP and Tooling Terms

Tool : A named capability exposed by an MCP server. Tool examples include search_products, add_to_cart, complete_payment, or get_order_status.

Tool Listing : The process of reading available tool names, descriptions, and schemas from an approved MCP server so they can be used through configured access controls.

MCP Proxy : An ACP Engine endpoint that executes a specific tool on a specific MCP server through the engine.

MCP Tool Selection : The configured policy layer that selects an approved MCP server and execution approach for a customer journey.

Routing Rule : A configurable rule that maps approved intents, tool names, and capabilities to target MCP servers and execution policies.

Flow Routing Profile : Realm-scoped metadata that makes a published Flow eligible for automatic intent selection and defines examples, constraints, confidence, fallback, and allowed handoffs.

Routing Strategy : The approved execution approach used by a rule, such as a primary tool server or a fallback path.

Tool Result : The structured or text result returned by a tool. ACP Engine can normalize this result before sending it to the frontend.

Commerce Terms

Store : A storefront, brand, region, or sales channel under a merchant.

Product : A sellable item.

Catalog Service : The ACP domain service for merchant- and store-scoped products, carts, checkouts, orders, and Catalog integrations. Public clients normally use ACP Engine REST routes or Catalog tools exposed by the unified MCP service.

Enrichment : A store workflow that selects from the merchant's provider registry to enrich Catalog product content. Its usage is store-specific and recorded separately from realm runtime usage.

Variant : A product option such as size, color, package, or configuration.

SKU : A stock keeping unit used to identify products or variants.

External ID : A product identifier from an external commerce, ERP, PIM, marketplace, or store platform.

Webhook : A server-to-server event sent by a merchant system when commerce data changes. Common events include product created, updated, upserted, or deleted.

Idempotency Key : A stable identifier such as SKU or external ID that lets repeated create/update requests safely target the same product.

Operational Terms

Usage Record : A record of AI or tool activity, including tokens, cost metadata, transaction type, tool name, session ID, and agent ID where applicable.

Transaction Type : A reporting category such as PRODUCT_LISTING, PAYMENT_COMPLETE, or OTHER.

Observability : Logs, traces, metrics, and alerts used to monitor runtime behavior and troubleshoot customer scenarios.

UAT : User Acceptance Testing. A controlled validation phase before production launch.

How the Pieces Fit Together

Typical runtime path:

Typical support path: