O editor de agentes da HubSpot por dentro: instructions, actions, knowledge, inputs e onde entra engenharia

O agent builder da HubSpot, antes chamado Breeze studio, é o editor onde se cria um agente personalizado a partir de quatro blocos de configuração: instructions, actions, knowledge e inputs. Ele está disponível nas edições Professional e Enterprise dos hubs de Marketing, Vendas, Serviço, Dados, Conteúdo e no Smart CRM, dentro do Agent Hub, cujo beta público abriu em 23 de julho de 2026. As automações e workflows do Agent Hub não consomem créditos; a execução de agentes personalizados consome HubSpot Credits, com estimativa por execução visível no editor e limite mensal configurável.

Este artigo percorre cada bloco com o detalhe que a documentação oficial descreve, e depois trata da fronteira em que o editor passa a exigir engenharia sobre a plataforma.

A anatomia de um agente

Instructions

O campo de instructions define o comportamento do agente. A documentação da HubSpot orienta uma estrutura de quatro partes: role, goal, approach e output. O exemplo oficial, de um agente de revisão de onboarding, atribui o papel (agente responsável por preparar o repasse interno após o fechamento de um negócio), o objetivo (analisar informações do cliente e resumir o que importa para o onboarding), a abordagem (revisar propriedades de contato e empresa, detalhes do negócio e atividade recente, identificar metas, produtos adquiridos, expectativa de prazo e riscos, sinalizar informação ausente) e o formato de saída em seções numeradas.

A parte mais subestimada dessas quatro é o output. Um agente sem formato de saída definido produz resultados corretos e inconsistentes entre execuções, o que inviabiliza qualquer consumo automatizado do resultado por um workflow subsequente. Quando o output do agente vai alimentar uma propriedade, uma branch condicional ou um segundo agente, ele precisa ser especificado com o mesmo rigor de um contrato de API.

Actions

As actions determinam o que o agente pode executar. O painel do editor separa em três abas:

HubSpot. Ações nativas agrupadas por tipo, como Get data, Generate e Take action, filtráveis pelo seletor de tipos.

Default. Capacidades transversais que são concedidas ou negadas por escolha explícita: navegar na web, ler registros do CRM e escrever em registros do CRM.

MCP. Conexão a sistemas externos pelo Model Context Protocol, tratada na seção seguinte.

A separação entre ler e escrever no CRM na aba Default é a decisão de desenho mais consequente do editor. Um agente com escrita habilitada altera o registro sem etapa intermediária de aprovação, e a reversão depende do histórico de propriedade, não de um mecanismo de desfazer. A prática recomendável é começar todo agente em modo de leitura e geração, validar a qualidade da saída em volume representativo e habilitar escrita apenas depois, com escopo de propriedade delimitado.

Knowledge

Knowledge é o contexto permanente do agente, disponível em toda execução sem precisar ser redefinido. As opções se dividem em Custom (knowledge vaults, os repositórios de contexto configuráveis da conta), Default (contexto já estruturado no portal, como o brand kit e os ICPs definidos nas configurações de IA) e Integrations (fontes vindas de integrações conectadas, com escopo configurável por integração).

Inputs

Inputs são os dados que variam a cada execução: um registro específico do CRM, um valor fornecido pelo usuário ou uma informação passada por outro processo. Configuram-se por tipo (por exemplo, CRM Object) e recebem um label.

A distinção entre knowledge e inputs é o ponto que mais gera erro de configuração. A regra é temporal: knowledge é permanente e vale para todas as execuções; input é fornecido no momento da execução e muda a cada uma. Um agente de qualificação carrega o critério de ICP como knowledge e recebe o contato a qualificar como input. Inverter os dois produz um agente que ou reprocessa contexto fixo a cada execução, elevando custo em créditos, ou trata como fixo um dado que deveria variar, produzindo saída errada com aparência de correta.

O cliente MCP: o que o agente alcança fora do portal

