> ## Documentation Index
> Fetch the complete documentation index at: https://docs.naga.ac/llms.txt
> Use this file to discover all available pages before exploring further.

# Migration to Responses

> Move from Anthropic-style Messages contracts to the recommended Responses API when it makes sense.

Use this migration when you want to keep building on NagaAI but move away from Anthropic-style message blocks to the main `Responses API`.

Stay on `Messages API` if your current Anthropic-compatible tooling already works well and compatibility matters more than a cleaner default surface.

## Mental Model Shift

| Messages                                | Responses                                |
| --------------------------------------- | ---------------------------------------- |
| content blocks                          | typed input/output items                 |
| `tool_use`                              | `function_call`                          |
| `tool_result`                           | `function_call_output`                   |
| `message_start` / `content_block_delta` | semantic Responses events                |
| thinking blocks                         | reasoning items                          |
| repeated message history                | `input` replay or `previous_response_id` |

## When To Stay On Messages

* your app already depends on Anthropic SDK behavior
* your tooling expects content blocks directly
* migration cost is higher than the near-term benefit

## When To Migrate

* you want the recommended primary NagaAI LLM surface
* you are starting a new app or redesigning your current one
* you want one docs path for new feature work

## Field mapping

| Messages field or concept | Responses equivalent                                     |
| ------------------------- | -------------------------------------------------------- |
| `system`                  | `instructions` or a `system` / `developer` input message |
| user text block           | `input_text`                                             |
| image block               | `input_image`                                            |
| document block            | `input_file`                                             |
| `tool_use` block          | `function_call`                                          |
| `tool_result` block       | `function_call_output`                                   |
| thinking block            | `reasoning` item                                         |

## Simple request conversion

```json Messages theme={null}
{
  "model": "claude-sonnet-4.5",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Summarize this document."
        }
      ]
    }
  ]
}
```

```json Responses theme={null}
{
  "model": "claude-sonnet-4.5",
  "input": [
    {
      "type": "message",
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Summarize this document."
        }
      ]
    }
  ]
}
```

## Tool and reasoning notes

* Anthropic `tool_use` and `tool_result` blocks map to `function_call` and `function_call_output`
* visible thinking maps to `reasoning` items and Responses reasoning events
* if you preserve reasoning continuity across turns, replay reasoning payloads unchanged

## Next steps

* [Responses API](/api/responses)
* [Responses Streaming](/api/responses/streaming)
* [Responses Tool Calling](/api/responses/tool-calling)
* [Messages API](/api/messages)