Annotations API

Consulte URLs e autenticação HTTP e a referência da API para os formatos completos de solicitação e resposta. A Annotations API anexa valores estruturados de revisão humana ao Trace e ao span de uma solicitação concluída. Enquanto a página Annotations aborda os fluxos de revisão do AI Studio (o painel Annotations em Traces e Logs, as Annotation Queues e os experimentos), esta página é o guia de uso da API: como capturar os identificadores, montar o corpo da solicitação e tratar a resposta.

Casos de uso

Avaliações programáticas

Registre avaliações positivas/negativas ou categóricas de forma programática à medida que os usuários interagem com as respostas, sem abrir o AI Studio.

Registro de defeitos

Registre em escala tags de defeito estruturadas, como alucinação, fuga do tema ou resposta incompleta, para uma análise sistemática de qualidade.

Correções de respostas

Armazene uma resposta corrigida junto com a original para criar pares de referência para datasets de avaliação.

Substituição de resultados de evaluators

Corrija um resultado de LLM-as-a-judge com uma revisão humana, anexando uma explicação à saída corrigida.

Anexar Annotations a um span

Cada anotação precisa ser definida antes de poder ser aplicada. A definição estabelece a chave, o título e o tipo de valor; toda anotação enviada pela API precisa corresponder a uma dessas definições, e uma chave que não existe no workspace é rejeitada com um 404. Crie as definições em Optimization > Annotations no AI Studio ou em Settings > Annotations no AI Gateway, conforme descrito na página Annotations. Com a definição pronta, são duas etapas:

Capture o trace_id e o span_id da execução a ser anotada. Ambos são obrigatórios, e a origem deles depende do endpoint; consulte De onde vêm os identificadores.
Envie as anotações com a API Annotate a Span, usando a key de uma definição de anotação existente.

curl -X POST "https://router.toqan.ai/eu/v2/traces/{trace_id}/spans/{span_id}/annotation" \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "annotations": [
      {
        "key": "star-rating",
        "value": 4
      }
    ]
  }'

Algumas mensagens de erro da API ainda se referem às anotações como human reviews. Os dois nomes descrevem o mesmo objeto: as anotações antes se chamavam human reviews, e uma mensagem como The human review with key "star-rating" ... was not found. se refere à definição de anotação com essa chave.

As anotações estão disponíveis em spans de chat completion e da Responses API. Ao anotar um span de deployment, o log associado é anotado automaticamente com os mesmos valores.

De onde vêm os identificadores

Toda execução retorna os dois ids. Quando o corpo da resposta contém um objeto telemetry, obtenha-os dele; caso contrário, obtenha-os dos cabeçalhos da resposta:

Endpoint	`trace_id`	`span_id`
`POST /v3/router/responses`	`telemetry.trace_id` no corpo ou o cabeçalho `x-orq-trace-id`	`telemetry.span_id` no corpo ou o cabeçalho `x-orq-trace-span-id`
`POST /v3/router/responses` com `model: "agent/<key>"`	`telemetry.trace_id` no corpo ou o cabeçalho `x-orq-trace-id`	`telemetry.span_id` no corpo ou o cabeçalho `x-orq-trace-span-id`
Outros endpoints `/v3/router/*` (chat completions, completions, embeddings, images, moderations, rerank, speech, transcriptions, translations, ocr)	Cabeçalho `x-orq-trace-id`	Cabeçalho `x-orq-trace-span-id`
`POST /v2/deployments/invoke`	`telemetry.trace_id` no corpo	`telemetry.span_id` no corpo

O objeto telemetry fica no nível superior da resposta:

{
  "telemetry": {
    "trace_id": "01M1H2VST506ZX2WE8KDQTRBEQ",
    "span_id": "01M1H2VST543YJ5DN5RXW1B6EC"
  }
}

Em POST /v2/deployments/invoke, o cabeçalho x-orq-trace-id não contém o id do trace. Ele contém o id da execução do workflow, que identifica o span raiz da execução; x-orq-workflow-run-id e o campo id da resposta têm o mesmo valor. Use telemetry.trace_id do corpo da resposta como trace_id — passar o valor do cabeçalho retorna um 404.

Os dois ids são comparados como strings opacas: a Annotations API faz uma correspondência exata de string com os ids armazenados e não aplica nenhuma validação de formato. O formato deles é um detalhe de implementação que pode variar entre execuções, então não valide sua forma nem presuma um comprimento fixo.

Campos de Annotations

Os campos marcados com * são sempre obrigatórios. key e parent_annotation_id são obrigatórios condicionalmente: cada entrada contém exatamente um deles.

Campo	Local	Tipo	Descrição
`trace_id*`	path	string	O id do trace ao qual o span pertence, obtido da resposta da execução; consulte De onde vêm os identificadores
`span_id*`	path	string	O id do span que está sendo anotado, obtido da resposta da execução; consulte De onde vêm os identificadores
`annotations*`	body	array	As anotações a serem aplicadas, entre 1 e 10 por solicitação
`annotations[].key`	body	string	A chave de uma definição de anotação existente. Obrigatória para uma anotação padrão e não aceita em uma correção
`annotations[].value*`	body	string, number, boolean ou array de strings	O valor da anotação; o tipo depende da definição da anotação (veja abaixo)
`annotations[].parent_annotation_id`	body	string	O eval id da anotação de evaluator que está sendo corrigida. Obrigatório para uma correção e não aceito em uma anotação padrão
`annotations[].explanation`	body	string	Explicação opcional para uma correção, com até 3000 caracteres
`metadata.identity_id`	body	string	Identidade opcional do revisor para atribuição; use `identityId` no SDK para Node

