Create an agent conversation

Creates a new agent conversation with a pinned system_prompt and a defaults block that every subsequent run inherits. The conversation starts at version: 0 — your first run’s expected_version will be 0.

What this endpoint actually does

1. Validates the defaults block. Failures here (alias regex, duplicate aliases, wire-name length, missing required fields) return 400 immediately — the conversation row is not created on validation failure.
2. Inserts a row in agent_conversations with version = 0, company_id from your bearer token, and the validated defaults serialized as JSONB.
3. Returns the persisted conversation echo.

No workflows are started here. The conversation is a long-lived container; the actual model execution happens later, in POST /agents/conversations/{id}/runs.

What you cannot change later

• system_prompt — pinned for the conversation’s lifetime. If you need a different system prompt, create a new conversation.
• company_id / user_id — derived from the bearer token at creation time; not exposed in the request body.

Everything else in defaults (model, max_iterations, tools, etc.) is just a default — any individual run can override any of those fields via config_override on its POST .../runs body. See Agent Conversations Reference for the override semantics.

Permission

agent_conversations resource with write verb. The same permission gates POST .../runs; read is required for the GET endpoints.

Example: minimal “hello world” conversation (no tools)

{
  "name": "hello world",
  "system_prompt": "You are a helpful assistant. Answer concisely.",
  "defaults": {
    "model": "anthropic.claude-opus-4.6",
    "data_plane_id": "f79cbdae-4848-47ca-95e8-69588364d185",
    "execution_cluster": "shared",
    "max_iterations": 3,
    "max_tokens": 1024,
    "temperature": 0.0,
    "output_format_schema": {
      "type": "object",
      "additionalProperties": false,
      "required": ["text"],
      "properties": { "text": { "type": "string" } }
    }
  }
}

Example: conversation that can search the Narrative docs

The mcp_servers entry registers two tools the model can call server-side. The platform handles the JSON-RPC calls to https://docs.narrative.io/mcp transparently.

{
  "name": "docs search",
  "system_prompt": "Use the available tools to look things up before answering.",
  "defaults": {
    "model": "anthropic.claude-opus-4.6",
    "data_plane_id": "f79cbdae-4848-47ca-95e8-69588364d185",
    "execution_cluster": "shared",
    "max_iterations": 8,
    "max_tokens": 2048,
    "temperature": 0.0,
    "output_format_schema": {
      "type": "object",
      "additionalProperties": false,
      "required": ["text"],
      "properties": { "text": { "type": "string" } }
    },
    "mcp_servers": [{
      "alias": "docs",
      "url": "https://docs.narrative.io/mcp",
      "tools": [
        {
          "name": "search_narrative_i_o_knowledge_base",
          "description": "Search the Narrative docs.",
          "input_schema": {
            "type": "object",
            "additionalProperties": false,
            "required": ["query"],
            "properties": { "query": { "type": "string" } }
          }
        }
      ]
    }]
  }
}

Example: conversation with a client-side tool (human in the loop)

client_tools entries cause the model’s call to pause the run with status: requires_action. The caller answers by posting a follow-up run with payload.kind: tool_outputs.

{
  "name": "booking flow",
  "system_prompt": "You are a booking assistant.",
  "defaults": {
    "model": "anthropic.claude-opus-4.6",
    "data_plane_id": "f79cbdae-4848-47ca-95e8-69588364d185",
    "execution_cluster": "shared",
    "max_iterations": 5,
    "output_format_schema": {
      "type": "object",
      "additionalProperties": false,
      "required": ["text"],
      "properties": { "text": { "type": "string" } }
    },
    "client_tools": [{
      "alias": "user",
      "tools": [{
        "name": "confirm_booking",
        "description": "Ask the user to confirm a proposed booking slot.",
        "input_schema": {
          "type": "object",
          "additionalProperties": false,
          "required": ["proposed_slot"],
          "properties": { "proposed_slot": { "type": "string" } }
        }
      }]
    }]
  }
}

Common 400 errors

See Agent Conversations error catalog for the full list.