AgentOps: monitore e governe agentes de IA com o IBM Telemetry usando o watsonx Orchestrate

À medida que os agentes de IA se tornam mais sofisticados e autônomos, conhecer seu comportamento, desempenho e processos de tomada de decisão é crítico para garantir confiabilidade e governança. O AgentOps, a prática de monitorar, observar e gerenciar Agente de IA na produção, apresenta a visibilidade necessária para criar sistemas de IA agêntica confiáveis.

Este tutorial apresenta um guia passo a passo para configurar e usar o IBM Telemetry com watsonx Orchestrate Developer Edition para monitorar e governar agentes de IA. Você aprenderá a habilitar a observabilidade para agentes de IA e a analisar seu comportamento em profundidade, desde chamadas de LLM individuais até fluxos de trabalho multietapas completos.

Até o fim deste tutorial você será capaz de:

• Instalar e configurar o watsonx Developer Edition localmente
• Ativar a IBM Telemetry para uma observabilidade abrangente dos agentes
• Importar e testar um agente de IA pré-configurado com integração de ferramenta externa
• Analisar o comportamento dos agentes por meio de rastreios detalhados, tarefas, abrangências e fluxos de trabalho
• Depure problemas e otimize o desempenho do agente com análise de dados avançada

IBM Telemetry é o framework de observabilidade nativa do watsonx Orchestrate que captura informações detalhadas sobre como seus agentes de IA executam solicitações. Ele registra cada etapa do ciclo de vida dos agentes, desde as decisões de roteamento e a construção do prompt até invocações de LLM e chamadas de ferramentas, apresentando visibilidade completa do comportamento do agente.

Com o IBM Telemetry você pode rastrear métricas de desempenho, monitorar o custo do LLM, identificar erros e garantir que seus agentes estejam operando conforme o esperado. O IBM Telemetry proporciona observabilidade de nível corporativo projetada para ambientes de produção e sistemas de IA em grande escala.

Antes de começar, certifique-se de que os seguintes pré-requisitos estejam instalados e configurados no seu sistema:

• Python 3.8+ (Verifique com python --version )
• 16 GB de RAM mínimo
• O watsonx Orchestrate Developer Edition por meio do watsonx Orchestrate ADK

Este guia inclui etapas de instalação do ADK.

• Conta do watsonx Orchestrate Teste gratuito de 30 dias disponível, caso você ainda não tenha uma conta.
• Chave da API do watsonx Orchestrate gerada a partir do seu painel do IBM Cloud

As etapas de autorização são apresentadas posteriormente neste guia.

Para começar, duplique o repositório GitHub usando https://github.com/IBM/ibmdotcom-tutorials.git como o URL HTTPS. Para ver etapas detalhadas sobre como clonar um repositório, consulte a documentação do GitHub.

Abra o repositório no seu ambiente integrado de desenvolvimento (IDE) preferido (por exemplo, Visual Studio Code) e localize a pasta do projeto deste tutorial: wxo-agentops . Esse diretório é onde você trabalhará enquanto acompanha o avanço.

O IBM watsonx Orchestrate Agent Development Kit (ADK) é uma ferramenta CLI que simplifica a instalação, a configuração e o gerenciamento do watsonx Orchestrate Developer Edition.

Para utilizar o ADK, você precisa conectá-lo a um ambiente watsonx Orchestrate existente. Se você ainda não tem uma conta watsonx Orchestrate, pode se cadastrar para um teste gratuito de 30 dias. Se você já tem conta, poderá usá-la para informar as credenciais de ambiente necessárias para o ADK.

Essas etapas vão guiá-lo durante a instalação utilizando um ambiente virtual Python, a abordagem recomendada para manter as dependências isoladas. Para obter métodos de instalação alternativos e instruções detalhadas, consulte a documentação Introdução ao ADK.

Crie um novo ambiente virtual do Python no diretório do projeto:

Essa etapa cria uma pasta .venv contendo um ambiente Python isolado.

O comando de ativação difere dependendo do seu sistema operacional.

macOS e Linux

Windows

Após a ativação, o prompt do terminal deverá mudar para indicar que você está trabalhando dentro do ambiente virtual (normalmente mostrando (.venv ) no início do prompt).

