Tools: conversations
9 tool(s) in this category.
conversation.get
Get Conversation
Fetch a single agent conversation by UUID along with its ordered turns (agent runs). Use when rendering chat history for a specific thread, resuming UI state after navigation, or auditing exactly what happened across every turn. Returns null when the conversation does not exist or belongs to a different business.
- HTTP:
GET /conversations/:id - Required scopes:
workflows:read - Required role:
viewer - Stability:
stable - Version:
1.0
Input
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes |
conversation.list
List Conversations
List agent conversations for this business, newest activity first. Use when rendering recent chat threads, a picker UI, or an audit view. Filter by status (active|archived) or profile_id; paginate via limit + offset.
- HTTP:
GET /conversations - Required scopes:
workflows:read - Required role:
viewer - Stability:
stable - Version:
1.0
Input
| Field | Type | Required | Description |
|---|---|---|---|
status | `enum("active" | "archived")` | no |
profile_id | string | no | |
limit | integer | no | |
offset | integer | no |
conversations.create
Create Conversation
Create a new chat conversation pinned to an agent profile. Use when starting a new multi-turn session with a specific profile (copilot, researcher, etc.). If first_turn_message is supplied, the first turn is enqueued immediately and turn_id is returned. The pinned profile is immutable and governs every subsequent turn.
- HTTP:
POST /conversations - Required scopes:
conversations:write - Required role:
editor - Stability:
stable - Version:
1.0 - Tags:
conversations,write
Input
| Field | Type | Required | Description |
|---|---|---|---|
profile_id | string | yes | Registered agent profile id (e.g. copilot). |
title | string | no | Optional initial title. If omitted, may be auto-generated post-first-turn. |
input_params | object | no | Structured creation-time params forwarded into every run. |
first_turn_message | string | no | Optional first user turn. When supplied, a run is enqueued immediately. |
conversations.turns.append
Append Conversation Turn
Append a new user message to an active conversation. Use when continuing an existing chat thread instead of starting a new one. Creates a new agent run, enqueues it for the pinned profile, and returns the turn id. The conversation must be in status=active; archived conversations reject new turns.
- HTTP:
POST /conversations/:id/turns - Required scopes:
conversations:write - Required role:
editor - Stability:
stable - Version:
1.0 - Tags:
conversations,write
Input
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | Conversation UUID. |
message | string | yes | User message that kicks off the new turn. |
input_params | object | no | Structured per-turn params. Reserved; the run currently inherits conversation.input_params. |
conversations.turns.cancel
Cancel Conversation Turn
Cancel an in-flight conversation turn. Use when the user hits a stop button on a running chat turn, or wants to abandon a turn that has gone sideways. Cascades to any sub-agents spawned from this turn — every live descendant is cancelled atomically. Already-completed turns cannot be canceled. The worker stops at the next iteration boundary after observing the status change.
- HTTP:
DELETE /conversations/:id/turns/:turn_id - Required scopes:
conversations:write - Required role:
editor - Stability:
stable - Version:
1.0 - Tags:
conversations,destructive
Input
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | Conversation UUID. |
turn_id | string | yes | Turn (agent run) UUID. |
reason | string | no | Optional operator note describing why the turn was canceled. |
conversations.turns.resume
Resume Conversation Turn
Resume a paused conversation turn with user input. Use when the user responds to a pending-input prompt on a chat turn (outline approval, clarification, continue/finish). The input payload must match the turn's pending_input_schema. Validates that the turn belongs to the claimed conversation before writing.
- HTTP:
POST /conversations/:id/turns/:turn_id/resume - Required scopes:
conversations:write - Required role:
editor - Stability:
stable - Version:
1.0 - Tags:
conversations,write
Input
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | Conversation UUID. |
turn_id | string | yes | Turn (agent run) UUID. |
input | object | yes | Resume payload matching the turns persisted pending_input_schema. |
conversations.update
Update Conversation
Patch a conversation. Use when renaming a chat (title) or archiving it (status=archived). Returns the updated row. The pinned agent profile is immutable and cannot be changed here; create a new conversation if a different profile is required.
- HTTP:
PATCH /conversations/:id - Required scopes:
conversations:write - Required role:
editor - Stability:
stable - Version:
1.0 - Tags:
conversations,write
Input
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | Conversation UUID. |
title | string | no | New title. Non-empty after trim. |
status | `enum("active" | "archived")` | no |
prompts.conversation.conversation_recap
Conversation Recap Prompt
Use when the user asks to recap a specific conversation (what was discussed, what was produced). Directs the agent to read conversation://<id>, walk the turns in order, and output a structured recap with artifacts linked.
- HTTP: (not exposed as REST)
- Required scopes:
workflows:read - Required role:
viewer - Stability:
stable - Version:
1.0 - Tags:
prompt,conversation
Input
| Field | Type | Required | Description |
|---|---|---|---|
conversation_id | string | yes | UUID of the conversation. |
prompts.conversation.resume_work
Resume Work Prompt
Use when the user wants to pick back up a conversation that stopped mid-task or is paused. Directs the agent to read the conversation, diagnose what completed vs what did not, and propose the single next concrete action to take.
- HTTP: (not exposed as REST)
- Required scopes:
workflows:read - Required role:
viewer - Stability:
stable - Version:
1.0 - Tags:
prompt,conversation,resume
Input
| Field | Type | Required | Description |
|---|---|---|---|
conversation_id | string | yes | UUID of the conversation. |