Runtime Resource Lifecycle

ACP Engine runtime behavior is assembled from realm-scoped resources. Understanding how those resources depend on one another makes deployments easier to test, promote, and troubleshoot.

Resource Map

The realm is the runtime isolation boundary. An organization may group multiple realms and define default-realm and switch metadata, but authorization is still evaluated independently for every realm. IDs from one realm must not be mixed with resources from another realm, even when names look identical.

Create

Create resources from the outside in:

1. Create identities and credentials.
2. Create the provider, prompt, and MCP server registrations.
3. Discover MCP tools.
4. Create the agent that references those resources.
5. Create the flow that references the agent and journey configuration, or generate a bounded draft and approve it in Manager.
6. Create routing rules if discovery alone is not sufficient.
7. Add agent profile rules when channel, capability, segment, or deployment should select an agent automatically.

Store returned IDs as environment-specific configuration. Names are useful for people, but API clients should use stable resource IDs.

Validate

Validation should prove both configuration correctness and business behavior.

• Provider validation proves the model endpoint and credential work.
• MCP connection testing proves network and authentication reachability.
• Tool discovery proves contracts are readable; probe, contract test, and approval prove they are eligible to be enabled.
• Flow fixtures and preview prove references and deterministic branches resolve before publication.
• Routing preview proves an intent resolves to the expected tool path.
• A test session proves the complete runtime path and produces trace evidence.

A successful health endpoint alone does not prove that a customer journey is ready.

Activate

Activation makes a configured resource eligible for runtime selection. Activate dependencies before activating the flow that uses them.

For production changes, record the previous active resource IDs. This creates a fast rollback path without editing the new resource under pressure.

Execute

Conversational applications normally use POST /api/v1/runtime/ai/chat; structured sync/async integrations use POST /api/v1/runtime/execute. Both use the same automatic/explicit Flow resolver. Omit flow_id for automatic intent routing, or supply it to force one validated Flow. Structured execution accepts input plus optional agent_id, flow_id, session_id, conditional resume_token, channel, client capabilities, safe metadata, deadline, and idempotency key. When agent_id is omitted from structured execution, ACP Engine resolves the highest-priority matching agent profile and falls back to the realm default agent.

The client should interpret the action rather than infer UI behavior from free-form text. Commerce actions include product and variant selection, cart updates, order summaries, and checkout handoff. Cart and checkout identifiers are stored as typed realm session state and are references, never authorization grants. ACP does not execute payment; a separate Payment MCP may consume the checkout handoff in a later delivery track.

When execution pauses for approval or an external event, ACP persists the exact node checkpoint. Approval returns a signed short-lived resume token; approve, deny, amend, expire, cancel, event signal, and asynchronous handoff operations do not require the original HTTP request to remain open.

The same orchestration boundary is used by direct public MCP tool execution. Active published flows are listed as versioned MCP tools, so MCP callers receive the flow's declared schema and still pass through realm authentication, policy, approvals, reliability controls, usage, and trace recording.

Reliability and Compensation

Agent policy bounds maximum concurrency, dependency concurrency, per-node timeout, retry count, base retry delay, orchestration depth, tool calls, latency, and cost. Retryable dependency failures use bounded exponential backoff with jitter. Repeated provider or MCP failures open a realm-scoped circuit temporarily, while dependency bulkheads prevent one saturated integration from consuming all execution capacity.

Do not treat retries as safe for every write. A multi-step write flow should declare compensation for reversible effects and use an idempotency key at the execution boundary. If a later node fails, registered compensations run in reverse order and their state is retained with the durable execution record.

Observe

The runtime pins the active realm policy version when an execution is queued. Effective tool permission is the intersection of realm policy, authenticated agent, active flow, enabled MCP server, approved discovered tool, and request restrictions. A policy change is re-evaluated before any side effect. Safe read-only MCP results may be cached only with realm, tool, normalized arguments, policy version, and freshness in the cache key.

For zero-retention sessions, set transcript_retention to false at session creation or select none in Manager. User and assistant messages are not written, while execution status, trace correlation, route decisions, tool metadata, usage, and administrative audit evidence remain available.

New sessions are subject-bound and return both session_id and resume_token. The token is required to resume the session through chat, structured execute, completion, cancellation, or routing reset. Keep it in protected BFF/server state. Complete successful journeys with /runtime/sessions/:session_id/complete, cancel abandoned journeys with /cancel, and use /reset only for a deliberate new routing decision in an active session.

Capture these identifiers for every production interaction:

Identifier	Purpose
realm_id	Identifies the tenant boundary.
agent_id	Identifies the runtime assistant configuration.
flow_id	Identifies the customer journey.
session_id	Groups related messages and state.
routing.decision_id	Identifies the durable automatic, explicit, shadow, fallback, clarification, or handoff decision.
trace_id	Correlates runtime, provider, and tool activity.
execution_id	Identifies the durable execution for status, events, retry, resume, cancellation, approval, and action replay.

Use usage summaries for capacity and cost analysis. Use trace records for a single execution path. Avoid logging raw prompts or tool results unless the approved data policy explicitly allows it.

Change and Roll Back

Treat prompts, Flow semantic manifests, Flow behavior fragments, visual graphs, Flow routing profiles, realm routing policy, provider settings, Agent profile rules, and MCP tool-routing rules as versioned operational configuration. Existing deterministic Flows remain compatible. Adaptive and hybrid Flows must version their bounded choices, confidence thresholds, fallbacks, allowed actions, and capability-based handoffs with the published Flow.

1. Create or update the candidate configuration in a test realm.
2. Run the same acceptance set used for the current production version.
3. Activate the candidate during a controlled change window.
4. Monitor errors, latency, tool selection, and cost.
5. Reactivate the previous known-good resources if acceptance thresholds fail.

Do not delete the previous version until the rollback window closes.

Automatic Flow routing has an immediate compatibility rollback: set the realm routing mode to disabled. shadow records an automatic proposal while executing compatibility selection; enforced executes automatic decisions for the configured canary percentage after a passing evaluation. See Automatic Flow Routing.

Changing a Flow from deterministic to adaptive or hybrid is a reviewed runtime behavior change, even though /runtime/ai/chat and /runtime/execute do not change. Test and publish a new immutable Flow version. Roll back to the previous published version if decision accuracy, fallback behavior, output permissions, latency, or cost misses its acceptance gate.

Retire

Before deleting or disabling a resource, find its dependents. A provider, prompt, or MCP server can still be referenced by an agent; an agent can still be referenced by a flow; and a flow can still be used by an application configuration.

Prefer disable, observe, and then delete. Revoke credentials immediately when a service identity or external integration is retired.