Como implementar Agent Builder e Chatkit da OpenAi com Laravel

🧠 O que são o Agent Kit, o Agent Builder e o Chat Kit da OpenAI

No dia 6 de outubro, a OpenAI apresentou oficialmente o Agent Kit, um novo conjunto de ferramentas criado para facilitar a construção, integração e publicação de agentes inteligentes dentro de qualquer aplicação web.

O pacote traz dois componentes principais: Agent Builder e Chat Kit — e juntos, eles representam um salto significativo na forma como desenvolvedores podem implementar IA conversacional e fluxos multiagentes em seus sistemas.

🔧 Agent Kit – o ecossistema

O Agent Kit é um conjunto integrado de recursos e APIs oferecidos pela OpenAI para permitir que desenvolvedores criem workflows multiagentes, interfaces de chat escaláveis e aplicações inteligentes seguras de forma nativa, sem precisar de infraestrutura complexa.

Ele foi pensado para ser plugável — ou seja, você pode usá-lo tanto de forma independente quanto acoplado a ferramentas de automação que já utiliza (como n8n, Zapier ou Make).

O objetivo é centralizar a inteligência e descentralizar a execução, permitindo que seu back-end continue responsável pelas regras de negócio, enquanto a OpenAI cuida da camada cognitiva e de mensagens.

🧩 Agent Builder – o construtor de agentes

O Agent Builder é a parte do kit voltada à criação e orquestração de workflows multiagentes.

Com ele, é possível montar visualmente fluxos compostos por diversos agentes especializados, que se comunicam entre si para resolver tarefas complexas — como se fosse uma automação inteligente, mas com IA capaz de raciocinar, acessar bases de conhecimento (RAG) e interagir com ferramentas externas.

Dentro do painel do Agent Builder, o desenvolvedor pode:

• Criar nós de agentes (cada um com seu próprio prompt e propósito);
• Definir o modelo usado (GPT-4, GPT-4.1-mini, GPT-5, etc.);
• Conectar ferramentas como Google Calendar, Gmail, Drive ou APIs próprias via MCP;
• Integrar uma Vector Store para buscas contextuais (RAG);
• Adicionar GuardRails, um sistema de proteção contra prompt injections, alucinações e vazamento de dados sensíveis.

Tudo isso acontece em uma interface visual, muito mais intuitiva que escrever código manualmente para cada conexão entre agentes.

Na prática, ele não compete com automatizadores de workflow como o n8n, mas complementa — já que o workflow criado no Agent Builder pode ser consumido dentro de outras plataformas.

Em resumo: o Agent Builder é o coração lógico do Agent Kit — é nele que você ensina o comportamento dos seus agentes, define suas funções, adiciona segurança e conecta suas fontes de dados.

💬 Chat Kit – a interface conversacional pronta

O Chat Kit é o front-end do ecossistema.

Com poucas linhas de código, você consegue embedar um chat completo, idêntico à interface do ChatGPT, diretamente no seu site — e o melhor: totalmente gerenciado e escalável pela OpenAI.

Isso significa que você não precisa hospedar ou gerenciar o servidor de mensagens, pois toda a comunicação, armazenamento e processamento das conversas é feita pela própria OpenAI.

No seu front-end, você apenas inicializa o componente, configura o tema (dark/light), idioma, prompts iniciais e conecta ao workflow criado no Agent Builder.

Ou seja:

• O Agent Builder define como o agente pensa.
• O Chat Kit define onde e como o usuário interage com ele.
• E o Agent Kit é o guarda-chuva que conecta tudo de forma segura e escalável.

1) Crie o workflow

No painel da OpenAI, crie e publique um workflow no Agent Builder e copie o workflow_id (vamos usar no back-end).

2) Inclua o script do Chat Kit no

<scripts src="https://cdn.platform.openai.com/deployments/chatkit/chatkit.js"></script>

3) Adicione o componente no ponto desejado do

<openai-chatkit id="openai-chat"
  style="height:560px;width:100%;display:none"
></openai-chatkit>

💡 o display:none é um truque para evitar que o navegador faça scroll automático para o iframe do chat ao carregar.

4) Script JS no final da página (sem localStorage)

// Mostra o chat 1s após o load para evitar scroll automático
const chatkit = document.getElementById('openai-chat');
setTimeout(() => (chatkit.style.display = 'block'), 1000);

// Gera um UUID simples por visita
function genUUID() {
  if (crypto?.randomUUID) return crypto.randomUUID();
  // fallback simples
  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, c => {
    const r = (crypto.getRandomValues(new Uint8Array(1))[0] & 0x0f) >> 0;
    const v = c === 'x' ? r : (r & 0x3) | 0x8;
    return v.toString(16);
  });
}

chatkit.setOptions({
  api: {
    async getClientSecret(currentClientSecret) {
      // Se a própria SDK já nos der um secret válido, use-o
      if (currentClientSecret) return currentClientSecret;

      const userId = genUUID();

      const res = await fetch('/api/chat-kit', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'Accept': 'application/json',
        },
        body: JSON.stringify({ user_id: userId }),
      });

      if (!res.ok) {
        throw new Error(`Falha ao obter client_secret: ${res.status}`);
      }

      const data = await res.json();

      // Ajuste conforme sua resposta do back-end:
      // tente as chaves mais prováveis antes de lançar erro
      const clientSecret =
        data?.client_secret ??
        data?.session?.client_secret ??
        data?.clientSecret;

      if (!clientSecret) {
        throw new Error('Resposta sem client_secret do servidor.');
      }

      return clientSecret;
    },
  },

  // Opcional: tema/locale/tela inicial
  theme: { colorScheme: 'dark' },
  locale: 'br',
  startScreen: {
    greeting: 'Como posso te ajudar hoje?',
  },
});

5) Rota de API com throttling (Laravel)

// routes/api.php
use Illuminate\Support\Facades\Route;
use App\Http\Controllers\ChatKitController;

Route::post('/chat-kit', ChatKitController::class)
    ->middleware('throttle:1,10'); // 1 requisição a cada 10 minutos por IP

6) Controller para criar a sessão (Laravel)

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Http;

class ChatKitController extends Controller
{
    public function __invoke(Request $request)
    {
        $request->validate([
            'user_id' => 'required|uuid',
        ], [
            'user_id.required' => 'ID INVALIDO',
            'user_id.uuid'     => 'ID INVALIDO',
        ]);

        $response = Http::withHeaders([
                'Content-Type' => 'application/json',
                'OpenAI-Beta'  => 'chatkit_beta=v1',
                'Authorization'=> 'Bearer ' . config('openai.api_key'),
            ])
            ->timeout(10)
            ->retry(2, 200) // 2 tentativas com backoff de 200ms
            ->post('https://api.openai.com/v1/chatkit/sessions', [
                'workflow' => ['id' => config('openai.workflow_id')],
                'user'     => $request->user_id,
            ]);

        if ($response->failed()) {
            $response->throw();
        }

        // Retorne o JSON cru da OpenAI (ou normalize aqui se preferir)
        return $response->json();
    }
}

📌 Dica: você pode normalizar a resposta e retornar apenas { client_secret: ... } no controller para simplificar o JS.

7) Configuração mínima

.env:

OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxx
OPENAI_WORKFLOW_ID=wf_XXXXXXXXXXXXXXXXXXXXXXXX

config/openai.php (exemplo simples):

<?php

return [
    'api_key'     => env('OPENAI_API_KEY'),
    'workflow_id' => env('OPENAI_WORKFLOW_ID'),
];

Link para o repositorio: https://github.com/beerandcodeteam/chatkit-example