agents.end-user.ask-stream

Ask the app's agent a question and stream the answer token-by-token. Same bounded end-user session as agents.end-user.ask (its tools are exactly the app's exposed compositions, every call re-authorized); the answer also returns in the terminal state.

Streaming twin of agents.end-user.ask.

Identical end-user gate, principal binding, quotas and app-pinned config — the ONLY differences are:

1. PENDING is auto_advance_async so the exposed composition wrapping this step returns its run id to the browser IMMEDIATELY (non-terminal), giving the browser an id to open GET /api/workflows/<id>/stream on before the answer exists. (Synchronous agents.end-user.ask returns the answer inline and cannot be streamed.)
2. It threads the composition run id (this step's parent_workflow_id) down to the runner via the session-launch context, so ai.chat.complete publishes token deltas under the id the browser is streaming — gated on AgentOrgSettings.streaming_enabled.
3. Principal binding is async-safe: because execute runs on the Kafka consumer, metadata['end_user'] is gone, so _resolve_principal falls back to the engine-stamped end_user_uuid column (+ ancestry walk).

The final answer still returns in the terminal state (the composition maps it to state_data.agent.answer); tokens are the live overlay.

Overview

Property	Value
Workflow type	Linear
Library	App-agents
Version	1.0

Input Schema

Field	Type	Required	Default	Description
organization_uuid	string	Yes	—	—
question	string	Yes	—	—
request_id	string	No	—	—
conversation_uuid	string	No	—	Work the continuation grant is scoped to; defaults to identity_app_uuid

Output Schema

Field	Type	Required	Default	Description
answer	string	No	—	—
session_uuid	string	No	—	—
question	string	No	—	—
launch_workflow_id	string	No	—	—
wait_phase	string	No	—	—
launch_deadline_epoch	integer	No	—	—
answer_deadline_epoch	integer	No	—	—
wait_poll_count	integer	No	—	—
request_id	string	No	—	—
conversation_uuid	string	No	—	—
continuation_grant_uuid	string	No	—	—
continuation_issue_workflow_id	string	No	—	—
continuation_redeem_workflow_id	string	No	—	—
continuation_token	string	No	—	—
continuation_redeemed	boolean	No	—	—
failure_reason	string	No	—	—
failed_at	string	No	—	—
failed_at_state	string	No	—	—
failed_step	string	No	—	—
failed_layer	integer	No	—	—
error	string	No	—	—
error_type	string	No	—	—
organization_uuid	json	No	—	—

States

State	Initial	Terminal	Success	Auto-advance	Description
pending	Yes	No	—	execute	—
waiting	No	No	—	—	—
completed	No	Yes	Yes	—	—
failed	No	Yes	No	—	—

State Diagram

Transitions

From	Action	To	Description
pending	execute	waiting	—
waiting	poll	waiting	—
waiting	complete	completed	—
* (any state)	fail	failed	—

API Usage

POST /api/workflows/start
Content-Type: application/json

{
  "workflow_type": "agents.end-user.ask-stream",
  "initial_data": {
    "organization_uuid": "value",
    "question": "value"
  }
}