A maioria dos chatbots só consegue conversar. Peça a um deles um preço na sua moeda, o status de um pedido ou a taxa de câmbio de hoje, e ele vai adivinhar ou dizer para você verificar em outro lugar. Um agente de IA que executa ações faz o contrário: ele chama uma API real no meio da conversa, lê o resultado e responde com ele.
Este guia cria um a partir de uma conta vazia, sem código. Ao final, você terá um agente que responde a perguntas com base no conhecimento que você fornece e chama uma API REST ativa durante o chat, e você verá isso acontecer no Inbox. A ação que você cria aqui é a receita principal: uma requisição HTTP descrita. Aponte-a para uma URL diferente e a mesma receita registra um lead em uma planilha, grava em um CRM ou modera um servidor de chat. Cada tutorial de integração no fim deste post é um exemplo prático dela.
Tudo abaixo foi criado e testado em um agente real. Cada conversa e chamada de API nas capturas de tela foi produzida pelo agente em execução real. Você pode reproduzir cada uma delas.
O que você vai criar
Um único agente de suporte para uma ferramenta fictícia de planejamento de projetos chamada Meridian. Ele faz duas coisas de ponta a ponta, em cerca de dez minutos:
- Responde com base em conhecimento que você fornece: planos, preços e recursos da Meridian.
- Chama uma API ativa no meio da conversa para converter um preço para a moeda do visitante, depois usa o resultado na resposta.
A ação chama a Frankfurter, uma API gratuita de câmbio que não exige chave, então você pode concluir tudo com apenas uma conta da Quickchat e sem se cadastrar em mais nada. O ponto é o padrão, não moedas: depois de criar esta ação, você criou o formato de toda integração.
O que você precisa:
- Uma conta gratuita da Quickchat AI (cadastre-se aqui).
- Nenhum código, nenhum servidor, nenhuma chave de API.
O que é um agente de IA, e como ele é diferente de um chatbot?
Um chatbot responde. Um agente responde e age. Na Quickchat, você cria um agente a partir de três partes.
As duas primeiras partes criam um chatbot. A terceira, Actions, faz dele um agente.
- Identity é quem o agente é: nome, função e instruções. Este é o AI Main Prompt.
- Knowledge é a partir do que ele responde: seus documentos, páginas e fatos.
- Actions & MCPs é o que ele pode fazer: chamar uma API durante a conversa.
As duas primeiras partes criam um bom chatbot. A terceira o transforma em um agente. Este post dedica a maior parte do tempo à terceira.
O que uma AI Action realmente é
Uma AI Action é uma requisição HTTP descrita. Você preenche a requisição uma vez (o método, a URL e os valores a enviar) e escreve uma descrição de quando usá-la. Durante uma conversa, o modelo decide se deve chamá-la e preenche as partes que você deixou abertas, a Quickchat envia a requisição, e o modelo lê a resposta.
A forma mais clara de entender por que isso é confiável é dividir todos os valores da requisição em dois tipos.
Você fixa os valores determinísticos. O modelo preenche os valores de julgamento a partir do chat. Os parâmetros são os únicos valores que ele precisa acertar.
- Valores determinísticos são aqueles que você fixa: o método, a URL, uma moeda-base. O modelo não pode errá-los porque nunca os toca.
- Valores de julgamento são aqueles que o modelo preenche a partir da conversa: qual moeda o visitante pediu, qual preço converter. Estes são os únicos valores que exigem alguma interpretação, e os únicos que você ajusta.
Você insere valores de julgamento com o menu Add AI Data, que coloca um chip {{...}} em qualquer campo. Esse menu oferece exatamente as três coisas que uma ação pode precisar buscar:
- Parameters que você define (os valores de julgamento que o modelo preenche, como
{{currency}}). - Conversation metadata que o canal define (como
{{conversation_channel}}ou{{metadata_visitor_email}}). - System Tokens: segredos que a Quickchat armazena e injeta, exibidos como um selo, nunca entregues ao modelo.
O menu Add AI Data insere um valor como chip: um parâmetro que você definiu, um valor de visitante ou conversa, ou uma variável integrada.
Os valores de metadados de conversa ficam prontos para uso sem que você precise pedi-los. Alguns que vale conhecer:
| Variable | O que contém |
|---|---|
{{conversation_channel}} | O canal em que o chat está (widget, telegram, whatsapp e assim por diante) |
{{conversation_url}} | Um link para esta conversa exata no seu Inbox |
{{language}}, {{country}} | O idioma e o país do visitante, como códigos de duas letras |
{{metadata_visitor_email}} | O e-mail do visitante, depois que ele o compartilha |
{{scenario_id}}, {{conversation_id}} | IDs deste agente e desta conversa |
Para esta ação, você só precisa do primeiro tipo (os parâmetros). Os outros importam quando você conecta um serviço real. Os guias do HubSpot e do Discord no fim usam os três.
Etapa 1: Crie o agente e dê conhecimento a ele
Cadastre-se e abra um novo agente. Na página Identity, defina o AI Agent Name como Meridian e cole isto no AI Main Prompt. Este é o campo de prompt sempre disponível que todo plano tem. Você não precisa da lista separada AI Guidelines.
As instruções do agente ficam no AI Main Prompt sempre disponível, não na lista separada AI Guidelines.
Você é o assistente de suporte da Meridian, uma ferramenta de planejamento de projetos para equipes de produto. Você responde a perguntas de visitantes no site da Meridian sobre planos, preços, recursos e primeiros passos.
Responda usando seu conhecimento. Todos os preços no seu conhecimento estão em dólares americanos (USD).
Quando um visitante perguntar quanto custa um plano ou preço em outra moeda, ou mencionar seu próprio país ou moeda local, chame a ação "Convert price to currency" com o valor em dólares americanos e o código de 3 letras da moeda de destino, depois informe tanto o preço em USD quanto o valor convertido pela taxa de hoje.
Se você não souber a resposta, diga isso de forma honesta e ofereça encaminhar a pessoa para a equipe. Nunca adivinhe.Duas linhas justificam sua presença. A linha sobre dólares americanos diz ao modelo o que os preços no conhecimento significam, para que ele saiba o que passar para a ação. A última linha, diga isso quando não souber, é o que produz uma recusa honesta em vez de um palpite. Testaremos as duas depois.
Agora dê a ele algo para responder. Na página Knowledge Base, adicione alguns artigos curtos com os fatos da Meridian. A demonstração se baseia principalmente no artigo de preços:
A Meridian tem três planos, cobrados por usuário por mês em dólares americanos (USD):
- Starter: US$ 19 por usuário por mês. Projetos ilimitados, visualizações de linha do tempo e quadro, até 3 integrações.
- Pro: US$ 49 por usuário por mês. Adiciona planejamento de sprints, dependências de tarefas, campos personalizados e integrações ilimitadas.
- Business: US$ 99 por usuário por mês. Adiciona roadmaps de portfólio, permissões avançadas, SSO e suporte prioritário.
A cobrança anual custa 17% menos que a mensal. Todos os planos começam com um teste gratuito de 14 dias, sem necessidade de cartão de crédito.
Os fatos da demonstração, adicionados como artigos curtos e marcados como Ready. O agente responde a perguntas de preços com base neles.
Isso basta para o agente responder a perguntas de preços. Deixe uma coisa de fora de propósito, uma certificação de segurança, para termos uma pergunta genuína que o agente não deve conseguir responder.
Etapa 2: A receita principal de AI Action: chame qualquer API REST
Esta é a parte reutilizável. Abra Actions & MCPs e, em Custom Actions, clique em Add Action, depois em API Action.
Em Custom Actions, Add Action lista API Action primeiro: uma requisição HTTP descrita para qualquer API REST.
Toda API Action usa o mesmo formulário, na mesma ordem. Aprenda aqui uma vez e toda receita posterior será composta pelas mesmas caixas com valores diferentes. Ele tem duas metades: o que coletar do visitante e a requisição a enviar. (Há também um caminho gerado: descreva a API em linguagem natural e deixe a Quickchat criar a ação para você, incluindo citações da documentação. Este guia é a versão manual da mesma ação, e o melhor lugar para aprender o que cada campo faz.)
Os valores a coletar
A parte superior do formulário: o API Action Name e os dois parâmetros obrigatórios que o modelo preenche, currency e amount.
API Action Name. Um nome curto que o modelo usa para se referir à ação.
Convert price to currencyWhat to ask the user first. Os valores de julgamento, uma linha para cada um. Dê a cada um um Format, um Name e uma Description que diga ao modelo como preenchê-lo, e marque-o como Required para que o modelo nunca chame a ação sem ele.
| Format | Name | Description | Required |
|---|---|---|---|
| Text | currency | O código ISO de 3 letras da moeda para a qual converter, por exemplo EUR, GBP ou JPY. Deduzir a partir da moeda ou do país mencionado pelo visitante. | yes |
| Decimal Number | amount | O valor em dólares americanos a converter, retirado do plano ou preço sobre o qual o visitante perguntou. | yes |
“What to ask the user first” é o rótulo do produto, mas o agente raramente para para perguntar. Quando o visitante escreve “quanto custa o Business em euros”, o modelo já tem os dois valores (amount a partir do seu conhecimento, currency a partir de “euros”) e os preenche diretamente.
A requisição a enviar
A requisição: um GET para a Frankfurter, com base fixada em USD e os chips currency e amount adicionados em Query Params.
API request method e endpoint URL. Um GET para o endpoint de taxas mais recentes da Frankfurter:
GET
https://api.frankfurter.dev/v1/latestQuery Params. É aqui que os valores determinísticos e de julgamento se encontram. Adicione três linhas na aba Query Params. Digite USD para a base e, para as outras duas, clique em Add AI Data e escolha os parâmetros que você definiu, o que insere os chips {{currency}} e {{amount}}.
| Key | Value |
|---|---|
base | USD |
symbols | {{currency}} |
amount | {{amount}} |
Headers e Body: nenhum. Este é um GET com tudo na query string.
API Action Description. O campo mais importante. É o que o modelo lê para decidir se deve chamar a ação, então associe-o a um sinal claro em vez de descrever o mecanismo.
Converta um valor em dólares americanos para outra moeda pela taxa de câmbio de hoje. Chame isto sempre que o visitante perguntar quanto custa um preço ou plano em uma moeda que não seja dólar americano, ou informar seu país ou moeda local. Passe o valor em dólares americanos e o código ISO de 3 letras da moeda para a qual converter.Salve e ative a ação. Essa é a receita completa: um nome, os valores a coletar, uma requisição e uma descrição.
A ação finalizada, ativada. O cartão mostra a contagem de chamadas e a taxa de sucesso rapidamente.
Nada aqui é específico de moedas. Troque a URL e a query pela sua própria API e você terá uma ação diferente.
Aponte para sua própria API
A ação da Frankfurter é uma leitura: um GET com dados públicos. Sua própria API normalmente usa o mesmo formulário com mais alguns campos preenchidos.
- Para gravar, não apenas ler, defina o método como
POST,PATCHouDELETE, e coloque os dados na aba Body como JSON. Os mesmos chips{{...}}funcionam dentro do body, então{ "email": "{{email}}" }envia o que o modelo coletou. - Para uma API que exige uma chave, adicione uma linha na aba Headers (por exemplo,
Authorization) e insira a chave com Add AI Data, escolhendo um System Token. A Quickchat armazena o segredo e o injeta no momento da chamada, então ele aparece como um selo e nunca é entregue ao modelo nem gravado no prompt. - Todo o resto é idêntico: o nome, os parâmetros a coletar e a descrição que decide quando a ação dispara.
O guia do HubSpot cria quatro ações POST dessa forma com um token OAuth injetado, e o guia do Discord cria sete contra a API do Discord com um token de bot no header. Ambos usam o mesmo formulário que você acabou de preencher, com outra URL e outro body.
Etapa 3: Teste e veja a chamada acontecer
Aqui está a viagem completa em uma imagem: o visitante pergunta, o modelo preenche os valores de julgamento, a Quickchat adiciona os valores fixos e faz a requisição, e a resposta leva o resultado de volta.
Uma chamada, de ponta a ponta: o modelo preenche os valores de julgamento, e a Quickchat adiciona os fixos e faz a requisição.
Converse com seu agente no AI Preview (no topo do menu à esquerda) ou no seu widget ativo, depois abra a conversa no seu Inbox. Faça primeiro uma pergunta simples sobre preços, depois peça o valor em outra moeda:
Visitante: Quanto custa o plano Business? Meridian: O plano Business custa US$ 99 por usuário por mês.
Visitante: Quanto é isso em euros? Meridian: O plano Business custa US$ 99 por usuário por mês, o que equivale a cerca de €86,81 por usuário por mês pela taxa de hoje.
A primeira resposta vem do conhecimento. A segunda é a ação disparando. Você não precisa confiar apenas na resposta: a conversa mostra um marcador 1 action called, e expandi-lo mostra a chamada em si.
O agente responde US$ 99 com base no conhecimento, depois converte para euros. O cartão 1 action called prova que a chamada disparou e retornou 200.
O cartão é o intermediário verificável entre a mensagem e a resposta. Ele mostra que a ação retornou 200, os valores exatos que o modelo enviou (amount: 99, currency: EUR) e a resposta que a Frankfurter devolveu. Quando você estiver criando sua própria ação, este cartão e o log de chamadas por ação (total de chamadas, taxa de sucesso, cada requisição e resposta) são onde você confirma que o agente chamou a ação certa com os valores certos, não apenas que a resposta pareceu correta.
A mesma ação lida com qualquer moeda. Peça o plano Starter em ienes japoneses e o agente chama a Frankfurter com amount: 19 e currency: JPY, depois responde que $19 é cerca de ¥3,087 pela taxa de hoje. Mesma receita, um valor diferente preenchido pelo modelo.
A mesma ação, uma moeda diferente: US$ 19 vira ¥3.087. Só o valor preenchido pelo modelo mudou.
Esse log por ação fica a um clique. Abra View logs na ação para ver todas as chamadas que ela fez: o total, a taxa de sucesso e, para cada chamada, a requisição exata e a resposta recebida.
Todas as chamadas feitas pela ação, com a requisição, a resposta e o status exatos. As duas conversões retornaram 200.
Etapa 4: Torne o agente confiável
A ação acima funciona na primeira tentativa por causa de quatro escolhas, cada uma uma alavanca que você reutilizará em toda integração.
Marque os parâmetros como obrigatórios. Tanto currency quanto amount são obrigatórios, então o modelo não consegue chamar a ação com uma requisição pela metade. Parâmetros opcionais servem para valores realmente opcionais.
Deixe a descrição decidir quando a ação dispara. O modelo lê a descrição, não o nome, para escolher a ação. Uma descrição vaga (“converte moedas”) dispara de forma imprevisível. Uma descrição ligada ao sinal (“chame isto sempre que o visitante perguntar quanto custa um preço em uma moeda que não seja dólar americano”) dispara quando deve. Quando uma ação é chamada na hora errada ou não é chamada, a descrição quase sempre é o ajuste correto.
Deixe a API fazer a aritmética, não o modelo. Uma primeira tentativa de ação de câmbio muitas vezes busca a taxa de câmbio e deixa a multiplicação para o modelo. Modelos de linguagem não são calculadoras confiáveis, e um total errado em uma pergunta de preço é pior do que nenhum total. A Frankfurter aceita um parâmetro amount e retorna o valor já convertido, então o modelo só precisa ler 86.81, nunca calculá-lo. Sempre que sua API puder retornar o valor final, prefira isso a pedir que o modelo faça a conta.
Confirme que ele diz não. Confiabilidade não é apenas disparar. Também é não inventar. Pergunte ao agente algo que seu conhecimento não cobre, a certificação de segurança que você deixou de fora:
O “não” honesto: sem nada sobre SOC 2 em seu conhecimento, o agente recusa em vez de adivinhar.
Visitante: A Meridian tem certificação SOC 2 Type II? Meridian: Não tenho informações na minha documentação sobre a Meridian ter certificação SOC 2 Type II, então não posso confirmar isso. Se você precisa de uma resposta definitiva para uma revisão de segurança ou processo de compras, recomendo entrar em contato diretamente com a equipe em support@meridian.example.
Essa recusa é a última linha do prompt fazendo seu trabalho. Um agente que chama APIs reais precisa ser confiável quanto aos limites do que sabe, então teste o “não” tão deliberadamente quanto o “sim”.
Essas quatro alavancas tornam uma ação de leitura confiável. Ações que gravam, uma devolução, um reembolso, um registro, precisam de mais: elas devem disparar apenas quando a coisa certa aconteceu, e passar um valor de forma limpa para a próxima ação. Esse é um guia próprio: torne as ações do seu agente confiáveis cobre como condicionar uma ação a regras no servidor que o chat não consegue contornar, e como levar um valor capturado adiante entre ações.
Colocando no ar
A ação pertence ao agente, não a um canal específico, então ela roda em todos os lugares onde o agente é implantado. Ative o web widget e a mesma conversão de moeda funciona para um visitante no seu site. Conecte Telegram, WhatsApp, Messenger, Slack ou Discord e ela também funciona lá, sem alterações. Não há nada por canal para refazer. Um agente implantado leva suas ações consigo.
Para onde ir agora: as integrações reais
Você criou a receita principal. Cada guia abaixo é o mesmo formato de ação apontado para um serviço real, então cada um começa de algo que você agora entende e adiciona apenas o que é específico a ele.
- Registre leads e relatórios no Google Sheets: o agente acrescenta uma linha quando uma conversa gera um lead ou um feedback.
- Crie contatos, negócios e tickets no HubSpot: um desenho de CRM apenas de escrita que preenche um registro turno a turno e nunca lê os dados de ninguém de volta.
- Modere um servidor Discord: timeout, kick e ban como AI Actions, com as ações destrutivas restritas a administradores por uma trava no servidor.
- Execute um bot de ticket de suporte no Discord: três ações encadeadas que abrem uma thread privada, adicionam o membro e notificam sua função de suporte.
- Gerencie um grupo Telegram: anuncie, fixe mensagens e modere usando linguagem natural sobre a Telegram Bot API.
- Transforme seu agente em um servidor MCP: exponha-o como uma ferramenta que ChatGPT, Claude e Cursor podem chamar.
- Execute e gerencie seu agente a partir do ChatGPT: controle o agente que você criou dentro de um cliente de IA via MCP.
A referência completa dos campos fica na documentação de AI Actions.
Perguntas frequentes
Como criar um agente de IA de graça?
Crie uma conta gratuita da Quickchat AI, dê ao agente um prompt principal curto e algum conhecimento para usar nas respostas, depois adicione uma AI Action, uma requisição HTTP descrita, para que ele possa chamar uma API durante a conversa. Criar o agente, carregar conhecimento, criar ações e ativá-las é gratuito, e todo o guia funciona no plano gratuito.
Preciso programar para criar um agente de IA?
Não. Você descreve o agente em linguagem natural e preenche um formulário de ação: um nome, os valores a coletar do visitante, o método e a URL da requisição, e uma descrição de quando chamá-la. A Quickchat envia a requisição e entrega a resposta de volta ao agente. Você nunca escreve nem hospeda código.
Quanto tempo leva para criar um agente de IA?
Cerca de dez minutos para o agente deste guia: alguns minutos para escrever o prompt e adicionar seus fatos como conhecimento, e mais alguns para preencher um formulário de AI Action. Não há nada para instalar e nenhum código para escrever.
Qual é a diferença entre um agente de IA e um chatbot?
Um chatbot responde a perguntas. Um agente de IA também executa ações: ele pode chamar uma API durante a conversa para consultar algo ou fazer uma alteração, depois usar o resultado na resposta. Na Quickchat, você cria um agente a partir de três partes: Identity (quem ele é), Knowledge (a partir do que ele responde) e Actions (o que ele pode fazer).
Um agente de IA pode usar dados ativos, em tempo real?
Sim. Toda vez que o agente chama uma AI Action, ele faz uma nova requisição, então sempre usa dados ativos. O agente deste guia busca a taxa de câmbio de hoje em cada conversão. Aponte a ação para sua própria API e ele lerá seus dados atuais da mesma forma.
O agente de IA pode chamar minha própria API?
Sim. A AI Action deste guia é uma requisição HTTP geral. Aponte-a para sua própria API REST em vez da API pública usada aqui, defina método, URL, headers e body, e descreva quando o agente deve chamá-la. A mesma receita funciona para qualquer API REST, inclusive APIs privadas protegidas por um token de autenticação.
Um agente de IA pode ter mais de uma ação?
Sim. Um agente pode ter muitas AI Actions, e escolhe a correta para cada mensagem com base nas descrições que você escreve. Este guia cria uma única ação para manter o foco. Os guias de integração adicionam várias ao mesmo agente.
ChatGPT, Claude ou Gemini podem criar um agente que executa ações?
Você pode criar o agente com a Quickchat e escolher qual modelo o alimenta. Durante uma conversa, o modelo decide quando chamar sua ação e preenche os valores a partir do chat, então o agente consulta algo ou faz uma alteração por conta própria. Você também pode expor seu agente finalizado para ChatGPT, Claude e Cursor como um servidor MCP.
O que o agente consegue fazer depois de criado?
Qualquer coisa que uma API REST possa fazer. Este guia usa uma consulta de moeda ativa, mas o mesmo formato de ação registra um lead no Google Sheets, cria um contato no HubSpot, modera um servidor Discord ou gerencia um grupo Telegram. Cada um desses casos é um exemplo prático da receita principal deste post.
Como o agente sabe quando chamar a ação?
A descrição da ação é o que o modelo lê para decidir. Associe-a a um sinal claro, por exemplo “chame isto quando o visitante pedir um preço em uma moeda que não seja dólar americano”, e marque os valores necessários como obrigatórios. Os parâmetros são os únicos valores que o modelo precisa preencher. Todo o resto na requisição é fixo.
É seguro permitir que um agente de IA chame uma API?
Você mantém o controle da requisição. Você fixa o método, a URL e quaisquer segredos (injetados pelo lado da Quickchat, nunca exibidos ao modelo), e o modelo preenche apenas os parâmetros que você define. Para ações que gravam dados, você pode condicionar a chamada a regras no servidor que o chat não consegue contornar. Os guias do HubSpot e do Discord mostram os padrões completos de segurança.
É gratuito criar e testar?
Sim. Criar o agente, adicionar conhecimento, criar e ativar AI Actions é gratuito, e todo o guia funciona no plano gratuito. Quando você estiver pronto para colocar seu agente no ar para mais visitantes, os planos pagos adicionam limites maiores e modelos mais avançados.