ACP Engine Control Plane Guide

The ACP Engine Manager is the operational control plane for runtime realms and independent merchant commerce accounts. Realm dashboards own identity and runtime configuration; merchant and store dashboards own teams, developer keys, Catalog, and Enrichment.

Use this guide when an environment already exists and you need to prepare or change its runtime configuration. Application developers that only consume the public runtime API can start with the Integration Overview.

Configuration Order

Configure resources in this order because each later resource depends on identifiers created earlier:

1. Confirm global team, realm access, and merchant access independently.
2. Create realm service identities for runtime clients and merchant developer keys for Catalog clients.
3. Configure a realm AI provider for runtime agents when required.
4. Create the merchant and its stores, then synchronize Catalog products and validate cart and order behavior.
5. Configure the merchant Enrichment provider registry and select a provider for each store workflow.
6. Create an active behavior prompt.
7. Register downstream MCP servers and discover their tools when external tools are required.
8. Create an agent and attach the provider, prompt, and allowed MCP servers.
9. Create and activate a flow for the customer journey.
10. Add routing rules when tool selection needs explicit control.
11. Start a test session, then verify realm runtime data and merchant/store Catalog and Enrichment data in their respective surfaces.

Identity

The Identity area manages human access and runtime identities separately.

• Team access controls who can administer or view a realm in Manager.
• Engine identities represent users, services, agents, or API clients in the runtime.
• Service identities are the preferred choice for backend integrations.
• Access and secret keys must remain in a server-side secret manager. A browser or mobile bundle must never contain them.

Use an administrator role only for operators who change realm resources. Use viewer access for support and audit users who only inspect state.

Realm AI Providers

Realm AI providers define the model endpoints and credentials available to runtime agents. They are separate from merchant Enrichment providers.

Before activating a provider, verify:

• The endpoint is reachable from ACP Engine.
• The API key has the minimum required provider permission.
• supports_text and supports_image accurately describe the endpoint. The same provider can support both.
• A text model is configured when text support is enabled.
• An image model is configured when image support is enabled.
• Token and image prices and the three-letter currency match the provider billing unit.

Thyris-managed internal providers are not shown in customer-managed provider lists.

Only one intended production configuration should be active for a journey. Test provider changes in a non-production realm before switching production traffic.

Merchants, Stores, and Catalog

Merchants are independent from realms. Each merchant owns its team, developer keys, stores, and enrichment provider registry. Each store exposes separate Catalog pages for Overview, Products, Carts, Orders, and Integrations.

• Products support create, update, inspect, and delete operations.
• Product synchronization should use a stable SKU or external ID.
• Carts use the product's 10-digit Catalog ID and produce a checkout ID.
• Orders are completed from a checkout ID and retain customer, shipping, payment-reference, and product snapshot data.
• Integration settings cover inbound and outbound Catalog event flows supported by the deployment.

Catalog can also be consumed through the Engine REST API and built-in Catalog MCP tools with a merchant API key scoped to the merchant, one store, or selected stores. See the Merchant, Store, Catalog, and Enrichment Guide, Enterprise API Documentation, and MCP Integration Guide.

Enrichment

Enrichment is a separate store workflow with Instant, Jobs, AI Providers, and Usage pages. Providers are configured from the store dashboard, stored at merchant scope, shared only with stores of that merchant, and isolated from realm providers.

Text enrichment requires a provider with text support. Image enrichment requires image support. A single provider may be eligible for both operations. Enrichment usage remains separate from general runtime AI usage even when both use the same provider.

The Enrichment worker API is internal to Manager and the service network. It is not currently part of the customer-facing ACP Engine REST contract.

Manager CLI

Select CLI in the lower-right corner of Manager to inspect the active realm without navigating away from the current page. The CLI is read-only and exposes an allowlisted command set for realm identities, API-key metadata, realm AI providers, MCP, sessions, and usage. Merchant Catalog and Enrichment are managed from merchant/store dashboards and their API surfaces.

See the Manager CLI Guide for commands, resource paths, aliases, and security behavior.

Prompts and Agents

A prompt contains the managed instructions and domain constraints used by an agent. An agent connects that behavior to a provider and the MCP servers it is allowed to use.

Keep prompt responsibilities narrow and testable. Tool permissions belong to the agent and routing configuration, not to prose instructions alone. A prompt saying that a tool must not be called is not a replacement for removing that tool from the agent's allowed set.

Use Agent Profile Routing when callers should not hard-code one agent_id. A rule selects an agent by channel, deployment, required client capabilities, and user segment. Higher priority wins; rules and target agents remain inside the realm. Keep a default realm agent for callers that do not match a specialized rule.

