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

# Gerenciar conversas

> Armazene o estado da conversa na API MKA1, adicione itens de mensagem e continue um fluxo de resposta sem reenviar todo o histórico.

Use o recurso de Conversas quando você quiser que a API MKA1 mantenha o estado da conversa entre as requisições de Responses.
Isso é útil para chats de múltiplas interações, threads de suporte e fluxos de trabalho onde você deseja buscar ou editar o histórico salvo posteriormente.

## Criar uma conversa

Crie uma conversa primeiro.
Você pode anexar metadados para manter seu próprio contexto de sessão ou roteamento.

<CodeGroup>
  ```bash CLI theme={null}
  mka1 llm conversations create \
    -H 'X-On-Behalf-Of: <end-user-id>' \
    --body '{
      "metadata": {
        "session_id": "web-42",
        "channel": "support"
      }
    }'
  ```

  ```ts MKA1 SDK theme={null}
  import { SDK } from '@meetkai/mka1';

  const mka1 = new SDK({
    bearerAuth: `Bearer ${YOUR_API_KEY}`,
  });

  const conv = await mka1.llm.conversations.create({
    metadata: {
      session_id: 'web-42',
      channel: 'support',
    },
  }, { headers: { 'X-On-Behalf-Of': '<end-user-id>' } });
  ```

  ```ts OpenAI SDK theme={null}
  import OpenAI from 'openai';

  const openai = new OpenAI({
    apiKey: '<mka1-api-key>',
    baseURL: 'https://apigw.mka1.com/api/v1/llm/',
    defaultHeaders: { 'X-On-Behalf-Of': '<end-user-id>' },
  });

  const conv = await openai.conversations.create({
    metadata: {
      session_id: 'web-42',
      channel: 'support',
    },
  });
  ```

  ```csharp C# SDK theme={null}
  using MeetKai.MKA1;
  using MeetKai.MKA1.Types.Components;

  var sdk = new SDK(bearerAuth: "Bearer YOUR_API_KEY");

  var conv = await sdk.Llm.Conversations.CreateAsync(new CreateConversationRequest()
  {
      Metadata = new Dictionary<string, string> { { "session_id", "web-42" } },
  });
  ```

  ```python Python SDK theme={null}
  from mka1 import SDK

  sdk = SDK(bearer_auth="Bearer YOUR_API_KEY")

  conv = sdk.llm.conversations.create(
      metadata={"session_id": "web-42"},
  )
  ```

  ```bash bash theme={null}
  curl https://apigw.mka1.com/api/v1/llm/conversations \
    --request POST \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer <mka1-api-key>' \
    --header 'X-On-Behalf-Of: <end-user-id>' \
    --data '{
      "metadata": {
        "session_id": "web-42",
        "channel": "support"
      }
    }'
  ```
</CodeGroup>

Se sua requisição não estiver vinculada a um usuário final específico, omita `X-On-Behalf-Of`.
Veja o [guia de autenticação](/pt/docs/authentication) para o padrão completo.

## Adicionar itens à conversa

Adicione um ou mais itens com `POST /api/v1/llm/conversations/{conversation_id}/items`.

<CodeGroup>
  ```bash CLI theme={null}
  mka1 llm conversations create-items \
    --conversation-id conv_abc123 \
    --body '{
      "items": [
        {
          "type": "message",
          "role": "user",
          "content": "Summarize the latest support ticket."
        }
      ]
    }'
  ```

  ```ts MKA1 SDK theme={null}
  const items = await mka1.llm.conversations.createItems({
    conversationId: 'conv_abc123',
    createItemsRequest: {
      items: [
        {
          type: 'message',
          role: 'user',
          content: 'Summarize the latest support ticket.',
        },
      ],
    },
  }, { headers: { 'X-On-Behalf-Of': '<end-user-id>' } });
  ```

  ```ts OpenAI SDK theme={null}
  const items = await openai.conversations.items.create('conv_abc123', {
    items: [
      {
        type: 'message',
        role: 'user',
        content: 'Summarize the latest support ticket.',
      },
    ],
  });
  ```

  ```csharp C# SDK theme={null}
  using MeetKai.MKA1;
  using MeetKai.MKA1.Types.Components;

  var sdk = new SDK(bearerAuth: "Bearer YOUR_API_KEY");

  var items = await sdk.Llm.Conversations.CreateItemsAsync("conv_abc123", new CreateItemsRequest()
  {
      Items = new List<Item>
      {
          Item.CreateInputMessage(new InputMessage()
          {
              Role = InputMessageRole.User,
              Content = InputMessageContent1.CreateStr("Summarize the latest support ticket."),
          }),
      },
  });
  ```

  ```python Python SDK theme={null}
  sdk.llm.conversations.create_items(
      conversation_id=conv.id,
      items=[
          {"type": "message", "role": "user", "content": "What is MKA1?"},
          {"type": "message", "role": "assistant", "content": "MKA1 is an AI platform."},
      ],
  )
  ```

  ```bash bash theme={null}
  curl https://apigw.mka1.com/api/v1/llm/conversations/conv_abc123/items \
    --request POST \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer <mka1-api-key>' \
    --header 'X-On-Behalf-Of: <end-user-id>' \
    --data '{
      "items": [
        {
          "type": "message",
          "role": "user",
          "content": "Summarize the latest support ticket."
        }
      ]
    }'
  ```
