Deployment Invoke and AG-UI¶

POST /v1/deployments/{deploymentId}:invoke invokes a Production application. It requires an ordinary virtual key with deployment.invoke, Team/key deployment allowance, and its actual user/service owner in the deployment's API caller grants. An invoke-only key may deny direct model/tool calls. Managed children use separate execution access funded by the publisher Team.

Request¶

Working directory: any client directory. Save the real caller key in MC_VIRTUAL_KEY; the IDs below are fictional.

curl --no-buffer --fail-with-body \
  --request POST \
  --header "Authorization: Bearer $MC_VIRTUAL_KEY" \
  --header "Content-Type: application/json" \
  --header "Accept: text/event-stream" \
  --data '{"threadId":"conversation_42","runId":"client_run_1","messages":[{"id":"message_1","role":"user","content":"Hello"}]}' \
  https://gateway.example.test/v1/deployments/deployment_example:invoke

The strict body is AG-UI RunAgentInput plus optional customer:{subject}. A backend customer label requires the actual entry key's authorized customer namespace/assertion/provisioning policy. It cannot choose a namespace, person, payer, execution key or definition. Public Preview mode headers and the former Agent invocation route are unsupported.

threadId is a client conversation label. runId is protocol vocabulary only and participates in request identity; it does not create a Mission Control Run resource. The gateway supplies X-Mission-Control-Trace-Id and correlation evidence. New caller messages must be user messages; caller tools/state never become execution authority.

Stream, approval and stop¶

The response is AG-UI SSE. RUN_STARTED, message/tool events and RUN_FINISHED/RUN_ERROR retain their protocol names. The database's Chat tables retain bounded authoritative messages and execution state; they do not treat an uploaded span as private history. RUN_FINISHED alone is not proof of physical termination: the driver settles on confirmed EOF. Disconnect, idle timeout or incomplete delivery records uncertainty and retains admission until confirmation/recovery.

Resume uses the same thread, a new client run ID and all pending interrupts:

{"threadId":"conversation_42","runId":"client_run_2","messages":[],"resume":[{"interruptId":"interrupt_example","status":"resolved","payload":{"approved":true}}]}

A declined resolution uses approved:false; cancellation has no dispatch capability. Consent binds the exact stored context, source turn, tool-call identity, schema and argument hash. It is consumed atomically with the physical ledger claim. Pre-dispatch preparation failure does not consume it; possible dispatch never restores it. Backend-key consent is recorded as backend provenance, not a verified human.

The logical managed root and original funding survive supported approval resume. Each runtime turn receives a fresh short-lived proof. Stop means aborting the HTTP stream; reconcile uncertainty before a new attempt. Managed per-round output is bounded at 4,096 tokens, not a whole-conversation token allowance.

Private Console boundary¶

Console uses actual signed user sessions on the control listener at /internal/deployments/{id}/invoke/chat, /preview or /production_test. The latter two suffixes share that same prefix. These fixed-purpose routes are not public credentials or mode switches. The gateway rechecks actual session/member/audience/test permission and assembles trusted history. Private bodies do not accept customer labels. The Console accepts at most 256 KiB of valid UTF-8 request data, stops reading when that limit is exceeded, and rejects invalid input with 400 invalid_request before forwarding.

A process-local ceiling allows 30 managed invocation requests per minute per private Organization/user or public Organization/key/trusted-thread-owner bucket. Exhaustion is 429 rate_limited with Retry-After: 60, before another runtime dispatch. Hierarchical budgets apply independently.

Delete a private Console conversation¶

An authenticated browser can delete its own idle stored conversation through:

DELETE /api/chat/deployments/{deploymentId}/threads?organizationSlug=example&kind=chat&threadId=conversation_42

This is a Console browser-session endpoint, not a public virtual-key or management-token API. Supply exactly one nonempty organizationSlug, kind (chat or test) and threadId, with no payload bytes or other query parameters. An empty transport stream is accepted as bodyless; a declared payload or the first actual payload byte is rejected with 400 invalid_delete_target without buffering the request body. test covers Preview and production-test history. The required Origin must match the configured Console APP_URL origin; forwarded/request host values do not grant trust. Browsers supply that header automatically.

For example, from a page on https://console.example.test after signing in:

const response = await fetch(
  "/api/chat/deployments/deployment_example/threads?organizationSlug=example&kind=chat&threadId=conversation_42",
  { method: "DELETE" },
);
if (response.status === 204) {
  // Remove this conversation from the displayed private history.
}

The server derives the exact user and Organization-membership owner from the current session and checks deployment and history kind. There is no caller-supplied owner. Losing audience or runtime access does not prevent deletion of otherwise eligible owned history; losing Organization membership does. Idle eligibility and deletion are checked together in an application-store transaction. Preparing, running, awaiting-approval and unreconciled uncertain work cannot be deleted. Applied lifecycle recovery can make historical indeterminate turns eligible without erasing their financial evidence.

Result	Meaning and recovery
`204`	Private conversation, stored messages and application execution records deleted. Financial and trace evidence remains.
`400 invalid_delete_target`	Missing, duplicate, unknown or invalid target parameters, or a request body. Correct the target shape.
`403 origin_mismatch`	Missing or incorrect browser origin. Use the configured Console.
`404 history_unavailable`	The current session cannot access that exact owned conversation. Sign in with its original active Organization membership.
`409 conversation_not_idle`	Work is active, preparing or unresolved. Refresh after lifecycle settlement/recovery; do not infer completion from Stop.
`503 delete_unavailable`	Deletion could not be confirmed. Refresh history before retrying.

Verification and recovery¶

A successful request produces canonical entry evidence and separately metered children. The wrapper adds no duplicate cost. Requests and runtime spans may share W3C context without opening or closing a Trace lifecycle resource.

For 403, inspect current key policy, actual owner grant and deployment state. For 409, reconcile the thread/revision before retrying. Missing runtime or unknown delivery must not be treated as a successful completion. Historical private reads require current Organization membership and exact ownership; new invocation/resume also rechecks current audience and policy.

See embed an application, namespaces, Chat, and errors.