Com seu ambiente virtual ativado, instale o ADK utilizando pip:

Esse comando baixa e instala o ADK junto com todas as suas dependências. A instalação pode levar alguns minutos para ser concluída.

Nota: Se você tiver uma versão anterior do ADK instalada (>2.0 ), execute pip install --upgrade ibm-watsonx-orchestrate . Talvez você também tenha que executar as etapas de solução de problemas na etapa 4b.

O ADK utiliza um arquivo .env para autenticar suas credenciais de usuário e configurar o watsonx Orchestrate Developer Edition. As variáveis de ambiente necessárias dependem do método de autenticação escolhido. Este tutorial utiliza o método de conta do watsonx Orchestrate, que é a abordagem mais simples para começar.

Para métodos alternativos de autenticação e instruções detalhadas de configuração, consulte a documentação sobre como configurar seu arquivo de ambiente.

Dentro do diretório wxo-agentops, crie um arquivo .env copiando o modelo informado:

Abra o arquivo .env em seu editor de texto e configure os dois campos essenciais a seguir:

• WO_INSTANCE : Esse URL é sua instância do watsonx Orchestrate. Você pode encontrar essas informações entrando na sua conta do watsonx Orchestrate e navegando até os detalhes da sua instância. Clique no ícone do seu perfil > Configurações e selecione a guia Detalhes da API. Para obter instruções detalhadas sobre como começar a utilizar a API, confira a documentação do watsonx Orchestrate.

O URL segue este formato:

Copie e cole o URL da instância de serviço para substituir o valor do modelo no seu arquivo .env. A região (por exemplo, us-south depende de sua localização geográfica).

• WO_API_KEY Esta chave é a chave da interface de programação de aplicativos do watsonx Orchestrate, que autentica sua conexão com os serviços de nuvem da IBM. Você pode gerar ou recuperar essa chave no dashboard da sua conta do IBM Cloud. Substitua <your-api-key> por sua chave de API real. Para obter instruções passo a passo sobre como gerar uma chave de API, consulte a documentação de primeiros passos.

Mantenha sua chave de API em segurança e nunca a inclua em um sistema de controle de versão. O arquivo .env já deve estar incluído em seu .gitignore para evitar exposição acidental. 

Agora você está pronto para instalar o watsonx Orchestrate Developer Edition, que executará uma instância local do servidor watsonx Orchestrate na sua máquina. Essa etapa também habilita o IBM Telemetry, dando a você acesso imediato às funcionalidades de observabilidade.

Noções básicas sobre o comando de instalação

O ADK oferece um único comando que lida com todo o processo de instalação:

Vamos analisar o que esse comando faz:

• orchestrate server start : Inicializa e inicia o servidor watsonx Orchestrate Developer Edition
• -e <path-.env-file> : aponta para seu arquivo de configuração contendo credenciais
• --with-ibm-telemetry : ativa o framework de observabilidade nativo do IBM Telemetry

Execute o comando do seu diretório wxo-agentops:

O comando a seguir inicia o servidor watsonx Orchestrate Developer Edition inicializando o ambiente do servidor: orchestrate server start -e <path-.env-file>. Adicionar o sinalizador --with-ibm-telemetry habilita o IBM Telemetry, seu framework nativo de observabilidade.

Execute este comando para instalar o servidor watsonx Orchestrate com o IBM Telemetry:

Esse comando cria contêineres internos gerenciados pelo ADK para:

• O servidor watsonx Orchestrate
• Bancos de dados PostgresSQL e Redis
• IBM Telemetry Services
• Dependências de suporte

O ADK configura automaticamente uma rede virtual que permite que esses contêiner se comuniquem entre si em http://localhost:3000.

O processo de instalação pode levar vários minutos, sobretudo na primeira execução, pois as imagens necessárias são baixadas. Uma instalação bem-sucedida produz uma saída semelhante a este exemplo:

Se você vir esta mensagem, parabéns! Seu ambiente local do watsonx Orchestrate com IBM Telemetry agora está em execução.

Se a instalação falhar ou travar, tente as seguintes etapas:

1. Reinicie o servidor:

Esse comando para e remove todos os containers criados para o watsonx Orchestrate, dando a você uma folha limpa.

2. Reinicie a instalação:

