Muitas perguntas em uma chamada só

A primeira integração com o Jev quase sempre nasce errada do mesmo jeito: um laço que faz uma chamada por pergunta. É o reflexo de quem vem de LLM, onde empilhar perguntas no mesmo prompt costuma piorar a resposta.

Aqui a mecânica é outra, e a recomendação oficial é a oposta: mande todas as perguntas que usam o mesmo state em uma requisição só.

A mecânica em três fatos

O state entra uma vez. O modelo ingere o conteúdo uma vez por requisição e avalia todas as perguntas contra ele. Nas chamadas avulsas, o mesmo conteúdo é reenviado e recobrado a cada vez.

As perguntas são avaliadas em paralelo e de forma independente. A documentação afirma as duas coisas: todas as perguntas de uma requisição rodam em paralelo, e uma resposta não vira contexto para outra pergunta.

O orçamento de contexto é compartilhado. São 64 mil tokens por requisição para o state mais todas as perguntas, e 32 mil para o state mais a pergunta mais longa. Não existe teto de contagem de perguntas — o teto é de tokens, e está detalhado em o contexto de 64k.

Dessas três coisas sai a frase que muda o desenho: acrescentar uma pergunta não acrescenta latência e custa apenas os tokens dela.

O número medido

O cookbook oficial de perguntas paralelas comparou as duas estratégias em uma tarefa de conformidade: treze perguntas sobre o artigo da Wikipédia em inglês sobre o GDPR, numa revisão fixada de 53.777 caracteres, divididas em 8 Noul, 2 Choice e 3 Score.

Duas ressalvas honestas. A primeira é do próprio cookbook: o ganho de tempo supõe as treze chamadas em sequência — disparadas em paralelo, a diferença de tempo encolhe, mas o custo de reenviar o documento treze vezes continua igual. A segunda é uma divergência entre as fontes oficiais: a página de primitivas cita 11,5 vezes e 9,6 vezes para o mesmo experimento, enquanto a receita publica 12,2 e 10,0. Usamos os números da receita e dizemos de onde vêm. A receita completa está em perguntas paralelas.

A forma da chamada

from typesafe_sdk import Choice, Noul, Score, TypeSafeClient

estado = {
    "mensagem": "Fiz a atualização ontem e o sistema não abre. Preciso disso hoje.",
    "plano": "Empresarial",
}

with TypeSafeClient() as client:
    r = client.system_one(
        state=estado,
        questions={
            "categoria": Choice(
                instructions="Qual o assunto principal deste ticket?",
                criteria={
                    "duvida_tecnica": "Algo não funciona, dá erro ou o cliente não sabe usar.",
                    "cobranca": "Fatura, valor, estorno ou forma de pagamento.",
                    "outro": "Não se encaixa nas categorias acima.",
                },
            ),
            "urgencia": Score(
                instructions="Qual a urgência do pedido?",
                criteria=[
                    "Nenhuma pressa declarada.",
                    "Quer resposta nos próximos dias.",
                    "Cita prazo curto ou impacto no trabalho.",
                    "Operação parada agora.",
                ],
            ),
            "pede_reembolso": Noul(
                instructions="O cliente pede estorno ou reembolso?"
            ),
            "cita_procon": Noul(
                instructions="O texto menciona Procon, advogado ou processo?"
            ),
        },
    )

Os três tipos convivem na mesma requisição, e cada chave que você escolhe volta na resposta com o mesmo nome. Vale lembrar que a chave em si não é enviada ao modelo: quem carrega o sentido é o campo instructions.

A pergunta que você talvez não use

Como a pergunta extra custa só os próprios tokens, a conta muda: vale perguntar o que só importa em um dos caminhos do fluxo. Se o ticket não for um bug, a resposta de severidade é ignorada e nada se perdeu; se for, você economizou uma ida ao servidor.

Esse é o padrão de fan-out especulativo, e ele é a razão de quase todo caso de uso deste site mandar cinco ou seis perguntas de uma vez.

Quando a segunda chamada é legítima

A documentação trata isso com cuidado, e vale repetir o critério: duas requisições são a exceção. A dependência só é real quando o seu código não consegue montar a segunda requisição sem a primeira resposta — porque precisa dela para buscar mais dados para o state, para decidir do que o state é feito, ou para escolher as opções da próxima pergunta.

Os três cookbooks oficiais que fazem duas chamadas, e por quê:

• escolher skill de agente ordena 182 skills numa requisição, depois busca o texto completo das três primeiras e julga de novo com evidência melhor;
• recuperar estrutura pergunta se cada quebra de linha partiu uma frase, monta os blocos a partir das respostas, e só então classifica os blocos — que não existiam antes;
• classificação hierárquica usa cada resposta para decidir quais opções a próxima pergunta oferece.

Se as perguntas da segunda requisição poderiam ter sido feitas contra o state original, faça tudo na primeira e deixe o código ignorar o que não precisa.

O efeito na fatura e na cota

Agrupar economiza duas coisas ao mesmo tempo: tokens, porque o state não é reenviado, e requisições, que são o recurso limitado pelos limites de taxa — 1.200 por minuto, segundo a documentação. Dez perguntas em uma chamada gastam uma das suas 1.200; em dez chamadas, gastam dez. O dimensionamento está em limites de taxa, e a conta em reais em quanto custa uma decisão.

O índice das primitivas está em primitivas.