Chat Completions: contexto, ferramentas e erros#
Para integrar um modelo pelo Sherpa AI Server, deve-se utilizar POST /api/v1/threads/chat/completions. O método executa uma solicitação sem criar chat ou execução. O cliente fornece o histórico de mensagens.
Autenticação e seleção do modelo#
É necessário um token de API válido com permissão de criação em Chat. POST /api/v1/threads/chat/preflight exige permissão de leitura. A autenticação determina a conta. Não é necessário enviar account_guid.
Em model, deve-se informar o nome de uma ficha de modelo da conta atual. O servidor seleciona uma instância ativa dessa ficha. A seleção anterior pelo nome de uma instância ativa da mesma conta também é aceita. Um nome desconhecido ou de outra conta retorna 404 model_not_found. Uma ficha sem instâncias ativas retorna 503 model_unavailable.
Um parâmetro explícito tem prioridade sobre a ficha e o ambiente do servidor. Parâmetros ausentes usam a ficha e depois o ambiente. O objeto chat_template_kwargs é substituído por inteiro. null, {} e um campo omitido são diferentes. Deve-se enviar apenas um campo de orçamento de saída: max_tokens ou max_completion_tokens.
Verificação do contexto antes da geração#
Deve-se enviar a solicitação completa pretendida para /api/v1/threads/chat/preflight com Authorization: Bearer <API_TOKEN> e Content-Type: application/json. No exemplo, deve-se substituir Support model pelo nome de uma ficha disponível:
{
"model": "Support model",
"messages": [{"role": "user", "content": "Read the test file"}],
"tools": [{
"type": "function",
"function": {
"name": "read_file",
"parameters": {
"type": "object",
"properties": {"path": {"type": "string"}},
"required": ["path"],
"additionalProperties": false
}
}
}],
"max_tokens": 512,
"chat_template_kwargs": {"enable_thinking": false}
}
Preflight não gera respostas, executa ferramentas nem cria histórico. O resultado está em data:
| Campo | Significado |
|---|---|
prompt_tokens |
Tamanho da entrada com mensagens, esquemas de ferramentas e reservas para imagens e formato da resposta. |
output_tokens |
Orçamento de saída. null quando desconhecido. |
context_limit |
Janela de contexto conhecida. null quando não há limite configurado. |
fits |
Indica se a solicitação e a saída cabem. null quando faltam dados. |
exact, count_method |
Contagem exata do tokenizer ou estimativa. Imagens e formato podem acrescentar reservas estimadas. |
would_reject |
Indica se um limite confiável rejeita a solicitação. Uma estimativa isolada não bloqueia a geração. |
fallback_reason |
Motivo da estimativa, como tokenizer indisponível ou provedor em nuvem sem tokenizer. |
allowed_max_output |
Contexto restante após a entrada calculada. Uma estimativa é orientativa. |
Se would_reject=true, deve-se reduzir o histórico, os esquemas ou a saída e verificar novamente. Depois, envia-se a mesma solicitação para /api/v1/threads/chat/completions. O servidor verifica o orçamento para a instância real, inclusive após uma troca. Os limites podem variar. Preflight não reserva uma instância para a próxima solicitação.
Chamadas de ferramentas#
O cliente externo de API executa as chamadas recebidas. tools declara funções e JSON Schema para os argumentos. Campos de entrada adicionais devem ser incluídos no esquema e em function.arguments.
Na próxima solicitação, deve-se preservar a mensagem do assistente com tool_calls e acrescentar resultados role=tool. function.arguments e tool.content são strings. tool_call_id associa cada resultado à chamada. Status, erros, artefatos e metadados da aplicação são JSON dentro da string content:
[
{"role":"assistant","content":null,"tool_calls":[{"id":"call_1","type":"function","function":{"name":"read_file","arguments":"{\"path\":\"sample.txt\"}"}}]},
{"role":"tool","tool_call_id":"call_1","content":"{\"status\":\"ok\",\"data\":\"Example text\",\"artifacts\":[]}"}
]
Cada novo ID de chamada deve ser único no histórico. Os resultados devem seguir sua mensagem do assistente antes de outra mensagem com papel diferente. Os argumentos incorretos devem ser mantidos junto com o resultado de erro para que o modelo corrija a chamada. Ações bem-sucedidas com efeitos colaterais não devem ser repetidas.
No modo Agente interno, argumentos corrigíveis são devolvidos ao modelo. A quantidade desses erros, por si só, não encerra a tarefa. Repetir uma chamada inválida idêntica coloca a execução em waiting com continuation.required=true. Após corrigir a causa, deve-se retomar explicitamente pelo método normal de execução. O contexto e os resultados concluídos são mantidos. O cancelamento e as restrições reais de acesso continuam em vigor.
/api/v1/threads/responses usa o formato Responses separado. Seus itens não devem ser misturados com mensagens Chat Completions.
Erros e novas tentativas#
Um erro contém error.code, repairable, retryable, request_id e details seguros. Com repairable=true, deve-se corrigir a solicitação conforme os detalhes. Com retryable=true, é permitida uma nova tentativa com atraso, respeitando Retry-After. Essas marcas não autorizam repetir ações de ferramentas já concluídas.
| Código | Ação |
|---|---|
invalid_arguments, invalid_tool_history |
Corrigir parâmetros, esquema ou pares de chamadas e resultados. |
context_limit |
Reduzir a entrada ou saída. Conferir os dados numéricos em details. |
model_not_found, model_unavailable |
Conferir nome, conta e instâncias ativas. |
access_denied |
Conferir token, permissões e acesso do servidor ao provedor. |
upstream_rate_limited |
Respeitar Retry-After. |
upstream_timeout, upstream_unavailable, invalid_upstream_response |
Conferir retryable e tentar novamente mais tarde quando adequado. |
Para SSE, é necessário stream=true. Deve-se ler até a conclusão e tratar event: error. HTTP 200 indica o início do fluxo e não garante a conclusão bem-sucedida. Falhas de leitura ou interrupções produzem um erro com o mesmo request_id.
Diagnóstico de solicitações#
Recomenda-se enviar X-Request-ID: de 1 a 128 caracteres A-Z, a-z, 0-9, ., _, :, -. Se estiver ausente ou inválido, o servidor cria um novo ID.
Respostas JSON e SSE incluem X-Request-ID e X-Sherpa-Attempt-Count. Quando uma ficha é selecionada, ficam disponíveis X-Sherpa-Model-Guid, X-Sherpa-Model-Instance-Guid e X-Sherpa-Configuration-Revision. A revisão distingue mudanças na configuração efetiva. JSON também inclui request_meta.request_id. Erros anteriores à seleção não incluem informações de instância.
Ao contatar o administrador, devem-se conservar ID, horário, código de erro e cabeçalhos de diagnóstico. O registro existente do servidor relaciona tentativas, motivos, latência, usage e conclusão do fluxo pelo ID. Execuções em segundo plano são vinculadas pelo GUID da execução e ID run:<GUID>. O evento de agendamento relaciona o ID externo ao GUID. Apenas administradores de infraestrutura acessam o registro. Mensagens, argumentos de ferramentas e chaves não fazem parte do novo registro de diagnóstico.
Os tempos limite de chamadas individuais ao modelo dependem da conexão. A verificação do contexto e o diagnóstico não limitam a duração de um robô externo.