Invocations

AN AGENT AND A WORKFLOW ARE THE SAME ROUTE, and differ in two fields

There is no separate endpoint and no kind to send. An AGENT gets its instruction in text. A WORKFLOW gets its launch inputs in inputs — and text is still required, as a readable one-liner rather than a prompt, because a run's title in any list is projected out of it. Sending inputs to an agent is accepted and ignored; omitting them for a workflow is not.

You never send nulls — an omitted input is filled from its default

Every declared input always resolves to a value in session state, because an OPTIONAL input is refused at manifest time unless it declares a default. So omit what you have no value for: an explicit null is treated identically. The reason it works that way is that a node reads its parameters out of session state, where a missing key RAISES rather than arriving as None — a hazard the platform closes at build time rather than pushing onto you. node_input is a reserved name and cannot be a declared input.

SENDING SOME INPUTS AND SENDING NONE ARE DIFFERENT MODES

Supply any inputs and requiredness is enforced: a missing one fails the run with input 'headcount' is required. Supply NO inputs and it is a FREE-TEXT launch instead — requiredness is not enforced, only defaulted inputs reach state, and each node's own Python default covers the rest. That is what keeps scripts and pre-declaration callers working, and it means a half-filled form is stricter than an empty one.

inputs is passed through unvalidated, and validated in the pod

rt-service holds no manifests by design, so a wrong or missing input is not a 422 here — the run starts, the runtime checks them against the declaration and names the offending field on the event stream. Watch the run to see it.

Which one is a workflow? manifest.kind, on GET /v1/agents

That route, on the Projects page, reports each target's manifest.kind and, for a workflow, manifest.input_names — its declared inputs by name. Their types, defaults and requiredness are served by no route; they are in the manifest you wrote.

state_delta seeds THIS conversation's state, on this turn

It is ADK's own run_async(state_delta=...): the keys are written on the run's own user event, so the agent reads them from the first model call and they stay in the conversation afterwards. Conversation keys only — app: reaches every user of the agent, user: every conversation of that user, temp: is never kept and agentkit: is the platform's — so each is refused with a 400 naming the key. 64 KiB serialized at most. A key that is also one of a WORKFLOW's launch inputs is refused too, but by the runtime, which holds the manifest — so that one arrives as an error event on the stream rather than as a 400. Pass it in inputs.

run_config is an allowlist of two

max_llm_calls can only LOWER the agent's own limit — the lower of the two applies, because that limit is the agent author's bound on what a run may cost. custom_metadata is merged by ADK into every event the run emits, live and stored, at payload.custom_metadata — the event's own keys win. Anything else is refused by name: streaming_mode because partial events would multiply what is published and billed per run, and the rest because they configure ADK's live audio sessions, which a queued run is not.

An agent deployed before these options must be redeployed once

An invocation with neither is byte-for-byte what it always was. One carrying either reaches an agent image that predates them as a message it cannot parse, which is dead-lettered: your socket sees queued and then nothing. Redeploy the agent and it accepts both.

end_user_id sends the events somewhere else

Naming one addresses the run's events to that person, so your own socket receives NOTHING for a run you started on their behalf — their browser watches it with a ticket. A process that invokes and watches at once will look broken.

Subscribe before you invoke

Events published to a topic with no subscriber are discarded, and the subscription is created when your first socket opens. Invoke first and you lose the reply — on a warm agent, that is the whole run.

ticket takes a ticket or your own token

A browser connects with a ticket from one of the two routes below; a backend can pass its own bearer token as ticket. An event reaches the socket only if its run belongs to the same subject as the credential — so a run started with end_user_id reaches that user's ticket and never your token.

A paused run emits no terminal event

It emits two paused events and no finished one, because the pause IS where it stopped. A reader waiting for a terminal kind waits out its whole timeout. Only one of the two carries interrupt_id — that key is the discriminator.

The stream is live, this is durable

Nothing buffers events for a socket that is not open, so a client that disconnected has lost them. This is the read path — it is also the only one a browser session can authenticate against.

It says that a run paused, not what for

interrupt_id is set while status is paused. Which kind of pause it is — an input, a confirmation, a tool call — is interrupt_kind on the last paused event in events. What the run cost is GET /v1/usage/invocations/{invocation_id} on the Usage page.

status=paused answers "what is waiting on me"

It covers BOTH pause kinds — a tool confirmation and a workflow input. The actions inbox holds only confirmations, so it cannot.

A listed run carries no interrupt

The rows are summaries, without interrupt_id or events. Read a paused run with GET /v1/runs/{invocation_id} to get what it is waiting on.

A ticket may open the socket and do NOTHING else

rt-service refuses a ticket on every HTTP route, including this one — so a ticket cannot invoke, cannot list, cannot decide and cannot mint another. That is a capability which is not expressible rather than a check somebody could forget to write.

So the browser WATCHES and your backend ACTS

The split is the design: your backend starts the run with end_user_id set, the browser watches it with a ticket. If you need the person to approve something, the decision goes through your backend, not from the page holding the ticket.

It is pinned to the origin you name

A ticket presented from any other web origin is refused, which is what makes a leaked one useless. Name the origin the browser will actually connect from, scheme and host.

Needs a tenant admin, and the project matters

Issuing a credential on behalf of your user is an administrative act; a service user with the admin role is the intended caller. The wallet is keyed on (project, end_user_id), so ada in one of your products is not ada in another — and a credential scoped to one project cannot mint a ticket for another's customer. The event stream is keyed on the person, though, not the project: the project a ticket carries does not filter what it receives, so ada's ticket from one project can watch a session ada has in another.

Why there is a second kind of ticket

The socket delivers an event only to the person the run belongs to. An end user's ticket is eu:<id>, and a run you start AS YOURSELF belongs to your own subject — so no end-user ticket can ever watch it. This one carries your own subject. It is what the console's Playground uses: somebody signed in by cookie, talking to their own agent.

Anybody may mint one, and only for themselves

There is no field naming whose: the subject is the verified caller's own, so the ticket reaches nothing your token does not already reach — and less. Like every ticket it is never an admin, is refused on every HTTP route, and cannot mint another.

It is pinned to the origin you name

Presented from any other web origin it is refused at the socket's handshake. Name the origin the browser will actually connect from, scheme and host.

Only a node's request for input

Whatever the run is waiting for, this route publishes its answer as the reply to a node's input request — it does not check the kind of pause. A run paused on a tool confirmation, an approval or a long-running tool call is answered through the Autonomy API instead; resuming one here does not answer it.

payload is for data, not consent

A node that asked for a corrected address, a chosen option or a reference is answered with one. approved, note and decided_by are the service's and cannot be set through it — a decision signed by whoever typed the request body is not signed at all.

A resume is the same invocation

The run keeps its invocation id, so one query over its events reads both halves. It replays the completed prefix without re-running it: zero extra model calls, but the events you already saw arrive again.