O Desafio da Transparência em Agentes de IA
O surgimento de agentes de inteligência artificial marca uma mudança profunda no desenvolvimento de software e na forma como as aplicações tomam decisões e interagem com usuários. Enquanto sistemas tradicionais seguem caminhos previsíveis, agentes de IA realizam raciocínios complexos que frequentemente permanecem ocultos à visão. Essa invisibilidade cria um desafio para as organizações: como confiar em algo que não conseguem visualizar completamente?
É nesse contexto que entra a observabilidade de agentes, oferecendo visibilidade profunda sobre como aplicações acionárias funcionam, interagem e executam suas tarefas. A capacidade de compreender cada etapa da execução de um agente não é apenas uma conveniência — é essencial para garantir confiabilidade, otimizar desempenho e controlar custos em produção.
Integrando Langfuse com Amazon Bedrock AgentCore
A Langfuse é uma plataforma de observabilidade e avaliação para aplicações que utilizam modelos de linguagem. Quando integrada com o Amazon Bedrock AgentCore, ela oferece visibilidade detalhada sobre o desempenho de agentes de IA, facilitando a depuração rápida de problemas e permitindo otimizações baseadas em dados reais.
O Amazon Bedrock AgentCore é uma plataforma abrangente que permite implantar e operar agentes de IA altamente capazes, de forma segura e em escala. Oferece infraestrutura propositalmente construída para cargas de trabalho dinâmicas de agentes, ferramentas poderosas para aprimorá-los e controles essenciais para implantação em ambientes reais. A plataforma funciona com diversos frameworks — incluindo CrewAI, LangGraph, LlamaIndex e Strands Agents — e com qualquer modelo de fundação, dentro ou fora do Bedrock, oferecendo flexibilidade e confiabilidade.
Como Funciona o Rastreamento com Langfuse
A Langfuse utiliza OpenTelemetry (OTEL) para rastrear e monitorar agentes implantados no Amazon Bedrock AgentCore. OpenTelemetry é um projeto da Cloud Native Computing Foundation (CNCF) que fornece especificações, APIs e bibliotecas para definir uma forma padrão de coletar traces distribuídos e métricas de uma aplicação.
Com essa integração, desenvolvedores conseguem acompanhar métricas de desempenho cruciais, incluindo uso de tokens, latência e durações de execução em diferentes fases de processamento. O sistema cria estruturas hierárquicas de rastreamento que capturam tanto respostas em streaming quanto não-streaming, com atributos detalhados de operações e estados de erro.
Através do endpoint `/api/public/otel`, a Langfuse funciona como um Backend OpenTelemetry, mapeando traces para seu modelo de dados usando convenções de IA generativa. Isso é particularmente valioso para aplicações complexas de modelos de linguagem que utilizam cadeias e agentes com ferramentas, onde traces aninhados ajudam desenvolvedores a identificar e resolver problemas rapidamente.
Além da observabilidade de agentes, a Langfuse oferece um conjunto integrado de ferramentas que abrangem todo o ciclo de vida do desenvolvimento de aplicações com IA: execução de avaliadores automatizados, organização de dados para análise de causa raiz, rastreamento de experimentos, iteração interativa em promptas e controle de versão através de gerenciamento de prompts.
Visão Geral da Solução
A solução demonstrada implanta um agente Strands no AgentCore Runtime com observabilidade Langfuse. A implementação utiliza modelos Anthropic Claude acessados através do Amazon Bedrock. Os dados de telemetria fluem do agente Strands através de exportadores OTEL até a Langfuse para monitoramento e depuração.
Os componentes-chave utilizados na solução incluem:
- Strands Agents: Framework Python para construir agentes acionários com suporte de telemetria integrado
- Amazon Bedrock AgentCore Runtime: Serviço de runtime gerenciado para hospedagem e dimensionamento de agentes na AWS
- Langfuse: Plataforma de observabilidade e avaliação de código aberto para aplicações com modelos de linguagem
- OpenTelemetry: Protocolo padrão do setor para coleta e exportação de dados de telemetria
Guia de Implementação Técnica
Pré-requisitos
Antes de começar, certifique-se de ter em mãos:
- Uma conta AWS com credenciais configuradas corretamente através do AWS CLI ou variáveis de ambiente
- Acesso a modelos Anthropic Claude 3.7 na região us-west-2
- Permissões adequadas do Amazon Bedrock AgentCore
- Python 3.10+ instalado
- Docker instalado localmente
- Uma conta Langfuse com chave de API gerada (registre-se em Langfuse cloud, crie um projeto e obtenha as chaves de API)
Passo 1: Dependências Python
Comece instalando as dependências necessárias definidas no arquivo requirements.txt:
!pip install --force-reinstall -U -r requirements.txt –quietPasso 2: Implementação do Agente
O arquivo do agente (strands_claude.py) implementa um agente de viagens com capacidades de busca na web. Aqui está a estrutura principal:
import os
import logging
from bedrock_agentcore.runtime import BedrockAgentCoreApp
from strands import Agent, tool
from strands.models import BedrockModel
from strands.telemetry import StrandsTelemetry
from ddgs import DDGS
logging.basicConfig(level=logging.ERROR, format="[%(levelname)s] %(message)s")
logger = logging.getLogger(__name__)
logger.setLevel(os.getenv("AGENT_RUNTIME_LOG_LEVEL", "INFO").upper())
@tool
def web_search(query: str) -> str:
"""
Search the web for information using DuckDuckGo.
Args:
query: The search query
Returns:
A string containing the search results
"""
try:
ddgs = DDGS()
results = ddgs.text(query, max_results=5)
formatted_results = []
for i, result in enumerate(results, 1):
formatted_results.append(
f"{i}. {result.get('title', 'No title')}\n"
f" {result.get('body', 'No summary')}\n"
f" Source: {result.get('href', 'No URL')}\n"
)
return "\n".join(formatted_results) if formatted_results else "No results found."
except Exception as e:
return f"Error searching the web: {str(e)}"
def get_bedrock_model():
region = os.getenv("AWS_DEFAULT_REGION", "us-west-2")
model_id = os.getenv("BEDROCK_MODEL_ID", "us.anthropic.claude-3-7-sonnet-20250219-v1:0")
bedrock_model = BedrockModel(
model_id=model_id,
region_name=region,
temperature=0.0,
max_tokens=1024
)
return bedrock_model
bedrock_model = get_bedrock_model()
system_prompt = """You are an experienced travel agent specializing in personalized travel recommendations with access to real-time web information. Your role is to find dream destinations matching user preferences using web search for current information. You should provide comprehensive recommendations with current information, brief descriptions, and practical travel details."""
app = BedrockAgentCoreApp()
def initialize_agent():
"""Initialize the agent with proper telemetry configuration."""
strands_telemetry = StrandsTelemetry()
strands_telemetry.setup_otlp_exporter()
agent = Agent(
model=bedrock_model,
system_prompt=system_prompt,
tools=[web_search]
)
return agent
@app.entrypoint
def strands_agent_bedrock(payload, context=None):
"""
Invoke the agent with a payload
"""
user_input = payload.get("prompt")
logger.info("[%s] User input: %s", context.session_id, user_input)
agent = initialize_agent()
response = agent(user_input)
return response.message['content'][0]['text']
if __name__ == "__main__":
app.run()Passo 3: Configuração do AgentCore Runtime
Utilize o kit de iniciação para configurar a implantação do AgentCore Runtime com o ponto de entrada, a função de execução e o arquivo de requisitos. O kit de iniciação também cria automaticamente o repositório Amazon Elastic Container Registry (ECR). Durante a etapa de configuração, o dockerfile é gerado com base no código da aplicação.
Importante: ao configurar o agente com o kit de iniciação, o AgentCore Observability é ativado por padrão. Para usar Langfuse, desative OTEL definindo o sinalizador de configuração como "True":
from bedrock_agentcore_starter_toolkit import Runtime
from boto3.session import Session
boto_session = Session()
region = boto_session.region_name
agentcore_runtime = Runtime()
agent_name = "strands_langfuse_observability"
response = agentcore_runtime.configure(
entrypoint="strands_claude.py",
auto_create_execution_role=True,
auto_create_ecr=True,
requirements_file="requirements.txt",
region=region,
agent_name=agent_name,
disable_otel=True,
)
responsePasso 4: Implantação no AgentCore Runtime
Após gerar o dockerfile, inicie o agente no AgentCore Runtime. Configure as chaves e endpoints da Langfuse no AWS Systems Manager Parameter Store para armazenamento seguro e hierárquico de dados de configuração:
import base64
otel_endpoint = "https://us.cloud.langfuse.com/api/public/otel"
langfuse_secret_key = ""
langfuse_public_key = " Passo 5: Verificação de Status da Implantação
Aguarde até que o runtime esteja pronto antes de invocar:
import time
status_response = agentcore_runtime.status()
status = status_response.endpoint['status']
end_status = ['READY', 'CREATE_FAILED', 'DELETE_FAILED', 'UPDATE_FAILED']
while status not in end_status:
time.sleep(10)
status_response = agentcore_runtime.status()
status = status_response.endpoint['status']
print(status)
statusUma implantação bem-sucedida exibe o status "READY" para o agente runtime.
Passo 6: Invocação do AgentCore Runtime
Com o runtime pronto, invoque-o com uma carga útil de teste:
invoke_response = agentcore_runtime.invoke({"prompt": "I'm planning a weekend trip to london. What are the must-visit places and local food I should try?"})Visualizando Traces na Langfuse
Após executar o agente, acesse o painel do projeto Langfuse para visualizar os traces detalhados. Os traces incluem:
- Detalhes de invocação do agente
- Chamadas de ferramentas (buscas na web)
- Interações com modelos, incluindo latência e uso de tokens
- Payloads de requisição e resposta
- Hierarquia completa de traces
A Langfuse captura todas as interações, desde requisições de usuários até chamadas individuais de modelos. Cada trace captura o caminho de execução completo, incluindo chamadas de API, invocações de funções e respostas de modelos, criando uma linha do tempo abrangente das atividades do agente. A estrutura aninhada de traces permite aos desenvolvedores investigar interações específicas e identificar gargalos de desempenho ou padrões de erro em qualquer nível da cadeia de execução.
Análise Hierárquica de Desempenho
A combinação de traces hierárquicos com marcação estratégica fornece insights profundos sobre operações de agentes, possibilitando otimizações orientadas por dados e experiências de usuário superiores. Ao investigar a hierarquia detalhada, você consegue visualizar o tempo preciso de cada operação dentro do fluxo de execução do agente. Por exemplo, uma requisição completa pode levar 26,57 segundos, com detalhamentos individuais para ciclo de evento, chamadas de ferramentas e outros componentes. Use essas informações de tempo para identificar gargalos de desempenho e reduzir tempos de resposta. Certas operações de IA podem levar mais tempo que o esperado, ou pode haver oportunidades para paralelizar ações específicas e reduzir a latência geral.
Dashboards de Monitoramento da Langfuse
A Langfuse oferece três dashboards diferentes para monitoramento: Custo, Latência e Gerenciamento de Uso. Cada um fornece perspectivas específicas sobre o desempenho e eficiência das aplicações com agentes.
Monitoramento de Custos
O monitoramento de custos ajuda a acompanhar despesas tanto em nível agregado quanto em requisições individuais, mantendo o controle sobre despesas de infraestrutura de IA. A plataforma fornece detalhamentos de custo granulares por modelo, usuário e chamada de função, permitindo que equipes identifiquem operações que consomem mais recursos e otimizem suas implementações. Essa visibilidade granular de custos facilita tomadas de decisão baseadas em dados sobre seleção de modelos, engenharia de prompts e alocação de recursos, mantendo restrições orçamentárias.
Dashboard de Latência
Métricas de latência podem ser monitoradas através de traces e gerações para otimização de desempenho. O dashboard exibe por padrão métricas como latência P95 por nível, latência máxima por ID de usuário, tempo médio até primeiro token por nome de prompt, latência P95 por modelo e tokens de saída médios por segundo por modelo. É possível criar gráficos e dashboards customizados conforme necessário.
Gerenciamento de Uso
Este dashboard apresenta métricas através de traces, observações e pontuações para gerenciar alocação de recursos. Oferece visibilidade completa sobre como os recursos estão sendo consumidos pela aplicação, ajudando equipes a otimizar a utilização e garantir eficiência operacional.
Conclusão
A integração entre Langfuse e Amazon Bedrock AgentCore oferece um caminho sólido para alcançar observabilidade completa em aplicações com agentes de IA. Com essas ferramentas, equipes conseguem rastrear desempenho em detalhes, depurar interações complexas e otimizar custos de forma contínua.
Ao implementar Langfuse com AgentCore hoje, você ganha visibilidade profunda no desempenho de seus agentes, consegue rastrear fluxos de conversação e otimizar aplicações de IA para oferecer melhor valor a seus usuários. A capacidade de compreender cada etapa da execução de um agente transforma-se em vantagem competitiva no desenvolvimento de sistemas de IA confiáveis e eficientes.
Para explorar mais sobre o tema, consulte os recursos adicionais como Perguntas frequentes sobre o Amazon Bedrock AgentCore e informações sobre integração com Amazon Bedrock AgentCore. Também há exemplos práticos disponíveis no repositório de amostras do Amazon Bedrock AgentCore no GitHub.
Fonte
Amazon Bedrock AgentCore Observability with Langfuse (https://aws.amazon.com/blogs/machine-learning/amazon-bedrock-agentcore-observability-with-langfuse/)