O cliente MCP da HubSpot conecta agentes do agent builder a sistemas externos pelo Model Context Protocol, sem integração customizada. Os servidores suportados hoje incluem Notion (consultar e atualizar bases e páginas), Atlassian (Jira e Confluence), Asana (tarefas, projetos e cronogramas), Zapier (disparar e monitorar automações), G2 (avaliações e comparativos de software), Linear (issues, projetos e sprints), Gong (gravações e transcrições de chamadas, menções de concorrentes, riscos de negócio) e Amplitude (análise de produto, comportamento de uso, testes A/B e feature flags).

A conexão segue dois padrões. O padrão OAuth cobre a maioria dos servidores: no editor, aba Connectors, botão Connect and add, autorização na tela. O padrão de URL tokenizada aplica-se a servidores em que o próprio usuário monta o conjunto de ferramentas, caso do Zapier: cria-se o servidor MCP no Zapier, selecionam-se as ferramentas, escolhe-se o transporte Streamable HTTP, copia-se a Server URL e cola-se no campo correspondente dentro da HubSpot.

Uma orientação da própria documentação merece destaque técnico: mesmo que a conexão MCP ofereça um catálogo amplo de ferramentas, o recomendado é selecionar apenas as necessárias para a tarefa do agente. A razão é de qualidade de decisão, não de segurança apenas. Quanto maior o número de ferramentas expostas, maior a superfície de escolha do modelo a cada passo, e maior a variância entre execuções. Agentes com escopo de ferramentas apertado são mais previsíveis e mais baratos.

Depois de conectar, as instruções de prompt precisam determinar quando e como o agente usa cada ferramenta MCP. Uma conexão sem regra de acionamento produz um agente que consulta o sistema externo em execuções que não precisavam disso, ou que deixa de consultar quando precisava.

Permissões: o que precisa estar ligado antes

O editor exige uma configuração prévia que costuma travar o primeiro teste. Um Super Admin precisa ativar, nas configurações de IA da conta, os acessos a ferramentas de IA generativa, dados do CRM, dados de conversão de cliente, dados de arquivos e acesso ao Breeze Assistant. Para criar e customizar agentes, exige-se permissão de Super Admin ou de Breeze Studio.

Há um detalhe de herança que importa em contas com governança madura: o agente pode exigir permissões adicionais conforme o objetivo. Um agente que publica uma landing page precisa que o usuário que o executa tenha permissão de edição e publicação de páginas. Se a configuração do agente depende de recursos aos quais o usuário não tem acesso, ele não consegue executar o agente, mesmo tendo permissão para editá-lo ou rodá-lo.

O controle de acesso ao agente oferece quatro modos: apenas proprietário e Super Admins editam e executam; proprietário e Super Admins editam e todos executam; todos editam e executam; ou acesso customizado por usuário e equipe, com distinção entre executar e executar mais editar.

Teste, custo e limites

O ciclo de teste dentro do editor não consome créditos, o que permite iterar instruções, knowledge e inputs até a saída ficar consistente antes de qualquer execução real. O roteiro que a documentação sugere é objetivo: verificar se o agente segue o formato esperado, se usa os dados e o contexto corretos, e identificar lacunas, imprecisões ou respostas ambíguas.

Depois do teste, o Run history mostra o custo estimado em créditos por execução, e é possível configurar limites mensais de execução para controlar quanto um agente pode consumir. As estimativas são informativas e o custo efetivo pode variar.

Esse é o elo direto entre desenho técnico e orçamento: um agente cuja instrução força varredura ampla de contexto custa mais por execução do que um agente com input preciso e knowledge enxuto, e a diferença se multiplica pelo volume de registros elegíveis.

Agentes dentro de workflows

O Agent Hub coloca agentes e workflows no mesmo canvas. Os gatilhos vão além de listas de inscrição e agendamentos: atualização de propriedade de contato, webhooks, eventos do Slack e eventos de aplicações de terceiros. As ações incluem execução em ferramentas externas como Google Sheets, Asana e Jira, ao lado das ações nativas.

Duas ações interessam particularmente a quem desenha automação. Run custom agent executa um agente já publicado na conta como um passo do workflow, o que permite reutilizar o mesmo agente em vários processos sem duplicar configuração. Add agentic step recebe um prompt customizado e inputs próprios, para quando a necessidade é pontual e não justifica um agente publicado.

