Dukk API — Documentação

Sessões, conversas e streaming SSE

Uma sessão é o agente vivo em execução; uma conversa é o histórico persistido. Você cria a sessão, manda mensagens e acompanha o trabalho em tempo real — token a token, tool a tool.

Como funciona

A resposta é entregue por Server-Sent Events: chegam deltas de texto, início e fim de cada chamada de ferramenta, pedidos de permissão e o evento de turno concluído. Se um turno já está rodando, a mensagem seguinte entra em fila em vez de ser recusada.

Detalhes que importam

Plan mode — o agente propõe um plano e espera aprovação antes de executar.
Permissões — modos ask, writer e agent definem o que roda sem perguntar. Em ask, o turno pausa e aguarda sua decisão.
Perguntas ao usuário — o modelo pode pausar e devolver alternativas para você escolher, retomando de onde parou.
Compactação — histórico longo é resumido automaticamente para caber na janela do modelo.

Rotas

POST /v1/sessions POST /v1/sessions/{id}/messages GET /v1/sessions/{id}/events GET /v1/sessions/{id}/permissions/pending POST /v1/permissions/{request_id}/decide POST /v1/sessions/{id}/questions/answer GET /v1/conversations

Modelos e provedores

O mesmo agente roda sobre provedores diferentes, sem mudar código. Troque o modelo por chamada, por sessão ou por padrão da conta.

Provedores suportados: Anthropic, OpenAI, xAI, DeepSeek direto, OpenCode (Go e Zen), Ollama e LM Studio para modelos locais, além de Bedrock, Vertex e Foundry. Um prefixo no nome do modelo escolhe a rota — deepseek:, ollama:, go:, zen:.
Credenciais: Resolvidas em ordem: variável de ambiente, Keychain do sistema, arquivo de credenciais e importação automática do Claude Code. A chave da DeepSeek é escolhida por requisição, a partir do domínio público que atendeu a chamada — ambientes internos e de produção não compartilham cota.
Rotas: GET /v1/models GET /v1/providers POST /v1/auth/api-key POST /dukk/compat/v1/chat/completions

/v1/chat/completions é compatível com o formato OpenAI: SDKs e ferramentas existentes funcionam apontando a base URL para o Dukk.

Ferramentas 139 no catálogo

O agente age através de ferramentas — ler e escrever arquivos, rodar comandos, navegar, consultar sistemas internos. O catálogo é declarativo e a seleção é semântica: o modelo recebe as ferramentas relevantes ao pedido, não as 139.

Famílias

Arquivos e shell — leitura, escrita, edição, busca por padrão e por conteúdo, execução de comandos.
Navegador — navegação, captura de tela, clique, extração de conteúdo e execução de scripts.
CRM e ERP — CRM interno, RD Station e Protheus (TOTVS) expostos como ferramentas.
Agentes — planejar, publicar, listar e remover agentes Agno; ligar e desligar canais de mensageria.
Kanban — criar quadros, enfileirar tarefas e aplicar mudanças propostas.
Aprendizado — registrar preferências e decisões que persistem entre conversas.

Protocolo de duas chamadas

Operações sensíveis seguem o mesmo desenho: a primeira chamada (planejar_*) devolve o catálogo real de recursos, para o modelo escolher identificadores que existem em vez de inventá-los; a segunda (publicar_*, conectar_*) só executa com confirmado=true, depois de você ver o que será feito.

Rotas

GET /v1/tools POST /v1/tools/exec

Escrita disciplinada SWD

Toda alteração de arquivo passa por uma camada que registra, versiona e permite desfazer — o agente não escreve no seu disco sem rastro.

Níveis

off — sem interceptação.
partial (padrão) — cada escrita gera snapshot SHA-256, com rollback e registro em log de auditoria.
full — as ferramentas de escrita são bloqueadas; o modelo emite blocos de ação que são aplicados transacionalmente, tudo ou nada.

Sandboxes por usuário

Comandos e código do agente rodam dentro de uma máquina isolada, não no servidor. Cada usuário tem a sua, com disco que sobrevive entre sessões.

Como funciona: O /workspace é um volume nomeado dedicado ao sandbox, criado de forma idempotente no boot e removido junto com ele. Sandboxes ociosas são recolhidas automaticamente, com teto de tempo de vida — instância parada não consome recurso indefinidamente.
Rotas: POST /v1/sandboxes GET /v1/sandboxes DELETE /v1/sandboxes/{id} GET /v1/sandboxes/{id}/files

Navegador headless e preview ao vivo

O agente abre páginas, clica, preenche e extrai conteúdo — e você assiste a isso acontecendo, em tempo real.

