Agentes de IA pela API

Liste os agentes do AI Hub, atualize o prompt, o modelo e o limite de tokens, veja funções, MCP e arquivos e salve mensagens no histórico da IA.

Guia10 min

Atualizado em 26/10/2026

Os agentes de IA são criados e ajustados no AI Hub. Pela API, o seu sistema mantém o agente em dia sem abrir a tela: troca o prompt quando o cardápio ou a tabela de preços muda, ajusta o modelo e o limite de tokens e consulta as funções, os servidores MCP e os arquivos ligados aos agentes. E pode contar à IA o que aconteceu fora da conversa, salvando mensagens no histórico da IA do contato.

Antes de começar

A chave de API na variável de ambiente NEXTAGS_API_KEY. Veja Autenticação com a chave de API.
Um provedor de IA conectado e um agente criado no AI Hub. Veja Conheça o AI Hub e Criar um agente de IA.

Passo a passo

Passo 1: Liste os agentes

Use Listar agentes de IA. O caminho termina com barra (/agents/), e a lista vem em data:

Listar agentes de IA

curl "https://app.nextagsai.com.br/api/agents/" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY"

const resposta = await fetch('https://app.nextagsai.com.br/api/agents/', {
  headers: {
    'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,
  },
});
const dados = await resposta.json();
console.log(resposta.status, dados);

import os

import requests

resposta = requests.get(
    "https://app.nextagsai.com.br/api/agents/",
    headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
    timeout=30,
)
print(resposta.status_code, resposta.json())

<?php
$ch = curl_init('https://app.nextagsai.com.br/api/agents/');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
    ],
]);
$dados = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($dados);

{
  "data": [
    {"id": 5001, "name": "Bia — Doce Encanto", "created_by": 10001, "created_at": "2026-10-01 12:00:00"}
  ]
}

O ID também aparece no endereço do editor do agente, no AI Hub (agent?id=5001).

Passo 2: Consulte um agente

Use Consultar agente de IA:

Consultar agente de IA

curl "https://app.nextagsai.com.br/api/agents/5001" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY"

const resposta = await fetch('https://app.nextagsai.com.br/api/agents/5001', {
  headers: {
    'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,
  },
});
const dados = await resposta.json();
console.log(resposta.status, dados);

import os

import requests

resposta = requests.get(
    "https://app.nextagsai.com.br/api/agents/5001",
    headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
    timeout=30,
)
print(resposta.status_code, resposta.json())

<?php
$ch = curl_init('https://app.nextagsai.com.br/api/agents/5001');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
    ],
]);
$dados = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($dados);

O contrato descreve só o id, o name, o created_by e o created_at. O prompt e os modelos atuais você confere no editor do agente, no AI Hub.

Passo 3: Atualize o prompt

Use Atualizar agente de IA, com o texto novo em prompt. Ele troca a Mensagem do sistema (Prompt) do agente:

Atualizar o prompt

curl -X POST "https://app.nextagsai.com.br/api/agents/5001" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Você é a Bia, da confeitaria Doce Encanto. Responda em frases curtas. Bolos de hoje: chocolate (R$ 89,90) e morango (R$ 94,90)."
  }'

const resposta = await fetch('https://app.nextagsai.com.br/api/agents/5001', {
  method: 'POST',
  headers: {
    'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    prompt: 'Você é a Bia, da confeitaria Doce Encanto. Responda em frases curtas. Bolos de hoje: chocolate (R$ 89,90) e morango (R$ 94,90).',
  }),
});
const dados = await resposta.json();
console.log(resposta.status, dados);

import os

import requests

resposta = requests.post(
    "https://app.nextagsai.com.br/api/agents/5001",
    headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
    json={
        "prompt": "Você é a Bia, da confeitaria Doce Encanto. Responda em frases curtas. Bolos de hoje: chocolate (R$ 89,90) e morango (R$ 94,90).",
    },
    timeout=30,
)
print(resposta.status_code, resposta.json())

<?php
$ch = curl_init('https://app.nextagsai.com.br/api/agents/5001');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'prompt' => 'Você é a Bia, da confeitaria Doce Encanto. Responda em frases curtas. Bolos de hoje: chocolate (R$ 89,90) e morango (R$ 94,90).',
    ]),
]);
$dados = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($dados);

