Start conversation
POST /api/conversations
Start a conversation in the local environment.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
agent | AgentBase-Input | yes | — |
workspace | LocalWorkspace-Input | yes | Working directory for agent operations and tool execution |
conversation_id | `string | null` | no |
confirmation_policy | ConfirmationPolicyBase-Input | no | Controls when the conversation will prompt the user before continuing. Defaults to never. |
initial_message | `SendMessageRequest | null` | no |
max_iterations | integer | no | If set, the max number of iterations the agent will run before stopping. This is useful to prevent infinite loops. |
stuck_detection | boolean | no | If true, the conversation will use stuck detection to prevent infinite loops. |
secrets | object | no | Secrets available in the conversation |
tool_module_qualnames | object | no | Mapping of tool names to their module qualnames from the client's registry. These modules will be dynamically imported on the server to register the tools for this conversation. |
plugins | `PluginSource[] | null` | no |
hook_config | `HookConfig-Input | null` | no |
Responses
| Status | Description |
|---|---|
200 | Successful Response |
422 | Validation Error |
Response body
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | Unique conversation ID |
agent | AgentBase-Output | yes | The agent running in the conversation. This is persisted to allow resuming conversations and check agent configuration to handle e.g., tool changes, LLM changes, etc. |
workspace | BaseWorkspace-Output | yes | Workspace used by the agent to execute commands and read/write files. Not the process working directory. |
persistence_dir | `string | null` | no |
max_iterations | integer | no | Maximum number of iterations the agent can perform in a single run. |
stuck_detection | boolean | no | Whether to enable stuck detection for the agent. |
execution_status | ConversationExecutionStatus | no | — |
confirmation_policy | ConfirmationPolicyBase-Output | no | — |
security_analyzer | `SecurityAnalyzerBase-Output | null` | no |
activated_knowledge_skills | string[] | no | List of activated knowledge skills name |
blocked_actions | object | no | Actions blocked by PreToolUse hooks, keyed by action ID |
blocked_messages | object | no | Messages blocked by UserPromptSubmit hooks, keyed by message ID |
stats | ConversationStats-Output | no | Conversation statistics for tracking LLM metrics |
secret_registry | SecretRegistry-Output | no | Registry for handling secrets and sensitive data |
agent_state | object | no | Dictionary for agent-specific runtime state that persists across iterations. Agents can store feature-specific state using string keys. To trigger autosave, always reassign: state.agent_state = {**state.agent_state, key: value}. See https://docs.faheem-code.dev/sdk/guides/convo-persistence#how-state-persistence-works |
title | `string | null` | no |
metrics | `MetricsSnapshot | null` | no |
created_at | string | no | — |
updated_at | string | no | — |
Operation ID: start_conversation_api_conversations_post