Como funciona: O motor de navegação roda como serviço dedicado, compartilhado entre sessões e isolado por usuário no protocolo. Ligando o preview, cada ação que altera a página dispara uma captura JPEG enviada por WebSocket (800 px, ~30–50 KB). Os quadros são efêmeros: nunca são gravados.
Rotas: POST /v1/sessions/{id}/browser/preview/start GET /v1/sessions/{id}/browser/preview/ws POST /v1/sessions/{id}/browser/preview/stop

Mensageria — Telegram, Slack e WhatsApp

Conecte um bot e fale com o agente pelo aplicativo de mensagem. Uma mensagem recebida roda um turno completo — mesmo histórico, mesmas ferramentas do desktop — e a resposta volta pelo mesmo chat.

Plataformas

Telegram — webhook ou long polling (o único com polling, o que viabiliza desenvolvimento atrás de NAT).
Slack — Events API, com verificação de assinatura e resposta ao desafio de URL.
WhatsApp Business — Cloud API, com verificação de assinatura e challenge de verificação.

Quem pode falar com o bot

Todo chat novo nasce pendente e não roda nada até o dono aprovar — qualquer pessoa pode escrever para um bot, e o turno sai da cota de quem o conectou. Em grupos, o padrão é responder apenas quando mencionado.

Garantias de entrega

As plataformas reenviam quando não recebem confirmação rápida. Uma chave de deduplicação por canal e mensagem converte esse ao menos uma vez em exatamente uma vez do lado do agente. Envios interrompidos no meio são reentregues com marcação visível, nunca duplicados em silêncio.

Por que uma mensagem não teve resposta

Todo evento ignorado guarda o motivo — chat não aprovado, sem menção em grupo, mensagem do próprio bot, limite por minuto ou teto diário, mídia sem legenda. A pergunta é respondível sem adivinhação.

Rotas

GET /v1/messaging/platforms POST /v1/messaging/channels GET /v1/messaging/channels/{id}/chats POST /v1/messaging/chats/{id}/authorize

Agentes Agno e vínculo com canal

Desenhe um agente conversacional a partir de um briefing em linguagem natural, publique-o de verdade e — se quiser — coloque-o para atender um canal de mensageria.

Do briefing ao agente publicado: A ferramenta de planejamento devolve o registro real de ferramentas disponíveis, e a configuração é validada antes de virar rascunho. A publicação cria o agente na instância dedicada, gera as credenciais de acesso e registra tudo — ou reverte por inteiro em caso de falha.
Agente atendendo no canal: Vinculado, o agente passa a responder como @seu_bot no Telegram e no Slack, ou pelo número no WhatsApp. O canal continua dono da fila, da deduplicação, do anti-loop, da aprovação de chats e dos limites — só a geração da resposta muda de lugar. O histórico continua na mesma conversa, então a busca segue encontrando.
Rotas: PUT /v1/messaging/channels/{id}/agent DELETE /v1/messaging/channels/{id}/agent

Desligar o vínculo não silencia o canal: ele volta a ser atendido por um turno do próprio Dukk.

Kanban multiagente

Quadros onde cada cartão pode virar trabalho de um agente. Útil para dividir uma tarefa grande entre execuções paralelas e revisar o resultado antes de aplicar.

Detalhes: Cartões despachados são reivindicados por um trabalhador de cada vez, com renovação de posse enquanto executa — se o processo morre, o cartão volta para a fila em vez de ficar preso. Mudanças propostas ficam em área de preparação para revisão antes de serem aplicadas. Eventos do quadro chegam por streaming.
Rotas: GET /v1/kanban/boards POST /v1/kanban/boards/{id}/cards GET /v1/kanban/boards/{id}/events

Busca no histórico de conversas

Busca textual sobre tudo o que foi dito nas suas conversas, com trechos destacados.

Como funciona: Índice de texto com stemming em português — buscar "integração" também encontra "integrações", "integrar". A sintaxe é a de buscador comum: aspas para frase exata, hífen para excluir termo. Consulta malformada devolve resultado vazio, nunca erro.
Escopo: Sempre restrita ao dono da conversa — inclusive para a equipe interna. Busca devolve trecho de conteúdo, e é o caminho clássico de vazamento entre contas; não há parâmetro que amplie esse escopo.
Rotas: GET /v1/search/messages

Skills, plugins e rotinas

Skills são instruções reutilizáveis que o agente carrega quando o assunto aparece. Rotinas executam trabalho no horário marcado, sem ninguém presente.

Skill Store: Catálogo unificado com skills embarcadas, trazidas por plugins e criadas por você. A seleção é semântica: a cada turno, as mais próximas do que você pediu são oferecidas ao modelo. Skills podem ser publicadas para revisão e aprovadas para uso coletivo.
Rotinas: Execuções agendadas em formato cron, com histórico de execução.
Rotas: GET /v1/skill-store POST /v1/skill-store/import GET /v1/skill-store/pinned GET /v1/routines GET /v1/plugins

Índice semântico e embeddings