A resposta traz o agente. Guarde a versão do prompt no seu sistema: assim dá para voltar à anterior. Como escrever um bom prompt: Escrever a mensagem do sistema (prompt).

Passo 4: Troque o modelo e o limite de tokens

Na mesma chamada, model leva o modelo de cada provedor (openAI, gemini, claude, xAI ou deepseek) e max_output_tokens, o limite de tokens da resposta:

Trocar o modelo

curl -X POST "https://app.nextagsai.com.br/api/agents/5001" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": {
      "openAI": "gpt-6-luna"
    },
    "max_output_tokens": 2048
  }'

const resposta = await fetch('https://app.nextagsai.com.br/api/agents/5001', {
  method: 'POST',
  headers: {
    'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: {
      openAI: 'gpt-6-luna',
    },
    max_output_tokens: 2048,
  }),
});
const dados = await resposta.json();
console.log(resposta.status, dados);

import os

import requests

resposta = requests.post(
    "https://app.nextagsai.com.br/api/agents/5001",
    headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
    json={
        "model": {
            "openAI": "gpt-6-luna",
        },
        "max_output_tokens": 2048,
    },
    timeout=30,
)
print(resposta.status_code, resposta.json())

<?php
$ch = curl_init('https://app.nextagsai.com.br/api/agents/5001');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'model' => [
            'openAI' => 'gpt-6-luna',
        ],
        'max_output_tokens' => 2048,
    ]),
]);
$dados = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($dados);

Use o nome exato do modelo, como ele aparece no AI Hub em Modelo (OpenAI), Modelo (Claude) e nos outros. A lista vem do provedor e muda com o tempo.
No editor, o Max tokens vai de 1 a 32768, e o agente novo começa com 2048.
O contrato marca os cinco provedores como obrigatórios dentro de model. Teste mandando só o provedor que você usa e confira no editor do agente se os outros ficaram como estavam.

Veja Modelo, temperatura e limite de tokens.

Passo 5: Veja as funções, os servidores MCP e os arquivos

Três chamadas listam o que os agentes podem usar, todas com a lista em data:

Listar funções dos agentes

curl "https://app.nextagsai.com.br/api/agents/functions" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY"

const resposta = await fetch('https://app.nextagsai.com.br/api/agents/functions', {
  headers: {
    'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,
  },
});
const dados = await resposta.json();
console.log(resposta.status, dados);

import os

import requests

resposta = requests.get(
    "https://app.nextagsai.com.br/api/agents/functions",
    headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
    timeout=30,
)
print(resposta.status_code, resposta.json())

<?php
$ch = curl_init('https://app.nextagsai.com.br/api/agents/functions');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
    ],
]);
$dados = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($dados);

Chamada	O que lista	Campos
Listar funções dos agentes, `GET /agents/functions`	As Funções de IA	`id`, `name`, `created_by`, `created_at`
Listar servidores MCP, `GET /agents/mcp`	Os Servidores MCP	`id`, `name`, `created_by`, `created_at`
Listar arquivos dos agentes, `GET /agents/files`	Os Arquivos (a base de conhecimento)	`id`, `name`, `size`, `url`, `created_by`, `created_at`

A API só lista: criar e ligar funções, servidores e arquivos fica no AI Hub. Veja Funções de IA, Servidores MCP no agente e Arquivos: a base de conhecimento do agente.

Passo 6: Salve mensagens no histórico da IA do contato

A IA guarda um histórico da conversa de cada contato. Use Salvar mensagens no histórico da IA para pôr nesse histórico o que aconteceu fora da conversa, como um pagamento ou uma resposta dada por outro canal, e a IA leva em conta nas próximas respostas:

Salvar mensagens no histórico da IA

curl -X POST "https://app.nextagsai.com.br/api/contacts/123456789/ai/save_messages" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "text": "O pedido PED-1001 foi pago e sai para entrega amanhã às 10h.",
        "type": "text",
        "role": "developer"
      },
      {
        "text": "Seu pedido foi confirmado, Ana! A entrega é amanhã às 10h.",
        "type": "text",
        "role": "assistant"
      }
    ]
  }'

