Crie um agente de suporte ao cliente com LangGraph, chamadas de ferramentas, aprovação humana e limites de execução

A decisão de design: permita que o agente encontre, mas não finalize, um reembolso

Um agente de suporte deve poder reunir detalhes da compra e encontrar registros correspondentes sem ter permissão para emitir um reembolso por conta própria. No LangGraph, essa distinção pode ser expressa no fluxo de trabalho: encaminhe a solicitação, chame ferramentas de consulta somente leitura quando necessário e pause antes da operação de reembolso para que uma pessoa possa aprová-la ou rejeitá-la.

Este tutorial desenvolve esse padrão para a triagem de suporte ao cliente. Ele usa o LangGraph para orquestração, um modelo de chat com chamadas de ferramentas para consultas, um ponto de verificação humano antes do nó consequencial e um limite de recursão para restringir a execução do grafo. O código é um padrão a ser adaptado, não uma integração OneMux testada.

O tutorial do LangSmith fornecido para este artigo desenvolve um bot de suporte para uma loja de música digital, com subgrafos separados para consulta e reembolso. Ele descreve a extração de dados do cliente e da compra, a solicitação de informações ausentes e a avaliação das respostas finais, das trajetórias de ferramentas e das etapas individuais. Seu exemplo de reembolso usa exclusão em banco de dados e explicitamente não inclui autenticação nem outras medidas de segurança de produção. Não copie o comportamento destrutivo dessa demonstração para um sistema de suporte ativo. Leia o tutorial de avaliação de agentes complexos do LangSmith.

Pré-requisitos e limites

Instale o LangGraph e a integração relevante do LangChain para o provedor de modelo escolhido. O tutorial de origem usa langgraph e langchain[openai], mas o exemplo abaixo deixa deliberadamente a inicialização do modelo específica do provedor. Você também precisa de um banco de dados ou serviço com uma consulta de compras somente leitura e uma operação de reembolso controlada pela sua aplicação.

Antes de conectar um modelo, defina o que cada ferramenta pode fazer:

• Consulta: retorne apenas registros que o cliente autenticado tem autorização para consultar.
• Preparação do reembolso: identifique a transação e o valor exatos; não altere registros.
• Execução do reembolso: realize a ação aprovada no código da aplicação, com autorização e registro de auditoria.

Mantenha a autenticação do cliente, a autorização, a idempotência e a política de reembolso fora da discricionariedade do modelo. Um nome de cliente ou ID de fatura gerado pelo modelo não é prova de identidade.

Crie um grafo com um ponto de verificação humano

O exemplo usa um modelo com suporte a chamadas de ferramentas, uma ferramenta de consulta e um nó de reembolso separado. Substitua as funções de aplicação marcadas pelas suas próprias chamadas de serviço autorizadas. O modelo e o esquema da ferramenta precisam ser compatíveis com o endpoint configurado; a compatibilidade depende do suporte documentado ao endpoint e aos parâmetros. Este trecho não comprova que um modelo específico ou uma configuração da OneMux tenha sido testado.

from typing import Annotated, Literal

from langchain.tools import tool
from langchain_core.messages import AnyMessage
from langgraph.graph import END, START, StateGraph
from langgraph.graph.message import add_messages
from langgraph.prebuilt import ToolNode, tools_condition
from langgraph.checkpoint.memory import MemorySaver
from langgraph.types import interrupt
from typing_extensions import TypedDict

# Replace with your provider's documented LangChain model setup.
# Confirm that the chosen endpoint supports tool calling and the parameters used.
model = make_your_chat_model().bind_tools([])  # bind the tools below in your application

class State(TypedDict):
    messages: Annotated[list[AnyMessage], add_messages]
    refund_request: dict | None
    approval: str | None

@tool
def find_purchases(customer_reference: str) -> list[dict]:
    """Find purchases for an already authenticated customer."""
    return authorized_purchase_lookup(customer_reference)

tools = [find_purchases]
model = make_your_chat_model().bind_tools(tools)

def assistant(state: State):
    return {"messages": [model.invoke(state["messages"])]}

def prepare_refund(state: State):
    # Build this from validated application data, not model-invented values.
    request = build_validated_refund_request(state["messages"])
    decision = interrupt({
        "type": "refund_approval",
        "request": request,
        "instruction": "Approve or reject this exact refund request.",
    })
    if decision != "approve":
        return {"approval": "rejected", "refund_request": request}
    return {"approval": "approved", "refund_request": request}

def execute_refund(state: State):
    if state.get("approval") != "approved":
        return {"messages": [{"role": "assistant", "content": "The refund was not approved."}]}
    result = issue_refund_safely(state["refund_request"])
    return {"messages": [{"role": "assistant", "content": format_refund_result(result)}]}

builder = StateGraph(State)
builder.add_node("assistant", assistant)
builder.add_node("tools", ToolNode(tools))
builder.add_node("prepare_refund", prepare_refund)
builder.add_node("execute_refund", execute_refund)
builder.add_edge(START, "assistant")
builder.add_conditional_edges("assistant", tools_condition)
builder.add_edge("tools", "assistant")
builder.add_edge("prepare_refund", "execute_refund")
builder.add_edge("execute_refund", END)

