Habilidade de Instrumentação Arize

Use esta habilidade quando o usuário quiser adicionar rastreamento Arize AX à sua aplicação. Siga o fluxo assistido por agente em duas fases de Configuração de Rastreamento Assistido por Agente e Rastreamento Arize AX — Prompt de Configuração do Agente.

Início rápido (para o usuário)

Se o usuário pedir para você "configurar o rastreamento" ou "instrumentar meu aplicativo com Arize", você pode começar com:

Siga as instruções de https://arize.com/docs/PROMPT.md e me faça perguntas conforme necessário.

Em seguida, execute as duas fases abaixo.

Princípios centrais

• Prefira inspeção em vez de mutação — entenda a base de código antes de alterá-la.
• Não altere a lógica de negócios — o rastreamento é puramente aditivo.
• Use a auto-instrumentação onde disponível — adicione spans manuais apenas para lógica personalizada não coberta por integrações.
• Siga o estilo de código existente e as convenções do projeto.
• Mantenha a saída concisa e focada na produção — não gere documentação extra ou arquivos de resumo.
• NUNCA incorpore valores literais de credenciais no código gerado — sempre referencie variáveis de ambiente (por exemplo, os.environ["ARIZE_API_KEY"], process.env.ARIZE_API_KEY). Isso inclui chaves de API, IDs de espaço e quaisquer outros segredos. O usuário os define em seu próprio ambiente; o agente nunca deve exibir valores brutos de segredos.

Fase 0: Verificação prévia do ambiente

Antes de alterar o código:

1. Confirme se o escopo do repositório/serviço está claro. Para monorepos, não presuma que todo o repositório deve ser instrumentado.
2. Identifique a superfície de tempo de execução local que você precisará para verificação:
   • gerenciador de pacotes e comando de inicialização do aplicativo
   • se o aplicativo é de longa duração, baseado em servidor ou um CLI/script de curta duração
   • se ax será necessário para verificação pós-alteração
3. NÃO verifique proativamente a instalação ou versão do ax. Se ax for necessário para verificação posteriormente, basta executá-lo quando chegar a hora. Se falhar, consulte references/ax-profiles.md.
4. Nunca substitua silenciosamente um ID de espaço, nome de projeto ou ID de projeto fornecido pelo usuário. Se o CLI, o coletor e a entrada do usuário discordarem, apresente essa discrepância como um bloqueador concreto.

Fase 1: Análise (somente leitura)

Não escreva nenhum código nem crie nenhum arquivo durante esta fase.

Etapas

1. Verifique os manifestos de dependência para detectar a pilha:

   • Python: pyproject.toml, requirements.txt, setup.py, Pipfile
   • TypeScript/JavaScript: package.json
   • Java: pom.xml, build.gradle, build.gradle.kts
   • Go: go.mod

2. Analise as instruções de importação nos arquivos de origem para confirmar o que está realmente sendo usado.

3. Verifique se há rastreamento/OTel existente — procure por importações TracerProvider, register(), opentelemetry, variáveis de ambiente ARIZE_*, OTEL_*, OTLP_*, ou outra configuração de observabilidade (Datadog, Honeycomb, etc.).

4. Identifique o escopo — para monorepos ou projetos multisserviço, pergunte qual(is) serviço(s) instrumentar.

O que identificar

Regra chave: Quando um framework é detectado junto com um provedor de LLM, inspecione primeiro a documentação de rastreamento específica do framework e prefira o caminho de integração nativo do framework quando ele já captura os spans do modelo e da ferramenta que você precisa. Adicione instrumentação de provedor separada apenas quando a documentação do framework exigir ou quando a integração nativa do framework deixar lacunas óbvias. Se o aplicativo executa ferramentas e a integração do framework não emite spans de ferramenta, adicione spans de FERRAMENTA manuais para que cada invocação apareça com entrada/saída (veja Enriquecendo rastros abaixo).

Saída da Fase 1

Retorne um resumo conciso:

• Linguagem detectada, gerenciador de pacotes, provedores, frameworks
• Lista de integração proposta (da tabela de roteamento na documentação)
• Qualquer OTel/rastreamento existente que precise de consideração
• Se monorepo: qual(is) serviço(s) você propõe instrumentar
• Se o aplicativo usa uso de ferramentas de LLM / chamadas de função: observe que você adicionará spans manuais de CHAIN + TOOL para que cada chamada de ferramenta apareça no rastreamento com entrada/saída (evita rastros esparsos).

…