Gerenciar conversas

Use o recurso Conversations quando quiser que a API MKA1 mantenha o estado da conversa entre solicitações de Responses. Isso é útil para chats com vários turnos, threads de suporte e fluxos de trabalho nos quais você deseja buscar ou editar o histórico salvo posteriormente.

Criar uma conversa

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

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

import { SDK } from '@meetkai/mka1';

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

const conv = await mka1.llm.conversations.create({
  xOnBehalfOf: '<end-user-id>', // optional — attribute the request to one of your end users
  createConversationRequest: {
    metadata: {
      session_id: 'web-42',
      channel: 'support',
    },
  },
});

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',
  },
});

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" } },
});

from meetkai_mka1 import SDK

sdk = SDK(bearer_auth="Bearer YOUR_API_KEY")

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

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"
    }
  }'

Se sua solicitação não estiver vinculada a um usuário final específico, omita X-On-Behalf-Of. Consulte o guia de autenticação para ver o padrão completo.

Adicionar itens à conversa

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

mka1 llm conversations create-items \
  --conversation-id conv_abc123 \
  --body '{
    "items": [
      {
        "type": "message",
        "role": "user",
        "content": "Resuma o ticket de suporte mais recente."
      }
    ]
  }'

const items = await mka1.llm.conversations.createItems({
  conversationId: 'conv_abc123',
  xOnBehalfOf: '<end-user-id>',
  createItemsRequest: {
    items: [
      {
        type: 'message',
        role: 'user',
        content: 'Resuma o ticket de suporte mais recente.',
      },
    ],
  },
});

const items = await openai.conversations.items.create('conv_abc123', {
  items: [
    {
      type: 'message',
      role: 'user',
      content: 'Resuma o ticket de suporte mais recente.',
    },
  ],
});

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("Resuma o ticket de suporte mais recente."),
        }),
    },
});

sdk.llm.conversations.create_items(
    conversation_id="conv_abc123",
    items=[
        {"type": "message", "role": "user", "content": "Resuma o ticket de suporte mais recente."},
    ],
)

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": "Resuma o ticket de suporte mais recente."
      }
    ]
  }'

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

Continuar o fluxo com o recurso Responses

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

mka1 llm responses create \
  --model meetkai:functionary-pt \
  --conversation conv_abc123 \
  --input '"Transforme esse resumo em uma resposta pronta para o cliente."'

const result = await mka1.llm.responses.create({
  responsesCreateRequest: {
    model: 'meetkai:functionary-pt',
    conversation: 'conv_abc123',
    input: 'Transforme esse resumo em uma resposta pronta para o cliente.',
  },
});

const response = await openai.responses.create({
  model: 'meetkai:functionary-pt',
  conversation: 'conv_abc123',
  input: 'Transforme esse resumo em uma resposta pronta para o cliente.',
  stream: false,
});

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("Transforme esse resumo em uma resposta pronta para o cliente."),
});

res = sdk.llm.responses.create(
    model="meetkai:functionary-pt",
    conversation="conv_abc123",
    input="Transforme esse resumo em uma resposta pronta para o cliente.",
)

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": "Transforme esse resumo em uma resposta pronta para o cliente."
  }'

Você também pode continuar adicionando itens à mesma conversa à medida que a troca cresce.

Ler, atualizar ou limpar uma conversa

Use os endpoints de Conversations para:

Listar conversas da conta ou do usuário final atual (GET /api/v1/llm/conversations).
Filtrar listas com after, limit, order, metadata e search.
Buscar uma conversa por 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 único item (GET /api/v1/llm/conversations/{conversation_id}/items/{item_id}).
Excluir itens (um ou vários) por meio de:
- 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}).

Observação: a exclusão de itens retorna o objeto de conversa atualizado. A exclusão de uma conversa retorna um objeto de exclusão, e os itens da conversa não serão excluídos. Use a aba API Reference para ver os formatos exatos de solicitação e resposta de cada operação.

Quando usar conversas em vez de `previous_response_id`

Use uma conversa quando:

Você quiser um contêiner reutilizável para vários turnos.
Precisar listar ou gerenciar itens salvos posteriormente.
Quiser anexar metadados à thread em andamento.

Use previous_response_id quando:

Você só precisar continuar a partir de uma resposta anterior.
Não precisar de um recurso de conversa armazenada separado.

Para o padrão do lado da resposta, consulte gerar uma resposta.

⌘I

Primeiros passos

Respostas

Recursos

Computação

CLI

Receitas

Benchmarks

Infraestrutura

Gerenciar conversas

Criar uma conversa

Adicionar itens à conversa

Continuar o fluxo com o recurso Responses

Ler, atualizar ou limpar uma conversa

Quando usar conversas em vez de `previous_response_id`

​Criar uma conversa

​Adicionar itens à conversa

​Continuar o fluxo com o recurso Responses

​Ler, atualizar ou limpar uma conversa

​Quando usar conversas em vez de previous_response_id

Criar uma conversa

Adicionar itens à conversa

Continuar o fluxo com o recurso Responses

Ler, atualizar ou limpar uma conversa

Quando usar conversas em vez de `previous_response_id`