O agente de IA do seu site, executado pelo seu sistema

1. Liberar os agentes (uma vez por site). No Harness, clique em 🤖 Agentes e depois em ▶ Liberar. Pronto: os agentes deste site passam a usar a IA e o limite mensal de tokens de quem liberou. O botão ⏸ Desligar para todos os agentes na hora — as chaves e os agentes cadastrados ficam guardados.
2. Cadastrar o agente. Em 🤖 Agentes → ➕ Novo agente: Nome (letras minúsculas, números e _), Descrição, Instruções, Modelo (vazio usa o da IA do site), Funções (JSON), Subagentes, Segundos e Guardar conversas. Teste com ▶ Testar antes de ligar qualquer sistema externo.
3. Criar a chave da API HTTP. Ainda em 🤖 Agentes, em Chaves da API HTTP, crie uma chave com um nome — “app do celular”, “ERP”. Copie na hora: ela não aparece de novo.
4. Guardar a chave só no servidor. Ela vai no cabeçalho Authorization: Bearer SUA_CHAVE, numa chamada feita pelo servidor do outro sistema — nunca numa página de navegador nem no aplicativo instalado no celular.

O corpo de fp-agent-run aceita o nome de um agente cadastrado ("agente": "recepcionista") ou a definição completa do agente. Em entrada vão a mensagem e o identificador da conversa. Com esperar: false a resposta volta na hora com executando, para execuções longas.

curl -X POST 'https://admin.flexpage.io/api.js?cmd=fp-agent-run' \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H 'Content-Type: application/json' \
  -d '{"agente":"recepcionista","entrada":{"texto":"Vocês abrem domingo?","conversa":"app-123"}}'

{
  "status": "concluido",
  "texto": "Domingo nós fechamos. No sábado atendemos das 9h às 15h.",
  "consumo": { "entrada": 812, "saida": 96, "chamadas": 1 }
}

Exemplo com valores fictícios. A resposta traz status — concluido, requer_acao, executando, falhou ou cancelado —, texto, dados (quando o agente tem saída estruturada), acoes e consumo. Em falhou, o motivo vem em erro.

As funções são declaradas no cadastro do agente, em Funções (JSON). Cada uma tem nome, descrição (é por ela que o agente decide quando usar) e parametros — "string", "number", "integer", "boolean", "array", "object", e um ? no fim torna o campo opcional. Uma função marcada com "confirmar": true sempre pede confirmação antes de acontecer.

{
  "status": "requer_acao",
  "execucao": "exe_0001",
  "acoes": [
    {
      "id": "a1",
      "nome": "cancelar_agendamento",
      "confirmar": true,
      "argumentos": { "codigo": "ABC-123" }
    }
  ]
}

Cada item de acoes traz id, nome, argumentos e confirmar — e, quando a ação veio de um subagente, também agente. Exemplo com valores fictícios.

curl -X POST 'https://admin.flexpage.io/api.js?cmd=fp-agent-continue' \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H 'Content-Type: application/json' \
  -d '{"execucao":"exe_0001","respostas":[{"id":"a1","resultado":{"cancelado":true}}]}'

Quando a ação não foi aprovada — ou falhou no seu sistema —, use erro no lugar de resultado: {"id":"a1","erro":"O cliente não confirmou o cancelamento."}. Não esconda uma falha devolvendo sucesso: com o erro, o agente explica ao usuário em vez de inventar que deu certo.

# execução demorada: consulta com espera de 20 segundos
curl 'https://admin.flexpage.io/api.js?cmd=fp-agent-status&execucao=exe_0001&espera_segundos=20' \
  -H "Authorization: Bearer SUA_CHAVE"

# cancelar uma execução que ninguém vai continuar
curl -X POST 'https://admin.flexpage.io/api.js?cmd=fp-agent-cancel' \
  -H "Authorization: Bearer SUA_CHAVE" -H 'Content-Type: application/json' \
  -d '{"execucao":"exe_0001"}'

# ler o histórico de uma conversa
curl 'https://admin.flexpage.io/api.js?cmd=fp-agent-history&agente=recepcionista&conversa=app-123' \
  -H "Authorization: Bearer SUA_CHAVE"

# apagar o histórico de uma conversa
curl -X POST 'https://admin.flexpage.io/api.js?cmd=fp-agent-forget' \
  -H "Authorization: Bearer SUA_CHAVE" -H 'Content-Type: application/json' \
  -d '{"agente":"recepcionista","conversa":"app-123"}'

Os limites do agente são definidos no cadastro: passos, tokens e segundos (padrão de 60 segundos, máximo de 600). Com subagentes, aumente o tempo. O consumo vem somado em consumo — { entrada, saida, chamadas }.