---
title: "Create agent conversation with streaming response"
method: POST
path: "/agents/{agentKey}/conversations/stream"
tags: ["Agents"]
---

# Create agent conversation with streaming response

`POST /agents/{agentKey}/conversations/stream`

Start a new conversation with the specified agent and stream the AI
response as Server-Sent Events (SSE). The first user message is saved
and forwarded to the upstream agent backend; subsequent tokens, tool
calls, and lifecycle events are emitted on the open SSE connection.

## Path parameters

- `agentKey` string, required

## Request body

- AgentStreamCreateConversationRequest — Request body for `POST /agents/{agentKey}/conversations/stream`. Only `query` is required; all other fields are optional overrides or routing hints. Unknown fields are stripped during validation.
  - `query` string, required — User prompt for the first turn. Saved as the initial `user_query` message and sent to the agent backend.
  - `recordIds` string[] — Optional record ids to include as context for this turn. Each id must be a 24-character MongoDB ObjectId.
  - `filters` Filters — App connector instance ids and knowledge-base / record-group ids that narrow retrieval for a turn. For **org assistant** chat streams, send explicit `apps` / `kb` lists. For **agent** chat streams, send explicit id lists, or **omit** `filters` (and `tools`) to let the service use the agent’s stored knowledge and tool configuration. Sending `{ "apps": [], "kb": [] }` on an agent stream means **no** knowledge sources for that turn (it is not “full org default”).
    - `apps` string[] — Connector instance ids to scope retrieval for this turn. Each element must be a UUID (connector instance id, record-group id, etc.) or the org knowledge-base collection sentinel `knowledgeBase_<orgId>` (pattern `knowledgeBase_[a-zA-Z0-9_-]+`). Gateway validation matches Zod `appOrKbIdSchema`.
    - `kb` string[] — Knowledge-base / record-group ids to scope retrieval for this turn. Each element uses the same accepted formats as `apps`: a UUID or `knowledgeBase_<orgId>` (pattern `knowledgeBase_[a-zA-Z0-9_-]+`).
  - `appliedFilters` AppliedFilters — Rich filter state selected by the user, used for display and persistence only. This mirrors the active selection shown in the UI and is distinct from the machine-readable `filters` field used for retrieval scoping.
    - `apps` AppliedFilterNode[] — Applied app/connector filter nodes
      - `id` string — Unique identifier of the filter node
      - `name` string — Display name of the filter node
      - `nodeType` string — Type of the node (e.g. app, recordGroup, folder, record)
      - `connector` string — Connector identifier associated with this node
    - `kb` AppliedFilterNode[] — Applied knowledge-base filter nodes
      - `id` string — Unique identifier of the filter node
      - `name` string — Display name of the filter node
      - `nodeType` string — Type of the node (e.g. app, recordGroup, folder, record)
      - `connector` string — Connector identifier associated with this node
  - `attachments` ChatAttachmentRef[] — Uploaded attachments to ground this turn. Each entry references a record id returned from the agent attachment upload endpoint.
    - `recordId` string, required — Attachment record id returned from the upload endpoint.
    - `recordName` string — Original display name of the file when known.
    - `mimeType` string — MIME type of the uploaded file.
    - `extension` string — File extension (e.g. `pdf`).
    - `virtualRecordId` string — Optional synthetic record id used by the graph layer.
  - `chatMode` 'auto' | 'quick' | 'verification' | 'deep' — Chat mode hint forwarded to the agent backend. - `auto` lets the agent pick its default strategy. - `quick` favors low-latency answers over depth. - `verification` runs additional grounding/verification passes. - `deep` performs deeper retrieval and reasoning.
  - `modelKey` string — AI model configuration id for this turn. Omit to use the agent's default model.
  - `modelName` string — Provider model name (the underlying LLM identifier).
  - `modelFriendlyName` string — Friendly UI label for the selected model.
  - `timezone` string — Client IANA timezone, such as `America/New_York`. Helps the agent resolve relative date references in the prompt.
  - `currentTime` string, date-time — Client time in ISO 8601 / RFC 3339 format (UTC `Z` or numeric offset). Sent alongside `timezone` for time-aware answers.
  - `tools` string[] — Allowed tool ids for this turn, such as `jira.create_issue`. Omit to let the agent use its default toolset; send `[]` to disable tools for this turn.

## Response `200`

SSE stream (text/event-stream)

## Other responses

- `400` — Invalid request body
- `401` — Unauthorized

---

[API](https://skmtc.net/pipeshub-ai/apis/pipeshub-api.md) · [All operations](https://skmtc.net/pipeshub-ai/apis/pipeshub-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/pipeshub-ai/pipeshub-api/versions/abd27cfefc73/schema)