Manual · engineer

Guia Técnico

Para engenheiros que integram o AgentOS, fazem onboarding numa equipa ou estendem a plataforma.

Arquitetura

Stack, runtimes e fronteiras de segurança.

Stack: TanStack Start v1 + React 19 + Vite 7 a correr em Cloudflare Workers. Backend Lovable Cloud (PostgreSQL + Auth + Storage + Realtime). Modelos via Lovable AI Gateway (Gemini, GPT-5, etc).

Fronteiras: - createServerFn — RPC tipado cliente→servidor para lógica interna. - src/routes/api/public/* — endpoints HTTP públicos (webhooks, cron, API v1). Bypass de auth — verificar HMAC/API key dentro do handler. - requireSupabaseAuth middleware — server fns autenticadas com RLS por workspace_id.

Multi-tenancy: todas as tabelas com workspace_id + RLS via has_workspace_role() security-definer. Roles em workspace_members (nunca no profile).

TanStack Start docs Cloudflare Workers

Runtime de agentes

Como uma mensagem se transforma em resposta com tools, memória e tracing.

O executeAgentMessage (em src/lib/agent-runtime.server.ts) é o coração. Fluxo:

1. Quota & budget check (assertQuota, assertBudget) — lança QuotaError 429. 2. Guardrails input — PII regex+Luhn, moderation Gateway flash-lite. 3. Smart routing (opcional) — classificador 1-5 escolhe cheap/balanced/strong. 4. Cache check — response_cache exato + semântico ≥0.93 (skip se houver tools). 5. Memory recall — top-K agent_memories (pgvector 768). 6. Tools — built-in + OAuth (Slack, Linear, HubSpot, GCal, Jira) + MCP + code interpreter + browser use. 7. streamText via AI SDK com stopWhen: stepCountIs(50). 8. Usage event — tokens, custo USD, latência, prompt_version_id, trace_id W3C. 9. Auto-curadoria — episodic/fewshot memories.

Trace explorer — spans com tokens, custo USD e latênciamockup ilustrativo

Pipelines visuais

DAG de steps (LLM, tool, branch, loop, parallel, approval, guardrails).

Editor em React Flow (src/routes/app.pipelines.$id.index.tsx). Runtime recursivo suporta:

- delay / loop (forEach) / parallel / try_catch — durabilidade via automation_step_runs + retries com backoff. - approval (HITL) — pausa em status=waiting, retoma via cron. - guardrails / classify — gates baseados em LLM. - Versioning — snapshots em pipeline_versions + restore one-click. - Realtime runs — Supabase Realtime no painel /app/runs.

Editor visual de pipeline com side panel de configuraçãomockup ilustrativo

API REST v1 + SDKs

Bearer auth aos_..., OpenAPI 3.1, SDKs TS/Python.

Endpoints: /api/v1/agents, /api/v1/pipelines, /api/v1/runs, /api/v1/approvals, /api/v1/devices, /api/v1/evals/datasets/:id/run.

Streaming: /api/v1/agents/{id}/messages/stream (SSE com eventos token / usage / done).

OpenAPI estática: /api/v1/openapi.json + UI Scalar em /app/api-docs.

SDKs oficiais: @agentos/sdk (TypeScript) e agentos-sdk (Python). Suportam agents.stream() e polling de runs.

Rate limit: por API key, configurável em workspace_quotas.api_rate_per_minute.

OpenAPI 3.1 Scalar API Reference

Onboarding numa empresa

Checklist de 1 hora para uma equipa nova começar.

1. Criar workspace via /app (primeiro user fica owner). 2. Adicionar membros em /app/members (roles: owner, admin, editor, viewer). 3. Ligar conectores (/app/connections) e OAuth (/app/oauth). 4. Importar/criar knowledge base (/app/knowledge) — PDF, MD, URL. 5. Criar primeiro agente a partir de skill (/app/skills) ou template. 6. Configurar guardrails e budgets (/app/governance, /app/budgets). 7. Gerar API key (/app/api-keys) e instalar SDK. 8. Ativar SSO/SAML e IP allowlist em /app/settings (planos Team+).