Os termos da plataforma Adalink em linguagem simples.
Antes de mergulhar na referência da API, vale entender o vocabulário básico da plataforma. Cada termo abaixo tem uma explicação simples (analogia do dia a dia) e uma técnica (como aparece na API).
O que é, em uma frase
Um assistente de IA configurável: você dá um nome, escolhe o modelo (cérebro) e diz como ele deve se comportar.
Detalhe técnico
Recurso /v1/agents com nome, modelo, instruções de sistema, lista de ferramentas habilitadas e (opcional) base de conhecimento associada. Identificado por UUID v7.
O que é, em uma frase
Um perfil pronto que dá ao agente uma "personalidade profissional" — Analista Financeiro, Code Reviewer, etc.
Detalhe técnico
Template de instruções + ferramentas + base de conhecimento promovido pela equipe Adalink (system) ou pela própria organização (custom). Pode ser instalado em vários agentes.
O que é, em uma frase
Uma habilidade reutilizável que você pode dar ao agente — por exemplo, "responder dúvidas sobre o produto".
Detalhe técnico
Pacote versionado de prompts + few-shots + tools + chunks de conhecimento, gerenciado em /v1/skills. Suporta ownership system/org e promote para sistema.
O que é, em uma frase
Uma receita de automação. Você desenha um fluxo de passos (buscar dados → chamar agente → mandar e-mail) e a plataforma executa do começo ao fim.
Detalhe técnico
DAG (Directed Acyclic Graph) com nós tipados (trigger, agent_call, http_request, condition...) e arestas. Executado pelo agents-service via Trigger.dev.
O que é, em uma frase
Uma "ponte" para um serviço externo (Google Drive, Slack, GitHub). Você autoriza uma vez e a plataforma passa a poder ler e escrever lá por você.
Detalhe técnico
Recurso OAuth/PAT armazenado em /v1/connections, com refresh automático de tokens, escopos e expiração. Consumido por tools dos agentes.
O que é, em uma frase
Onde o agente "guarda lembranças" entre conversas — preferências do usuário, fatos importantes, contexto de longo prazo.
Detalhe técnico
Storage chave/valor + busca semântica via embeddings (pgvector HNSW), com escopos org/user/agent. Acessada pelas tools memory.read/write.
O que é, em uma frase
Um "anexo rico" que o agente cria durante a conversa — um documento, um gráfico, um trecho de código que você pode baixar ou editar.
Detalhe técnico
Recurso /v1/artifacts com tipos: code, document, chart, sheet, diagram, html, ppt, email, image. Persistido por conversation e versionado.
O que é, em uma frase
Um diálogo aberto com um agente. Vários turnos de mensagens; pode ter anexos, ferramentas chamadas e artefatos gerados.
Detalhe técnico
Recurso /v1/conversations gerenciado pelo chat-service. Mensagens em SSE streaming; cada turno pode disparar tool calls e gerar artefatos.
O que é, em uma frase
Cada conversa em andamento — mais ou menos como uma janela de mensageiro aberta entre você e o agente.
Detalhe técnico
Equivalente a uma Conversation. Mantém histórico ordenado; novos turnos vão para /v1/chat/sessions/{id}/messages com SSE streaming na resposta.
O que é, em uma frase
Uma URL do seu sistema que a Adalink chama quando algo acontece (um agente terminou, um arquivo foi processado).
Detalhe técnico
Endpoint HTTP registrado em /v1/webhooks com filtros de evento, secret HMAC-SHA256 (header X-Adalink-Signature), retry com backoff exponencial e idempotência via id do evento.
O que é, em uma frase
A "chave de acesso" que prova que é você quem está chamando a API. Você pega no login e usa em toda chamada.
Detalhe técnico
JWT Bearer assinado com 60 minutos de validade, emitido em /v1/auth/token. Validado no api-gateway via JWKS remoto (Better Auth).
O que é, em uma frase
Sua empresa dentro da Adalink. Tudo que você cria (agentes, conversas, conexões) pertence à organização — não a você diretamente.
Detalhe técnico
Tenant isolado, com plano, créditos, membros e papéis. Cada chamada autenticada já vem amarrada à organização do usuário (header x-internal-organization-id).
O que é, em uma frase
Não dá pra se cadastrar sozinho. Um administrador da empresa precisa te convidar para você poder criar conta.
Detalhe técnico
Fluxo onde POST /v1/invitations cria um User inativo; ao fazer signup, o hook user.create.after ativa a conta e aceita todos os convites pendentes para o email.
O que é, em uma frase
A moeda interna da plataforma. Cada execução de agente, geração de imagem ou consulta cara consome adacoins do seu plano.
Detalhe técnico
Unidade contábil da credits-service. Consumida por usage events; convertida em pricing por modelo via catálogo unificado de LLM models (sync:models).
O que é, em uma frase
A carteira de créditos da sua organização. Mostra quanto você tem, quanto já gastou e quando renova.
Detalhe técnico
Recurso da credits-service com saldo de adacoins, histórico de transações e limites por plano. Consultável em /v1/billing/usage.
O que é, em uma frase
O "cérebro" que faz a IA pensar e responder — Claude, GPT, Gemini etc. Você escolhe qual usar em cada agente.
Detalhe técnico
Modelo de linguagem listado em /v1/models, vindo do catálogo curado libs/shared/domain/src/catalog/llm-models.catalog.ts. Cada modelo tem capacidades (vision, tools, contextWindow) e pricing.
O que é, em uma frase
Liga e desliga funcionalidades por usuário ou organização — útil para liberar uma feature nova só para alguns clientes antes de abrir para todo mundo.
Detalhe técnico
Flag booleana ou de variantes avaliada em runtime pelo authz-service, consultável em /v1/feature-flags. Suporta segmentação por org, plano, role.
O que é, em uma frase
Uma habilidade extra que o agente pode usar — buscar na web, ler um PDF, mandar e-mail. O agente decide quando chamar.
Detalhe técnico
Função invocável pelo modelo via tool calling, registrada em /v1/tools. Pode ser nativa (web_search, http_request) ou MCP (Model Context Protocol).
O que é, em uma frase
Quando o agente busca trechos relevantes nos seus documentos antes de responder — em vez de só usar o que o modelo "já sabia".
Detalhe técnico
Pipeline de chunking + embedding + busca vetorial (pgvector HNSW) servido pelo rag-service. Gera citações junto da resposta.
O que é, em uma frase
Maneira do servidor mandar pedacinhos da resposta enquanto vai gerando — é o que faz o chat parecer que está "digitando" para você.
Detalhe técnico
Conexão HTTP unidirecional persistente (Content-Type: text/event-stream). Usada em /v1/chat/sessions/{id}/messages e /v1/monitoring/runs/{id}/stream.