Phase 14: Agent Engineering

OpenTelemetry Convenções semânticas GenAI

Type: Learn + Build

Languages: Python (stdlib)

Prerequisites: Phase 14 · 13 (LangGraph), Phase 14 · 24 (Observability Platforms)

Time: ~60 minutes

Objetivos de aprendizagem

• Nomear as categorias de abrangência da GenAI: modelo/cliente, agente, ferramenta.
• Distinguirinvoke_agentCLIENT vs INTERNAL e quando cada um se aplica.
• Lista dos atributos de nível superior da GenAI: nome do fornecedor, modelo de solicitação, ID da fonte de dados.
• Explicar o contrato de captura de conteúdo: optar-in, OTEL_SEMCONV_STABILITY_OPT_IN, recomendação de referência externa.

O problema

Cada fornecedor inventa seus próprios nomes de espaço. equipes de operações acabam construindo painéis de controle por quadro.

O conceito

Categoria de espaços

1. Model / client spans.Cobrir chamadas de LLM crus. emitidas pelos SDKs (Antropic, OpenAI, Bedrock) e adaptadores de modelos frameworks.
2. Agent spans. create_agent(quando o agente é construído) e invoke_agent(quando ele corre).
3. Tool spans.Uma por invocação de ferramenta; ligada ao espaço de agente pela relação pai-filho.

Nomeamento do agente span

• Nome em espanhol: invoke_agent {gen_ai.agent.name}se for nomeado; retorno a invoke_agent- Não .
• Tipo de espinha:

- CLIENT para serviços de agentes remotos (OpenAI Assistants API, Bedrock Agents).

- INTERNAL para os quadros de agentes em processo (LangChain, CrewAI, local ReAct).

Atributos-chave

• gen_ai.provider.name- Não .anthropic- Não .openai- Não .aws.bedrock- Não .google.vertex- Não .
• gen_ai.request.model Identificação do modelo.
• gen_ai.response.model o modelo resolvido (poderá diferir do pedido devido ao roteamento).
• gen_ai.agent.nameIdentificação do agente.
• gen_ai.operation.name- Não .chat- Não .completion- Não .invoke_agent- Não .tool_call- Não .
• gen_ai.data_source.id para o RAG: qual o corpus ou loja foi consultado.

Existem convenções específicas de tecnologia para Anthropic, Azure AI Inference, AWS Bedrock, OpenAI.

Captura de conteúdo

A regra padrão: as instrumentações NÃO DEVEM capturar entradas/salidas por padrão.

• gen_ai.system_instructions
• gen_ai.input.messages
• gen_ai.output.messages

Padrão de produção recomendado: armazenar conteúdo externamente (S3, a sua loja de log), registar referências em intervalos (ID de indicador, não prosa). Esta é a lição 27 de defesa contra intoxicação de conteúdo conectada à observabilidade.

Estabilidade

A maioria das convenções é experimental a partir de março de 2026.

CopyOTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental

O DataDog v1.37+ mapeia que a GenAI atribui nativamente ao seu esquema de observabilidade LLM. Outros backends (Grafana, Honeycomb, Jaeger) suportam os atributos brutos.

Onde este padrão vai mal

• Capturing full prompts in spans.Informações pessoais, segredos, dados de clientes em vestígios que podem ser lidos.
• No gen_ai.provider.name.Os painéis de multi-provedor quebram quando falta atribuição.
• Spans without parent links.Ferramentas órfãs, sempre propagam contexto.
• Not setting stability opt-in.Os seus atributos podem ser renomeados no upgrade de backend.

Construí-lo

code/main.pyImplementa um emissor de estdlib com um período de tempo correspondente às convenções da GenAI:

• Spancom esquema de atributos GenAI.
• Tracercomstart_span, contextos aninhados.
• Um agente com roteiro que emite:create_agent- Não .invoke_agent(INTERNAL), por ferramenta,chat- As chamadas de LLM.
• Um modo de captura de conteúdo que armazena pedidos externamente e registra IDs em intervalos.

• É o que é ?

Copypython3 code/main.py

Output: uma árvore de extensão com todos os atributos GenAI necessários e uma "localização externa" que mostra as referências de conteúdo de opção.

Usá-lo

• Datadog LLM Observability(v1.37+) mapas atributos nativo.
• Langfuse / Phoenix / Opik(Lessão 24) auto-instrumentar o ecossistema.
• Jaeger / Honeycomb / Grafana Tempo rastreamento bruto de OTel; criar painéis de controle a partir de atributos GenAI.
• Self-hosted executar o Colector OTel com um processador GenAI.

Envia-o

outputs/skill-otel-genai.mdOs cabos OTel GenAI se estendem a um agente existente com padrões de captura de conteúdo e armazenamento de referências externos.

Exercícios

1. Instrumenta a sua lição 01 ReAct loop com invoke_agent(INTERNAL) + extensões por ferramenta. Enviar para uma instância Jaeger.
2. Adicionar captura de conteúdo no modo "apenas referências": pedidos para SQLite, atributos span carregam apenas IDs de fila.
3. Leia a especificação para gen_ai.data_source.idEntre em sua pesquisa Memorandum de lição 9.
4. Set OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimentale verifique se os seus atributos não são renomeados pelo coletor.
5. Construir um painel de instrumentos: "qual erro de ferramenta correlaciona com quais modelos" apenas a partir dos atributos da GenAI.

Termos-chave

Mais leitura

• OpenTelemetry GenAI semantic conventions a especificação
• OpenAI Agents SDK Gênero de tempo de tempo por padrão
• AutoGen v0.4 (Microsoft Research) Espaços OTel incorporados
• Claude Agent SDK Proibição de conteúdo de rastreamento W3C

This free lesson is part of the AI Engineering from Scratch curriculum. Read the full explanation, run the lesson code, and verify the result in the interactive reader or from the repository source.

Browse the complete course catalog or open this lesson on GitHub.