const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/ai/save_messages', {
  method: 'POST',
  headers: {
    'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    messages: [
      {
        text: 'O pedido PED-1001 foi pago e sai para entrega amanhã às 10h.',
        type: 'text',
        role: 'developer',
      },
      {
        text: 'Seu pedido foi confirmado, Ana! A entrega é amanhã às 10h.',
        type: 'text',
        role: 'assistant',
      },
    ],
  }),
});
const dados = await resposta.json();
console.log(resposta.status, dados);

import os

import requests

resposta = requests.post(
    "https://app.nextagsai.com.br/api/contacts/123456789/ai/save_messages",
    headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
    json={
        "messages": [
            {
                "text": "O pedido PED-1001 foi pago e sai para entrega amanhã às 10h.",
                "type": "text",
                "role": "developer",
            },
            {
                "text": "Seu pedido foi confirmado, Ana! A entrega é amanhã às 10h.",
                "type": "text",
                "role": "assistant",
            },
        ],
    },
    timeout=30,
)
print(resposta.status_code, resposta.json())

<?php
$ch = curl_init('https://app.nextagsai.com.br/api/contacts/123456789/ai/save_messages');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'messages' => [
            [
                'text' => 'O pedido PED-1001 foi pago e sai para entrega amanhã às 10h.',
                'type' => 'text',
                'role' => 'developer',
            ],
            [
                'text' => 'Seu pedido foi confirmado, Ana! A entrega é amanhã às 10h.',
                'type' => 'text',
                'role' => 'assistant',
            ],
        ],
    ]),
]);
$dados = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($dados);

Cada mensagem tem text e role (os dois obrigatórios) e, se quiser, type (text, image, file ou audio):

`role`	Quando usar
`user`	Algo que o contato disse fora desta conversa, como num e-mail.
`assistant`	Algo que foi respondido ao contato fora do agente, como pelo seu sistema.
`developer`	Uma informação ou instrução para a IA levar em conta, que não é fala de ninguém.

As mensagens salvas não são enviadas ao contato: elas só entram no histórico. Nos fluxos, a ação de IA lê o histórico com Lembrar conversa em Sim, e Excluir histórico de mensagens apaga o histórico. Veja Chamar a IA no fluxo.

Pronto: como conferir

No AI Hub, abra o agente: a Mensagem do sistema (Prompt) mostra o texto novo, e os ajustes mostram o modelo e o Max tokens.
Converse com o agente e veja se ele usa o prompt novo e o que foi salvo no histórico. Veja Testar e ajustar o agente.

Se não funcionou

401 com "No valid API key provided."

A chave não chegou ou não vale. Veja Autenticação com a chave de API.

400 ao atualizar o agente

O corpo tem um erro: confira o JSON, o nome do provedor em model (openAI, gemini, claude, xAI ou deepseek) e se max_output_tokens é um número.

O agente continua com o modelo antigo

O nome do modelo não está na lista do provedor. Abra o editor do agente no AI Hub, veja os nomes em Modelo (OpenAI) e nos outros, e use um deles.

A resposta do agente sai cortada

O max_output_tokens ficou baixo para o tamanho das respostas. Aumente o valor e teste de novo.

A IA não levou em conta o que foi salvo no histórico

Confira o ID do contato e o role de cada mensagem. No fluxo, a ação de IA precisa estar com Lembrar conversa em Sim, e o histórico some quando roda Excluir histórico de mensagens. Veja Chamar a IA no fluxo.

Faça com a IA

Copie o pedido e cole no ChatGPT ou no Claude.

Leia https://docs.nextags.com.br/guias/agentes-de-ia-pela-api.md.

Quero manter o agente de IA [nome] da NexTags em dia com [a fonte, por exemplo: o cardápio do dia no meu sistema]. Escreva, em [linguagem], um script que monta o prompt com os dados atuais, atualiza o agente pelo ID com POST /agents/{agent_id}, guarda a versão anterior do prompt para eu poder voltar e, quando [evento], salva uma mensagem com role developer no histórico da IA do contato. A chave vem da variável de ambiente NEXTAGS_API_KEY.

Obrigado! Sua resposta ajuda a melhorar a central.