Agent runtime settings enforce execution and dependency concurrency, per-node timeout, bounded retries, retry base delay, orchestration depth, tool-call count, latency, cost, provider region, data-handling mode, retention, and handoff policy. Provider selection scores eligible providers against capability, quality, latency, cost, region, and data-handling requirements. These settings are runtime controls, not documentation-only targets.

When updating a live prompt:

1. Save the new prompt as an inactive version.
2. Preview it with representative inputs.
3. Activate it in the test realm.
4. Run the journey acceptance scenarios.
5. Promote the same reviewed configuration to production.

MCP Servers and Tool Discovery

An MCP server registration contains its display name, URL, connection type, optional server-side credential, and active state. Automatic discovery calls tools/list after the server is saved and stores the returned tool contracts in the realm tool registry.

After registration, confirm that:

• The connection test succeeds.
• Discovery returns the expected tools.
• Tool descriptions explain when the tool should be selected.
• Input schemas mark required values correctly.
• Write tools are disabled unless the target journey needs them.

Manager shows negotiated protocol, probe latency, call error rate, authentication failures, schema freshness, contract status, and approval status. Rediscover after a contract change; drift marks the contract stale and disables the affected tool. AI-assisted classification, tags, argument aliases, output mappings, and synthetic tests remain proposals until an operator approves them. Read-only tools become routable only after contract tests pass; higher-risk tools also require explicit policy approval.

Flows

A Flow is a realm-scoped, versioned capability module. It can represent product discovery, incident triage, employee onboarding, account support, document analysis, or another approved AI use case. It combines a semantic routing manifest, a bounded system-instruction fragment, permissions, tools, output actions, and optional deterministic execution steps. Applications may supply its stable flow_id for explicit execution or omit flow_id so ACP selects an eligible Flow automatically.

Use Generate from goal to produce a reviewable draft from a natural-language outcome. ACP restricts generation to approved realm tools, validates the generated graph deterministically, and includes proposed bindings and a happy-path fixture. If semantic generation is unavailable or invalid, the bounded fallback still produces a valid draft. Drafts stay in pending_approval and cannot execute until an operator approves and saves them as an unpublished flow.

Flows can compose AI decision, AI, MCP tool, MCP resource, condition, transform, parallel, bounded loop, approval, delay, event wait, pinned subflow, supervisor, specialist-agent, compensation, and output nodes. AI Decision selects only from two to twenty declared choices, with a confidence threshold and optional deterministic fallback. An adaptive Supervisor selects only one configured child; it cannot invent another branch. Specialist nodes use isolated context, explicit tool permissions, and tool-call budgets. Compensation nodes are executed in reverse order for registered side effects when a later step fails.

Choose an orchestration mode in the drag-and-drop Flow Builder:

• deterministic preserves the reviewed graph and is the compatibility mode for existing Flows;
• adaptive enables bounded AI decisions and adaptive supervisors;
• hybrid keeps critical operations deterministic while allowing semantic branch selection where appropriate.

For adaptive and hybrid Flows, configure When to use, When not to use, semantic Capabilities, capability-based handoffs, Flow system instructions, completion criteria, allowed ACP actions, and risk tier. Runtime composes only the selected Flow instruction fragment with the realm and Agent system prompt. The visual graph remains server-side.

Use preview before activation. Preview validates the compiled configuration without silently changing the active production journey. Activation publishes the flow, assigns its current version to the public contract, and exposes it to realm-authenticated MCP clients as acp_flow_<normalized_name>_v<version>.

Changing flow configuration creates a draft version. Add deterministic fixtures with mocked AI, tools, resources, and subflows, then run the test action before publishing. Publication compiles an immutable graph, checks input/output compatibility, and rejects unbounded cycles. Activation windows, channel overrides, authenticated event/schedule triggers, rollback, and promotion through development, QA, UAT, and production are available from the Flows surface. Because MCP clients cache tool definitions, rediscover tools/list after publishing or changing a flow and update callers to the new versioned name.

Flow Routing Settings

Use Orchestration → Flow Routing Settings to configure realm rollout policy and inspect automatic selection independently from an immutable published Flow plan. A new adaptive or hybrid Flow can supply its compact semantic manifest directly from Flow Builder. A dedicated routing profile remains available for advanced intents, positive and negative utterance examples, channel and locale constraints, required client capabilities, allowed handoffs, priority, minimum confidence, and fallback behavior. When both exist, the dedicated profile takes precedence.

The realm default active text-capable provider is the Flow classifier. Agent-level providers are resolved only after the Flow has been selected. ACP never silently substitutes another provider when the default is missing, inactive, routing-disabled, or blocked by data-egress policy.

