Reutilização de sessão

A reutilização de sessão permite que um cliente chat/completions sem estado mantenha o contexto do lado do servidor de uma conversa entre solicitações. Seu aplicativo ainda armazena e envia o histórico de mensagens; a AIVAX apenas restaura o que o histórico não consegue transportar. Para saber o que esse contexto contém, consulte Contexto do lado do servidor.

Reutilização de sessão e sessões de clientes de chat #

A AIVAX possui dois recursos com “sessão” no nome. Eles resolvem problemas diferentes:

Uma sessão de cliente de chat gerencia seu próprio token de conversa internamente; você não envia conversation_token para ela. Use a reutilização de sessão quando seu aplicativo for proprietário do histórico, e use um cliente de chat quando a AIVAX dever ser proprietária dele.

Enviar o token #

Envie conversation_token em todas as solicitações da mesma conversa. A AIVAX o usa para restaurar o que aconteceu no lado do servidor nas rodadas anteriores e para atualizar um único registro de conversa armazenado, em vez de criar um novo para cada solicitação.

Ferramentas do lado do servidor, como ferramentas integradas, ferramentas MCP e funções de protocolo, são executadas dentro da AIVAX. Suas chamadas e resultados não são retornadas a você como mensagens: a resposta contém apenas a mensagem final do assistente, com o texto de cada etapa unido. Quando você envia o histórico da conversa de volta, essas chamadas e resultados de ferramentas estão ausentes. Com o mesmo conversation_token, a AIVAX os insere de volta no histórico antes que o modelo seja executado, para que o modelo ainda veja os dados retornados por suas ferramentas e não repita as mesmas chamadas.

{
    "model": "your-model-or-gateway-id",
    "conversation_token": "support-ticket-1042",
    "messages": [
        {
            "role": "user",
            "content": "Qual é o status do pedido 123?"
        },
        {
            "id": "aivx_k2m9x0q4tr",
            "role": "assistant",
            "content": "O pedido 123 foi enviado ontem e deve chegar na sexta-feira."
        },
        {
            "role": "user",
            "content": "Você pode alterar o endereço de entrega?"
        }
    ]
}

Você pode criar o token você mesmo e enviá-lo a partir da primeira solicitação da conversa; não precisa esperar que a AIVAX retorne um. Qualquer string não vazia com 128 caracteres ou menos é aceita, sem formato obrigatório, como o ID que seu aplicativo já usa para a conversa. Os tokens são limitados à sua conta, portanto, outra conta pode usar o mesmo valor sem compartilhar estado com o seu. Quando omitido, a AIVAX gera um token e o retorna, e você pode reutilizar o valor retornado a partir da segunda solicitação.

Cada resposta retorna dois valores:

A AIVAX corresponde às mensagens do assistente que você envia de volta às suas rodadas armazenadas nesta ordem:

1. O id da mensagem do assistente, quando você o envia.
2. Os IDs das chamadas de ferramentas que ele carrega, quando a rodada também solicitou ferramentas do seu cliente.
3. O texto da mensagem, dentro do mesmo conversation_token.

A correspondência por id é a mais confiável. A correspondência por texto é um fallback para clientes que descartam o id, e pode falhar sem erro, por exemplo, quando o texto foi alterado ou quando duas respostas na mesma conversa têm o mesmo texto. Quando nenhuma correspondência é encontrada, a mensagem é usada exatamente como você a enviou.

Requisitos do cliente #

• Use um token por conversa. Reutilizar um token entre conversas, usuários ou ramificações diferentes pode restaurar resultados de ferramentas de outra conversa. Gere um novo token quando uma nova conversa começar e não use valores que os usuários possam adivinhar ou escolher.
• Não compartilhe tokens entre usuários finais. O token não é uma credencial, mas qualquer pessoa que possa chamar sua conta com ele pode continuar o contexto armazenado dessa conversa.
• Armazene e reenvie o id da mensagem. Salve o ID aivx_... de cada mensagem do assistente que você recebe e envie-o de volta como o id dessa mensagem em solicitações posteriores. Esta é a maneira recomendada de restaurar uma rodada e continua funcionando quando o texto sozinho não consegue identificá-la.
• Reenvie exatamente o conteúdo que a AIVAX retornou. Mantenha o texto completo de cada mensagem do assistente conforme você a recebeu, incluindo o texto que o modelo escreveu antes de chamar ferramentas, unido em uma única mensagem do assistente. Não o divida em várias mensagens, remova partes dele ou o reescreva, traduza ou resuma. A correspondência por texto ignora apenas espaços em branco. Quando rendering_mode é textual_blocks, o conteúdo mistura blocos de raciocínio e resposta, portanto, apenas o id pode identificar a rodada.
• Preserve os IDs de chamada de ferramentas. Quando uma resposta solicitar ferramentas do seu cliente, reenvie os mesmos valores de tool_calls[].id e responda a cada um com uma mensagem tool.
• Gerencie estados expirados. O estado do lado do servidor de uma rodada expira após uma hora sem uso. Após isso, ou quando não puder ser encontrado, a conversa continua normalmente, mas o modelo não vê mais os resultados dessas ferramentas do lado do servidor anteriores.
• Não reenvie ferramentas restauradas você mesmo. Você não precisa reconstruir chamadas ou resultados de ferramentas do lado do servidor. Se seu histórico já contiver eles com os mesmos IDs, a AIVAX não os adicionará novamente.

idempotency_key é um alias obsoleto de conversation_token. Ainda funciona, mas novas integrações devem usar conversation_token. Quando ambos são enviados, eles devem ter o mesmo valor; caso contrário, a solicitação falha com 400 Bad Request.

Para manter o estado da conversa em seu aplicativo e a configuração do gateway na AIVAX, consulte migrando threads de Assistants para Responses.