graph = builder.compile(checkpointer=MemorySaver())

Este é um exemplo estrutural, não um grafo de roteamento completo: sua aplicação precisa encaminhar uma intenção de reembolso verificada para prepare_refund e perguntas comuns para o caminho do assistente/de consulta. A chamada interrupt() pausa o grafo e retorna o payload de aprovação ao chamador. Uma interface de revisão humana deve exibir o cliente, a transação, o valor e o contexto da política antes de enviar uma decisão. Retome a mesma thread com o mecanismo Command(resume=...) do LangGraph e o mesmo identificador de thread. Persista os pontos de verificação adequadamente; o armazenamento em memória serve para desenvolvimento, não para fluxos de trabalho de produção duráveis.

Um detalhe crucial do fluxo de controle: um interrupt é uma pausa, não um sistema de permissões. Verifique novamente o valor da aprovação no nó de execução do reembolso e garanta que o próprio serviço de reembolso valide autorização, elegibilidade da transação e solicitações duplicadas.

Limite a execução e torne as falhas visíveis

Passe um limite de recursão ao invocar o grafo. Ele limita os superpassos do grafo; não limita tokens do modelo, tempo de execução das ferramentas, custo de consultas ao banco de dados nem o número de solicitações do usuário. Defina timeouts e limites de recursos separados para chamadas de modelo e ferramentas.

from langgraph.errors import GraphRecursionError

config = {
    "configurable": {"thread_id": "support-case-123"},
    "recursion_limit": 12,
}

try:
    result = graph.invoke(
        {"messages": [{"role": "user", "content": "I need help with a purchase."}]},
        config=config,
    )
except GraphRecursionError:
    # Return a safe handoff or ask for clarification; log the trace for review.
    result = {"status": "needs_human_review"}

Escolha um limite com base no fluxo de trabalho esperado e teste tanto a conclusão normal quanto entradas propensas a loops. Evite repetir silenciosamente um grafo esgotado: as tentativas podem repetir chamadas de ferramentas, a menos que elas sejam idempotentes. Ferramentas de consulta somente leitura são mais seguras para novas tentativas do que operações com efeitos colaterais.

Avalie o caminho, não apenas a resposta

O tutorial do LangSmith fornecido identifica três objetivos úteis de avaliação: resposta final (a resposta ao cliente foi adequada?), trajetória (o agente seguiu o caminho esperado de chamadas de ferramentas?) e etapa individual (ele escolheu a ferramenta correta para uma decisão específica?). Para a triagem de reembolsos, crie casos com dados de identidade ausentes, várias compras correspondentes, uma consulta sem resultados, uma aprovação rejeitada e um reembolso aprovado.

Verifique se o agente solicita as informações necessárias em vez de inventá-las; se uma consulta não aciona um reembolso; e se a execução não pode ocorrer sem aprovação. Use serviços simulados ou de teste na avaliação para que os testes não alterem registros reais de clientes. O tutorial de origem usa um modo simulado para suas operações de banco de dados, mas descreve a própria configuração de demonstração — não uma garantia de segurança de produção.

Usando a OneMux para acessar modelos

A OneMux oferece acesso aos principais modelos de IA por meio de uma única API compatível com OpenAI. Se você deseja uma única superfície de API para acessar modelos, consulte o guia de início rápido da OneMux, a documentação da API e os modelos disponíveis. A compatibilidade com este fluxo depende do suporte documentado a chamadas de ferramentas e dos parâmetros aceitos pelo endpoint do modelo selecionado. Confirme esses detalhes antes da implantação; este artigo não afirma que o exemplo do LangGraph foi testado com a OneMux.

Limitações e solução de problemas

• O modelo não chama uma ferramenta: verifique se o endpoint selecionado oferece suporte a chamadas de ferramentas e se o esquema da ferramenta é enviado no formato documentado.
• O grafo entra em loop: inspecione as transições entre o assistente e as ferramentas, limite as etapas do grafo e garanta que um resultado de ferramenta concluído altere a próxima decisão.
• A aprovação retoma o caso errado: use um identificador de thread estável vinculado ao caso de suporte e verifique o ponto de verificação antes de retomar.
• Um reembolso é executado duas vezes: adicione idempotência no limite do serviço e registre a solicitação aprovada e o resultado.
• O agente expõe registros de outro cliente: corrija a autorização no serviço de consulta; uma instrução no prompt não é controle de acesso.

Conclusão

O LangGraph permite expressar a triagem de suporte como etapas explícitas de um fluxo de trabalho, em vez de confiar em uma única resposta do modelo para decidir e agir. Mantenha as consultas como somente leitura, pause antes dos reembolsos, valide a aprovação durante a execução e limite as etapas do grafo. Em seguida, avalie a resposta e o caminho percorrido pelo agente. Esses controles tornam o fluxo mais fácil de inspecionar, mas a segurança de produção e a aplicação das políticas continuam sendo responsabilidades da aplicação.

Fontes

• LangSmith: Avalie um agente complexo — fonte do exemplo de suporte para loja de música, da estrutura de consulta/reembolso, do modo simulado e dos três objetivos de avaliação.