Após a redefinição, execute o comando de inicialização novamente:

3. Verifique o status do contêiner nos logs do servidor:

Você pode consultar os logs de serviço do servidor do Orchestrate para verificar avisos ou erros:

Se as etapas anteriores não funcionarem, redefina o servidor e removendo completamente o ambiente do servidor: orchestrate server purge e reinstale.

Com o servidor watsonx Orchestrate instalado, agora você precisa ativar seu ambiente local e iniciar a interface de chat onde interagirá com seus agentes de IA.

O ADK do watsonx Orchestrate é compatível com vários ambientes (local, desenvolvimento, produção etc.). Você precisa ativar explicitamente o ambiente local que você criou:

Você deve receber a confirmação de que o ambiente está ativo:

Isso define o ambiente local como seu contexto padrão para todos os comandos ADK subsequentes. Todos os agentes, ferramentas ou configurações com os quais você trabalha agora serão direcionados a essa instância local.

Inicie o serviço de interface de bate-papo do watsonx Orchestrate com o seguinte comando:

Esse comando inicializa a interface de chat baseada na web e a abre automaticamente no seu navegador padrão. Você deve ver uma saída semelhante a:

A interface de chat oferece uma maneira fácil de interagir com seus agentes de IA. Se o navegador não abrir automaticamente, você poderá navegar manualmente até http://localhost:3000/chat-lite.

Assim que a interface de chat carregar, você deverá ver uma janela de chat limpa e pronta para interação. Neste estágio, você ainda não importou nenhum agente, então a interface estará bastante vazia. Esse resultado é esperado e você adicionará seu primeiro agente na próxima etapa.

Agora que seu ambiente está configurado, é hora de importar um agente de IA pré-configurado que demonstre os recursos de monitoramento do IBM Telemetry. Esse agente meteorológico utiliza uma ferramenta de API externa para buscar dados meteorológicos em tempo real, apresentando um exemplo prático para observar e analisar.

O agente meteorológico é um ponto de partida ideal porque:

• Demonstra o uso da ferramenta: Mostra como os agentes chamam APIs externas
• Proporciona um comportamento claro e observável: cada solicitação segue um padrão previsível
• Gera dados de telemetria relevantes: Produz rastreamentos detalhados que você pode analisar no IBM Telemetry
• Inclui cenários de erro: Ajuda você a entender como a telemetria lida com falhas
• Ilustra a automação: Elimina a busca manual de dados por meio de ações do agente

Na raiz do projeto (wxo-agentops ), navegue até a pasta Weather Agent:

Esse diretório contém dois arquivos de configuração YAML:

• get_weather.yaml : Define a ferramenta de API de clima
• weather_agent.yaml : Define o agente que utiliza essa ferramenta

As ferramentas são recursos reutilizáveis que os agentes podem invocar para executar ações específicas. Importe as ferramentas get_weather primeiro:

A flag --kind openapi indica que essa ferramenta utiliza uma especificação OpenAPI para definir sua interface. Você deve ver a confirmação de que a ferramenta foi importada com sucesso.

Agora importe o agente que usará a ferramenta:

Esse comando registra o agente meteorológico no ambiente local do watsonx Orchestrate. O agente é pré-configurado com:

• Instruções sobre como interpretar dados meteorológicos
• Permissão para chamar a ferramenta get_weather
• Comportamento de fallback para locais inválidos

Retorne ao navegador onde a interface de bate-papo está em execução. Talvez seja necessário atualizar a página para ver o agente recém-importado.

Clique no menu suspenso do agente (normalmente localizado na parte superior da interface de bate-papo) e selecione Weather_Agent na lista

Com o Agente Meteorológico selecionado, tente fazer algumas perguntas para gerar dados de telemetria:

Exemplos de consultas:

• "Como está o clima na cidade de Nova York?"
• “Você pode me dizer a temperatura atual em Londres?”
• "Qual é o clima em Tóquio?"
• Está chovendo em Seattle neste momento?

O agente processará cada solicitação por meio de:

1. Entenda sua consulta
2. Extraindo a localização
3. Chamando a ferramenta get_weather com coordenadas apropriadas
4. Interpretação dos dados meteorológicos
5. Resposta em linguagem natural

