Agentes

Agentes são as unidades operacionais do Hub: cada agente é uma configuração nomeada de um grafo do LangGraph, vinculada a uma organização, com prompt, modelo, ferramentas MCP, coleções RAG e credenciais próprias.

Esta página descreve o ciclo de vida do agente no Hub — desde a escolha do template até a edição da configuração na UI — e como ele se relaciona com os deployments do LangGraph que servem como backend de execução.

O que é um agente

No Hub, um agente é uma instância configurável de um grafo (graph) do LangGraph. O grafo define a topologia de execução (nodes, edges, ferramentas disponíveis); o agente carrega os parâmetros que personalizam essa execução para um caso de uso específico.

Cada agente expõe:

• assistant_id — identificador único do agente (UUID), retornado pelo LangGraph na criação.
• graph_id — identificador do grafo backing (ex.: oap_agent, sdr_agent).
• deploymentId — deployment do LangGraph onde o agente roda.
• name e metadata.description — exibidos no card do agente.
• config — bloco de configuração serializável que carrega prompt, modelo, ferramentas selecionadas, coleções RAG e variáveis de contexto.

A configuração é dirigida pelo schema do grafo via campos x_oap_ui_config. No grafo oap_agent, por exemplo, o schema declara campos como model, system_prompt, temperature, reasoning_effort, tools, rag, response_mode e tts_voice — cada um com um type (model_selector, textarea, slider, select, mcp, rag) que a UI do Hub usa para renderizar o campo correspondente.

Criar um agente

A criação de um agente é feita em Agents → Templates ou Agents → All agents → Create agent.

O fluxo completo de salvamento envolve quatro chamadas:

// 1. Criar o assistant no LangGraph
createAgent(deploymentId, graphId, { name, description, config });

// 2. Persistir overrides de credenciais por agente
POST /api/organizations/{orgId}/credentials/agent-overrides

// 3. Vincular credential sets a integrações
POST /api/organizations/{orgId}/credential-sets/agent-bindings

// 4. Persistir o estado de toggle por ferramenta
PUT  /api/organizations/{orgId}/agent-tools

Categorias

O Hub não usa um conceito explícito de "categoria" no domínio do agente — a organização visual de agentes acontece em três eixos:

• Template (graph_id). Agentes que rodam o mesmo grafo aparecem agrupados no mesmo card em Templates. O título do template usa _.startCase(graph_id).
• Deployment. O badge do deployment (nome configurado em NEXT_PUBLIC_DEPLOYMENTS) qualifica cada agente — o mesmo graph_id em deployments diferentes gera grupos separados.
• Configurações suportadas. Cada agente exibe badges baseadas em supportedConfigs: rag, tools (MCP) e supervisor. Esses marcadores derivam do schema do grafo, não de tags arbitrárias.

Em All agents, há um filtro de template (deploymentId:graphId) e um campo de busca por nome do agente. A combinação substitui a noção de categoria por uma filtragem dinâmica baseada em grafo + deployment.

Deployments e LangGraph

Um deployment é uma instância do LangGraph Server que serve um ou mais grafos. O Hub descobre os deployments a partir da env var NEXT_PUBLIC_DEPLOYMENTS, que aceita um array JSON com id, name, url e demais metadados.

Cada agente do Hub está vinculado a um deployment via deploymentId. Em runtime:

• O frontend do Hub injeta X-Org-Id, X-Agent-Id e X-Deployment-Id em cada chamada de chat ou tool playground.
• O LangGraph executa o grafo no deployment do agente.
• O grafo carrega ferramentas MCP via MultiServerMCPClient, montando a URL {MCP_SERVER_URL}/mcp e propagando os headers de contexto.
• Tools selecionadas (config.tools.tools[]) são filtradas dentre as tools disponíveis no MCP server da org.

Variáveis de contexto adicionais — telefone do contato, JID, lead CRM, provider do webhook — são propagadas como headers X-Contact-Phone, X-Contact-Jid, X-Contact-Name, X-Webhook-Provider e X-Crm-Lead-Id, lidos pelas tools MCP via extra.requestInfo.headers.

Para grafos versionados, o prompt é resolvido pelo Langfuse usando a convenção hub-<client_slug>-<agent_id>, com label production. A resolução tem cache de 60s e fallback para o system_prompt declarado no config do agente quando o Langfuse está indisponível.

Editar configuração via UI

Ao clicar em Edit no card de um agente, o Hub abre o mesmo formulário usado na criação, pré-preenchido com a configuração atual. Operações que ocorrem:

• O schema do grafo é refetchado para refletir mudanças no LangGraph (campos novos ganham defaults vazios).
• A UI separa modelo, configuração, ferramentas, RAG, supervisor, personas, credenciais e bindings em blocos com Separator entre eles.
• A visibilidade de campos dependentes é dinâmica: temperature é ocultada quando reasoning_effort != "none"; reasoning_effort é ocultado para providers que não suportam reasoning (atualmente OpenAI, Anthropic e OpenRouter).
• Salvar dispara o mesmo pipeline de quatro chamadas da criação — atualizando o assistant no LangGraph e re-persistindo overrides, bindings e toggles.

Agentes marcados como default assistant (criados pelo próprio sistema, não pelo usuário) não exibem o botão Edit — apenas Chat. Use isUserCreatedDefaultAssistant(agent) como referência da regra.