Cómo funciona

Entiende lo que la plataforma hace automáticamente, para que sepas qué NO necesitas configurar. Envía una task; la plataforma enruta, llama a las herramientas y entrega el resultado.

Enrutado automático: un endpoint, dos carriles

Cuando envías una task a POST /v1/workspaces/{workspace_id}/agent/runs, la plataforma decide qué carril de ejecución encaja — tú nunca eliges un endpoint:

Carril Chat — respuestas rápidas, solo texto. Para preguntas que un modelo puede responder directamente en un turno ("explica SEPA Instant", "traduce esto"). Rápido y económico.
Carril Agent — autónomo, de varios pasos y con uso de herramientas. Para tareas que necesitan investigación, creación de archivos, ejecución de código o un navegador ("compara las comisiones de Wise y Airwallex y genera una tabla", "lee mi knowledge base y resume la política de reembolso").

El enrutador prioriza la heurística (coste casi nulo, sin llamada al LLM) y solo escala cuando una tarea claramente necesita herramientas o varios pasos. Si una respuesta de chat resulta necesitar herramientas a mitad de proceso, escala automáticamente al carril agent — sin transición visible, sin reintento por tu parte.

Envías a un único endpoint en ambos casos. Que tu tarea se ejecute como un chat rápido o como un bucle agent completo es decisión de la plataforma, no tuya. Si necesitas garantizar una respuesta puramente de chat (sin herramientas, latencia mínima), usa directamente POST …/chat — ver Chat.

Herramientas integradas: nada que configurar

El agent incluye un conjunto completo de herramientas integradas. Decide cuáles llamar en función de la tarea — tú nunca seleccionas, configuras ni conectas herramientas. Todas están disponibles por defecto en cada ejecución:

Categoría	Herramientas	Se llama automáticamente cuando
Búsqueda web	`web_search`, `url_reader`, `advanced_scrape`, `document_read`, `ocr_extract`	la tarea necesita información web en vivo, lectura de páginas o extracción de PDF/imágenes
Tu knowledge base	`rag_search`, `spreadsheet_analyze`, `sql_query`	la tarea hace referencia a archivos o datos subidos a tu workspace
Datasets abiertos	`arxiv_search`, `sec_edgar`, `world_bank`, `oecd`, `financial_data`, `currency_convert`, `weather`, `rss_read`	la tarea pide datos financieros, académicos o públicos estructurados
Ejecución de código	`python_exec`	la tarea necesita cálculo, procesamiento de datos o análisis
Navegador	`browser_navigate`, `browser_act`, `browser_extract`	la tarea necesita visitar un sitio web, iniciar sesión o interactuar con una página
Creación de archivos	`create_pdf`, `create_docx`, `create_slides`, `create_markdown`, `create_webapp`	la tarea pide un documento entregable, una hoja de cálculo o una presentación
Memoria	`remember`, `forget`	el agent necesita guardar o recordar un dato para ejecuciones futuras
Utilidades de cálculo	`calculator`, `convert`, `current_time`, `base64`, `random_choice`	la tarea necesita aritmética, conversión de unidades o una marca de tiempo

Todo lo anterior es de configuración cero — forma parte de la plataforma y está disponible en cada ejecución del agent. El modelo elige la herramienta adecuada para la tarea; ves cada llamada en los eventos en streaming (tool_call → tool_result).

La única excepción: los conectores. Las cuentas de terceros (Gmail, Slack, GitHub, Notion, Supabase, Datadog, …) requieren una conexión única por OAuth o API key en Settings → Connectors. Una vez conectados, el agent también los usa automáticamente. Ver Connectors.

Salida automática: planificar → actuar → entregar

Una ejecución del agent es un bucle autodirigido. Tú no programas los pasos — el agent los planifica:

Planificar — el modelo descompone la tarea en pasos ("primero busca X, luego lee el resultado principal, luego sintetiza").
Actuar — llama a las herramientas que planificó, una a una (o en paralelo cuando es seguro), leyendo cada resultado antes del siguiente paso.
Verificar — comprueba su propia salida frente a la tarea y lo reintenta si una herramienta falló o el resultado está incompleto.
Entregar — la respuesta final llega en el final_text del evento run_end; los archivos producidos se devuelven como artifacts.

Cada paso se transmite en tiempo real vía GET …/agent/runs/{run_id}/attach — ves el razonamiento, las llamadas a herramientas y la respuesta a medida que ocurren. También puedes obtener la ejecución completada (con su trayectoria completa de pasos) más tarde vía GET …/agent/runs/{run_id}.

Mejoras opcionales (no obligatorias)

La línea base — una task sin parámetros adicionales — ya tiene capacidad completa de herramientas y enrutado inteligente. Estas son mejoras puramente opcionales:

Skills — guiones de flujo de trabajo reutilizables. Inyecta uno para guiar CÓMO aborda el agent una tarea (p. ej. un guion de "análisis competitivo"). Nunca se adjuntan automáticamente; se eligen explícitamente.
Roles especialistas — una identidad de dominio (abogado, analista de datos, guardián de marca). Define QUIÉN es el agent en esa ejecución. Como máximo uno.
Projects — instrucciones permanentes + conocimiento subido, empaquetados como contexto reutilizable. Ancla una ejecución a un proyecto para que se apoye en tu dominio.
Memory — la memoria a largo plazo del workspace. Guarda datos una vez; el agent los recupera automáticamente en ejecuciones futuras relevantes.
modo **pro** — desbloquea un razonamiento más profundo y multihilo (sub-agentes en paralelo) para tareas complejas. Un flag booleano en el body de la ejecución.

Ninguno de estos es obligatorio para integrar. Empieza con solo {"task": "…"} y añade mejoras solo cuando surja una necesidad específica. El Cookbook muestra cada mejora en acción.