Toda interação que você tem com o agente meteorológico é capturada pelo IBM Telemetry. O sistema está gravando:

• O contexto completo da conversa
• Cada invocação de LLM e o token usado
• Chamadas de ferramenta com suas entradas e saídas
• Decisões de roteamento e etapas do fluxo de trabalho
• Tempos de execução e métricas de desempenho
• Quaisquer erros ou exceções que ocorram
• Interações com fornecedores externos e seus tempos de resposta

Na próxima etapa, você explorará esses dados de telemetria em detalhes para entender exatamente como seu agente se comporta.

Agora vem a parte mais poderosa deste tutorial: utilizar o IBM Telemetry para obter visibilidade profunda do comportamento do seu agente. O IBM Telemetry disponibiliza várias visualizações e ferramentas de análise que permitem que você entenda cada aspecto de como seu agente processa as solicitações.

Abra seu navegador e navegue até https://localhost:8765/? serviceName=wxo-server. A interface oferece replays de sessão que permitem revisitar interações anteriores dos agentes para análise.

Nota: O URL utiliza https mas como esse espaço é um ambiente de desenvolvimento local, seu navegador pode mostrar um aviso de segurança sobre um certificado autoassinado. Essa mensagem é esperada e é seguro prosseguir em seu ambiente local.

Quando a tela de login for exibida, digite qualquer nome (para identificar sua sessão local) e clique em Login.

Você será direcionado para o dashboard principal do IBM Telemetry.

O dashboard mostra uma lista de rastreios recentes, cada um representando uma única interação do usuário com um agente. Clique no primeiro rastro no painel Rastreamento e Seleção de Grupo para consultar análises detalhadas sobre seu bate-papo mais recente com o Agente Meteorológico.

Essa etapa leva você à tela Agent Analytics, que serve como hub central para entender o comportamento do agente.

A tela Análise de dados do agente apresenta uma visão geral do rastreamento selecionado, incluindo:

• Estatísticas resumidas: Tempo total de execução, utilização de token, estimativas de custos e dados de benchmarking
• Informações do agente: Qual agente tratou da solicitação
• Consulta do usuário: A pergunta original feita
• Prévia da resposta: a resposta final do agente
• Indicadores de status: Sucesso, avisos ou erros

Essa visão de alto nível apresenta insights imediatos sobre se o agente teve o desempenho esperado e quão eficientemente operou.

A seção Tarefas é onde você passará a maior parte do tempo analisando o comportamento do agente. Apresenta uma linha do tempo visual, passo a passo, de tudo o que o agente fez durante uma solicitação (todas as chamadas de LLM, invocação de ferramentas, decisão de roteamento e geração de saídas).

As tarefas são organizadas hierarquicamente para refletir como o agente realmente executou o fluxo de trabalho, facilitando a compreensão da sequência das operações e seus relacionamentos.

Vamos examinar o caminho de execução padrão de uma solicitação de um agente do watsonx Orchestrate. O rastreio do Weather Agent deve mostrar uma estrutura semelhante a este exemplo:

Esse fluxo de trabalho mostra todo o ciclo de vida de uma única consulta do usuário. Veja o que cada tarefa representa:

• 0:_ROOT : O intervalo de nível superior que contém todas as tarefas secundárias. Pense nessa pasta como aquela que contém toda a execução do agente. Ele define o horário de início e de término do rastreamento completo, desde o momento em que a solicitação entra no sistema até a entrega da resposta final.

Essa abordagem é importante porque a duração da tarefa raiz indica a latência total que o usuário experimentou. Se o número for muito alto, você poderá analisar as tarefas secundárias para identificar gargalos.

• 0.0:agent_style_router : A tarefa de roteamento determina qual agente deve lidar com a mensagem e classifica a solicitação em um estilo de manuseio. O roteador analisa a requisição recebida e decide se ela requer manuseio conversacional, execução baseada em ferramentas, geração aumentada por recuperação (RAG) ou orquestração multiagente.

O roteador garante que a lógica downstream correta seja invocada. Se as solicitações estiverem sendo encaminhadas incorretamente, é aqui que você identificará o problema.

• 0.1:agent : O contexto de execução do agente principal que orquestra toda a solicitação. Essa tarefa reúne o prompt a partir das interações do sistema, do histórico de conversas e das respostas da ferramenta. Ele aplica regras e políticas de orquestração e prepara insumos para o LLM. Essa tarefa determina o tipo de chamada LLM a ser feita.

