---
title: "Run Conversation Turn (Stream)"
method: POST
path: "/v1/agents/{agent_id}/conversations/invoke/stream"
tags: ["API v1", "Agents", "Agent Conversations"]
---

# Run Conversation Turn (Stream)

`POST /v1/agents/{agent_id}/conversations/invoke/stream`

## Request

- Base URL: `https://api.xpander.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.xpander.ai/v1/agents/{agent_id}/conversations/invoke/stream`
- Auth: API key in header `x-api-key`

Run one turn and stream every event over SSE: the head's `task_created` (its id is the conversation id), the task's `task_created`, the task's chunks, tool calls, plans and cards, then one `task_finished` for the head carrying the answer. Pass `id` = conversation_id to continue a conversation.

## Path parameters

- `agent_id` string, required

## Query parameters

- `version` string, nullable: Agent version to run.
- `sub_tasks` 'sync' | 'async' | 'auto'

## Request body

- AgentExecutionRequest
  - `input` AgentExecutionInputInput, required
    - `text` string, nullable
    - `files` string[], nullable
    - `attachments` AttachmentRef[], nullable
      - `url` string, required
      - `name` string, nullable
      - `mime` string, nullable
      - `size` integer, nullable
      - `kind` 'image' | 'pdf' | 'document' | 'text' | 'audio' | 'video' | 'archive' | 'unknown': Coarse attachment class, resolved from mime/magic/extension. Mirrored in xpander-sdk (models/task.py + models/generic-adjacent); keep the members identical.
      - `sha256` string, nullable
      - `expires_at` string, nullable
      - `source` string, nullable
      - `transcript` string, nullable
    - `user` UserInput: Represents the details of a user. Attributes: id (Optional[str]): The unique identifier of the user. Defaults to None. first_name (Optional[str]): The first name of the user. Defaults to None. last_name (Optional[str]): The last name of the user. Defaults to None. email (str): The email address of the user. This field is required. additional_attributes (Optional[dict]): Possible additional parameters for the assistant's service. role (Optional[str]): The user's role in the organization. Defaults to "member". is_super_admin (Optional[bool]): Whether the user is a super admin. Defaults to False. timezone (Optional[str]): The user's timezone in IANA format (e.g. "America/New_York"). Defaults to None.
      - `id` string, nullable
      - `first_name` string, nullable
      - `last_name` string, nullable
      - `email` string, required
      - `additional_attributes` object, nullable
      - `role` string, nullable
      - `is_super_admin` boolean, nullable
      - `timezone` string, nullable
    - `principal` Principal: Typed caller identity: who invoked the run and through which door.
      - `kind` 'user' | 'slack' | 'api_key' | 'system' | 'anonymous', required
      - `id` string, required
      - `email` string, nullable
      - `display_name` string, nullable
    - `from_agent_id` string, nullable
    - `from_agent_name` string, nullable
  - `id` string, nullable
  - `minted_conversation_id` boolean, nullable
  - `normalized_id_fields` string[], nullable
  - `payload_extension` object, nullable
  - `parent_execution_id` string, nullable
  - `worker_id` string, nullable
  - `source` string, nullable
  - `output_format` 'text' | 'markdown' | 'json' | 'voice'
  - `output_schema` object, nullable
  - `run_locally` boolean, nullable
  - `additional_context` string, nullable
  - `instructions_override` string, nullable
  - `test_run_node_id` string, nullable
  - `expected_output` string, nullable
  - `engagement_instructions` string, nullable: Channel engagement-rule action prompts for this turn, rendered into the gateway system context in addition to the agent's instructions.
  - `output_format_instructions` string, nullable: Channel-binding output-format text for this turn, rendered into the gateway system context in addition to the agent's instructions.
  - `events_streaming` boolean, nullable
  - `mcp_servers` object[], nullable
  - `triggering_agent_id` string, nullable
  - `title` string, nullable
  - `think_mode` 'default' | 'harder'
  - `disable_attachment_injection` boolean, nullable
  - `user_tokens` object, nullable
  - `user_oidc_token` string, nullable
  - `return_metrics` boolean, nullable
  - `llm_model_provider` string, nullable: Per-execution override for the LLM provider (e.g. 'openai', 'anthropic'). Falls back to the agent's configured provider when unset.
  - `llm_model_name` string, nullable: Per-execution override for the LLM model name. Falls back to the agent's configured model when unset.
  - `llm_reasoning_effort` 'low' | 'medium' | 'high' | 'xhigh'
  - `harness_cli` 'claude-code' | 'codex' | 'opencode' | 'xpander': A CLI the harness container can run; chosen per conversation, never per agent.
  - `permission_mode` 'full' | 'gated'
  - `builtin_tools` HarnessBuiltinTools: The CLI's own built-in tools (`harness`) and the platform's tools (`xpander`); a missing half stays on.
    - `harness` HarnessBuiltinToggle: One built-in tool set switched on or off; None leaves the decision to the next layer down.
      - `enabled` boolean, nullable
    - `xpander` HarnessBuiltinToggle: One built-in tool set switched on or off; None leaves the decision to the next layer down.
      - `enabled` boolean, nullable
  - `tool_call_limit` integer, nullable: Max tool calls for this execution. The budget belongs to the work, not the agent: a scheduled run knows how much it is worth. Falls back to the agent's setting when unset.
  - `source_node_type` 'workbench' | 'sdk' | 'task' | 'assistant' | 'webhook' | 'mcp' | 'a2a' | 'telegram' | 'slack' | 'whatsapp' | 'ms-teams' | 'email' | 'api'
  - `is_app` boolean, nullable
  - `verified_user_transport` string, nullable: Transport that VERIFIED input.user this turn ('chat' = Bearer session, 'mcp' = OAuth). Set only by the services that resolved the user themselves and stripped from caller-supplied bodies; downstream consent gates key off it.
  - `is_steering` boolean, nullable
  - `sub_tasks_mode` 'sync' | 'async' | 'auto'
  - `channel_session` ChannelSessionRef: Names the (channel, external key) whose standing conversation this turn belongs to.
    - `channel` string, required
    - `channel_key` string
    - `adopt_conversation_id` string, nullable
  - `channel_context` string, nullable: Pre-rendered cross-channel recency block for channel turns; the gateway appends it to the turn's context verbatim.
  - `thread_context` string, nullable: Pre-rendered history of the channel thread this turn arrived in; the gateway appends it to the turn's context, and it never becomes part of the user's message.
  - `attachment_context` string, nullable: Pre-rendered text a channel extracted from this message's attachments and links (OCR, transcripts, fetched pages, readable files); the gateway appends it to the turn's context, and it never becomes part of the user's message.

## Response `200`

Successful Response

- unknown

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/xpander/apis/xpander-ai-api-service.md) - [All operations](https://skmtc.dev/xpander/apis/xpander-ai-api-service/llms.txt) - [OpenAPI document](https://skmtc.dev/xpander/apis/xpander-ai-api-service/revisions/725c0066d5df?raw)