</CodeGroup>

Use este endpoint quando quiser escrever o histórico explicitamente antes de chamar o recurso Responses.

## Continue o fluxo com o recurso Responses

Passe o ID da conversa na sua próxima requisição de Responses.
Isso permite que a API MKA1 use o estado salvo da conversa.

<CodeGroup>
  ```bash CLI theme={null}
  mka1 llm responses create \
    --model meetkai:functionary-pt \
    --conversation conv_abc123 \
    --input '"Turn that summary into a customer-ready reply."'
  ```

  ```ts MKA1 SDK theme={null}
  const result = await mka1.llm.responses.create({
    model: 'meetkai:functionary-pt',
    conversation: 'conv_abc123',
    input: 'Turn that summary into a customer-ready reply.',
  });
  ```

  ```ts OpenAI SDK theme={null}
  const response = await openai.responses.create({
    model: 'meetkai:functionary-pt',
    conversation: 'conv_abc123',
    input: 'Turn that summary into a customer-ready reply.',
    stream: false,
  });
  ```

  ```csharp C# SDK theme={null}
  using MeetKai.MKA1;
  using MeetKai.MKA1.Types.Components;

  var sdk = new SDK(bearerAuth: "Bearer YOUR_API_KEY");

  var conv = await sdk.Llm.Conversations.CreateAsync(new CreateConversationRequest()
  {
      Metadata = new Dictionary<string, string> { { "session_id", "csharp-test" } },
  });

  var res = await sdk.Llm.Responses.CreateAsync(new ResponsesCreateRequest()
  {
      Model = "meetkai:functionary-pt",
      Conversation = ResponsesCreateRequestConversation.CreateStr(conv.ConversationObject!.Id),
      Input = ResponsesCreateRequestInput.CreateStr("Turn that summary into a customer-ready reply."),
  });
  ```

  ```python Python SDK theme={null}
  res = sdk.llm.responses.create(
      model="meetkai:functionary-pt",
      conversation="conv_abc123",
      input="Turn that summary into a customer-ready reply.",
  )
  ```

  ```bash bash theme={null}
  curl https://apigw.mka1.com/api/v1/llm/responses \
    --request POST \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer <mka1-api-key>' \
    --header 'X-On-Behalf-Of: <end-user-id>' \
    --data '{
      "model": "meetkai:functionary-pt",
      "conversation": "conv_abc123",
      "input": "Turn that summary into a customer-ready reply."
    }'
  ```
</CodeGroup>

Você também pode continuar adicionando itens à mesma conversa conforme a troca evolui.

## Ler, atualizar ou limpar uma conversa

Use os endpoints de Conversas para:

* Listar conversas para a conta atual ou usuário final (`GET /api/v1/llm/conversations`).
* Filtrar listas com `after`, `limit`, `order`, `metadata` e `search`.
* Buscar uma conversa pelo ID (`GET /api/v1/llm/conversations/{conversation_id}`).
* Atualizar os metadados da conversa (`POST /api/v1/llm/conversations/{conversation_id}`).
* Listar itens em uma conversa (`GET /api/v1/llm/conversations/{conversation_id}/items`).
* Buscar um item específico (`GET /api/v1/llm/conversations/{conversation_id}/items/{item_id}`).
* Excluir itens (um ou vários) via:
  * `DELETE /api/v1/llm/conversations/{conversation_id}/items/{item_id}`
  * `DELETE /api/v1/llm/conversations/{conversation_id}/items` com `{ "item_ids": ["item_..."] }`
* Excluir a conversa (`DELETE /api/v1/llm/conversations/{conversation_id}`).

Nota: excluir uma conversa **não** exclui seus itens.

Use a aba de Referência da API para os formatos exatos de requisição e resposta de cada operação.

## Quando usar conversas vs `previous_response_id`

Use uma conversa quando:

* Você deseja um contêiner reutilizável para várias interações.
* Você precisa listar ou gerenciar itens salvos posteriormente.
* Você quer anexar metadados ao thread em andamento.

Use `previous_response_id` quando:

* Você só precisa continuar a partir de uma resposta anterior.
* Você não precisa de um recurso de conversa armazenado separadamente.

Para o padrão do lado da resposta, veja [gerar uma resposta](/pt/docs/generate-a-response).