# 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.

Endereço: https://docs.nextags.com.br/guias/agentes-de-ia-pela-api/
Tipo: Guia

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](https://docs.nextags.com.br/comecar/autenticacao/).
- Um provedor de IA conectado e um agente criado no AI Hub. Veja [Conheça o AI Hub](https://help.nextags.com.br/tutoriais/ia/ia-hub/) e [Criar um agente de IA](https://help.nextags.com.br/tutoriais/ia/criar-agente/).

## Passo a passo

### Passo 1: Liste os agentes

Use [Listar agentes de IA](https://docs.nextags.com.br/referencia/agentes-de-ia/listar-agentes-de-ia/). O caminho termina com barra (`/agents/`), e a lista vem em `data`:

**Listar agentes de IA**

```bash
curl "https://app.nextagsai.com.br/api/agents/" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY"
```
```javascript
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);
```
```python
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
<?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);
```

```json
{
  "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](https://docs.nextags.com.br/referencia/agentes-de-ia/consultar-agente-de-ia/):

**Consultar agente de IA**

```bash
curl "https://app.nextagsai.com.br/api/agents/5001" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY"
```
```javascript
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);
```
```python
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
<?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](https://docs.nextags.com.br/referencia/agentes-de-ia/atualizar-agente-de-ia/), com o texto novo em `prompt`. Ele troca a **Mensagem do sistema (Prompt)** do agente:

**Atualizar o prompt**

```bash
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)."
  }'
```
```javascript
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);
```
```python
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
<?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)](https://help.nextags.com.br/tutoriais/ia/escrever-o-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**

```bash
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
  }'
```
```javascript
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);
```
```python
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
<?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](https://help.nextags.com.br/tutoriais/ia/modelo-e-parametros/).

### 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**

```bash
curl "https://app.nextagsai.com.br/api/agents/functions" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY"
```
```javascript
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);
```
```python
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
<?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](https://docs.nextags.com.br/referencia/agentes-de-ia/listar-funcoes-dos-agentes/), `GET /agents/functions` | As **Funções de IA** | `id`, `name`, `created_by`, `created_at` |
| [Listar servidores MCP](https://docs.nextags.com.br/referencia/agentes-de-ia/listar-servidores-mcp/), `GET /agents/mcp` | Os **Servidores MCP** | `id`, `name`, `created_by`, `created_at` |
| [Listar arquivos dos agentes](https://docs.nextags.com.br/referencia/agentes-de-ia/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](https://help.nextags.com.br/tutoriais/ia/funcoes-do-agente/), [Servidores MCP no agente](https://help.nextags.com.br/tutoriais/ia/mcp-no-agente/) e [Arquivos: a base de conhecimento do agente](https://help.nextags.com.br/tutoriais/ia/base-de-conhecimento/).

### 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](https://docs.nextags.com.br/referencia/agentes-de-ia/salvar-mensagens-no-historico-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**

```bash
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"
      }
    ]
  }'
```
```javascript
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);
```
```python
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
<?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](https://help.nextags.com.br/tutoriais/fluxos/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](https://help.nextags.com.br/tutoriais/ia/testar-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](https://docs.nextags.com.br/comecar/autenticacao/).

### 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](https://help.nextags.com.br/tutoriais/fluxos/ia-no-fluxo/).

### Faça com a IA

Cole este pedido no ChatGPT ou no Claude:

```text
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.
```