É nessa etapa que a “inteligência” da orquestração acontece. A tarefa do agente garante que o LLM receba todo o contexto necessário para tomar decisões informadas.

• 0.1.0:WatsonxChatModel.chat : A chamada real do LLM, em que ele recebe o prompt completo e decide se deve chamar uma ferramenta, pedir esclarecimento ou produzir uma resposta direta. Ele gera a resposta, em texto ou chamadas de ferramentas estruturadas.

Essa etapa é a etapa de "pensamento", em que o modelo processa informações e toma decisões. Uso de token, latência e problemas de qualidade decorrem dessa tarefa. Se o seu agente estiver lento ou tiver um custo elevado, essa etapa geralmente é a principal responsável por isso.

• 0.2:answer : A etapa final da cadeia pega a saída do LLM e a formata para entrega. Essa tarefa converte a saída bruta do LLM no formato de resposta final e aplica todas as regras de pós-processamento ou formatação. Finalmente, envia a resposta de volta à interface de chat.

Essa tarefa garante que o usuário receba uma resposta formatada corretamente. Se as respostas estiverem sendo truncadas ou formatadas incorretamente, é nesta etapa que você deverá investigar.

Resumo do fluxo de trabalho da tarefa

Para resumir todo o fluxo de trabalho:

1. O roteador decide como lidar com a solicitação
2. O agente prepara o contexto e a lógica de orquestração
3. O LLM gera as respostas ou chamadas de ferramentas
4. A resposta formata e retorna a saída final

Todo esse fluxo de trabalho é agrupado sob o contêiner de solicitações ROOT, apresentando uma visão completa da execução do agente, do início ao fim. Esse nível de observabilidade é essencial para equipes de MLOps e DevOps que gerenciam operações de agentes e pipelines complexos em escala.

Cada tarefa na hierarquia contém três categories de atributos que apresentam metadados detalhados sobre o que a tarefa consumiu e produziu:

1. Atributos de entrada: Mostra tudo o que a tarefa recebeu antes da execução: mensagens, respostas da ferramenta, instruções do sistema, o estado interno.

Exemplo: Para a tarefa WatsonxChatModel.chat,   os atributos de entrada contêm o prompt totalmente montado, com instruções do sistema, histórico da conversa e todos os resultados de ferramentas que precisam ser interpretados.

2. Atributos de saída: Mostre o que a tarefa produziu, incluindo: conclusões do LLM, chamadas de ferramentas e decisões.

Exemplo: A mesma tarefaWatsonxChatModel.chat pode ter uma produção em linguagem natural ou uma chamada de ferramenta estruturada como get_weather(latitude=40, longitude=-74) .

3. Atributos gerais: apresente metadados de telemetria: uso do token, informações de tempo, identificadores como IDs exclusivos e informações do modelo.

Exemplo: Você pode ver que uma tarefa usou 450 tokens de entrada e 120 tokens de saída, levou 1,2 segundos para ser executada e usou o ibm/granite-3.1-8b-instruct model .

Como utilizar os atributos da tarefa

Juntos, esses atributos permitem entender completamente o que o modelo viu, o que decidiu e como respondeu.

Esse nível de detalhe é de valor inestimável para depuração, otimização e validação.

Cada tarefa inclui métricas relacionadas ao desempenho e aos custos que resumem como a tarefa foi executada. Essas métricas apresentam dados quantitativos sobre o desempenho dos agentes.

As principais métricas são:

• Tempo total de execução: Quanto tempo a tarefa levou do início ao fim
• Contagem de chamadas do LLM: Quantas vezes o modelo de linguagem foi invocado
• Contagem de chamadas de ferramentas: Quantas vezes as ferramentas externas foram chamadas
• Utilização de token: token de input, token de produção e total de tokens consumidos
• Estimativa de custos: Custos aproximados com base na utilização de token (quando os dados de preços estiverem disponíveis)
• Distribuição das subtarefas: como o trabalho foi distribuído entre as subtarefas

