Thyris Agentic Commerce Integration Overview

Thyris Agentic Commerce is the controlled orchestration layer between customer-facing applications and approved business capabilities. It gives frontend and backend clients one consistent public API surface for authentication, Catalog, chat, runtime journeys, approved tool access, usage reporting, and operational observability.

In an agentic commerce deployment, Thyris Agentic Commerce helps an assistant experience understand customer intent, select the approved journey, call approved MCP tools, retrieve allowed merchant service data, and return an actionable customer-facing response.

Core Responsibilities

ACP Engine handles:

• Authentication and token exchange.
• Realm-level tenant isolation.
• Merchant- and store-scoped Catalog products, carts, checkouts, and orders.
• Assistant behavior configuration and runtime execution.
• MCP server registration, tool listing, controlled tool selection, and tool execution.
• Configured selection between flows, agents, tools, and MCP servers.
• Session context and conversation continuity.
• Usage and transaction reporting.
• Operational logs, metrics, and traces.

Customer applications should treat ACP Engine as the main integration boundary. Frontends should not call downstream MCP servers directly unless explicitly agreed for a special deployment model.

High-Level Architecture

Main Actors

Realm : A customer tenant or workspace. Most resources are scoped to a realm.

User : An authenticated identity that can administer or use a realm.

Agent : A runtime assistant identity. Agents are used for chat, flows, MCP permissions, and usage reporting.

Service : A backend-to-backend integration identity.

Merchant : An independent commerce account that owns stores, a merchant team, developer API keys, and Enrichment providers.

AI Provider : A text and/or image provider. Runtime providers are realm-scoped; Enrichment providers are merchant-scoped and kept in a separate registry.

MCP Server : A downstream tool server that exposes customer capabilities such as product search, cart, checkout, order lookup, CRM lookup, or custom actions.

Flow : A realm-scoped capability module that combines semantic selection metadata, a bounded system-instruction fragment, approved tools and outputs, and optional deterministic or adaptive execution steps. Flows are domain-neutral and can represent commerce, support, operations, HR, banking, developer tooling, or another approved use case.

Session : A conversation or runtime interaction context used for continuity and reporting.

Recommended Integration Sequence

1. Create or receive customer credentials.
2. Exchange credentials for a JWT token.
3. Confirm authentication with GET /api/v1/auth/is-authenticated.
4. Confirm the target realm and agent IDs.
5. Configure or validate the realm runtime provider when the journey uses runtime AI.
6. Create or select the merchant and store, issue a merchant API key, and synchronize representative Catalog products.
7. Register downstream MCP servers and confirm the approved tool list when external capabilities are required.
8. Publish eligible Flows with a reviewed semantic manifest or dedicated routing profile, then set the realm routing mode.
9. Create a subject-bound session and run a chat request through POST /api/v1/runtime/ai/chat without flow_id for automatic routing.
10. Validate Catalog operations, Enrichment usage where applicable, runtime usage, logs, and traces.
11. Complete UAT scenarios before production traffic is enabled.

Authentication Flow

The customer integration uses an access key and secret key to obtain a short-lived bearer token.

POST /api/v1/auth/token
Content-Type: application/json

{
  "access_key": "{{access_key}}",
  "secret_key": "{{secret_key}}"
}

The response includes:

{
  "access_token": "eyJ...",
  "expires_in": 900,
  "token_type": "Bearer",
  "user_id": "user-id",
  "realm_id": "realm-id",
  "user_type": "service"
}

All authenticated API requests should include:

Authorization: Bearer {{token}}

Runtime Chat Flow

A typical frontend sends user intent to ACP Engine:

POST /api/v1/runtime/ai/chat
Content-Type: application/json
Authorization: Bearer {{token}}

{
  "agent_id": "{{agent_id}}",
  "session_id": "{{session_id}}",
  "resume_token": "{{resume_token}}",
  "messages": [
    {
      "role": "user",
      "content": "Find black running shoes under 150 USD."
    }
  ]
}

When flow_id is omitted, ACP selects an eligible active published Flow from the authenticated realm and session context. Supplying flow_id forces that exact validated Flow and skips intent classification. ACP then composes only the selected Flow's instructions with the realm and Agent system prompt, enforces its tools and output permissions, records usage, and returns a normalized response. The integration contract is identical for deterministic, adaptive, and hybrid Flows. See Automatic Flow Routing.

Integration Boundaries

Customer teams are expected to manage:

• Customer frontend experience.
• Customer MCP server contract, availability, and business behavior.
• API credentials and secure storage on their side.
• Network access from Thyris Agentic Commerce to customer MCP servers.
• User-facing content, business rules, and domain data exposed by their MCP tools.

ACP Engine manages:

• Public API contract.
• Merchant- and store-scoped Catalog API and built-in Catalog MCP tools.
• Runtime orchestration.
• Authentication and scoped access.
• MCP server registration, tool listing, and controlled tool-selection behavior.
• Usage reporting and operational telemetry.

Environment Checklist

Before UAT, confirm:

• base_url is reachable from the customer test environment.
• Token exchange works.
• The customer realm is available.
• At least one eligible AI provider is active.
• The merchant API key has the intended merchant, store, or custom store scope.
• Required Catalog products and store scope are available.
• Any required downstream MCP server is registered and active.
• Registered downstream servers and built-in Catalog tools expose the expected approved tools.
• A runtime chat request returns a valid response.
• Usage summary returns records after test traffic.