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. Both gate every subsequent read endpoint on this conversation: peers in the same company cannot see each other’s conversations, runs, or messages. Cross-user access surfaces as 404 — the API does not distinguish “doesn’t exist” from “owned by another user”.

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",
      "description": "Narrative docs MCP server"
    }]
  }
}

Example: conversation with a caller-declared tool (human in the loop)

Caller-declared 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. These tools have no alias — the model sees the bare name, and the platform routes any dash-free tool call to caller-declared resolution.

{
  "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" } }
    },
    "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.