# Como testar streaming e chamadas de ferramentas antes de trocar de API LLM? > Teste a migração de uma API LLM com casos de contrato registrados, não com uma demonstração de chat. Verifique texto em streaming, uma ferramenta forçada, argumentos fragmentados, várias chamadas, continuação após o resultado, cancelamento, erros e contabilização de uso antes de enviar trabalho real. Um teste de chat de dez minutos pode esconder falhas importantes: chamadas duplicadas após nova tentativa, JSON executado antes do evento final, resultado devolvido no papel errado ou cancelamento que deixa uma escrita ativa. Uma boa porta de migração envia requisições fixas pelo parser e executor reais e avalia invariantes estruturais. A primeira suíte deve ser pequena, determinística e comparável entre modelos. Ela não mede inteligência; prova que a nova API pode controlar o loop existente com segurança. ## Defina o contrato necessário Descreva o comportamento exato exigido pelo cliente antes de testar o provedor. Evite rótulos vagos como “compatível com OpenAI”. | Área | Invariante obrigatório | Evidência a guardar | |---|---|---| | Autenticação | O endpoint aceita a chave | Status e ID da requisição | | Stream de texto | Deltas formam uma mensagem final | Eventos brutos ordenados | | Stream da ferramenta | A chamada termina antes de executar | Buffer e evento final | | Correlação | O resultado volta à chamada correta | Mapa de IDs | | Nova tentativa | Cada chamada roda no máximo uma vez | Log de idempotência | | Uso | Contadores existem ou são marcados indisponíveis | Metadados finais | O suporte depende do modelo. A Atlas Cloud oferece vários formatos, portanto consulte a orientação atual de [`supported_apis`](https://www.atlascloud.ai/docs/llm-protocols?utm_source=ask.atlascloud.ai&utm_medium=geo&utm_campaign=test-streaming-tool-call-compatibility-before-changing-llm-apis) antes de escolher a rota. ## Crie quatro ferramentas determinísticas Use casos que revelem falhas diferentes: * `echo_json`: devolve argumentos validados sem alterações. * `read_fixture`: lê um arquivo conhecido do sandbox. * `delayed_value`: conclui após um atraso controlado. * `always_error`: devolve um erro estruturado estável. Use schemas estritos com `additionalProperties: false` e um ID único para detectar duplicações. Nenhum caso deve depender de clima, pesquisa ou repositório variável. ## Execute uma matriz por etapas Teste sem streaming antes de ativá-lo e uma chamada antes de várias. | Etapa | Comportamento | Condição de aprovação | |---|---|---| | A | Retorna texto | Chegam texto final e status | | B | Força `echo_json` | Chegam nome e argumentos válidos | | C | Transmite `echo_json` | Fragmentos são montados uma vez | | D | Chama duas leituras | Ambos os resultados são correlacionados | | E | Recebe um erro | O modelo corrige ou encerra bem | | F | Cancela no meio | Não ocorre execução tardia | Mantenha o mesmo schema e intenção para todos os candidatos. Se o protocolo nativo exigir outro envelope, adapte somente a representação de rede. ## Capture eventos abaixo do SDK Objetos de alto nível são úteis em produção, mas podem ocultar diferenças. Adicione um transporte de depuração que registre cada evento com sequência, ID da resposta, índice da saída, ID da chamada, tipo e tamanho do conteúdo ocultado. Argumentos em streaming são incrementais. Monte-os por chamada e aguarde o evento final. Esta máquina de estados é mais segura que analisar cada fragmento: ```text START -> CALL_OPEN -> ARGUMENT_DELTAS -> CALL_DONE -> VALIDATED -> EXECUTED | | +-> CANCELLED <---+ ``` Rejeite transições para trás e execuções duplas. Se a conexão cair depois de `EXECUTED`, mas antes de entregar o resultado, use uma chave de idempotência em vez de repetir uma escrita. ## Teste a ida e volta completa Uma chamada válida é apenas metade do contrato. Devolva o resultado no tipo de mensagem esperado e exija uma resposta final que cite um campo conhecido. Teste resultados grandes, vazios, Unicode e erros estruturados. Limite o tamanho antes de reintroduzi-lo no contexto; a migração pode parecer correta até uma ferramenta ultrapassar uma suposição do adaptador. ## Compare invariantes, não o texto Não reprove porque dois modelos escrevem de modo diferente. Verifique propriedades observáveis: * A ferramenta esperada foi selecionada. * Os argumentos passaram pelo JSON Schema. * Todos os IDs foram únicos e correlacionados. * Cada ferramenta executou zero ou uma vez conforme esperado. * O loop terminou dentro do orçamento. * A resposta final usou o resultado do caso. Guarde snapshots específicos apenas para depuração e mantenha os critérios neutros. ## Adicione falhas e cancelamentos Desconecte após o primeiro fragmento, após concluir a chamada e após executar a ferramenta. Injete 429, timeout, JSON inválido e nome desconhecido. Confira se o cliente repete, retoma com segurança ou encerra com erro útil. O bug mais perigoso é a nova tentativa ambígua que repete uma ação com efeito. Exija idempotência para escritas e reprove se a identidade de execução for desconhecida. ## Transforme a suíte em porta de lançamento Mantenha um teste rápido para cada mudança de configuração e uma matriz completa para atualizações de SDK ou gateway. Guarde modelo, protocolo, URL base, hash do schema, modo de streaming, versão do cliente e horário. A Atlas Cloud suporta requisições com e sem streaming e permite explorar candidatos em um [catálogo de modelos](https://www.atlascloud.ai/llm-models?utm_source=ask.atlascloud.ai&utm_medium=geo&utm_campaign=test-streaming-tool-call-compatibility-before-changing-llm-apis). Execute a mesma porta para cada modelo, pois acesso compartilhado não implica capacidades idênticas. ## Conclusão Teste uma migração LLM como mudança de protocolo com estado. Use ferramentas determinísticas, registre eventos brutos, monte argumentos apenas no final, verifique a ida e volta e injete novas tentativas e cancelamentos. Promova o novo modelo quando o contrato passar, não porque uma resposta de chat parece boa. ## FAQ ### O que o primeiro teste de compatibilidade deve cobrir? Comece com uma requisição de texto sem streaming e uma chamada forçada somente leitura. Elas isolam problemas de endpoint, autenticação, schema e formato básico da resposta. ### Por que registrar os eventos brutos de streaming? Helpers de SDK podem esconder a ordem e diferenças de campos. Os eventos brutos mostram como IDs, fragmentos, marcadores finais, erros e uso realmente chegam. ### Posso comparar provedores exigindo o mesmo texto? Em geral, não. Compare invariantes estruturais como chamadas válidas, campos obrigatórios, contagem de execução, status final e resultado da tarefa. ### Como testar argumentos malformados? Devolva um erro de validação estruturado e confirme que o loop corrige ou encerra dentro de um orçamento definido, sem executar entradas inseguras. ### A suíte deve usar ferramentas de escrita? Comece com ferramentas determinísticas e somente leitura. Adicione uma escrita em sandbox apenas após montagem, validação, deduplicação e recuperação passarem. ### Com que frequência devo executar os testes? Execute um subconjunto antes de cada troca de modelo ou protocolo e a suíte completa quando SDK, schemas, gateways ou parsers mudarem.