Essas métricas ajudam a otimizar o desempenho e a depurar o comportamento do agente. Podem também ajudar na identificação de tarefas lentas que podem ser paralelizadas ou armazenadas em cache. Essa visualização é essencial para o planejamento de capacidade, pois possibilita que se conheçam os recursos necessários para escalar o sistema e acompanhar o uso de tokens para controlar os custos.

Por exemplo, se você perceber que um rastreio levou 8 segundos, mas apenas 0,5 segundo foi gasto em chamadas de LLM, sabe que o gargalo está em outro lugar (provavelmente na execução da ferramenta ou na latência da rede).

Embora as tarefas mostrem o fluxo de trabalho lógico do seu agente, os intervalos representam as operações subjacentes no nível do sistema que ocorrem durante a execução. Um clique na aba Expansões revela o que a plataforma está fazendo internamente para processar cada solicitação.

Os intervalos apresentam visibilidade sobre as etapas de execução de baixo nível registradas pelo framework de orquestração (neste caso, o LangGraph, um framework de código aberto executado dentro do wxo-server). Cada intervalo representa uma operação discreta, como:

• Encaminhamento da solicitação para o agente correto (agent_style_router )
• Invocação do agente e inicialização de seu contexto (agent.task )
• Criação de prompts e contexto a partir de modelos (ChatPromptTemplate.task )
• Chamando o LLM com o prompt montado (WatsonxChatModel.chat )
• Devolução dos resultados ao usuário (answer.task

Enquanto as tarefas mostram os passos lógicos da execução do agente (o que o agente está tentando realizar), os intervalos (spans) mostram os passos técnicos (como o sistema faz isso). Essa visão dupla oferece o conhecimento de alto nível e os recursos de depuração de baixo nível.

Exemplo: Uma única tarefa como 0.1:agent pode conter múltiplos spans representando consultas de banco de dados, consultas de cache e carregamento de configurações. Essas operações acontecem nos bastidores para apoiar a execução do agente.

Cada intervalo contém tags que apresentam metadados e contexto adicionais. Essas tags são essenciais para filtrar, depurar e analisar o desempenho dos agentes.

As etiquetas de extensão comuns são:

• Identificação do agente: agent_id, agent_name
• Rastreamento de sessão: thread_id , session_id , conversation_id
• Contexto do fluxo de trabalho: step_number , workflow_path , parent_span_id
• Dados de desempenho: token_count , duration_ms , model_name
• Detalhes da solicitação: tool_calls , input_preview , output_preview

Os intervalos são úteis para rastrear a latência, conhecer falhas vendo qual componente interno falhou, analisar padrões filtrando intervalos por tag para identificar tendências e referências cruzadas vinculando intervalos em vários rastreamentos utilizando IDs de sessão.

Por exemplo, se o seu agente travar ocasionalmente, você poderá filtrar os spans por duração para identificar quais operações internas estão levando mais tempo do que o esperado, como uma consulta ao banco de dados ou uma chamada de rede para um serviço externo.

A aba Fluxos de Trabalho apresenta uma visualização hierárquica chamada Árvore de executáveis, que mostra a estrutura de execução completa do fluxo de trabalho do seu agente. Essa visualização é especialmente útil para entender sistemas complexos multiagentes e padrões de execução aninhados.

No framework watsonx Orchestrate, um executável é uma unidade de trabalho ou tarefa que pode ser executada. Os executáveis podem ser:

• Operações simples: Uma única chamada de LLM ou invocação de ferramenta
• Fluxos de trabalho compostos: Vários executáveis encadeados
• Desvios condicionais: Diversos caminhos de execução com base em condições
• Execuções paralelas: Vários executáveis sendo executados simultaneamente

A árvore de executáveis exibe as relações pai-filho, facilitando a visualização:

• Quais tarefas acionam outras: Seguindo a cadeia de execução
• Execução paralela versus sequencial: compreensão da simultaneidade de fluxos de trabalho
• Lógica ramificada: como as decisões levam a caminhos de execução diferentes
• Profundidade do fluxo de trabalho: quão profundamente aninhada está a lógica do seu agente

Para agentes simples como o agente de clima, a visualização dos fluxos de trabalho reflete de perto a visualização da tarefa. No entanto, os fluxos de trabalho se tornam indispensáveis quando você está trabalhando com:

• Sistemas multiagentes: Vários agentes especializados colaborando em uma tarefa.
• Orquestração complexa: Agentes que escolhem dinamicamente entre diferentes ferramentas ou subagentes
• Refinamento iterativo: Agentes que repetem etapas até uma condição ser atendida
• Roteamento condicional: fluxos de trabalho que se ramificam com base em resultados intermediários
• Arquiteturas escaláveis: Projetando fluxos de trabalho que lidam com cargas do mundo real com eficiência

Por exemplo, imagine um agente que primeiro verifica se uma consulta exige pesquisa na web, depois decide entre utilizar uma ferramenta de calculadora ou uma ferramenta de consulta ao banco de dados e, finalmente, valida o resultado antes de responder. A árvore de executáveis mostraria claramente toda essa estrutura ramificada.

Você pode interagir com a árvore por meio de:

• Nós que se expandem/retraem: Concentre-se em seções específicas do fluxo de trabalho
• Clique nos nós: Acesse as informações detalhadas da tarefa
• Acompanhamento dos caminhos de execução: Acompanhe como os dados fluem pela janela
• Identificação de gargalos: Identifique onde os fluxos de trabalho ficam ineficientes

A visualização torna os fluxos de trabalho de depuração significativamente mais fáceis do que tentar seguir logs de texto ou acompanhar somente dados.

A aba Eval (avaliação) apresenta uma visão de garantia de qualidade e monitoramento que mede a correção e a confiabilidade da execução do seu agente. É nessa etapa que você deixa de observar o que aconteceu para avaliar o quão bem isso aconteceu.

A aba Eval exibe os resultados da avaliação da qualidade com base nas proteções

• Sucesso da tarefa: Quais tarefas foram concluídas e quais não foram concluídas
• Qualidade da produção: se a produção correspondeu aos esperados ou aos critérios de qualidade
• Pontuações de desempenho: Métricas quantitativas que indicam os níveis de sucesso
• Análise de erros: Categorização e gravidade das falhas
• Validação de casos de uso: se o comportamento do agente corresponde aos casos de uso pretendidos

As avaliações ajudam a monitorar a confiabilidade acompanhando a consistência com que seu agente produz resultados corretos, identificar quando mudanças degradam o desempenho do agente, priorizar melhorias e construir confiança validando que os agentes funcionam corretamente antes da implementação em produção.

Você pode utilizar as medidas de avaliação para configurar alertas, acompanhar melhorias, identificar padrões e utilizar o feedback para orientar o desenvolvimento para melhorar prompt ou ferramentas.

Se você perceber que 15% das consultas meteorológicas falham na avaliação, você pode investigar esses rastreamentos específicos para entender se o problema é o mau tratamento de inputs, falhas de API ou formatação de resposta incorreta.

A aba Problemas apresenta uma visão centralizada de todos os problemas ocorridos durante a execução do fluxo de trabalho. Essa aba é sua primeira parada na depuração de falhas de agentes ou comportamentos inesperados.

A aba Questões lista problemas como:

• Chamadas de API com falhas: Serviços externos retornando erros
• Falhas na execução da ferramenta: ferramentas que falharam ou atingiram o tempo limite
• input ausentes: Dados necessários não disponíveis quando necessário
• Exceções do modelo: erros de LLM, como limites de token ou inputs inválidas
• Erros de validação: Dados que não atendem aos formatos esperados
• Erros de tempo esgotado: operações que excederam os limites de tempo
• Falhas de tempo de execução não tratadas: Exceções inesperadas no código do agente

Na captura de tela acima há um erro de ferramenta que ocorreu quando a API de previsão do tempo retornou um erro 424 (Dependência Falhou) ou 404 (Não Encontrado). A aba de problemas mostra:

1. Tipo de erro: “Erro de ferramenta”
2. A ferramenta específica: get_weather
3. Resposta de erro: Resposta completa da API mostrando a falha
4. Direct Link: Clique para ir diretamente à tarefa em que ocorreu a falha

Essa abordagem simplifica o entendimento do que houve de errado sem vasculhar registros nem dados de rastreamento.

A aba "Problemas" é especialmente valiosa porque agrega falhas em vez de forçar você a buscar tarefas individuais. Ele apresenta um contexto completo, incluindo todos os detalhes dos erros e dados relacionados, enquanto os níveis de gravidade permitem uma triagem rápida, para você priorizar quais problemas devem ser lidar com primeiro. Os Direct Links para as tarefas de origem significam que um clique leva você ao ponto de execução exato onde as coisas deram errado.

A aba Trajetória apresenta uma visão cronológica, em formato de conversa, da interação do agente entre o usuário e quaisquer ferramentas que o agente utilize. Essa visão é inestimável para entender todo o contexto e o fluxo de comportamento dos agentes.

A visualização de trajetória é útil porque permite ver exatamente como o agente processa solicitações do início ao fim, oferecendo visibilidade completa sobre o comportamento do agente. Você pode validar a integração de ferramentas garantindo que as ferramentas sejam chamadas com os parâmetros corretos e recebam as respostas apropriadas. Depurando respostas inesperadas, a trajetória ajuda a rastrear onde a lógica divergiu de suas expectativas. Você também pode analisar como o contexto se constrói durante várias conversas, observando o fluxo de trabalho evoluir naturalmente. Além da depuração, a trajetória serve como documentação, permitindo capturar exemplos de comportamento correto que podem ser compartilhados com membros da equipe ou usados como casos de referência para desenvolvimentos futuros. Essa visão é particularmente valiosa para equipes que trabalham com IA generativa e precisam validar a adaptabilidade dos agentes em diversos cenários.

Vamos percorrer a trajetória do Agente meteorológico mostrada na captura de tela:

1.    A consulta do usuário

A conversa começa com uma solicitação clara e específica sobre o clima em Nova York.

2.    O agente faz uma chamada de ferramenta.

O agente reconhece que precisa de dados externos e invoca a ferramenta de clima:

Este exemplo mostra que o agente identificou corretamente as coordenadas aproximadas de Nova York, estruturou adequadamente a solicitação para a API e definiu a sinalização apropriada para o clima atual.

O IBM Telemetry exibe esse resultado como JSON bruto e uma visualização em árvore expansível e bem analisada.

3.    A ferramenta retorna dados

A API meteorológica responde com dados meteorológicos estruturados:

Este exemplo mostra que a ferramenta recuperou os dados com sucesso e a resposta segue o esquema esperado e todos os campos obrigatórios estão presentes. Ser capaz de inspecionar a resposta bruta da ferramenta é muito importante para depurar problemas em que o agente interpreta mal as saídas da ferramenta.

4.    O agente resume o resultado

Finalmente o agente processa os dados estruturados e responde naturalmente:

O agente extraiu corretamente o código de temperatura e clima e converteu os dados estruturados em linguagem natural. A resposta é concisa e responde à pergunta do usuário.

A aba trajetória também permite a filtragem por função para visualizar apenas as mensagens dos usuários, mensagens dos agentes ou interações com as ferramentas. Você também pode expandir e reduzir partes de conversas longas para se concentrar em detalhes importantes para você. Para uma análise ou depuração mais detalhada é possível exportar os dados como JSON para acessar tarefas vinculadas a partir de etapas de trajetória para obter os detalhes correspondentes.

Parabéns! Você configurou com sucesso o IBM Telemetry com o watsonx Orchestrate e aprendeu a monitorar e analisar em detalhes o comportamento de agentes de IA. O IBM Telemetry apresenta várias camadas de visibilidade para dar a você total observabilidade sobre como seus agentes de IA pensam, decidem e agem. Esses recursos que você explorou são fundamentais para o gerenciamento eficaz do ciclo de vida das operações do agente em produção ou integração com outros frameworks de agentes no seu ambiente.

Se encontrar problemas ou se tiver dúvidas, consulte a documentação. Os problemas mais comuns estão abordados no guia de resolução de problemas. Você também pode revisar os problemas do GitHub para ver se outras pessoas passaram por problemas semelhantes.

O monitoramento de agentes por meio de plataformas como o IBM Telemetry criou um ecossistema robusto para o AgentOps, tornando-se essencial à medida que os agentes autônomos assumem tarefas mais complexas que envolvem a integração de SDKs, ferramentas e APIs externas. A visibilidade que você obteve sobre o comportamento dos agentes permite que você crie sistemas de IA mais confiáveis, eficientes e de IA confiável.