Como monitorar agentes LangChain em produção

Você passou dias construindo seu agente LangChain. Funcionou no notebook. Você colocou em produção. Agora ele falha em 8% dos inputs e você recebe reports de usuários com erros que não consegue reproduzir localmente. Você não sabe onde na cadeia o problema está acontecendo.

Esse é o problema de observabilidade de agentes LangChain. E não é resolvido com print().

Por que logging tradicional não funciona

Uma cadeia LangChain pode ter:

• Múltiplas chamadas de LLM encadeadas
• Ferramentas com I/O complexo (web search, SQL, APIs)
• Prompts que variam dinamicamente com contexto do usuário
• Erros que aparecem no passo 7 mas têm origem no passo 2

Um log de linha única INFO: chain executed in 4.2s não te diz nada útil quando algo falha.

Opção 1: OrkaCallbackHandler (recomendado)

Instale o SDK:

pip install "orkaia[langchain]"

Adicione ao seu LLM:

import orka
from orka.integrations.langchain import OrkaCallbackHandler
from langchain_openai import ChatOpenAI

orka.init(api_key="orka_...")  # seu key em orka.ia.br → Settings → API Keys

cb  = OrkaCallbackHandler(agent_id="meu-agente")
llm = ChatOpenAI(model="gpt-4o", callbacks=[cb])

# Seu código existente — sem outras mudanças
response = llm.invoke("Resuma este artigo...")
# → Cada chamada aparece em orka.ia.br/dashboard/executions

O handler registra automaticamente:

• langchain.llm_start — modelo chamado + contagem de prompts
• langchain.llm_end — token usage da resposta
• langchain.tool_start — nome da ferramenta + input (truncado em 500 chars)
• langchain.tool_end — output da ferramenta
• langchain.tool_error — exceção, com status FAILED
• langchain.agent_action — qual ferramenta o agente escolheu e por quê
• langchain.agent_finish — output final do agente

Opção 2: @orka.guard por função

Se você quer rastrear a cadeia inteira como uma entrada única no audit trail:

import orka
from langchain_openai import ChatOpenAI

orka.init(api_key="orka_...")

@orka.guard(agent_id="meu-agente", task_type="chain_run", risk="MINIMAL")
def run_chain(user_input: str) -> str:
    chain = prompt | ChatOpenAI(model="gpt-4o") | output_parser
    return chain.invoke({"input": user_input})

# A execução completa (input, output, duração, status) fica em uma entrada
result = run_chain("Qual é o status do pedido #1234?")

O que você vê no dashboard

Para cada execução, você tem acesso a:

• Timeline de eventos: cada chamada de ferramenta na ordem exata em que aconteceu
• Input e output de cada etapa: o que entrou no LLM, o que saiu, o que foi passado para a próxima ferramenta
• Duração por etapa: identifica qual parte da cadeia está mais lenta
• Risk score: calculado automaticamente por tipo de ação
• Status: COMPLETED / FAILED / BLOCKED

Debugando falhas em produção

Quando um usuário reporta um erro, você vai em Dashboard → Execuções e filtra pelo agente. Você vê a execução exata que falhou, com o evento completo que causou o problema — sem precisar reproduzir o input localmente.

Isso é o que torna a diferença entre "demoramos 4 horas para debugar" e "encontramos em 5 minutos".

Fail-safe: nunca quebra a produção

Se a Orka estiver indisponível (rede, servidor), o callback simplesmente não registra — mas sua cadeia LangChain continua executando normalmente. Toda chamada de telemetria tem except Exception: pass. A observabilidade é best-effort, nunca um ponto de falha.

Próximos passos

Após instalar o handler, configure políticas em Dashboard → X-Shield → Policies para bloquear automaticamente tipos de ação que não deveriam acontecer em produção — como chamadas de ferramentas de escrita quando o agente está no modo de consulta.