O que torna possível "encontre a ferramenta certa" e "sugira a skill que serve aqui" sem lista fixa.

Provedores de embedding: Jina (padrão, 1024 dimensões, multimodal) e fastembed local, que roda dentro do processo — sem rede, sem cota, sem chave. Se o provedor configurado estiver indisponível, o servidor cai automaticamente no local em vez de ficar sem busca semântica.
Coleções por dimensão: Vetores de modelos diferentes não são comparáveis, então cada dimensão tem seu próprio espaço. Trocar de provedor não renomeia nada nem exige migração, e é reversível a qualquer momento.

Aprendizado entre conversas

Preferências e decisões que você deu uma vez continuam valendo nas próximas conversas, sem precisar repetir.

Rotas: GET /v1/learning/memory GET /v1/learning/skills

Artifacts, uploads e PDF

Arquivos que o agente produz ficam guardados e acessíveis; arquivos que você envia são lidos e usados como contexto.

Detalhes: Uploads têm o conteúdo extraído conforme o tipo — texto, planilha, documento, PDF, imagem. A geração de PDF é nativa, sem depender de navegador. Documentos DOCX e apresentações também são geráveis por ferramenta.
Rotas: GET /v1/artifacts POST /v1/uploads/extract POST /v1/tools/pdf_generate

Conectores OAuth e MCP

Ligue contas de terceiros uma vez e o agente passa a agir nelas. Servidores MCP adicionam ferramentas de fora sem alterar o Dukk.

Conectores: Fluxo OAuth com renovação automática de token. As credenciais são cifradas em repouso e nunca retornam em resposta de API.
MCP: Servidores registrados pelo usuário têm as ferramentas descobertas e incorporadas ao catálogo, participando da mesma seleção semântica das nativas.
Rotas: GET /v1/connectors GET /v1/connectors/{id}/authorize GET /v1/mcp/servers

Autenticação Zitadel

O acesso de usuários e organizações é feito com Zitadel como provedor de identidade. Integrações programáticas usam chave de API.

Formas de autenticar

JWT do Zitadel — usuários do aplicativo e do painel. Os claims do token trazem a organização e o papel, que determinam o que aparece.
Chave de API — integrações e automações, com escopos por chave.
Bearer local — uso headless na própria máquina, via loopback.

Organizações e papéis

A organização vem do token e define o isolamento entre contas. O papel de equipe interna é derivado dos claims, não de configuração local.

Capacidades por plano

Funcionalidades sensíveis são liberadas por capacidade — escolher modelo, agente na nuvem, controle remoto, sandboxes, mensageria, entre outras. O padrão é negar: capacidade não concedida não aparece nem responde.

Rotas

GET /v1/me GET /v1/auth/status POST /v1/auth/api-key

Painel administrativo

Operação da plataforma para a equipe interna: quem entra, o que está acontecendo e o que precisa de revisão.

O que cobre: Convites e lista de espera, gestão de usuários e planos, registros de execução do servidor, fila de revisão da skill store, atalhos de boas-vindas, distribuição do aplicativo e variáveis de ambiente das máquinas.
Rotas: GET /v1/admin/users GET /v1/admin/logs GET /v1/admin/invites

Webhooks de entrada

Eventos de fora entram por rotas públicas, sempre com verificação de autenticidade.

Origens: Plataformas de mensagem (Telegram, Slack, WhatsApp), GitHub e callbacks OAuth dos conectores. Cada origem tem seu esquema de assinatura, verificado em tempo constante e com janela de validade — requisição sem assinatura válida é indistinguível de canal inexistente, por escolha.
Rotas: POST /v1/messaging/webhook/{platform}/{token} POST /v1/webhooks/github/app

Documentação interativa do servidor Dukk

Referência completa (Redoc)

Console interativo (Swagger UI)

OpenAPI 3.1 (YAML)

SDKs — Python & TypeScript

Sessions, Conversations & SSE

Sandboxes & Browser Preview

Kanban Multiagente

Artifacts, Uploads & PDF

Skill Store, Routines & Connectors

Mensageria — Telegram, Slack & WhatsApp

Agente Agno atendendo no canal

Busca no histórico

Workspace, Git & MCP

Painel staff

Webhooks & OAuth

O que o Dukk faz

Sessões, conversas e streaming SSE

Modelos e provedores

Ferramentas 139 no catálogo

Escrita disciplinada SWD

Sandboxes por usuário

Navegador headless e preview ao vivo

Mensageria — Telegram, Slack e WhatsApp

Agentes Agno e vínculo com canal

Kanban multiagente

Busca no histórico de conversas

Skills, plugins e rotinas

Índice semântico e embeddings

Aprendizado entre conversas

Artifacts, uploads e PDF

Conectores OAuth e MCP

Autenticação Zitadel

Painel administrativo

Webhooks de entrada