Como funciona

Entenda o que a plataforma faz automaticamente, para que você saiba o que NÃO precisa configurar. Envie uma task; a plataforma roteia, chama as ferramentas e entrega o resultado.

Roteamento automático: um endpoint, duas pistas

Quando você envia uma task para POST /v1/workspaces/{workspace_id}/agent/runs, a plataforma decide qual pista de execução se encaixa — você nunca escolhe um endpoint:

Pista Chat — respostas rápidas, somente texto. Para perguntas que um modelo consegue responder diretamente em um turno ("explique o SEPA Instant", "traduza isto"). Rápido e barato.
Pista Agent — autônoma, de múltiplas etapas, com chamada de ferramentas. Para tarefas que exigem pesquisa, criação de arquivos, execução de código ou um navegador ("compare as taxas da Wise e da Airwallex e gere uma tabela", "leia minha knowledge base e resuma a política de reembolso").

O roteador é heurístico primeiro (custo quase zero, sem chamada ao LLM) e só escala quando uma tarefa claramente precisa de ferramentas ou de várias etapas. Se uma resposta de chat acabar precisando de ferramentas no meio do caminho, ela escala automaticamente para a pista agent — sem transição visível, sem reenvio do seu lado.

Você envia para um único endpoint em ambos os casos. Se a sua tarefa roda como um chat rápido ou como um loop agent completo é decisão da plataforma, não sua. Se você precisa garantir uma resposta puramente de chat (sem ferramentas, menor latência), use POST …/chat diretamente — veja Chat.

Ferramentas integradas: nada para configurar

O agent tem um kit de ferramentas completo integrado. Ele decide quais ferramentas chamar com base na tarefa — você nunca seleciona, configura ou conecta ferramentas. Todas estão disponíveis por padrão em cada execução:

Categoria	Ferramentas	Chamada automaticamente quando
Pesquisa na web	`web_search`, `url_reader`, `advanced_scrape`, `document_read`, `ocr_extract`	a tarefa precisa de informações da web em tempo real, leitura de páginas ou extração de PDF/imagens
Sua knowledge base	`rag_search`, `spreadsheet_analyze`, `sql_query`	a tarefa referencia arquivos ou dados enviados ao seu workspace
Datasets abertos	`arxiv_search`, `sec_edgar`, `world_bank`, `oecd`, `financial_data`, `currency_convert`, `weather`, `rss_read`	a tarefa pede dados financeiros, acadêmicos ou públicos estruturados
Execução de código	`python_exec`	a tarefa precisa de cálculo, processamento de dados ou análise
Navegador	`browser_navigate`, `browser_act`, `browser_extract`	a tarefa precisa visitar um site, fazer login ou interagir com uma página
Criação de arquivos	`create_pdf`, `create_docx`, `create_slides`, `create_markdown`, `create_webapp`	a tarefa pede um documento, uma planilha ou uma apresentação como entregável
Memória	`remember`, `forget`	o agent precisa salvar ou lembrar de um fato para execuções futuras
Auxiliares de cálculo	`calculator`, `convert`, `current_time`, `base64`, `random_choice`	a tarefa precisa de aritmética, conversão de unidades ou um carimbo de data/hora

Tudo o que está acima é de configuração zero — faz parte da plataforma e está disponível em cada execução do agent. O modelo escolhe a ferramenta certa para a tarefa; você vê cada chamada nos eventos transmitidos (tool_call → tool_result).

A única exceção: conectores. Contas de terceiros (Gmail, Slack, GitHub, Notion, Supabase, Datadog, …) exigem uma conexão única por OAuth ou API key em Settings → Connectors. Depois de conectados, o agent também os usa automaticamente. Veja Connectors.

Saída automática: planejar → agir → entregar

Uma execução do agent é um loop autodirigido. Você não escreve as etapas — o agent as planeja:

Planejar — o modelo divide a tarefa em etapas ("primeiro pesquise X, depois leia o principal resultado, depois sintetize").
Agir — ele chama as ferramentas que planejou, uma de cada vez (ou em paralelo quando seguro), lendo cada resultado antes da próxima etapa.
Verificar — ele checa sua própria saída frente à tarefa e repete se uma ferramenta falhou ou o resultado está incompleto.
Entregar — a resposta final chega no final_text do evento run_end; os arquivos produzidos voltam como artifacts.

Cada etapa é transmitida em tempo real via GET …/agent/runs/{run_id}/attach — você vê o raciocínio, as chamadas de ferramentas e a resposta conforme acontecem. Você também pode buscar a execução concluída (com sua trajetória completa de etapas) depois via GET …/agent/runs/{run_id}.

Aprimoramentos opcionais (não obrigatórios)

A linha de base — uma task sem parâmetros extras — já tem capacidade completa de ferramentas e roteamento inteligente. Estes são aprimoramentos puramente opcionais:

Skills — manuais de fluxo de trabalho reutilizáveis. Injete um para guiar COMO o agent aborda uma tarefa (ex.: um manual de "análise competitiva"). Nunca são anexados automaticamente; escolha explicitamente.
Funções de especialista — uma identidade de domínio (advogado, analista de dados, guardião de marca). Molda QUEM o agent é na execução. No máximo uma.
Projects — instruções permanentes + conhecimento enviado, empacotados como contexto reutilizável. Ancore uma execução em um projeto para que se baseie no seu domínio.
Memory — a lembrança de longo prazo do workspace. Salve fatos uma vez; o agent os recupera automaticamente em execuções futuras relevantes.
modo **pro** — desbloqueia raciocínio mais profundo e multithread (sub-agentes em paralelo) para tarefas complexas. Um flag booleano no corpo da execução.

Nenhum deles é obrigatório para a integração. Comece apenas com {"task": "…"} e adicione aprimoramentos somente quando surgir uma necessidade específica. O Cookbook mostra cada aprimoramento em ação.