Create an objective and stream its events
Creates an objective and streams its events over server-sent events (SSE) on the same connection, so a single request both starts the work and shows it happening. The request body is identical to Create objective, except that metadata.externalId is REQUIRED (it is this endpoint’s idempotency key) and the stream-only includeDeltas flag is accepted. Repeating the request with an externalId that already exists in the workspace does not start a second objective — it attaches to the existing one and streams, resuming from Last-Event-ID when the header is present and from the current moment when it is not. (Create objective instead rejects a duplicate externalId with AlreadyExists.) That makes the endpoint safe to retry, so an SDK’s automatic SSE reconnect resumes the objective rather than launching another. Each message is tagged by type: the first is always objective, carrying the objective and its ID, and every message after it is an event identical to what Stream objective events yields — including transient hb_ heartbeats, and dlt_ text deltas when includeDeltas is set.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
"workspace_01HXKD2E5NQM3T9AYWCF133E3Q"
Body
The request body for creating an objective and streaming its events.
Accepts everything Create objective accepts, and additionally requires
metadata.externalId, which is the idempotency key for the stream, and
accepts the stream-only includeDeltas flag.
"agent_01HXKD2E5NQM3T9AYWCFMGWT9Y"
Required here, though Create objective leaves it optional: the external ID inside it is the idempotency key that makes a retry of this request resume the objective instead of starting another.
Optional explicit variation selection. Overrides the agent's variation_selection_mode.
"agentvar_01HXKD2E5NQM3T9AYWCF32BSPP"
Arbitrary data rendered into the selected variation's system_prompt_template (liquid) to produce the objective's system prompt. If the agent has a system_prompt_data_schema, this must satisfy it.
Optional explicit first user message for the LLM chat history. When not set, the selected variation's first_user_message_template is rendered with first_user_message_data instead. If neither this field nor a first_user_message_template is present, the request is rejected with InvalidArgument.
Secrets that can be used in the headers for tool calls using the secret interpolation format.
Memory layers/entries layered over the baseline cascade inherited from the selected variation — element-level rules over inherited styles, in CSS terms.
Array order is resolution order: EARLIER elements are more specific and are consulted first. Entries pinned via memory_entry_id behave as single-entry layers at their position.
System-managed layers (e.g., episodic) cannot be referenced here; they attach themselves automatically based on the episodic key.
Size cap: the TOTAL effective cascade (this field + the variation's memory layer assignments) must not exceed 10 entries. A request that would produce a larger cascade is rejected with InvalidArgument.
Arbitrary data rendered into the selected variation's first_user_message_template
(liquid) to produce the first user message. Separate from system_prompt_data,
which renders the system prompt template.
If the agent variation that is selected has episodic memory enabled, then this key is used to create/update a memory layer specific to the episodic memory. The layer may have a TTL configured by the variation.
Optional tenant assertion — the customer's org/company identifier for the end user this objective serves. Upserts the tenant record in the workspace and associates the objective with it.
Optional subject assertion — the person within the tenant this objective
serves. Requires tenant; a subject asserted without a tenant is
rejected with InvalidArgument.
Parameters forced onto this objective's tool calls. A pinned parameter is removed from the tool schema the LLM sees, and its value is always overwritten server-side with the pinned value — the model cannot choose a different value for it. By default a pinned key applies to every tool with a top-level parameter of the same name; a tool set's overlays (ToolSetSpec.overlays) can bind pinned keys to nested paths, differently named parameters, or a subset of tools.
Tools the caller defines and executes for this objective. Each definition is upserted into the agent's client tools tool set, and only the definitions listed here are loaded into this objective, always in its context window. A client tool replaces a variation tool with the same function name.
Also stream transient assistantMessageDelta and reasoningDelta events: text fragments as the model generates them, ahead of the durable assistantMessage and reasoning events. Off by default. Applies only to the stream, so Create objective has no equivalent field.
Response
A stream of Server-Sent Events
- Option 1
- Option 2
One message on the create-and-stream feed. The first message is always
the objective variant, sent as soon as the objective exists; every
message after it is an event.