Uma entrada de anotação é uma anotação padrão, com key e value, ou uma correção, com parent_annotation_id, value e, opcionalmente, explanation. Os dois formatos são mutuamente exclusivos.

Valores de Annotations

O tipo de value deve corresponder à definição da anotação:

Categórica, seleção única: uma string ou um array com um único elemento, por exemplo "good" ou ["good"]
Categórica, seleção múltipla: um array de strings, por exemplo ["grammatical", "hallucination"]
Intervalo: um número dentro do mínimo/máximo configurado para a anotação, por exemplo 4 em um intervalo de 1 a 5
Booleana: true ou false
Texto ou correção: uma string com até 3000 caracteres

Valores de string fora das opções configuradas para a anotação são rejeitados; consulte Tratamento de erros.

Correções

Uma correção substitui uma saída existente de evaluator por um valor revisado por uma pessoa:

curl -X POST "https://router.toqan.ai/eu/v2/traces/{trace_id}/spans/{span_id}/annotation" \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "annotations": [
      {
        "parent_annotation_id": "<evaluator_annotation_id>",
        "value": false,
        "explanation": "The response omitted a required disclaimer."
      }
    ]
  }'

O value corrigido deve corresponder ao tipo de saída da própria anotação de evaluator. Consulte Corrigir um resultado de Evaluator para ver o equivalente na interface.

Annotations em lote

Envie até 10 entradas de anotação em uma única solicitação:

curl -X POST "https://router.toqan.ai/eu/v2/traces/{trace_id}/spans/{span_id}/annotation" \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "annotations": [
      {
        "key": "rating",
        "value": "good"
      },
      {
        "key": "star-rating",
        "value": 4
      },
      {
        "key": "categories",
        "value": ["helpful", "accurate", "concise"]
      }
    ]
  }'

Remover Annotations

Envie keys para a API Remove an Annotation from a Span para excluir anotações padrão, ou parent_annotation_ids para excluir correções pelos eval ids das anotações pai. Até 10 de cada por solicitação. Os exemplos abaixo mostram keys; para excluir uma correção, substitua o corpo por {"parent_annotation_ids": ["<evaluator_annotation_id>"]}.

curl -X DELETE "https://router.toqan.ai/eu/v2/traces/{trace_id}/spans/{span_id}/annotation" \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "keys": ["rating", "defects"]
  }'

Onde as Annotations aparecem

As anotações aplicadas pela API aparecem no painel Annotations das visualizações de detalhes de span e de log em Traces e Logs.

Tratamento de erros

Código de status	Erro	Exemplo de mensagem	Solução
404	Annotation não encontrada	`The human review with key "star-rating" for workspace abc123 was not found.`	Crie uma Annotation com a chave especificada antes de anotar.
404	Span não encontrado	`Span with id xyz789 and trace id trace456 for workspace abc123 was not found.`	Verifique se o `trace_id` e o `span_id` estão corretos e pertencem ao workspace. Se os ids estiverem corretos e a solicitação vier logo após a chamada que a gerou, tente novamente com um breve backoff: a ingestão de spans é assíncrona e pode ainda não ter sido concluída.
400	Valor inválido	`Invalid value: poor. Valid options are: good, bad.`	Garanta que o valor corresponda às opções definidas na Annotation.
400	Valor fora do intervalo	`Value 15 is out of range [0, 10].`	Informe um número dentro do intervalo mínimo/máximo definido para a Annotation.
400	String longa demais	Erro de validação da solicitação em `annotations[].value`	Mantenha os valores de string dentro de 3000 caracteres.

Veja um ciclo de feedback completo implementado do zero. Leia nosso cookbook Capturing User Feedback.

Restrições

Limites de lote: até 10 anotações por solicitação de criação e até 10 chaves e 10 parent_annotation_ids por solicitação de exclusão
Comprimento do valor: os valores de string são limitados a 3000 caracteres; as definições de anotação não impõem um limite menor
Campos de metadados: o objeto opcional metadata aceita identity_id (identityId no SDK para Node) para atribuição do revisor

Veja também

Annotations: os fluxos de revisão do AI Studio
Annotation Queues: fluxos de revisão em lote
Referência do SDK de Annotations: assinaturas dos métodos do SDK

Visão geral

Instrumente seu app

Explorar

Monitorar

Exportar

Revisar

Privacidade e segurança de dados

Integrações com frameworks

Casos de uso

Anexar Annotations a um span

De onde vêm os identificadores

Campos de Annotations

Valores de Annotations

Correções

Annotations em lote

Remover Annotations

Onde as Annotations aparecem

Tratamento de erros

Restrições

Veja também

​Casos de uso

​Anexar Annotations a um span

​De onde vêm os identificadores

​Campos de Annotations

​Valores de Annotations

​Correções

​Annotations em lote

​Remover Annotations

​Onde as Annotations aparecem

​Tratamento de erros

​Restrições

​Veja também

Casos de uso

Anexar Annotations a um span

De onde vêm os identificadores

Campos de Annotations

Valores de Annotations

Correções

Annotations em lote

Remover Annotations

Onde as Annotations aparecem

Tratamento de erros

Restrições

Veja também