O builder também aceita custom code actions, e o Breeze Assistant gera o código correspondente a partir de descrição em texto. É o ponto em que o editor no-code e a camada programável se encontram no mesmo fluxo.

Onde o editor termina e a engenharia começa

O agent builder resolve muito bem uma classe específica de problema: tarefa repetível, contexto contido no CRM ou em fontes conectadas, saída estruturada, gatilho definido. Quando os requisitos saem desse perímetro, a própria HubSpot oferece as camadas para ir além, e é aí que entra trabalho de engenharia sobre a plataforma.

Os sinais concretos dessa fronteira:

• Idempotência e reprocessamento. Quando a mesma execução pode ocorrer duas vezes e a segunda não pode duplicar o efeito, a lógica de controle precisa existir fora da instrução em linguagem natural, em custom code action ou em um app privado.

• Orquestração determinística. Fluxos com muitos ramos condicionais, ordem obrigatória entre etapas e tratamento de exceção por tipo de falha pedem estrutura explícita, não decisão do modelo a cada passo.

• Volume e latência. Processamento em lote sobre grandes conjuntos de registros, ou resposta sob restrição de tempo, exigem arquitetura pensada para isso, com uso da API e controle de fila.

• Dados fora do alcance nativo. Sistemas sem servidor MCP disponível, ERPs proprietários e bases internas exigem integração construída, com mapeamento de objetos e regra de reconciliação.

• Auditoria e conformidade. Quando cada decisão automatizada precisa de trilha, versão da instrução vigente e justificativa recuperável, o registro precisa ser projetado.

Continue lendo

• Agentes de IA na HubSpot: o que já é nativo e o que pode ser feito sob medida

• Onde a IA gera ganho de fato na operação comercial

• Conheça os Hubs e as ofertas da Reevia

Perguntas frequentes

Qual a diferença entre knowledge e inputs no agent builder da HubSpot?
Knowledge é o contexto permanente, disponível ao agente em toda execução sem ser redefinido. Inputs são fornecidos no momento da execução e variam a cada uma. Critério de ICP, brand kit e política comercial são knowledge; o registro específico a ser processado é input.

O editor de agentes está disponível em quais planos?
O agent builder está incluído nas edições Professional e Enterprise da HubSpot. Automações e workflows não consomem créditos; agentes personalizados consomem HubSpot Credits a cada ação promovida configurada, e as edições Professional e Enterprise já incluem uma cota de créditos.

Testar um agente consome créditos?
Não. O teste dentro do editor não consome créditos, o que permite iterar a configuração antes de publicar. O consumo ocorre nas execuções após a publicação.

Quais servidores MCP a HubSpot suporta hoje?
Notion, Atlassian, Asana, Zapier, G2, Linear, Gong e Amplitude, com conexão por OAuth na maioria dos casos e por URL tokenizada no caso do Zapier. Cada servidor tem requisitos e capacidades próprios.

Um agente pode escrever no CRM sem aprovação humana?
Pode, quando a ação de escrita em registros do CRM é habilitada explicitamente na aba Default. Por isso a recomendação de manter o agente em leitura e geração até a saída estar validada, e delimitar quais propriedades ele pode alterar quando a escrita for habilitada.

O que aconteceu com os custom assistants?
Foram descontinuados em 13 de julho de 2026. Os assistentes criados na própria conta ficaram em modo somente leitura e foram migrados automaticamente para projects, sem migração de mensagens de boas-vindas e iniciadores de conversa. Assistentes instalados pelo Marketplace não foram migrados.

Fontes

• HubSpot Knowledge Base: criar e customizar agentes no agent builder

• HubSpot Knowledge Base: conectar agentes a sistemas externos com o cliente MCP

• HubSpot Knowledge Base: ações de workflow no Agent Hub

• HubSpot: Agent Builder e Agent Hub

Agent Hub está em beta público. Recursos, nomenclatura e disponibilidade por edição podem mudar; confirme na documentação oficial na data da configuração.