Start a realm at disabled, validate profiles and labeled evaluation data, then use shadow to compare applied and proposed decisions. A passing evaluation is required before enforced; begin with a limited canary percentage. Return to disabled for immediate compatibility rollback. See Automatic Flow Routing for endpoint and session semantics.

Routing Rules

Routing rules add deterministic control when a realm has multiple MCP servers or multiple tools with related purposes. A rule can match an intent, keyword set, tool name, or capability tag and then apply an execution strategy.

Supported strategies exposed by Manager include:

Strategy	Use it when
Tool registry	The discovered registry can select the matching enabled tool.
First healthy server	Equivalent servers exist and availability is more important than a fixed target.
Parallel aggregate	Multiple approved sources should be called and their results combined.
Explicit server	Compliance, data locality, or a business contract requires one server.

Set a timeout and retry count that fit the customer-facing latency budget. Do not retry non-idempotent write tools unless their contract explicitly supports idempotency.

Eligible MCP candidates are scored by health, observed latency, error rate, estimated per-call cost, region, and data-handling compatibility after realm, agent, flow, server, and tool policy intersections pass. Explicit server remains exclusive. Registry and first-healthy strategies use the scored order as an approved fallback chain. Parallel aggregate returns successful results together with bounded per-server failures. Route traces record selected and rejected candidates plus the effective timeout, retries, policy version, region, and data-handling decision.

Sessions and Messages

The Sessions area is useful for controlled runtime tests and support investigations. A session links messages to an Agent and optional pinned Flow while preserving state and metadata. Subject-bound sessions return a signed resume_token; the BFF must retain it and send it whenever the session is resumed.

Use a new session for each independent customer journey. One session may contain multiple product listings and allowed Flow handoffs until completion, cancellation, or expiry. Reuse the same session only when conversation continuity is intended. Never place credentials, full payment data, or unnecessary personal data in session metadata.

Governance, Evaluations, and Production Profiles

The realm Runtime > Governance surface owns versioned deny-by-default policy, maker-checker allowlists, alert rules, integration clients, evaluation datasets and runs, deployment profiles, quotas, customer-approved support access, and lawful-request metadata records. Integration client and webhook secrets are shown once; only hashes and version history remain in the control plane.

Create synthetic or explicitly approved redacted-trace evaluation datasets, approve the dataset, and run offline, shadow, or adversarial evaluations against the exact flow, prompt, model, routing, or tool-schema version. Evaluation runs never execute side effects and never auto-publish a recommendation. When an approved dataset exists, the latest applicable regression result must pass before a flow version can be promoted.

Deployment profiles describe on_premise, hybrid, cloud_shared, or cloud_dedicated ownership, environment, region, residency, retention, key isolation, sub-processors, and deny-by-default egress. Set session transcript retention to none when the customer contract requires zero conversation retention; trace IDs, status, latency, route decisions, and tool metadata remain available without storing the conversation.

MCP credentials must use versioned local encryption or an approved kubernetes://, vault://, or kms:// reference. Credential values are resolved only by the MCP execution worker and are never returned through Manager, API reads, traces, or errors.

Use Credential lifecycle on the realm MCP page to rotate a local key. Manager tests the candidate against the server before activation, retains version metadata and a short overlap for safe cutover, and allows a previous local version to be tested and atomically restored. Managed secret references are rotated in their owning secret backend.

Release Checklist

• Realm membership and service identities follow least privilege.
• Provider and MCP credentials are stored server-side.
• The active prompt and flow have passed representative tests.
• Agent profile routing resolves the expected agent for every supported channel and deployment.
• Agent concurrency, dependency concurrency, timeout, retry, cost, and depth limits fit the journey's service-level objective.
• Generated flow drafts were reviewed by an operator before publication.
• Published flow MCP schemas and versioned tool names match the intended client contract.
• Every routable Flow has a reviewed semantic manifest or dedicated routing profile covering positive, negative, ambiguous, continuation, and handoff behavior for every supported locale.
• Adaptive decisions expose only declared choices, have a reviewed confidence threshold and fallback, and cannot reach undeclared tools, children, or output actions.
• The realm default routing provider is active, text-capable, and allowed by the data-egress policy.
• Shadow decisions and the approved labeled evaluation meet the routing accuracy, high-risk safety, latency, and cost gates before enforced rollout.
• Tool discovery is current and write tools are intentionally enabled.
• Routing preview selects the expected server and tool.
• A runtime session completes with a trace ID.
• Usage records appear for the test interaction.
• Rollback identifiers for the previous prompt, flow, and provider are recorded.