# Getting started Welcome! This guide helps you get comfortable with the Gaia platform directly from the in-product help pane (click the **?** button in the upper-right corner of supported screens). It’s written for builders, admins, and curious teammates who want to understand how to launch and maintain AI-powered experiences—no engineering background required. This page is the canonical landing guide for the signed-in platform experience. Older references to **Home** or **Getting started** in Gaia documentation now point back here. - **What you’ll find:** step-by-step walkthroughs, real-life examples, and links between topics so you can follow a workflow end-to-end. - **What you won’t see:** source code, implementation internals, repo scripts, infrastructure setup, installation procedures, or DevOps deployment instructions. This guide stays focused on using Gaia from the platform itself. ## Supported browsers Gaia supports current stable versions of Chrome, Edge, Firefox, and Safari. Voice conversations and microphone permissions depend on browser media support, so use Chrome, Edge, or Safari for the broadest voice feature coverage. ## How to use this guide 1. Start here to tour the interface and confirm you have the right project role. 2. Use the left navigation in Gaia to open the page you care about (Conversations, Dashboard, Data Model, etc.). The help pane will automatically highlight the matching article. 3. Prefer a dedicated view? Open the full-screen User Guide at `/user-guide` to browse the documentation without leaving the page open underneath. Use `/user-guide/contents` for the full table of contents plus a topic search that helps when you know the subject but not the page title. 4. Use the search field at the top of either full-screen view when you know the topic but not the page name, for example `composite tools` or `workflow actions`. 5. Follow the “Real-life example” callouts to see how teams use the feature in practice. 6. Use the cross-links inside each article to learn the supporting features (for example, jump from Conversations to Gaia or Data Model). 7. Use [Tutorials](/platform/support/tutorials) for guided walkthroughs grouped by theme. Each tutorial card keeps the focus on the live in-product flow with clear start, resume, or restart actions. See [Tutorials](#doc-tutorials) for details. 8. Use [Training Program](/platform/support/training-program) for the signed-in three-day, prepared-workspace training agenda and downloadable training materials. 9. Use [Installation Guide](#doc-platform-installation-guide) when you need signed-in access to DevOps setup, hosted deployment, and Azure rollout instructions. 10. If you want a structured learning path to become a Gaia AI Engineer, use the [AI Engineer Handbook](/handbook). ## Teams and projects The **Teams** page at `/platform/user/teams` is the signed-in landing page for Gaia. It helps you: - Pick a **team** - Browse and create **projects** for that team - Open a project to start using tools like Agents, Conversations, and the Data Model The **Organizations** page at `/platform/user/organizations` opens with a directory of the organizations you can access. Use **New** from the directory header to create an organization, or open an organization from the list to manage its settings, users, billing, instance information, and organization-specific login options. Azure Marketplace SaaS configuration links open `/marketplace/azure` so an authenticated user can create a new Marketplace-managed Organization with a subscription-based suffix, or an Organization admin or billing admin can attach the Marketplace purchase to an existing Organization. The linked entitlement appears in the Organization **Billing** tab as an external Marketplace source rather than a Stripe customer-portal subscription. On privileged host contexts, Organization admins can use the **Instances** tab to track runtime hosts, review license source and capacity, and activate an instance with an encrypted license-file JSON payload. Organization admins can set a login slug, choose whether Microsoft and email code sign-in are available, and decide whether access is invite-only or uses the signup form from the **Login settings** card. Invitation copy lives in its own **Invitation settings** card. The **Theme** tab uses light/dark radio buttons to edit the selected login logo and theme tokens at full width, with a read-only login preview that can be resized on larger screens. The default Gaia login remains available for the Gaia organization. Organization and team user lists show **Identity** separately from **Lifecycle** so admins can distinguish invited, anonymous, provisioned, and signed-in users from active, suspended, or archived account state. Admins can also send or resend invitation emails from user rows; organization, team, and project settings each keep their own invitation email template with a full-width subject field and rich message editor. Sent invitation emails use the editor body without appending hidden button copy, and plain `http` and `https` URLs are sent as links. Platform admins also get an **Organizations** page under **Operations** at `/platform/operations/organizations`. That view lists every organization in the current Gaia instance so admins can inspect and manage settings centrally. ### Teams The left panel lists your teams as a collapsible tree. - Use the organization selector beside **Teams** to focus the tree on one organization or show all accessible teams. - Expand or collapse a team to show or hide its sub-teams. - Select any team node to load its projects. - Click a team (except **Shared Projects**) to view and manage team details. - Use **Create team** to add a top-level team or choose a parent team to create a sub-team. - Parent team selection uses a searchable picker and only shows teams where you are an admin. - In **Edit team**, change the **Parent Team** field to move a team to a different branch. You must be an admin in both the current team and the selected parent team. #### Shared Projects **Shared Projects** is a special entry that shows projects you can access even if you’re not a member of the owning team. ### Projects The right panel shows projects for the selected team. - Select a project to open the first workspace you can access in the left sidebar order. For example, built-in project users normally land in **Conversations** instead of being sent into a channel app route. - The Teams page includes an **Ask Gaia** button in the bottom-right corner. Open it when you want the team-scoped **Design With Gaia** panel for pre-project work, where Gaia reasons through the architecture first, keeps the work in a persisted design session, and provisions a new project only after approval. It is not the path for modifying an existing live project. - Use the three-dot menu on a project card to open the project, rename it, delete it, or jump straight into any available **Text** or **Personal assistant** app channel in a new browser tab. - Use **Create project** to add a new project to the currently selected team. In the dialog you can stay with **Blank project** for an empty workspace shell or switch to **Ask Gaia** to draft a starter scaffold from a short brief before anything is created. - Use **Import** to create a new project from a Gaia export file or another Gaia instance without opening a blank workspace first. - In **Ask Gaia** mode, fill in the project goal, review the starter preview, optionally trim suggested structure such as entities, automation, or folders, and then approve creation. Gaia creates the project from a canonical project spec and opens a handoff conversation inside the new workspace. - After the project shell exists, open the lightning-bolt [Gaia](#doc-platform-assistant) assistant inside that project to evolve it safely through discussion. This is the live-project path: Gaia plans configuration changes from the project spec, shows the proposed patch review and diff, and waits for approval before applying them. - In the import dialog, choose **Export file** for a `.json` export generated by Gaia. You can also attach an RFC 6902 patch file when the export should be patched before Gaia creates the new project. - In the import dialog, choose **Gaia instance** for cross-instance project transfer. Run preflight before starting the transfer so Gaia can verify instance settings, token state, source permissions, and the source manifest summary. - Cross-instance import relies on a transfer token issued from the source project's [Settings](#doc-settings-cross-instance-project-transfer) page. ## Sign in and pick a project 1. Navigate to the Gaia URL provided by your organization and sign in. 2. If you’re not already on the **Teams** page, use the top navigation or click the Gaia logo in the top-left to return to `/platform/user/teams`. 3. From **Teams**, pick a team and then pick a project. If you don’t have a project yet, use the bottom-right **Ask Gaia** button for an assistant-led pre-project design session, use **Create project** for a blank workspace or an **Ask Gaia** starter scaffold, or use **Import** to start from an exported Gaia project. If you already have a live project, open it first and then use Gaia inside the project for reviewed spec-driven changes. 4. Your recently opened projects appear in the **Recent projects** menu. 5. If you can’t see a project you expect, ask an admin to add you via [Project settings → Project users](#doc-settings-project-users). 6. If you only have **app user** access and not project access, Gaia sends you to the first associated app landing page at `/apps/[slug]/login` instead of opening the platform workspace. That sign-in screen keeps the app header pinned while the rest of the page scrolls on smaller screens. ## Tour the interface - **Left sidebar:** Shortcuts to Conversations, Memory, Evals, AI Agents, Data Model, Dashboard, and Settings. Icons change color when active. - **Module tabs:** Some related tools live inside a module header. **Conversations** now groups **List**, **Channels**, **UI Layouts**, **Folders**, **Actions**, and **File Extractors** in one workspace. - **Governance workspace:** The Governance module groups **Overview**, **Runtime**, **Catalog**, **Risk & Compliance**, **Evidence**, and **Discovery**. Use it when your application is ready for package-backed oversight, governed contracts and policies, controls and obligations, state-memory review, regulatory intake, discovery onboarding, and explainability review. - **Top navigation tabs:** Jump between **Organizations**, **Teams**, **Discussions**, **Tutorials**, **Training Program**, **Cost Estimator**, and any platform-wide tabs your effective platform role exposes, such as **Organizations** in **Operations**, **Dashboard**, **Users**, **Models**, **Settings**, **Tasks**, or **Access Requests**. - **Top bar:** Shows the current page title, any tabs, and action buttons like **Update Statistics** or **New** (visible in the conversation header). - **Help button (❓):** Opens the in-app help pane. It automatically loads the article that matches the page you're on, so guidance is always context-aware. Use the **Print** button in the help pane to create a PDF of the user guide, or download the complete guide as a single document. - **Gaia (⚡):** The lightning icon opens a side-by-side assistant who can navigate, run tools, or answer questions about the platform. See [Gaia](#doc-platform-assistant). ## Confirm your role Roles control which features you see. Built-in roles include **admin** (full access) and **user** (conversations only), and projects can add custom roles with granular permissions. Not sure which role you have? Open the user menu in the bottom-left corner of the sidebar. If you need additional access, contact a project admin. ## Try a conversation 1. Click the chat bubble icon to open **Conversations**. 2. Use the **New** button to create a thread and send a question. 3. Explore advanced tools like [Timeline](#doc-conversations-dialogs-timeline) or [Inside Info](#doc-conversations-monitor-a-turn-with-inside-info) once you’re comfortable. ## Real-life example > A new customer success manager spent 10 minutes here before onboarding. They read this guide, confirmed their role permissions, asked Gaia to “Open the RenewalOpportunity entity,” and immediately saw how conversations, data, and layouts connect. ## Next steps - Dive into [Conversations](#doc-conversations) to master day-to-day chats. - Configure agents via [AI Agents](#doc-agents). - Set up structured data in [Data Model](#doc-data-model) and present it through [UI Layouts](#doc-conversations-ui-layouts). - Open [Governance](#doc-governance) once you need reusable framework packages, runtime governance records, or release-ready evidence tracking. If governance is new to you, begin with [Governance Foundations](#doc-governance-foundations). ## Contents - [Getting started](#doc-root) - [Control Plane Evidence](#doc-control-plane-evidence) - [Build an AI application](#doc-building-an-ai-application) - [Coding agents](#doc-coding-agents) - [Claude Code](#doc-coding-agents-claude-code) - [Lot B interoperability evidence](#doc-coding-agents-lot-b-interoperability-evidence) - [Discussions](#doc-discuss) - [Tutorials](#doc-tutorials) - [Installation Guide](#doc-platform-installation-guide) - [Conversations](#doc-conversations) - [Channels](#doc-conversations-channels) - [Channel security and access](#doc-conversations-channels-security-and-access) - [UI Layouts](#doc-conversations-ui-layouts) - [Data Binding in UI Layouts](#doc-conversations-ui-layouts-data-binding) - [Document Folders](#doc-conversations-document-folders) - [Azure AI Search Adapter](#doc-conversations-document-folders-azure-ai-search-adapter) - [Workflow actions](#doc-conversations-workflow-actions) - [File extractor registry](#doc-conversations-file-extractor-registry) - [Agent Config Checklist for Canvas and Document Workflows](#doc-conversations-agent-config-checklist) - [Conversation Scenarios](#doc-conversations-scenarios) - [Scenario: Live-agent bridge takeover workflow](#doc-conversations-scenarios-live-agent-bridge-takeover-workflow) - [Scenario: Folder-grounded Personal Assistant setup](#doc-conversations-scenarios-folder-grounded-personal-assistant-setup) - [Scenario: Inline UI layout responses](#doc-conversations-scenarios-inline-ui-layout-responses) - [Scenario: Entity canvas workflow](#doc-conversations-scenarios-entity-canvas-workflow) - [Scenario: Runtime UI canvas artifact workflow](#doc-conversations-scenarios-runtime-ui-canvas-artifact-workflow) - [Scenario: Document upload, edit, and download workflow](#doc-conversations-scenarios-document-editing-workflow) - [Gaia](#doc-platform-assistant) - Dialogs & quick actions - [Give feedback on a reply](#doc-conversations-dialogs-feedback) - [View a conversation timeline](#doc-conversations-dialogs-timeline) - [Update project statistics](#doc-conversations-dialogs-update-statistics) - [Start a voice conversation](#doc-conversations-dialogs-voice-conversation) - [Memory Workspace](#doc-memory) - [AI Agents](#doc-agents) - [Model Tier Routing](#doc-agents-model-tier-routing) - [Code execution](#doc-agents-code-execution) - [Fragments](#doc-agents-fragments) - [Protocols](#doc-agents-protocols) - [Agent Configuration](#doc-agents-configs) - [Bridge Agent Settings](#doc-agents-live-chat-bridge-agent) - [Guardrails](#doc-agents-guardrails) - [Skills](#doc-agents-skills) - [MCP server registry](#doc-agents-mcp-servers) - [Engineering reference: TypeScript tools](#doc-agents-typescript-tools) - [Data Model](#doc-data-model) - [Databricks data platform](#doc-data-model-databricks-data-platform) - [Entities](#doc-data-model-entities) - [Storage](#doc-data-model-storage) - [Pipelines](#doc-data-model-pipelines) - [Engineering reference: TypeScript in data pipelines](#doc-data-model-typescript-pipelines) - TypeScript in pipelines (split reference) - [Index](#doc-data-model-typescript) - [Record formats](#doc-data-model-typescript-record-formats) - [TypeScript source](#doc-data-model-typescript-source) - [TypeScript transform](#doc-data-model-typescript-transform) - [TypeScript target](#doc-data-model-typescript-target) - [AI transform aggregation](#doc-data-model-typescript-ai-transform-aggregation) - [Workflow context sharing](#doc-data-model-typescript-workflow-context-sharing) - [Workflows](#doc-data-model-workflows) - [Runs](#doc-data-model-runs) - [Tool registry](#doc-data-model-tool-registry) - [Scheduled jobs](#doc-data-model-scheduled) - [Ingestion webhook](#doc-data-model-ingestion-webhook) - [Delivery Management](#doc-delivery) - [Delivery Discussions](#doc-delivery-discuss) - [Delivery Process Cycle](#doc-delivery-process-cycle) - [Delivery Milestones](#doc-delivery-milestones) - [Delivery Timeline (Gantt)](#doc-delivery-timeline) - [Project Versions and Branches](#doc-delivery-versions) - [Artifact Templates](#doc-artifact-templates) - [Audit Trail](#doc-audit) - [Dashboard](#doc-dashboard) - [Platform Dashboard](#doc-platform-dashboard) - [Status and incidents](#doc-platform-dashboard-status-and-incidents) - [Usage billing and quotas](#doc-platform-dashboard-usage-billing-and-quotas) - [Sandbox and API versioning](#doc-platform-dashboard-sandbox-and-api-versioning) - [Background jobs](#doc-platform-dashboard-background-jobs) - [Operational logs](#doc-platform-dashboard-operational-logs) - [Platform Cost Estimator](#doc-platform-cost-estimator) - [Timesheet](#doc-timesheet) - [Tasks](#doc-tasks) - [Tasks](#doc-tasks-all-tasks) - [Task calendar](#doc-tasks-task-calendar) - [Evals](#doc-evals) - Pages - [Eval design process](#doc-evals-eval-design-process) - [Ultimate guide: Creating and evolving evals in Gaia](#doc-evals-ultimate-guide) - [Eval scenarios](#doc-evals-scenarios) - [Scenario: Create and run an eval](#doc-evals-scenarios-create-and-run-an-eval) - [Scenario: Operate an eval improvement loop](#doc-evals-scenarios-operate-an-eval-improvement-loop) - [Datasets](#doc-evals-datasets) - [Dataset details](#doc-evals-dataset-details) - [Runs](#doc-evals-runs) - [Run details](#doc-evals-run-details) - [Trial details](#doc-evals-trial-details) - [Graders](#doc-evals-graders) - [Reports](#doc-evals-reports) - [Settings](#doc-evals-settings) - Dialogs - [Eval Design Wizard](#doc-evals-dialogs-eval-design-wizard) - [Create or edit a dataset](#doc-evals-dialogs-dataset-editor) - [Create or edit an eval task](#doc-evals-dialogs-eval-task-editor) - [Create or edit a grader](#doc-evals-dialogs-grader-editor) - [Select eval runs](#doc-evals-dialogs-select-eval-runs) - [Manage eval folders](#doc-evals-dialogs-rename-folder) - [Start an eval run](#doc-evals-dialogs-start-run) - [Import tasks](#doc-evals-dialogs-import-candidates) - [Generate security tasks](#doc-evals-dialogs-generate-security-evals) - [LLM Judge Configuration](#doc-evals-dialogs-llm-judge) - [Agent Behavior Trace](#doc-evals-dialogs-agent-behavior-trace) - [Promote Conversation to Eval](#doc-evals-dialogs-promote-to-eval) - [Human review an eval turn](#doc-evals-dialogs-human-review) - [View trial details](#doc-evals-dialogs-turn-details) - [Governance](#doc-governance) - [Governance Foundations](#doc-governance-foundations) - [Governed application lifecycle](#doc-governance-governed-application-lifecycle) - [Overview](#doc-governance-overview) - [Orchestration](#doc-governance-orchestration) - [Registry](#doc-governance-registry) - [Agent Systems](#doc-governance-agent-systems) - [Contracts](#doc-governance-contracts) - [Policies](#doc-governance-policies) - [Operations](#doc-governance-operations) - [State & Memory](#doc-governance-state-memory) - [Risk Library](#doc-governance-risk-library) - [Controls](#doc-governance-controls) - [Obligations](#doc-governance-obligations) - [Classifications](#doc-governance-classifications) - [Regulatory Updates](#doc-governance-regulatory-updates) - [Discovery](#doc-governance-discovery) - [Explainability](#doc-governance-explainability) - [Settings](#doc-settings) - [Localization](#doc-settings-localization) - [Model routing and failover](#doc-settings-model-routing) - [Platform users and roles](#doc-settings-platform-users) - [Cross-instance project transfer](#doc-settings-cross-instance-project-transfer) - [Configurable authentication](#doc-settings-configurable-auth) - [App user roles](#doc-settings-app-user-roles) - [Project users](#doc-settings-project-users) - [Project roles](#doc-settings-project-roles) - [Service accounts](#doc-settings-service-accounts) --- # Control Plane Evidence Use this page when you need to show how Gaia's signed-in product surfaces support an enterprise AI/RAG control-plane review. It links the operational areas that usually provide proposal, audit, or vendor-onboarding evidence. This page is a product evidence guide. Deployment-specific topology, high availability, disaster recovery, network controls, and customer-specific SIEM configuration belong in the delivery or installation evidence pack for the selected hosting model. Store the product-side references for that pack in **Project Settings -> General -> Evidence posture**. ## Evidence map | Review area | Gaia evidence surface | What to capture | | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Architecture overview | This page, [Document Folders](#doc-conversations-document-folders), [Governance](#doc-governance), [Platform Dashboard](#doc-platform-dashboard), and [Coding Agents](#doc-coding-agents) | The control-plane layers, runtime surfaces, evidence sources, and deployment caveats. | | Ingestion and retrieval | [Document Folders](#doc-conversations-document-folders) and [File extractor registry](#doc-conversations-file-extractor-registry) | Folder settings, indexing policy, supported file types, index run history, retrieval mode, backend id, capability path, ranking profile, search diagnostics, citations, and source previews. | | Databricks data platform | [Databricks data platform](#doc-data-model-databricks-data-platform), [Data Model](#doc-data-model), [Document Folders](#doc-conversations-document-folders), and [Service accounts](#doc-settings-service-accounts) | Databricks workspace, service principal or connector principal, SQL warehouse, Unity Catalog scope, Vector Search index, export path, access review, test query, retrieval eval, audit row, and fallback posture. | | Retrieval quality | [Evals](#doc-evals), [Reports](#doc-evals-reports), and [Document Folders](#doc-conversations-document-folders) | Eval datasets, expected evidence, run coverage, selected runs, pass/fail posture, citation quality, backend diagnostics, and retrieval diagnostics. | | Model routing and cost | [Deployment-pool routing and failover](#doc-settings-model-routing), [Model Tier Routing](#doc-agents-model-tier-routing), [Dashboard](#doc-dashboard), [Usage billing and quotas](#doc-platform-dashboard-usage-billing-and-quotas), and [Governance Operations](#doc-governance-operations) | Deployment target tiers and weights, retry/failover trace, final target, tier policy, selected model/config, workload-policy approval or rejection, exception expiry, usage ledger export, token volume, estimated cost, and latency. | | Prompt governance | [Agent Configuration](#doc-agents-configs), [Fragments](#doc-agents-fragments), and [Governance Policies](#doc-governance-policies) | Active configuration, prompt fragments, variables, linked fragment versions, config diff, active/default assignment, and related governance policy. | | Grounding and safety | [Agent Configuration](#doc-agents-configs), [Guardrails](#doc-agents-guardrails), [Document Folders](#doc-conversations-document-folders), [Governance](#doc-governance), and [Evals](#doc-evals) | Conversation-scope, instruction-confidentiality, and response-validation decisions; linked governance policies; folder search tools; citations; and review results. | | Monitoring and AI operations | [Dashboard](#doc-dashboard), [Platform Dashboard](#doc-platform-dashboard), [Status and incidents](#doc-platform-dashboard-status-and-incidents), and [Audit Trail](#doc-audit) | Project trends, model usage, cost, latency, folder indexing spend, background jobs, logs, incidents, audit rows, and SIEM export. | | Compliance evidence | [Settings](#doc-settings), [Governance Foundations](#doc-governance-foundations), [Governed application lifecycle](#doc-governance-governed-application-lifecycle), [Agent Systems](#doc-governance-agent-systems), [Policies](#doc-governance-policies), [Controls](#doc-governance-controls), [Obligations](#doc-governance-obligations), [Classifications](#doc-governance-classifications), and [Explainability](#doc-governance-explainability) | Deployment evidence posture, operations owner, SIEM target reference, HA/DR reference, GDPR, EU AI Act, DORA, audit or delivery links, runtime policy decisions, MCP gateway decisions, schema drift findings, enforced block/fallback or quarantine evidence, review-mode warning evidence, tool-message evidence, agent-system telemetry, reviewer report, controls, obligations, classifications, explainability artifacts, runtime boundary records, linked evidence, and review posture. | | Vendor interoperability | [Settings](#doc-settings), [Lot B interoperability evidence](#doc-coding-agents-lot-b-interoperability-evidence), [Coding Agents](#doc-coding-agents), [Delivery Management](#doc-delivery), [Delivery Process Cycle](#doc-delivery-process-cycle), and [Service accounts](#doc-settings-service-accounts) | External-agent profile, vendor/platform reference, runtime boundary, Gaia access surface, Databricks linkage reference when applicable, project-bound MCP or connector setup, service-account or connector-principal access, allowed actions, discovery output, preview/test evidence, milestones, tasks, discussions, certification evidence, support handoff expectations, and audit or delivery references. | ## Control-plane layers ```mermaid flowchart TD Ingress["Channels and apps"] --> Runtime["Agent runtime and orchestration"] Runtime --> Prompts["Configurations, fragments, variables"] Runtime --> Tools["Tools, workflows, MCP, and integrations"] Runtime --> Retrieval["Document folders and retrieval"] Retrieval --> Indexing["Indexing, extraction, structure, embeddings"] Runtime --> Evals["Evals and human review"] Runtime --> Telemetry["Performance logs and audit trail"] Telemetry --> Dashboards["Project and platform dashboards"] Telemetry --> Governance["Governance records and evidence links"] Governance --> Operations["Operations queues, reviews, and exports"] ``` Use the diagram as the review frame: 1. **Ingress and runtime:** Channels, app routes, conversations, agents, configs, and tools show what the assistant is allowed to do. 2. **Knowledge and retrieval:** Document folders show the controlled knowledge scope, indexing policy, search mode, source previews, and citations. 3. **Governance and evidence:** Governance records, evals, audit trail, and dashboards show how Gaia records quality, controls, operations, and review posture. 4. **Integration and onboarding:** MCP and delivery surfaces show how other teams or vendors connect to a bounded project without bypassing project authorization. For Lot A proposals, use this as interoperability evidence for a separately selected Lot B vendor rather than as a commitment to deliver the Lot B scope. ## Architecture evidence workflow 1. Start with the product scope: project, channel, agent, active configuration, attached document folders, and service accounts. 2. Open [Agent Configuration](#doc-agents-configs) to capture model settings, tools, prompt fragments, guardrail assignments, handoff rules, post-steps, and active version assignment. 3. Open [Document Folders](#doc-conversations-document-folders) to capture indexing settings, retrieval mode, index status, source files, search diagnostics, and source previews. If Databricks is the customer data platform, open [Databricks data platform](#doc-data-model-databricks-data-platform) to capture the SQL warehouse, Unity Catalog, Vector Search, export, or connector path. 4. Run a representative conversation and capture citations, Inside Info, timeline, selected agent/config, tool calls, and visible answer evidence. 5. Promote representative turns into [Evals](#doc-evals) or run an existing dataset, then capture [Reports](#doc-evals-reports) for quality and regression posture. 6. Open [Dashboard](#doc-dashboard) and [Platform Dashboard](#doc-platform-dashboard) to capture token, cost, latency, folder indexing spend, workflow activity, background jobs, logs, and model usage. 7. Open [Audit Trail](#doc-audit) when the review needs change history or SIEM-ready project audit rows. 8. Open [Governance](#doc-governance) to capture framework package, policies, runtime policy decisions, MCP gateway decisions, controls, obligations, classifications, explainability, agent-system boundary, linked evidence, and operations queue posture. For runtime governance proof, capture both an enforced policy decision that blocks, quarantines, or returns fallback and a review-mode warning decision that records the configured would-block or would-fallback intent without stopping execution; each capture should keep the tool-message reference, agent-system telemetry reference, and audit or delivery link together. For MCP governance proof, include a gateway intervention or review-mode warning, the searchable gateway source/phase/server/channel attributes in the control-plane preview, and any schema drift Discovery finding or accepted-baseline review. In **Governance -> Runtime -> Agent Systems**, select the boundary and generate a runtime evidence report so the summary, findings, citations, suggested actions, and evidence references are stored as a review run. 9. For vendor or partner evidence, open [Lot B interoperability evidence](#doc-coding-agents-lot-b-interoperability-evidence), [Coding Agents](#doc-coding-agents), and [Delivery Management](#doc-delivery) to capture the external-agent profile, project-bound MCP or connector setup, service-account or connector-principal authentication, project-spec or action workflow, milestones, tasks, discussions, certification gates, and support handoff. ## Deployment-specific evidence The following items depend on the selected hosting and operations model and should be finalized in the delivery evidence pack rather than treated as universal product screenshots: - storage, compute, scaling, backup, failover, RPO, and RTO; - private network, identity provider, key management, regionality, and tenant isolation details; - SIEM destination, alert thresholds, collector format, and escalation policy; - GDPR retention, deletion, and data-subject request procedures; - EU AI Act risk classification for the specific use case; - DORA ICT risk, continuity, incident, exit, and third-party dependency controls. Use Gaia's governance and audit surfaces to store and review the standard evidence. Use the customer delivery pack to bind that evidence to the selected deployment. ## Proposal evidence checklist Before a proposal table row is marked complete, collect: - the user-guide page or section that explains the capability; - the product screen or export that proves the capability is configured; - a representative run, conversation, eval, audit row, dashboard, or governance record; - the validation result or threshold used to judge success; - any deployment-specific caveat that still needs the customer environment. Avoid relying on a generic statement such as "the platform supports this" when the review asks for architecture, dashboards, runbooks, SDKs, schemas, or operational evidence. Link the row to the specific Gaia page and the live evidence artifact after deployment. Use **Project Settings -> Evidence** to generate the reviewer artifacts from the live matrix. **Request** creates the missing-ref request, **Answers** creates proposal-answer draft wording, and **Checklist** shows which rows are currently finalizable versus still blocked or waiting for customer evidence. ## Related pages - [Document Folders](#doc-conversations-document-folders) - [Databricks data platform](#doc-data-model-databricks-data-platform) - [Agent Configuration](#doc-agents-configs) - [Fragments](#doc-agents-fragments) - [Model Tier Routing](#doc-agents-model-tier-routing) - [Deployment-pool routing and failover](#doc-settings-model-routing) - [Dashboard](#doc-dashboard) - [Platform Dashboard](#doc-platform-dashboard) - [Audit Trail](#doc-audit) - [Evals](#doc-evals) - [Governance](#doc-governance) - [Coding Agents](#doc-coding-agents) - [Lot B interoperability evidence](#doc-coding-agents-lot-b-interoperability-evidence) --- # Build an AI application This walkthrough connects the key pieces of Gaia into one end-to-end path, from creating a project to shipping a working AI application. Governance is part of that path from the beginning. It is not only a late approval step. Each step links to the deeper guide so you can drill into the details. ## 1. Create a project and confirm access - Create or select a team and project in [Getting started](#doc-root). - Confirm you have the right role and permissions in [Getting started](#doc-root) and [Project roles](#doc-settings-project-roles). - Review project settings (language, roles, and audit history) in [Settings](#doc-settings). - If you want Gaia to scaffold the work from a high-level brief, choose **Ask Gaia** in the create-project dialog. Gaia drafts a starter preview and canonical project spec before it creates anything, then opens a handoff conversation after approval. ## 2. Define the application scope and governance posture - Identify the business workflow, user decisions, and unacceptable failure modes before you start building. - Decide which governance expectations apply to the system and who owns approvals, remediation, and release gates. - Use [Governance](#doc-governance) to understand how framework packages, contracts, runtime policies, controls, obligations, classifications, evidence links, and explainability fit into the Gaia lifecycle. - If you want one scenario-driven example, use [Governed application lifecycle](#doc-governance-governed-application-lifecycle). - If you want the full step-by-step neo-bank build tutorial, use [Governed Application From Scratch](../handbook/ch11-capstone-build-and-ship/05-governed-application-from-scratch.md). ## 3. Define your data model - Map your structured data in [Data Model](#doc-data-model). - Create entities and link relationships in [Entities](#doc-data-model-entities). - Store source files or exports in [Storage](#doc-data-model-storage). Governance starts here too: - define which entities and files become evidence-bearing source systems - identify which records need stronger review, auditability, or human escalation ## 4. Automate and operate data flows - Configure data flows in [Pipelines](#doc-data-model-pipelines). - Chain steps with triggers in [Workflows](#doc-data-model-workflows). - Accept inbound system payloads with [Ingestion Webhook](#doc-data-model-ingestion-webhook). - Schedule recurring updates in [Scheduled](#doc-data-model-scheduled). - Monitor execution in [Runs](#doc-data-model-runs). These operational surfaces later feed governance evidence: - workflow runs - retained outputs - operator approvals - source files and supporting artifacts ## 5. Build reusable tools and skills - Define shared tools in the [Tool registry](#doc-data-model-tool-registry). - Package instructions and tool sets in the [Skill registry](#doc-agents-skills). ## 6. Design the user experience - Build layouts and forms in [UI Layouts](#doc-conversations-ui-layouts). - Wire components to entities with [Data Binding](#doc-conversations-ui-layouts-data-binding). ## 7. Configure your agents - Create agents and tune their prompts in [AI Agents](#doc-agents). - Set up configurations, tools, and handoffs in [Agent Configuration](#doc-agents-configs). - Use [Gaia](#doc-platform-assistant) to navigate and run tools while you build. When early conversations reveal changes, Gaia can now plan spec-driven updates and show the proposed migration before it applies them. Agent design and governance should inform each other: - agent handoff and refusal logic affects governance review - tool boundaries and escalation rules affect obligations and control design - specialist agents often need distinct evidence and explainability expectations Hands-on example: Work through [Governed Application From Scratch](../handbook/ch11-capstone-build-and-ship/05-governed-application-from-scratch.md) to build the full neo-bank application in one sequence. If you want in-product repetition for individual slices, use [Tutorials](/platform/support/tutorials) as companion drills after the corresponding handbook phase. ## 8. Set up governance before release pressure arrives - Open [Governance](#doc-governance) once the use case, data model, workflows, and agent topology are clear enough to review. - Use [Overview](#doc-governance-overview) and [Operations](#doc-governance-operations) to see governance as a cross-platform coordination layer and command center. - Use [Registry](#doc-governance-registry), [Contracts](#doc-governance-contracts), [Policies](#doc-governance-policies), and [State & Memory](#doc-governance-state-memory) to define reusable governance scope, governed interfaces, runtime rules, and retention posture. - Use [Classifications](#doc-governance-classifications) when the system needs a formal governance decision about category, treatment, or reassessment. - Use [Obligations](#doc-governance-obligations) and [Controls](#doc-governance-controls) to anchor requirements and safeguards to the project. - Use [Regulatory Updates](#doc-governance-regulatory-updates), [Discovery](#doc-governance-discovery), and [Explainability](#doc-governance-explainability) when the system needs ongoing oversight after initial setup. - Assign the relevant framework package directly to the working governance records when the application belongs to a reusable standard, sector overlay, or internal governance profile. Governance in Gaia should usually link back to existing evidence sources such as runs, files, review records, tasks, and eval outputs instead of creating duplicate evidence copies. ## 9. Connect channels and branding - Create a public entrypoint and channel routing in [Channels](#doc-conversations-channels). - Confirm your app slug and theme settings in the Text channel configuration. ## 10. Test in conversations - Run live checks in [Conversations](#doc-conversations). - Inspect tool usage with [Timeline](#doc-conversations-dialogs-timeline). - Capture feedback with [Give feedback on a reply](#doc-conversations-dialogs-feedback). ### Interactive walkthrough popover script Use this storyboard when building/updating the live in-platform tutorial popovers for this flow. Open [Tutorials](/platform/support/tutorials) and select **First Use Case: Team to Conversation**. | Step | Target (`data-testid`) | Action | Popover title | Popover body | | ---- | -------------------------------------- | ----------- | ----------------------- | -------------------------------------------------------------------------------------- | | 01 | `e2e-home-create-team` | Click | Create a team | Click **Create team** and enter a team name to start your project workspace. | | 02 | `e2e-home-create-project` | Click | Create a project | Add a project under your new team so you can configure agents and channels. | | 03 | `e2e-agents-new` | Click | Add orchestrator | Create an orchestrator agent that will handle your first conversation flow. | | 04 | `e2e-config-name` | Fill | Name your config | Set a basic configuration name and choose a model for the agent. | | 05 | `e2e-config-prompt-fragments-editor-0` | Fill | Add prompt instructions | Add a short prompt fragment describing how the assistant should respond. | | 06 | `e2e-channels-new` | Click | Create text channel | Open the channel menu and choose **Text** to configure the public app entrypoint. | | 07 | `e2e-channel-slug` | Fill | Set app slug | Define the `/apps/` value used by your text channel. | | 08 | `e2e-channel-save` | Click | Save channel | Save the channel and verify it appears in the channels list. | | 09 | `e2e-conversation-input` | Type + Send | Run first conversation | Send a first message in the platform conversation UI to validate the setup end-to-end. | ## 11. Evaluate and iterate - Create eval datasets in [Evals](#doc-evals). - Use the [Eval Design Wizard](#doc-evals-dialogs-eval-design-wizard) to generate tasks. - Launch runs via [Start an eval run](#doc-evals-dialogs-start-run). - Calibrate results with [Human Review](#doc-evals-dialogs-human-review). Evals and governance work together, but they are not the same thing: - evals verify behavior quality, safety, and escalation patterns under defined scenarios - governance decides which obligations, controls, classifications, reviews, and release evidence the system must maintain ## 12. Operate and deliver - Track performance in [Dashboard](#doc-dashboard). - Manage delivery work in [Tasks](#doc-tasks) and [Delivery Management](#doc-delivery). - Capture structured evidence with [Artifact Templates](#doc-artifact-templates). - Audit critical changes in [Audit Trail](#doc-audit). Use delivery work to close governance findings in a visible way: - create tasks for remediation and control implementation - attach evidence and review outputs to the work item - use milestones and release gates to decide when the system is ready to ship ## Use Gaia as the orchestrator For cross-surface requests, Gaia is most effective when you give it the outcome instead of only the next click. - Ask for the target state, for example: "Plan and build the intake workflow, the review UI, and the delivery evidence for a new support escalation process." - Gaia uses the **Handbook** for sequencing and operating method, and the **User Guide** for exact feature-level steps. - Gaia records the work in Delivery Process, Tasks, Milestones, Evidence, Evals, and related platform resources instead of leaving the plan only in chat. - Gaia can still open the relevant pages and documentation panes when you want to inspect or take over manually. ## Real-life example > A neo-bank creates a "Customer Operations Copilot" project. The team models customers, accounts, transactions, and review cases as entities, synchronizes policy notices and case data through workflows, and designs specialist agents for onboarding, servicing, and risk review. Before release, they classify the system, map obligations and controls, run evals for escalation and refusal behavior, and route the remaining governance findings into delivery tasks before launch. ## Checklist - Project created, roles confirmed, and settings reviewed. - Governance posture and approval ownership defined early enough to guide the build. - Entities, pipelines, and workflows in place with healthy runs. - Tools and skills linked to agent configurations. - UI layouts connected to entity data. - Governance records linked to real evidence sources and not treated as a separate authoring system. - Channels configured with branding. - Conversations and evals validating quality. - Delivery work and release decisions reflect both eval outcomes and governance review outcomes. --- # Coding Agents Use this page when an external coding agent should work against Gaia from a repository that stores project briefs, spec patches, QA notes, or exported reference material. Gaia exposes a project-bound MCP setup pattern for coding agents: - **Project-bound Gaia MCP:** `http://localhost:3000/api/mcp/gaia?projectId=` The default project-bound endpoint exposes a small Project Spec Operations surface plus `gaia_mcp_skill_catalog`. Add a `skill=` or `skills=,` query parameter for focused resource work. Use your Gaia instance URL as the host. Local development instances commonly use `http://localhost:3000`; shared and production instances should use their deployed Gaia origin. Supported adapters: - [Claude Code](#doc-coding-agents-claude-code) Related proposal evidence: [Lot B interoperability evidence](#doc-coding-agents-lot-b-interoperability-evidence) covers coding agents, business-agent platforms, customer connectors, and evidence-only reviewers. ## Project-bound Gaia MCP Use the built-in `gaia` route when the repository maps to one real Gaia project and the agent should patch, review, or QA that exact project. - Bind the repository to one `projectId`. - Configure the MCP URL with that same `projectId`. - Prefer a service account from that same Gaia project. - Start with `project_spec_get_current`, then use `project_spec_patch_preview` before any apply step. This is the route for live project work, including production projects. It exposes project-spec tools and individual Gaia resource tools through the same project authorization boundary. Use skill-scoped URLs to keep external coding agents from loading hundreds of tools at once: ```text http://localhost:3000/api/mcp/gaia?projectId=&skill=project-spec-operations http://localhost:3000/api/mcp/gaia?projectId=&skill=data-model-and-entity-authoring http://localhost:3000/api/mcp/gaia?projectId=&skill=ui-layout-authoring ``` Call `gaia_mcp_skill_catalog` on the default endpoint to list the current skill slugs, descriptions, and tool names. ## Bind a repository to a Gaia project A simple repo convention is to keep the non-secret project binding in a root-level `gaia.config.json` file: ```json { "projectId": "your-gaia-project-id", "projectName": "Production Support Assistant", "gaiaBaseUrl": "https://gaia.example.com" } ``` Gaia does not read this file. It is for your repository instructions, MCP configuration, and agent prompts so every patch targets the same project. Keep the project service-account key in a root-level `.env` file or the client's secret store and keep that file out of git. When you configure the project-bound MCP server, use the same `projectId` in the URL: ```text http://localhost:3000/api/mcp/gaia?projectId= ``` The slug `gaia` is reserved for this endpoint. Do not configure MCP or ChatGPT channel slugs with that value. ## Authentication For project-bound Gaia MCP, prefer a project service account: 1. Open the target project in Gaia. 2. Create or choose a service account with the project role you want the coding agent to use. 3. Generate a **Primary** or **Secondary** API key and copy it immediately. 4. Send that key as `Authorization: Bearer ` or `X-API-Key: `. Both header forms authorize the same project service-account key. Use `X-API-Key` when an app or editor extension lets you configure static headers but cannot interpolate environment variables. Keep literal keys only in private local app or extension secret storage; committed workspace configuration should use environment placeholders or the client's secret mechanism. The built-in `gaia` route also accepts a legacy Gaia user API key when that user already has access to the target project, but service accounts are the preferred machine-to-machine credential. ## Test the connection Before you attempt a patch, prove the connection on the same repo-bound project: - In your MCP client, confirm the project-bound server appears as connected. - Make a read-only call first: ```text Use the project-bound Gaia MCP server and call project_spec_get_current. ``` - Only after that succeeds, preview a patch against the same project with `project_spec_patch_preview`. ## MCP tools By default, project-bound Gaia MCP exposes `gaia_mcp_skill_catalog` and the Project Spec Operations skill, including: - `project_spec_get_current` - `project_spec_patch_preview` - `project_spec_validate` - `project_spec_plan_migration` - `project_spec_apply_migration` Focused skill URLs expose individual resource tools when those tools are available to the shared Gaia skill catalogue, including families such as: - `agent_*` - `config_*` - `entity_definition_*` - `entity_record_*` - `workflow_*` - `ui_layout_*` - `gaia_capability_inventory_get` Use `tools=all` only when you intentionally want the full Gaia assistant non-agent tool surface in one MCP server. Browser automation remains outside Gaia. Gaia returns tools, previews, links, and state; the coding agent uses its own browser or Playwright tools for UI and canvas validation. ## Vendor onboarding evidence Use this page as the starting point when a Lot B vendor, implementation partner, or external coding agent needs controlled MCP access to one Gaia project. In a Lot A response, this evidence shows interoperability with a separately selected Lot B vendor; it does not require Gaia to own that vendor's delivery scope. For the full proposal-ready checklist, including non-coding agents such as Microsoft Copilot-style or Salesforce-style business agents, use [Lot B interoperability evidence](#doc-coding-agents-lot-b-interoperability-evidence). For onboarding evidence, capture: - the project-bound MCP URL with the target `projectId`; - the service account and project role assigned to the vendor or agent; - the authentication header pattern, without exposing the secret value; - the first read-only `project_spec_get_current` call; - the skill catalog output or the chosen `skill=` scoped URL; - a `project_spec_patch_preview` result before any apply step; - the delivery task, milestone, discussion, or eval that records the vendor's certification work. Keep vendor MCP access project-bound. Use `tools=all` only for short diagnostics by trusted operators; vendor automation should usually use focused skill URLs. ## Coding-agent setup Use the adapter page for your coding agent: - [Claude Code](#doc-coding-agents-claude-code): add focused project-bound Gaia MCP servers for the target `projectId`. ## Recommended repository shape ```text project-repo/ gaia.config.json gaia/ current-export.json gaia-patches/ qa/ eval-scenarios.md feedback-log.md content/ notes/ implementation-plan.md session-log.md ``` If the repository does not include exported reference material, start with `project_spec_get_current` from the project-bound route and save the relevant outputs or follow-up notes into the repo before drafting patches. ## Future coding agents Other coding agents can use the same project-bound Gaia MCP surfaces. A future adapter should provide: - instructions for configuring the project-bound Gaia MCP server with a concrete `projectId` - guidance to keep the repository bound to one project through a non-secret `gaia.config.json` file - a read-only authentication test before any patch preview or apply step - project-spec patch preview discipline for live project work - browser and UI validation workflow Keep those adapters thin. Gaia should expose durable capabilities through MCP, while each coding-agent adapter should only describe how that client invokes MCP tools, stores secrets, and drives browser validation. Related evidence guide: [Control Plane Evidence](#doc-control-plane-evidence). --- # Claude Code Use Claude Code with Gaia MCP when a project repository is bound to one real Gaia project. Claude Code connects to Gaia through MCP. Put the configuration in the external project repository that owns the Gaia project assets, not in the Gaia application repository. Use the built-in Gaia MCP route `/api/mcp/gaia?projectId=` for project-spec export, patch preview/apply workflows, and focused skill-scoped individual resource operations. ## MCP setup From the project repository, add the project-bound Gaia MCP server: ```bash claude mcp add --transport http gaia-project http://localhost:3000/api/mcp/gaia?projectId=your-gaia-project-id \ --scope project \ --header "Authorization: Bearer ${GAIA_PROJECT_API_KEY}" ``` Claude Code stores project-scoped MCP servers in `.mcp.json`, which can be committed for team use. Keep the API key itself outside the repository and provide it through the user's shell or secret manager. Use a root-level `gaia.config.json` file in the repository for the non-secret project binding, and keep any local CLI secrets in a root-level `.env` file that is ignored by git. Gaia accepts the same project service-account key as either `Authorization: Bearer ` or `X-API-Key: `. Use `X-API-Key` in private local app or editor-extension settings when the client can store static headers but cannot expand environment variables. Do not commit literal API keys to `.mcp.json`. The default `gaia-project` server exposes Project Spec Operations and `gaia_mcp_skill_catalog`. Add focused servers such as `gaia-data-model` with `&skill=data-model-and-entity-authoring` when the repository needs targeted resource work. Add focused servers for the Gaia surfaces this repository expects Claude Code to manipulate: ```bash claude mcp add --transport http gaia-data-model "http://localhost:3000/api/mcp/gaia?projectId=your-gaia-project-id&skill=data-model-and-entity-authoring" \ --scope project \ --header "Authorization: Bearer ${GAIA_PROJECT_API_KEY}" claude mcp add --transport http gaia-agent-config "http://localhost:3000/api/mcp/gaia?projectId=your-gaia-project-id&skill=agent-and-config-operations" \ --scope project \ --header "Authorization: Bearer ${GAIA_PROJECT_API_KEY}" claude mcp add --transport http gaia-ui-layouts "http://localhost:3000/api/mcp/gaia?projectId=your-gaia-project-id&skill=ui-layout-authoring" \ --scope project \ --header "Authorization: Bearer ${GAIA_PROJECT_API_KEY}" claude mcp add --transport http gaia-evals "http://localhost:3000/api/mcp/gaia?projectId=your-gaia-project-id&skill=evals-and-quality-operations" \ --scope project \ --header "Authorization: Bearer ${GAIA_PROJECT_API_KEY}" claude mcp add --transport http gaia-governance "http://localhost:3000/api/mcp/gaia?projectId=your-gaia-project-id&skill=governance-operations" \ --scope project \ --header "Authorization: Bearer ${GAIA_PROJECT_API_KEY}" claude mcp add --transport http gaia-delivery "http://localhost:3000/api/mcp/gaia?projectId=your-gaia-project-id&skill=delivery-process-and-evidence" \ --scope project \ --header "Authorization: Bearer ${GAIA_PROJECT_API_KEY}" ``` Use `tools=all` only for short diagnostics: ```bash claude mcp add --transport http gaia-all-tools "http://localhost:3000/api/mcp/gaia?projectId=your-gaia-project-id&tools=all" \ --scope local \ --header "Authorization: Bearer ${GAIA_PROJECT_API_KEY}" ``` Equivalent `.mcp.json` shape: ```json { "mcpServers": { "gaia-project": { "type": "http", "url": "http://localhost:3000/api/mcp/gaia?projectId=your-gaia-project-id", "headers": { "Authorization": "Bearer ${GAIA_PROJECT_API_KEY}" } }, "gaia-data-model": { "type": "http", "url": "http://localhost:3000/api/mcp/gaia?projectId=your-gaia-project-id&skill=data-model-and-entity-authoring", "headers": { "Authorization": "Bearer ${GAIA_PROJECT_API_KEY}" } }, "gaia-agent-config": { "type": "http", "url": "http://localhost:3000/api/mcp/gaia?projectId=your-gaia-project-id&skill=agent-and-config-operations", "headers": { "Authorization": "Bearer ${GAIA_PROJECT_API_KEY}" } }, "gaia-ui-layouts": { "type": "http", "url": "http://localhost:3000/api/mcp/gaia?projectId=your-gaia-project-id&skill=ui-layout-authoring", "headers": { "Authorization": "Bearer ${GAIA_PROJECT_API_KEY}" } }, "gaia-evals": { "type": "http", "url": "http://localhost:3000/api/mcp/gaia?projectId=your-gaia-project-id&skill=evals-and-quality-operations", "headers": { "Authorization": "Bearer ${GAIA_PROJECT_API_KEY}" } }, "gaia-governance": { "type": "http", "url": "http://localhost:3000/api/mcp/gaia?projectId=your-gaia-project-id&skill=governance-operations", "headers": { "Authorization": "Bearer ${GAIA_PROJECT_API_KEY}" } }, "gaia-delivery": { "type": "http", "url": "http://localhost:3000/api/mcp/gaia?projectId=your-gaia-project-id&skill=delivery-process-and-evidence", "headers": { "Authorization": "Bearer ${GAIA_PROJECT_API_KEY}" } } } } ``` In Claude Code, run `/mcp` to confirm that the server is connected. Useful Gaia skill slugs: - `project-spec-operations` - `agent-and-config-operations` - `data-model-and-entity-authoring` - `ui-layout-authoring` - `workflow-and-run-troubleshooting` - `evals-and-quality-operations` - `governance-operations` - `delivery-process-and-evidence` - `document-folder-setup-and-retrieval` - `document-artifact-editing` - `platform-build-orchestration` ## Repository instructions Add project-local instructions such as `CLAUDE.md`: ```markdown # Gaia Automation Use the `gaia-project` MCP server for live project work. - Read `gaia.config.json` first and treat that `projectId` as authoritative. - Start by calling `project_spec_get_current`. - Use `project_spec_patch_preview` before applying any project change. - Use the same bound `projectId` for every preview and apply step. - Use `gaia_mcp_skill_catalog` to choose focused skill-scoped servers for targeted resource inspection or edits. - Use `gaia-data-model` for entity definitions, entity relationships, and data-model authoring. - Use `gaia-agent-config` for agents, active configs, prompt fragments, tool lists, handoff rules, and config comparisons. - Use `gaia-ui-layouts` for persisted UI layout authoring and validation. - Use `gaia-evals`, `gaia-governance`, and `gaia-delivery` only when the task explicitly touches those surfaces. - Do not use `gaia-all-tools` unless the task is a short diagnostic that genuinely needs the full Gaia assistant tool catalog. ``` ## Suggested repository shape ```text project-repo/ .env gaia.config.json .mcp.json CLAUDE.md project-brief.md gaia/ current-export.json gaia-patches/ qa/ eval-scenarios.md feedback-log.md content/ notes/ implementation-plan.md session-log.md ``` ## Notes - Claude Code supports project-scoped MCP via `.mcp.json` and environment-variable expansion in `url` and `headers`. - For CLI use, you can keep `GAIA_PROJECT_API_KEY` in a root `.env` file and run `set -a; source .env; set +a` before starting `claude`. - Use project scope when a whole team should share the Gaia MCP server definition. - Use local scope instead when the MCP configuration should remain private to one developer. - For the project-bound route, prefer a service account from **Settings -> Service accounts** in the same target project. - In this local repository, the configured Better Auth base URL is `http://localhost:3000`. - Browser and canvas validation still happens in Claude Code's browser-capable tooling, not inside Gaia server code. ## Related docs - [Coding agents](#doc-coding-agents) --- # Lot B interoperability evidence Use this page when a proposal, audit, or delivery review needs proof that an external implementation partner, business-agent platform, automation tool, or coding agent can work with one Gaia project through bounded, reviewable interfaces. For a Lot A response, this page is interoperability evidence. It shows how Gaia can support a separately selected Lot B vendor without making Gaia responsible for that vendor's delivery scope. ## Evidence boundary Gaia evidence should prove: - project-bound access instead of tenant-wide access; - a named integration identity, service account, or customer-approved connector principal tied to a project role; - a bounded access channel for the vendor's assigned work, such as skill-scoped MCP, a customer connector, webhook, API proxy, or managed integration; - schema, project-spec, and capability discovery before changes are drafted; - preview and validation before any Gaia project-spec apply step or external-agent action enablement; - delivery records, evals, audit rows, and discussions that show certification and handoff. Deployment topology, commercial responsibilities, support hours, and customer-specific escalation paths belong in the delivery evidence pack for the selected vendor and hosting model. ## Onboarding package Prepare one package per vendor or integration boundary: 1. **Scope statement:** Name the project, the vendor role, the permitted Gaia surfaces, and the excluded surfaces. 2. **Integration profile:** Identify whether the third party is a coding agent, Microsoft Copilot-style business agent, Salesforce-style business agent, RPA/orchestration platform, custom middleware, or evidence-only reviewer. 3. **Access record:** Capture the service account, connector principal, project role, key slot or credential owner, and rotation owner without exposing the secret value. 4. **Channel list:** Record the MCP endpoint, connector, webhook, API proxy, or managed integration path used by that profile. 5. **Discovery evidence:** Capture `gaia_mcp_skill_catalog`, `gaia_capability_inventory_get`, the relevant project-spec read output, or the external platform's schema/action discovery screen. 6. **Sandbox or prepared project:** Identify whether the vendor is using a sandbox project, a branch workspace, a customer-managed test environment, or a live project with preview-only discipline. 7. **Certification gates:** Link the evals, validation checks, human review, and delivery tasks that define acceptance. 8. **Support handoff:** Record the support owner, escalation channel, evidence refresh cadence, and access end date. ## Integration profiles Use the same evidence boundary for every external agent, then adapt the channel proof: | Profile | Typical channel | Evidence to capture | | --------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | Coding agent or developer automation | Project-bound Gaia MCP with focused skill URLs | MCP URL, service account, skill catalog, read-only test, patch preview, validation, apply approval, and audit row. | | Microsoft Copilot-style business agent | Customer-approved connector, API action, webhook, or MCP bridge where available | Connector principal, allowed actions, schema/action discovery, test invocation, grounding policy, eval, and audit. | | Salesforce-style business agent or CRM agent | Customer-approved connector, API action, webhook, or middleware | Connected app or integration identity, object/action scope, test record, validation result, handoff, and audit. | | Databricks data-platform integration | SQL warehouse, Unity Catalog, Vector Search, export, webhook, or middleware | Databricks principal, catalog/schema/index scope, query or retrieval test, masking policy, eval, fallback, audit. | | Databricks agent integration | Databricks Agent Framework, Databricks App, managed MCP, external MCP, or API | Agent endpoint, model/tool scope, MCP/action direction, smoke test, eval or trace, Gaia handoff, audit, support. | | RPA, workflow, or integration-platform agent | Webhook, API proxy, queue, middleware, or managed connector | Trigger scope, payload schema, retry/error behavior, least-privilege identity, monitoring, and support owner. | | Evidence-only reviewer or certification agent | Read-only MCP, export, dashboard, audit, eval, or governance access | Read-only role, exported evidence package, access expiry, review result, and offboarding owner. | Do not force a business-agent platform into the coding-agent workflow. Use MCP when the third party can consume it directly or through a bridge. Otherwise, treat the third party as an external action consumer or connector and prove the same access, discovery, validation, audit, and support controls through that channel. ## MCP access pattern For coding agents and MCP-compatible integrations, use one project-bound route as the root contract: ```text https:///api/mcp/gaia?projectId= ``` For routine MCP work, prefer focused skill URLs: ```text https:///api/mcp/gaia?projectId=&skill=project-spec-operations https:///api/mcp/gaia?projectId=&skill=data-model-and-entity-authoring https:///api/mcp/gaia?projectId=&skill=delivery-process-and-evidence ``` Use `gaia_mcp_skill_catalog` to choose additional eval, governance, workflow, document-folder, or UI-layout skill slugs when the vendor's assignment needs them. Use `tools=all` only for short diagnostics by trusted Gaia operators. Vendor automation should normally stay on skill-scoped URLs so the review can show least-privilege intent. For non-MCP business agents, capture the equivalent connector or action configuration instead of an MCP URL. The evidence still needs the same boundary: named principal, allowed actions, schema discovery, test invocation, validation gate, telemetry, audit, and offboarding owner. ## Read, preview, apply Require this sequence before a vendor or external agent changes a Gaia project or enables a Gaia-backed action: 1. **Read:** Call `project_spec_get_current`, use the narrow resource read tool, or inspect the connector's configured schema/action list. 2. **Discover:** Call the skill catalog, capability inventory, or external platform action discovery when the vendor needs to confirm available schemas and tool families. 3. **Preview:** Call `project_spec_patch_preview` for proposed Gaia project-spec changes, or run the external platform's equivalent test action before enabling it. 4. **Validate:** Call `project_spec_validate` or run the agreed eval, delivery, governance, or connector certification check. 5. **Apply or enable:** Call `project_spec_apply_migration` or enable the external action only after the preview and validation evidence is accepted. 6. **Record:** Link the preview, validation result, applied change or enabled action, and follow-up evidence to the delivery task or discussion. If a vendor only needs evidence access, stop at read, discover, and preview. Do not grant apply permissions for review-only work. ## Certification evidence Use Gaia delivery and quality surfaces to prove the vendor can operate safely: - [Delivery Process Cycle](#doc-delivery-process-cycle): stage activities, evidence, owners, and acceptance notes. - [Delivery Tasks](#doc-tasks): assigned certification tasks and blocker resolution. - [Delivery Discussions](#doc-delivery-discuss): decisions, questions, and support handoff notes. - [Evals](#doc-evals): regression, grounding, tool-use, and safety checks. - [Audit Trail](#doc-audit): service-account activity and change history. - [Project Versions and Branches](#doc-delivery-versions): baseline snapshots, branch workspaces, and merge evidence. For proposal evidence, capture the product pages and exports that show the vendor completed the agreed gate. Avoid relying only on meeting notes or email summaries. ## Evidence checklist Before marking interoperability evidence complete, collect: - the integration profile and permitted Gaia surfaces; - the project-bound MCP URL, connector, webhook, API proxy, or managed integration path with the target `projectId` where applicable; - the service account, connector principal, project role, and key-slot or credential posture; - the focused skill URLs or external action scopes assigned to the vendor; - the read-only connection test result; - the schema, capability, or external action discovery output; - one patch preview, connector test, action test, or preview-only certification result; - the eval, validation, or human-review gate used for acceptance; - the delivery task, milestone, discussion, or version record that stores the handoff; - the audit row or export that proves the machine principal was used; - the access review date and offboarding owner. ## Related pages - [Coding Agents](#doc-coding-agents) - [Databricks data platform](#doc-data-model-databricks-data-platform) - [Service accounts](#doc-settings-service-accounts) - [Delivery Management](#doc-delivery) - [Evals](#doc-evals) - [Audit Trail](#doc-audit) - [Control Plane Evidence](#doc-control-plane-evidence) --- # Discussions The platform-level **Discussions** page at `/platform/support/discussions` gives all signed-in users a shared discussion space across projects. ## Related pages - [Tasks](#doc-tasks) - [Delivery Discussions](#doc-delivery-discuss) - [Conversations](#doc-conversations) ## What you can do - **Browse global topics.** See discussion threads created at the platform level. - **Search and filter.** Use keyword search, task-status filters, tags, and sorting (`Recently updated`, `Recently created`, `Top voted`) to find active conversations quickly. Choose **No status** in the task-status filter to show discussions that are not linked to a platform task. Tag and task-status filters can be combined with search and sorting. Topic rows show whether the visible timestamp is the original creation time or newer activity. - **Create topics.** Start a new discussion with a title, optional body, tags, and optional file attachments. - **Write with Markdown.** Topic bodies and replies open in the Visual editor by default, with Markdown source available when you want to work directly with the canonical text. Inline screenshots still work from the editor toolbar. - **Vote and follow activity.** Upvote useful posts and track which threads are gaining momentum. - **Get automatic Gaia follow-up when it adds value.** Gaia reviews new platform topics and replies. It may answer platform-usage questions directly, ask for missing details on bug reports, or help turn feature requests into clearer product requirements. - **Open topic detail pages.** Review the topic body, author, created time, replies, and tags from the thread view. - **Share topic links.** Opening a topic updates the URL with that topic, and the link button in the topic header copies a direct link for users who can access the thread. - **Close inactive topics.** Topic owners and platform discussion moderators can close a topic when no further action is planned. Closed topics stay commentable, and a new comment reopens the topic automatically. - **Watch topics.** New topics are watched automatically by their creator. Use **Unwatch** anytime to stop alerts, or **Watch** again later. - **Escalate platform work into Platform Tasks.** Platform discussion topics can attach directly to the platform-maintainer task queue when the thread needs tracked follow-up. - **Show public progress for linked work.** Once a topic is linked to a platform task, Gaia automatically mirrors task progress with a public badge such as **Open**, **In progress**, or **Closed**, plus an outcome like **Addressed in 3.0.25** or **Will not address**. If the linked completion version is the current platform version or a newer one, Gaia also adds a **Deployed** badge. ## Topic-level actions - **Watch or unwatch a thread.** The topic page includes a dedicated watch toggle so you can subscribe only to threads that matter to you. - **Edit or delete your own topics.** Topic owners can update or remove their own threads. - **Embed images in topics and replies.** Use the image button in the editor, or paste/drag an image directly into the body field. - **Print the rendered topic body.** Use the **Print** button in the topic body card to open the browser print dialog for the rendered Markdown. - **Pin or lock topics.** Platform admins can pin important topics or lock threads when a conversation should stay read-only. - **Attach discussions to tasks.** Project discussions attach to project tasks, while platform discussions attach to platform tasks, so follow-up work leaves the thread and enters the right queue. - **Open linked tasks from the topic.** When you can access the relevant task surface, the topic detail view shows direct links back to the linked project or platform task. - **Copy a direct topic URL.** Use the link button in the topic header when you need to reference a specific thread in another conversation, task, or handoff note. - **Mention people in discussion content.** Type `@` in a topic title, topic description, or comment to pick a matching user from the discussion audience. Delivery Discussions only suggest people who can access that project, while Platform Discussions suggest active platform users. Rendered mentions appear as highlighted labels in the thread. - **Open linked maintainer work.** When a platform discussion is attached to a platform task, the linked item in the task dialog opens the full discussion thread so maintainers can move between execution work and the original report. - **See automatic public status updates.** Linked platform topics reflect the state of their platform task automatically. When the task is completed, Gaia also shows the version tag recorded on that task and marks the topic as **Deployed** once that version has reached the current platform runtime. ## Open Discussions 1. Use the top navigation bar. 2. Click **Discussions** or open `/platform/support/discussions`. 3. Browse existing topics or select **New Topic** to start one. If you need a project-specific thread tied to execution work, open [Delivery Discussions](#doc-delivery-discuss) inside the project instead. ## Operational workflow Use Discussions as the intake surface for ideas, decisions, and open questions, then move execution into [Tasks](#doc-tasks): 1. Start or review a platform-level topic. 2. Clarify the next action in the thread title, body, or replies. Gaia may respond automatically when the thread looks like a product question, bug report, or feature request that needs more detail. 3. Attach the topic to a platform task if the thread needs platform-maintainer follow-up. 4. If the topic is linked, keep the attached platform task up to date. Gaia reflects the task state and completion version on the topic automatically, and users with task access can jump straight from the topic into the linked task. 5. If the work belongs to a specific project, continue the conversation in [Delivery Discussions](#doc-delivery-discuss). 6. Capture the resulting follow-up as a task so it can be scheduled, assigned, and tracked. ## Access requirements - You must be signed in. - Platform-wide moderation actions such as pinning or locking are restricted to platform admins. ## Tips - Add concise tags so related topics are easier to discover. - The topic-status filter defaults to open topics. Switch it to **Closed topics** or **All topics** when you need earlier discussion history. - Platform task-status filters can show linked topics by task progress or untracked topics with **No status**. - `Recently updated` reflects the latest topic activity, including reply edits and linked platform-task status changes. - Use descriptive titles that state the question or proposal clearly. - If Gaia needs more information, reply in the same thread with the missing steps, screenshots, or requirements details so the conversation can keep moving without opening a separate support channel. - Images embedded in global discussions are stored with the topic or reply and are removed automatically when that topic or reply is deleted. - `@` user mentions work in both Platform Discussions and Delivery Discussions. Delivery suggestions stay scoped to the current project audience, while platform suggestions include active platform users. - File attachment pickers appear only while you are creating a topic or editing an existing one. Topic pages keep uploaded files available for download without reopening the attachment editor. - Use platform Discussions for cross-project topics, announcements, and shared operating questions; use [Delivery Discussions](#doc-delivery-discuss) when the thread belongs to one project's delivery cycle. - Shared topic links preserve access control. A recipient must still be signed in and allowed to view the discussion. --- # Tutorials Use **Tutorials** for guided, in-app walkthroughs that combine route navigation, highlighted UI targets, and live step-by-step progress. The platform-level tutorials workspace lives at `/platform/support/tutorials`. For the full neo-bank build tutorial, use [Governed Application From Scratch](../../handbook/ch11-capstone-build-and-ship/05-governed-application-from-scratch.md). The Tutorials page is best used for focused in-product practice after you complete the corresponding handbook phase. ## Related pages - [Getting started](#doc-root) - [Build an AI application](#doc-building-an-ai-application) - [Conversations](#doc-conversations) ## What you can do - Browse tutorials grouped by category. - Run the new **Operations & Governance** walkthroughs for operational review and discussion handoff flows. - Preview each tutorial before starting. - Start an interactive walkthrough that moves step-by-step through the product. - Follow the **Document Folders: Collaboration Basics** walkthrough for folder creation, sharing, conversations, upload/import, and search. - Use **Operations: Review, Audit, and Rebalance** to move from dashboard signals to tracked follow-up work. - Use **Operations: Discussion to Execution** to turn a platform discussion into owned project work. - Use governance tutorial cards to rehearse package setup, evidence linking, and review routing after you complete the handbook capstone steps. ## Open Tutorials 1. Use the top navigation bar. 2. Click **Tutorials** or open `/platform/support/tutorials`. 3. Choose a card and select **Start tutorial**. ## Real-life example > An operations lead opens Tutorials, runs the operational review walkthrough to investigate a dashboard spike, creates a follow-up task from the review, and then rechecks Timesheet before assigning the work. ## Tips - Run tutorials in sequence when onboarding a new team. - Use the operations tutorials as recurring review drills, not only first-day onboarding material. - Re-run a tutorial after UI updates to verify the flow still matches your process. - Use tutorials as companion drills inside the [AI Engineer Handbook](/handbook) learning path. --- # Installation Guide Use **Installation Guide** at `/platform/support/installation-guide` when you need signed-in access to infrastructure setup, hosted deployment, and Azure rollout instructions. This resource is intended for DevOps, infrastructure, and platform engineering teams. It renders the repository installation guide markdown inside Gaia so operators can browse deployment pages without using the public marketing documentation routes. ## What you can do - Browse installation topics from the Support section. - Search hosted deployment and Azure rollout instructions. - Open deep links to individual installation guide pages. - Keep the guide access limited to signed-in users with Support learning-resource access. ## Related pages - [Getting started](#doc-root) - [Tutorials](#doc-tutorials) - [Training Program](/platform/support/training-program) --- # Conversations The **Conversations** workspace is where teammates and customers chat with your Gaia agents. It combines messages, tool output, and optional data panels so you can see everything that happened in a turn without switching screens. The canonical list view for this workspace now lives at `/projects/[projectId]/tools/conversations/list`. Project-level navigation for this module now lives in tabs at the top of the page: - **List** for chat threads - **Channels** for channel configuration - **UI Layouts** for the visual layout editor and layout folders - **Folders** for shared document workspaces - **Memory** for shared-memory review, proposals, and lifecycle actions - **Actions** for workflow approval and operator-input queues - **File Extractors** for reusable upload extraction rules shared by channels This grouping keeps the interaction workspace together: channels define how conversations enter the platform, layouts shape the conversation-side canvas but also power published apps, folders manage shared files, actions handle operator follow-up, and file extractors control upload enrichment across channel entry points. ## Workspace map Use the tab docs in the same order you see them in the product header: - [Channels](#doc-conversations-channels) for channel routing, publishable entry points, file-upload rules, and channel theme settings. - [UI Layouts](#doc-conversations-ui-layouts) for conversation-side and app-side data presentation. - [Document Folders](#doc-conversations-document-folders) for shared file workspaces, folder-linked search, and Personal Assistant folder flows. - [Memory Workspace](#doc-memory) for durable shared memory review and lifecycle controls. - [Workflow Actions](#doc-conversations-workflow-actions) for approvals, decisions, and operator-input queues created by workflow runs. - [File extractor registry](#doc-conversations-file-extractor-registry) for reusable upload extraction policies shared across channels. ## Key capabilities - **Chat with context.** Share links, attach files, and format responses in Markdown when your prompt allows it. - **Inspect cited sources.** Grounded replies can show compact numbered citation markers, a **Sources** tray beneath the answer, or both, according to the channel citation settings. Open a source preview to review the excerpt, page, line, sheet, or row details, then jump to the underlying document, artifact, or web source. Retrieval times stay hidden by default and can be shown with a citation or only inside source details; exact evidence remains available to authorized diagnostics and internal exports. - **Control configuration.** Switch agents, language, and evaluation markers directly from the conversation header. - **Track review workflows.** Mark conversations as **For review**, **In review**, **In progress**, or **Addressed** and optionally capture pass/fail decisions during review. - **Review feedback faster.** The **Review** section now shows how many assistant bubbles have thumbs up, thumbs down, and written feedback, plus previous/next controls that jump between reviewed bubbles inside the transcript. - **Capture fast sentiment signals.** Use assistant-message thumbs up/down reactions when you need conversation-level positive or negative ratings without opening the note dialog. - **Tag conversations.** Add reusable tags in the conversation header and filter the conversation list by one or more tags. - **See conversation creators.** The conversation list shows a **Created by** column for platform members and app users, including guest app conversations. - **Favorite important threads.** Click the star icon to mark conversations as favorites. Use the filter toggle to show only starred threads when you need quick access to high-priority chats. - **Review staged runs.** In the main project Conversations workspace, use the toolbar's **Execution** panel to inspect staged protocol status, checkpoints, and typed outputs without leaving the thread. - **Invite conversation participants.** Use the participants button beside the composer to invite app users and agents into a thread. Folder-linked conversations also show inherited folder participants. - **Mention invited people and agents.** Type `@` in the composer to mention invited participants. `@human` mentions send platform notifications when the app user is linked to a platform account; `@agent` mentions force that invited agent to reply. - **Navigate the runtime accessibly.** Gaia end-user shells now include skip links on login, text, and Personal Assistant routes, plus named message and composer regions for assistive technology. - **Use an accessible composer.** The message log announces new replies, icon-only controls expose spoken names, and mention suggestions stay available to screen readers while you type. - **Let invited agents react.** On normal conversation turns, Gaia can automatically route the turn to up to two invited agents whose names and descriptions match the latest request. - **Run bulk actions.** Select one or more conversations from the list and use **Select action** to apply Delete, Evaluate/Unevaluate, Export, Favorite/Unfavorite, or Tag to all selected rows at once. - **Export multiple conversations.** Select one or more rows and use **Select action -> Export** to generate either a single DOCX or a JSON array file containing all selected conversations. Leave **Include feedback in export** enabled when you want reviewer notes embedded with the exported messages. - **Keep your filters handy.** Gaia remembers the last filter set you used in each project, including folder filters, so returning to Conversations restores your view automatically. - **Share filtered views.** Use **Share** in the Conversations toolbar to copy a deep link for the current filtered list. Teammates who already have access to the same project will open the same filtered view directly. - **Monitor execution.** Open the [Timeline dialog](#doc-conversations-dialogs-timeline) or **Inside Info** to understand how long a turn took, which tools ran, and how many tokens were consumed. - **Inspect the raw transcript.** Click **Messages** to open the JSON view for debugging or exporting interactions. - **Share conversations quickly.** Use the **Print** button for a PDF-friendly layout or **Export** to download a DOCX or PPTX copy of the conversation or email a transcript. The export dialog can also include assistant-message feedback when you want review notes in the file or attachment. - **Open app previews from the list.** In the Conversations screen, **End-user UI** opens the selected published channel directly, or lets you choose from a channel dropdown when multiple end-user channels are active. **Portal UI** appears only for Text channels. - **Jump between views.** In conversation pages, **End-user view** opens directly to the matching end-user channel for that conversation type (no channel menu). If the conversation type has no end-user app (for example, MCP), the button is hidden. - **Open portal mode only for Text conversations.** In conversation pages, **Portal UI** appears only when the current conversation belongs to a Text channel. - **Open folder tools from conversations.** In Personal Assistant conversations, Gaia shows the linked folder directly in the header so you can jump into that folder context. In project conversation pages for Personal Assistant channels with folder features enabled, use **Folder workspace** to open the same file-and-folder tools in a dialog without leaving the conversation. When you start a new conversation from a thread that is already linked to a folder, Gaia keeps the new conversation linked to that same folder. - **Preview Text portal mode.** Use **Portal view** to open `/apps/[slug]/portal` for Text channels; the floating panel there loads the same end-user conversation URL as the current thread so you can preview the embedded app context and the generated embed-script experience before you install it on a customer site. The floating frame includes minimize, maximize, and close controls by default, and channel settings let you hide maximize, choose whether expanded mode uses half screen or full screen, configure the default chat width and expanded half-screen width, and set the default chat height as a viewport percentage without code changes. Default width can be stored as either a viewport percentage or a fixed pixel value, while default height stays viewport-relative so the panel can stay tall across different browser sizes and half-screen expansion can grow horizontally without changing height. When a new assistant reply arrives while the launcher is minimized, Gaia now shows a red-dot unread badge on the launcher bubble until the user reopens the chat. Text-channel portal settings can also show localized Info and Warning banners, a localized close-confirmation dialog, and a localized read-only Terms & Privacy notice above the composer until the first user message. The **Messages** tab owns that wording, while the **Portal** tab keeps styling, icons, link URLs, and layout controls. The same Text-channel settings page also exposes a hosted/downloadable embed script, an optional custom-JavaScript hook for host-side behavior, URL-pattern controls for deciding which host pages should show the launcher, and an optional **Reuse conversation across tabs** toggle for keeping Portal preview tabs, direct end-user app tabs, and embedded iframe sessions on the same thread. Hosted and downloaded embed links stay anchored to Gaia's configured public base URL so customer-hosted copies still target the correct app origin. Portal preview also keeps the bridge simulator on the page surface above the floating assistant so you can test embed params, and host context when enabled, without giving up popup space. - **Launch voice sessions.** Start a realtime conversation whenever your project includes a compatible voice model. Use the mic button above the paperclip in the composer and Gaia will stream the transcript into the same message list, with live status announcements for setup, recording, and playback states ([learn more](#doc-conversations-dialogs-voice-conversation)). - **Open related canvases.** Some agents can launch a split-screen view to show entity data, forms, or dashboards alongside the chat. - **Keep lists clean.** Gaia hides zero-turn draft conversations from the main Conversations table. In Personal Assistant history, zero-turn drafts are hidden unless they are the currently open conversation. - **Browse longer personal history.** In Personal Assistant channel history, the list is scrollable and loads additional conversations in batches of 20 with **Load more**. ## Roles & access - **All authenticated project members** can open Conversations, create threads, and give feedback unless your organization limits it. - **Project admins** unlock extras such as Timeline, Inside Info, Assessment, Update Statistics, and the raw **Messages** log button. - **Project admins** can also lock or unlock the current conversation from its header. Locking stops new turns and queues the conversation-level post-events configured on its agent; unlocking starts a fresh inactivity window. - **Conversation creators, conversation owner participants, and users with Manage conversations** can invite or remove conversation-only participants. Folder-inherited participants must be managed from the folder participants UI. ## Conversation participants and mentions Conversation participants are scoped to the transcript. Inviting a human or agent to a standalone conversation lets them participate in that conversation, but it does not grant access to a document folder or its files. For channel-backed conversations, collaboration is controlled per channel. Open **Conversations -> Channels -> Text/Personal Assistant -> Files** and enable **Allow collaboration** before users can invite participants, use mention autocomplete, or trigger invited-agent reactions through that channel. Use the participants button next to the composer to review who is in the thread: - **Human participants** can open the conversation and receive notifications when mentioned if their app-user record is linked to a platform user. - **Agent participants** become available for automatic collaborative reactions and explicit `@agent` replies. - **Owner** participants can manage conversation-only participants. - **Folder** badges mark participants inherited from a linked document folder. Remove those participants from the folder, not from the conversation. Mentions are resolved only against current conversation participants. If you type an unresolved `@name`, Gaia leaves the text as normal message content and does not notify or route anyone. When you mention an invited agent, Gaia forces that agent to answer for the turn. Forced mentioned agents are processed before any automatically selected agents. If a mentioned agent has no active configuration, Gaia adds a visible error for that agent and continues with the rest of the selected agents. When no agent is explicitly mentioned, Gaia may select up to two invited agents based on each agent's name and description plus the latest conversation context. If Gaia selects any invited agents, the active coordinator skips its normal answer for that turn and only posts lightweight routing status while the selected agents reply. ## Start or resume a conversation 1. Click the chat bubble icon in the left navigation. 2. Stay on the **List** tab. 3. Pick an existing thread from the list or select **New** to start fresh. The **New** menu lists the configured channels in your project so you can choose the right entry point (text, SMS, email, or voice), and the new conversation always opens in the platform Conversations workspace. If you pick a folder-capable **Personal Assistant** channel, Gaia opens a create dialog so you can start with **No folder**, an **Existing folder**, or a **New folder**. If only one non-folder channel is configured, **New** starts that channel immediately. Use **End-user UI** beside **New** when you want the published channel surfaces, and use **Portal UI** when a Text channel is available. 4. Type a message and press **Enter** (or click the paper airplane). Hold **Shift+Enter** for a newline. 5. Watch the assistant respond in real time. When the turn finishes you can rate it or [leave feedback](#doc-conversations-dialogs-feedback). 6. If you need to interrupt a running reply, click the **Stop** button (the stop icon that appears in place of Send while Gaia is generating). If you edit a previous user message, Gaia also stops the in-flight reply before rewinding the thread. The discarded branch is preserved as a recoverable branch snapshot with the edited message, later branch messages, preservation time, and restore audit metadata. Use **Branches** in the conversation toolbar to list preserved branches and restore the branch that should become current again. Interactive walkthrough: Open [Tutorials](/platform/support/tutorials) and select **First Use Case: Team to Conversation**. ### Configure the turn The configuration bar at the top now opens with full controls visible by default. Click **Hide details** to collapse back to the compact summary chips (Agent, Config@Version, Language). Expanded controls let you: - Choose the **Agent** and **Version** you want to test. Active versions are clearly labelled. - Use **Model tier** when the project has tier-labelled configurations such as `T1`, `T2`, and `T3`; selecting a tier switches the conversation to that tier's active configuration. - Switch the **Language** for the current conversation without impacting other projects. - Set **Review** state and optional **Decision** (pass/fail while in review) from the dedicated **Review** section. - Use the **Review** section counters to spot how many assistant replies already have thumbs up, thumbs down, or written notes. - Use the **Review** section's **Previous** and **Next** controls to jump between assistant replies that already have feedback, with a live `current of total` position indicator between the buttons. - Toggle **For evaluation** from the **Review** section so the thread appears inside [Evals](#doc-evals). - Use these review controls as part of a full error-analysis loop with [the Ultimate Evals Guide](#doc-evals-ultimate-guide). - Add or select conversation **Tags** for triage and filtering from the **Review** section. - Manage tag cleanup from the **Tags** dropdown in the **Review** section. Users with **Manage conversations** permission can click the **X** next to a tag to remove it globally from all conversations in the project (with confirmation). - Rename the thread. Gaia auto-saves titles after a short pause. ### Filter by review and tags Open **Filters** in the conversation list to combine: - review state - review decision (pass/fail) - Gaia assistant visibility (hidden by default; you can include Gaia conversations or limit the list to Gaia-only) - thumbs up / thumbs down conversation ratings - tags (choose existing tags or type new ones) - folder - existing filters such as favorites, errors, feedback, creator, channel, and date Use **Share** after applying filters to copy a link that preserves the current conversation-list view. The shared URL keeps the active filters in the address bar, so refreshing the page or opening the link later restores the same filtered result set. When tag clutter builds up (for example, temporary QA labels), open a conversation, go to **Review → Tags**, and delete obsolete tags from the dropdown so they disappear project-wide. ### Bulk actions in the list Use the checkbox column at the start of each row to select multiple conversations on the current page. After at least one selection, a **Select action** dropdown appears next to the filter summary. - **Project admins** can run: Delete, Evaluate, Unevaluate, Export, Favorite, Unfavorite, and Tag. - **All members with conversation-management access** can run: Export, Favorite, and Unfavorite. - Every bulk action opens a confirmation dialog before changes are applied. - **Tag** opens the same tag picker used in single-conversation view. In bulk mode, the merged tags from the selected conversations appear as chips in the field first, and the dropdown shows the remaining project tags that are not already selected. You can still type a new tag if needed. - Use the `x` next to a tag suggestion to delete that tag entirely, matching the single-conversation tag manager behavior. ### Monitor a turn with Inside Info Admins can toggle **Inside Info** from the action bar. Conversation-level usage appears as an always-visible inline summary above the transcript, showing the total token equation along with cost, AI time, tool time, turn count, and throughput. Message-level Inside Info exposes the deeper tool logs, prompt context, and errors for each turn. When an assistant reply uses a logical deployment pool, its **Model routing** block shows the logical and selected models, each routed target attempt, provider attempts and retries within that target, duration, outcome, whether Gaia failed over, and safe correlation fields such as the HTTP status, error code, and provider request ID. A target-scoped `401` or `403` can therefore appear as a non-retryable target failure followed by failover to a different deployment. Gaia does not fail over when that provider attempt already emitted partial content or proposed a tool call. If a terminal provider failure triggers the channel's configured automatic live-support handoff, the same block reports whether that handoff succeeded. Raw provider messages, prompts, credentials, endpoints, and response payloads are not included in this trace. Use it with the [Timeline](#doc-conversations-dialogs-timeline) to connect the routing decision to the rest of the turn. See [Model routing and failover](#doc-settings-model-routing) for configuration and validation. Inside Info is available only in the authenticated project workspace to users with the required administrative access. It is not added to the assistant's message text and is not exposed in normal published app or portal conversations. ### Review staged execution If the active configuration uses an execution protocol and you can view AI Agents, the main project **Conversations** workspace shows an **Execution** button in the toolbar. This panel is for the signed-in project workspace; published app-style conversation views do not expose it. 1. Click **Execution** in the toolbar. 2. Review the compact panel above the transcript. Gaia shows the overall session status, current stage, any pending next stage, last-updated time, latest checkpoint summary, and any typed checkpoint outputs recorded for that stage. 3. Click **Review details** to expand the latest checkpoint summary and structured outputs. 4. If the panel shows **Waiting for user**, send an explicit approval message such as "continue", "approved", or "go ahead" to move into the pending next stage. 5. If the checkpoint is **blocked**, reply with the missing input or evidence. Gaia keeps the same stage active; there is no separate resume button in the conversation panel today. 6. To cancel or restart a staged run, open [Agent Configuration](#doc-agents-configs) and use **Execution -> Recent execution sessions**. ### Assess quality Enable **Assessment** to see clarity, tone, helpfulness, and coherence scores. Gaia shows the latest assessment generated by the agent's **Assessment** post-step, so run another conversation turn after changing the config if you need refreshed results. ### Inspect the raw transcript Project admins can open **More** in the action bar and select **Messages** to open the JSON transcript for the current conversation. Use it to confirm tool calls, share a reproducible log with teammates, or copy specific request/response payloads when filing a bug. The JSON viewer includes a **search bar** so you can quickly locate specific text, tool names, or error messages within large transcripts. Need a formatted copy? Open **More** and choose **Print** for a print-friendly view (ideal for PDF exports), or **Export** to download a DOCX/PPTX document or email a transcript to teammates. In the export dialog, leave **Include feedback in export** checked when you want reviewer notes attached under assistant replies that have feedback. Assistant replies that carry provider source evidence include a **Source evidence** section in exports with retrieval timestamp, provider, URL, and file details where available. ### Inline UI blocks An assistant can also embed an interactive UI directly inside a reply when the task is small enough to stay in the transcript. Use this when you want a quick review form, checklist, or compact dashboard without opening the side canvas. Choose inline UI when: - the surface is short-lived or turn-specific - you want the UI to stay attached to the reply itself - you do not need artifact revision history or a right-side runtime session For a complete setup example, follow [Scenario: Inline UI layout responses](#doc-conversations-scenarios-inline-ui-layout-responses). ### Multi-pane canvas When an agent shares extra data, a right-side canvas appears. Use it to edit or review records without leaving the conversation. The canvas respects the layouts and validation rules defined in [UI Layouts](#doc-conversations-ui-layouts) and the [Data Model](#doc-data-model). For conversation artifacts, the canvas now supports multiple artifact types: - **Markdown artifacts** render in the markdown editor. - **p5 artifacts** render as a live sketch preview and open in read-only mode by default. When opened in editable mode, the canvas splits into two panes: - Top: sketch output preview - Bottom: p5 source code editor - **Spreadsheet artifacts (`grid-json`)** render in a spreadsheet canvas with bottom sheet tabs (Excel-style), editable formulas with calculated values, resizable columns, row/column header menus for insert/delete operations, and multi-selection (cell range, row range, column range) plus a formatting toolbar (font size, bold, italic, background color, text color, format, and wrap). Interaction follows spreadsheet conventions: single-click selects, drag creates range selections, Shift+Arrow extends selections, and double-click/F2/typing enters cell edit mode. - **Runtime UI canvas artifacts (`ui-layout-canvas`)** render a saved or snapshot UI layout plus live state values in the side canvas so the conversation can continue around that interactive session. - **Oversized spreadsheet preview artifacts** open as read-only workbook previews when an uploaded CSV/XLSX exceeds the interactive grid limits. Gaia preserves the original spreadsheet source, shows a bounded preview in the canvas, and keeps the file exportable while editable/query-first workbook support is expanded. ### Activate and use the canvas 1. Configure the entity in **Data Model → Entities**: - Ensure the entity is set up for UI usage. - Attach at least one UI Layout to that entity. 2. Configure the layout in **Conversations -> UI Layouts**: - Bind form fields to entity properties. - Save the layout and confirm it is linked to the target entity. 3. Confirm your agent can operate on entity records in conversations (for example, opening and updating records). 4. Open a conversation in either a **Text** channel or a **Personal Assistant** channel. 5. Ask the assistant to open a specific entity record (for example: “Open the Renewal Opportunity for account ACME-102”). 6. When the assistant returns a canvas update, the conversation splits: - Left panel: chat - Right panel: entity UI layout with record data 7. Edit values in the right panel. Changes write back to entity records according to your layout bindings. Continue chatting in the left panel for follow-up actions. 8. Use the **X** button to close the canvas, or drag the divider to resize it. If a record is updated again during the same conversation, the canvas can refresh to show the latest saved values. For a pure document workflow (upload, edit, export) that does not require entity canvas setup, follow [Scenario: Document upload, edit, and download workflow](#doc-conversations-scenarios-document-editing-workflow). For split-canvas runtime UI sessions that are not entity-bound, follow [Scenario: Runtime UI canvas artifact workflow](#doc-conversations-scenarios-runtime-ui-canvas-artifact-workflow). ## Real-life example > A field-operations manager asked, “Show the three most recent safety incidents and draft an email to follow up.” The assistant opened the incidents in the split canvas, displayed editable cards, and drafted the email inside the chat. The manager tweaked the copy, sent it, and then reviewed the [Timeline](#doc-conversations-dialogs-timeline) to confirm the handoff rules behaved as expected. ## Related guides - [Gaia](#doc-platform-assistant) — a side-panel assistant that can navigate or perform quick actions for you. - [Agent Config Checklist for Canvas and Document Workflows](#doc-conversations-agent-config-checklist) - [Conversation Scenarios](#doc-conversations-scenarios) - [Scenario: Live-agent bridge takeover workflow](#doc-conversations-scenarios-live-agent-bridge-takeover-workflow) - [Scenario: Folder-grounded Personal Assistant setup](#doc-conversations-scenarios-folder-grounded-personal-assistant-setup) - [Scenario: Inline UI layout responses](#doc-conversations-scenarios-inline-ui-layout-responses) - [Scenario: Entity canvas workflow](#doc-conversations-scenarios-entity-canvas-workflow) - [Scenario: Runtime UI canvas artifact workflow](#doc-conversations-scenarios-runtime-ui-canvas-artifact-workflow) - [Scenario: Document upload, edit, and download workflow](#doc-conversations-scenarios-document-editing-workflow) - Dialog references: - [Give feedback on a reply](#doc-conversations-dialogs-feedback) - [View a conversation timeline](#doc-conversations-dialogs-timeline) - [Update project statistics](#doc-conversations-dialogs-update-statistics) - [Start a voice conversation](#doc-conversations-dialogs-voice-conversation) ## Tips & shortcuts - **Search quickly:** Use the browser’s find shortcut (⌘/Ctrl + F) while the conversation list is focused. - **Tag important threads:** Rename conversations with a prefix such as “🔥 Urgent” so they stand out. - **Attach files:** File uploads are disabled by default. Enable **Allow attach to model** and/or **Allow upload to storage** in **Conversations -> Channels -> Text/Personal Assistant -> Files** to show the paperclip next to the message box. Then choose **Attach to model** (supported by eligible primary models) or **Upload to storage** (saved under the conversation folder and optionally routed into data workflows). The attachment picker supports **PDF**, **DOCX**, **ODT**, **MD**, **TXT**, **CSV**, **XLSX**, **ODS**, **PPTX**, and **ODP**. - **Image and vision inputs:** When the selected model and channel support visual inputs, upload image or visual PDF material through the same attachment controls. Gaia keeps the source in conversation or folder storage, sends supported visual inputs to the configured model, and shows citations or source previews where the answer uses retrieved visual evidence. - **Route uploads into workflows:** In the same **Files** tab, add rules with a filename pattern, one or more file types, and a workflow. Each matching rule starts its own workflow run and passes only the matching files into the first source. - **Reuse extraction logic across channels:** Create shared rules in [File extractor registry](#doc-conversations-file-extractor-registry) when multiple channels should classify or enrich uploads the same way. - **Export transcripts:** Use the conversation **Export** action to download the current transcript as DOCX or PPTX, including reviewer feedback when the export dialog option is enabled. - **Artifact workflow (Phase 1):** For fresh work, agents can create artifacts directly with `artifact_create`. For uploaded files, Gaia mirrors attachments into conversation artifact storage and eagerly materializes supported uploads as conversation artifacts after the message is sent. Those artifacts appear in the **Artifact** selector without opening the canvas automatically; agents or users can open them later when needed. When the active runtime supports the file type, Gaia also sends the file to the model in parallel. If the provider rejects direct model attachment for a format (for example `DOCX`, `ODT`, `XLSX`, or `ODS` on some providers), Gaia falls back to artifact-only handling without blocking the message. OpenAI Responses supports the full document/spreadsheet set listed below, PDF-only attachment runtimes stay limited to PDFs, and Anthropic native runtimes attach PDFs plus text-style documents while keeping spreadsheets artifact-only. Continue edits with `artifact_update` and export with `artifact_export` using revision-based collaboration. If the open canvas has unsaved edits, Gaia asks you to save first. If a newer saved revision arrives while your local draft is still unsaved, Gaia keeps your draft visible, shows that a newer saved revision exists, and lets you review **Current draft** vs **Latest saved revision** before choosing whether to combine both versions, keep only your draft, switch to the latest saved version, or decide later. If Gaia cannot merge saved revisions safely, it asks you to review the latest revision before retrying. For spreadsheets, agents should prefer `artifact_spreadsheet_mutate` for structured edits such as cells, formulas, styles, rows, columns, and sheets instead of rewriting the full workbook JSON. Phase 1 import support covers **PDF**, **DOCX**, **ODT**, **ODP**, **MD**, **TXT**, **CSV**, **XLSX**, **ODS**, and **PPTX**. Artifact editing supports canonical formats **markdown**, **p5-js**, and **grid-json** (spreadsheets). Spreadsheet exports support **XLSX** (default) and **CSV**; CSV export uses the active sheet. - **Large spreadsheets:** When a workbook is too large to read comfortably as raw `grid-json`, agents should query it server-side for sheet summaries, exact A1 ranges, filtered row previews, grouped totals, multi-column aggregations, distinct counts, medians, percentiles, and date-bucketed analysis instead of streaming the full canonical JSON through the model context. Those query results should be consumed as compact `table.schema` + `table.records` data or `coordinate-cells-v1` cells for `range_read`. For `table_rows`, `group_sum`, or `aggregate` results that span multiple pages, continue with the returned `window.nextOffset`. - **Keyboard navigation:** `Esc` closes dialogs, `Tab` and `Shift+Tab` move focus, and `Ctrl/Cmd+K` opens the browser search box. ## Troubleshooting - **Messages aren’t sending:** Check your connection. If the send button spins for more than 30 seconds, refresh the page—drafts usually recover. - **Timeline or Inside Info missing:** Confirm you’re signed in as a project admin. Viewers only see the core chat experience. - **Voice button disabled:** Your project may not include a realtime-capable model yet. See [Start a voice conversation](#doc-conversations-dialogs-voice-conversation) for setup tips. - **Paperclip icon missing even though “Allow attach to model” is on:** Check the channel first. The paperclip appears only when the active Text/Personal Assistant channel enables file uploads. Then check the conversation's primary model. Attach-to-model is available only when the active model supports model attachments. - **Canvas never opens:** Confirm the entity has a linked UI Layout and that your active agent is configured to open entity records in conversations. - **Canvas shows but does not save edits:** Check field bindings and write-back configuration in the UI Layout. Also verify you are not in a read-only conversation context. --- # Channels Channels define how your project receives inbound communication and which AI agents handle it when needed. Open this page from **Conversations -> Channels**. ## Related pages - [Settings → Channels (Text)](#doc-settings-tabs) - [Channel security and access](#doc-conversations-channels-security-and-access) - [Conversations](#doc-conversations) ## What you can do - Create channels (Text, Personal Assistant, Alternative frontend, SIP, MCP, ChatGPT, Webhook, Twilio SMS, WhatsApp, Viber, Email) - Assign agents to conversational channels - Use channels without a default agent when the channel type supports it, and route MCP or ChatGPT agent tools per capability - Review how many agents are involved in each channel (including handoffs and agent tools) - Manage channel versions and switch each version on or off - Expand/collapse channel versions grouped by channel name - Duplicate an existing channel into a new version - Open a channel to edit its configuration - Copy the **Experience**, **Messages**, or **Files** tab settings from one Text or Personal Assistant channel into another, including channels in other projects you can access, without changing the current slug or channel identity - Configure channel-level file uploads, knowledge folders, and file-to-workflow routing for Text and Personal Assistant channels - Review [channel security and access](#doc-conversations-channels-security-and-access) before publishing guest, authenticated, or folder-backed Text and Personal Assistant experiences - Review disabled **Downloadable packages** fields on Text and Personal Assistant channel **App** tabs when an offer needs PWA, desktop, or mobile package evidence To add a channel, use the **New** menu in the Channels list, pick a channel type, and complete the configuration in the dialog that opens. Interactive walkthrough: Open [Tutorials](/platform/support/tutorials) and select **First Use Case: Team to Conversation**. Popover script: [Build an AI application → Interactive walkthrough popover script](#doc-building-an-ai-application-interactive-walkthrough-popover-script). ## Channel versions and availability - Every channel has a **Version** (default: `1.0`) and an **Enabled** toggle. - Only one version can be enabled for a given channel name/type at the same time. - If all versions are disabled, that channel is not available on its endpoint. - New channels are enabled by default unless you explicitly turn them off. ## Copy settings When you open a **Text** or **Personal Assistant** channel, use **Copy settings** above the tab strip when you want to reuse another channel's shell setup without duplicating the whole channel. - Choose the source **project** first. When the project belongs to a team, Gaia shows it as **Team / Project**. Then choose the **Text** or **Personal Assistant** channel from that project. - Select any combination of **Experience**, **Messages**, and **Files** before applying the copy. - Gaia keeps the current channel's slug, name, version, enabled state, and agent bindings. - If the source and target use different channel types, Gaia copies only the fields that both tabs expose. For example, Text portal-frame settings do not move into Personal Assistant, and Personal Assistant folder controls do not overwrite Text-only settings. ## Real-life example > A retail team launches a Text channel for their public chatbot, adds WhatsApp for mobile support, and configures a Webhook channel to trigger the order-status workflow from their CRM. ## Text (chatbot) The **Text** channel is the main entry point for chatbot-style experiences. - Set the **App slug** used for the public `/apps/` entrypoint (unique across the platform). - Use **Lock inactive conversations** to close a Text conversation after the configured number of minutes without a completed turn. The next visit starts a new conversation instead of appending to the locked transcript. Project admins can still unlock an individual conversation from its conversation header, or disable the rule and use **Unlock** to reopen every conversation for that channel. - Use **Default language** to override the project default for this channel when the app URL does not include `lang`. - Use **Authentication** to control access for this channel only: anonymous, required, or optional sign-in. When the channel needs a partner or institution sign-in broker instead of the default platform login, configure the provider and policy in [Configurable authentication](#doc-settings-configurable-auth). - Use **Typography -> Font family** on the App tab to keep the default UI font, choose a Google Font, or select an uploaded custom font for the hosted Text channel and embedded portal. - Use **Upload font** in the same section when the Text channel should use a channel-scoped custom font family. Enter the family name first, then upload a `TTF`, `OTF`, `WOFF`, or `WOFF2` file. Gaia keeps uploaded fonts available in the selector even after you switch the selected family back to **Default**. - Use the **PII** tab to redact detected personal data from user message text before transcript storage, search indexing, model input, and tool input. Attachments are not redacted by this setting. The tab lets you enable redaction, choose whether Azure should detect all categories except exclusions or only selected categories, tune the minimum confidence, set the Azure model version, and decide whether the channel fails closed when redaction is unavailable. New redaction configs exclude date/time categories by default to avoid masking ordinary words such as "now". - Use **Show feedback button** to show or hide only the written-feedback control under assistant messages. When disabled, Gaia hides the written-feedback icon and rejects new written-feedback submissions for the channel, but thumbs up/down remain available when their footer toggle stays on. - Use **Like active color**, **Dislike active color**, **Feedback active color**, and **Voice active color** to control the selected or submitted footer-action colors for this channel. - Use **Show assistant timestamps**, **Show assistant thumbs feedback**, and **Show assistant read-aloud** to control the assistant-message footer for this channel. Thumbs feedback remains available when the written-feedback button is hidden. When read-aloud is enabled, **Read-aloud model** can override the assigned agent's Voice tab TTS model for this channel; leave it set to the agent voice setting to inherit the agent configuration. - Use **Source citations** on the **Conversation** tab to show or hide citations, place them inline, at the end of the answer, or in both positions, and keep retrieval times hidden or expose them with the citation or only in source details. New and legacy Text channels default to hidden citations, inline placement, and hidden retrieval times. Visible PDF transcripts follow this policy, while authorized diagnostic exports retain exact source evidence. - Use **Show dislike handoff button** to add the configured handoff label to the thumbs-down dialog. The button is hidden by default; when users click it, Gaia sends the visible button text as a normal user message instead of triggering a direct handoff action. Selecting **Incorrect information** or **Not relevant** saves that reason against the assistant message, shows the configured confirmation toast, and keeps the feedback available in the conversation review surfaces even when the written-feedback icon is hidden. Use **Dislike modal button colors** to set independent background and text colors for **Incorrect information**, **Not relevant**, and **Connect to live agent**. The button wording and the confirmation toast text stay configurable in the **Messages** tab. - Use **Enable user input character counter** to show a live `current/max` counter inside the Portal composer and enforce a per-message character maximum for this Text channel. When enabled, **Maximum characters** defaults to `500` until you set a different limit. - Use **Show off-topic cause in visible reply** to decide whether Gaia appends the detector explanation for end users. **Inside Info** and the **Messages** page always show it for reviewers. - Use the **Avatars** section to enable user avatars and agent avatars separately. - User avatars reuse the standard Gaia user avatar by default, and anonymous users show a generic user icon until you configure a channel-specific avatar asset. - When **Show user avatars** is on, you can upload a supported User avatar asset or paste its URL, preview it, restore Gaia's default icon, choose whether Gaia keeps the uploaded colors or applies the configured icon color, and set User avatar background, border, and icon colors independently. Leave any color blank to keep Gaia's existing behavior. - Agent avatars show an AI badge with the assigned agent name below it until you configure a channel-specific Agent avatar asset. - When **Show agent avatars** is on, you can upload a supported AI Agent avatar asset or paste its URL, preview it, restore Gaia's default icon, choose whether Gaia keeps the uploaded colors or applies the configured icon color, and set Agent avatar background, border, and icon colors independently. Leave any color blank to inherit the channel theme defaults. - SVG is the recommended avatar format because it stays crisp at small sizes and works best with configurable icon coloring. Gaia also accepts supported PNG and WebP avatar uploads. - When configured icon color is selected for a custom avatar asset, Gaia renders the uploaded SVG, PNG, or WebP avatar through the shared configurable image renderer instead of CSS masking. - Use **External participants** when a third-party human or system needs to take over the conversation temporarily. - Bind the channel to a **Bridge Agent** so provider connection, authentication, actor identity, routing, and bridge hooks are managed in one place. See [Bridge Agent Settings](#doc-agents-live-chat-bridge-agent) for the form-field reference. - Bridge Agent **Provider** defaults to **Custom** for normalized transport envelopes and project-owned integration logic. Choose **Genesys** when you want Gaia's reference Genesys adapter and Genesys-specific runtime controls. - Use channel-level **Allowed origins** and host-context controls for the embedded surface. When the Bridge Agent provider is **Genesys**, use **Auth mode** for API-key or signed-webhook server-to-server calls. - Turn on **Automatic handoff on AI failure** when a configured Bridge Agent should take over after Gaia exhausts an AI provider request or exceeds the turn response deadline. Provider failures and timeouts are selected by default; enable **Execution failures** only when other unrecoverable runtime or tool failures should also escalate. User stops, locked conversations, and recoverable budget or policy outcomes do not trigger this flow. Customize the short end-user notice in the channel **Messages** tab. - Configure named external actors on the Bridge Agent so the conversation UI shows the correct speaker name and avatar while Gaia is paused. - Use Bridge Agent **User turn routing** to decide whether new end-user turns use the default takeover-only behavior, always stay with Gaia, always go to the external provider, or run custom TypeScript that returns one of those two outcomes per message. - TypeScript-based Bridge Agent routing and incoming or outgoing bridge hooks expose an optional **Execution timeout (ms)** override. Leave it blank to use Gaia's default limit. - Custom TypeScript routing can also call the shared provider-dispatch helper described in [Engineering reference: TypeScript tools](#doc-agents-typescript-tools) when the external path should immediately forward Gaia's normalized bridge envelope to your integration layer. - In the default takeover-only routing mode, Gaia records new end-user turns in the transcript but does not open another assistant response until the bridge posts an explicit `resume`. The **Always use Gaia orchestrator** and **Custom TypeScript decision** modes can route selected turns back through Gaia even while takeover state exists. - Gaia now includes a reference Genesys transport adapter on the provider-facing bridge route. Keep outbound live-support calls, retry logic, and any non-Genesys vendor mapping in your own TypeScript tools or integration service. - Turn on **Allow iframe host context** when the app is embedded inside another web experience that needs to pass session-specific JSON into bridge-aware tools without writing that JSON into the conversation history. - Use **Host context TTL (seconds)** to control how long Gaia keeps that host-provided JSON available for the active embedded session before it expires automatically. - Use **Portal view** from the Conversations workspace to test embed params for Text channels and, when enabled, iframe host context manually. The portal preview exposes the simulator on the preview surface above the floating assistant so you can provide a host origin plus JSON payloads without shrinking the popup. - Use the **Portal assistant** section to keep or hide the default **Maximize** button, show a copy action for the internal Gaia project URL of the current conversation, choose whether it expands the floating portal window to **Half Screen** or **Full Screen**, set the default chat width as either a viewport percentage or a fixed pixel value, set the default chat height as a viewport percentage, tune the expanded half-screen width percentage, choose how horizontally overflowing assistant cards expose extra content, and customize the floating launcher button color/image. The card overflow control defaults to the browser and OS scrollbar behavior, with optional prominent scrollbar and arrow-button modes. Gaia stores the uploaded launcher image in its original supported web format, and if you clear it, the portal falls back to the default message icon. - Use **Show real-time voice chat** in the same section when the embedded portal should expose the left-side realtime voice conversation control. Turn it off when the channel must stay text-only even if the assigned agent has realtime voice configured. - Use **Show speech-to-text microphone** in the same section when the embedded portal should expose the composer microphone for one-off dictated text messages. Turn it off when end users should type only. - Use **Show PDF download button** in the same section when the embedded portal header should show a PDF icon button to the left of **New conversation**. The button downloads a PDF transcript of the current conversation with only the visible **User** and **Assistant** message content. - Use the **New conversation** controls in the same section when the portal header button should use portal-specific text, aria label, a custom left icon, dedicated background, border, and text colors, or custom button padding. Leave the icon blank to keep Gaia's default plus icon, use 1 to 4 `px` or `rem` values when you set padding, and update the localized text from the **Messages** tab. Uploaded SVG icons inherit the button color and hover styling automatically. - Use **Assistant frame -> Header controls** in the same section when you want to reorder the embedded portal header controls without typing a custom layout string. The editor lets you move the existing controls, add one divider, and preview the result before saving. **Portal controls idle color** applies the subdued default color for **Copy Conversation Link**, **Expand**, **Minimize**, and **Close**, **Portal controls interaction color** applies the hover, keyboard-focus, and pressed color for those same controls, and **Header controls divider color** styles the divider when present. Gaia blocks duplicate controls or duplicate dividers, keeps existing visibility toggles unchanged, and removes orphan dividers automatically when hidden controls leave one side empty. - Use **Composer -> Initial rows** in the same section when the embedded portal message box should start taller than the default single-line composer. - Use **Composer -> AI disclaimer** in the same section when the portal should show persistent informational text below the message box. Turn on **Show AI disclaimer** to display the footer, and edit the localized wording in **Messages** under `portal-ai-disclaimer-text`. - Minimized Text launchers now show a red-dot unread badge when a new assistant reply arrives while the launcher is collapsed, and Gaia clears that badge as soon as the user reopens the chat. - Use the **Assistant frame** controls in the same section to tune the floating portal frame background, border, text, and icon colors. The portal frame preview shows the embedded conversation container together with the minimize, optional maximize, and close controls. - Clear **Portal assistant -> Assistant label** when the public portal avatar should show no label text under the assistant icon. - Use **Info message** and **Warning message** in the same section when the portal chatbot should show dismissible conversation-top banners under the embedded header. Each banner keeps its toggle, icon URL or uploaded SVG/image asset, accent color, optional background color, and text color in the Portal tab, while the banner wording now lives in the **Messages** tab so it can localize with the rest of the Text channel. Gaia shows enabled banners above the first assistant message, keeps them at the top of the chat history instead of making them sticky, and restores them after a refresh or chatbot reset. - Use **Close confirmation** when the portal close button should ask the end user what to do before the widget closes. The Portal tab keeps the dialog icon, primary button colors, per-action visibility toggles, and the optional Tool Registry hook that Gaia runs when an active portal conversation is ended. The title, description, button labels, and return-link copy now live in the **Messages** tab so they change with the active chatbot language. Leave the dialog icon blank when the modal should render without any icon. When the setting is off, the close button keeps closing the portal immediately. When it is on, the primary button ends the portal session, while the secondary button and return link dismiss the modal and return to the chat. The same hook also runs when the end user starts a **New conversation** from an active chat, and Gaia passes `source` as `close_action` or `new_conversation` so the tool can distinguish the trigger path. - Use **Terms & Privacy message** in the same section when the Text chat must show a legal notice before the end user sends the first message. The Portal tab keeps the toggle, inline link URLs, and optional dedicated link color. The notice text and inline link labels are managed from the **Messages** tab so Gaia can localize them per platform language. Gaia keeps the notice read-only for end users, replaces each matching phrase with an external link that opens in a new tab, and hides the notice automatically after the first user message in that conversation. - The AI disclaimer is separate from **Terms & Privacy message**. It appears below the composer, stays visible after the first user message, does not support links, and does not require consent or acknowledgement. - Use the **Embed script** controls in the same section when you want Gaia to generate a hosted installer for an external website or customer portal. - Copy the recommended `` snippet to load the Gaia-hosted script directly, or use **Download script** if the customer wants to host the JavaScript file themselves. Gaia now keeps those links anchored to the configured public Gaia base URL so downloaded files still point back to the right hosted app origin even when the script itself lives on a customer-managed site. - Add an optional `data-lang="en"` attribute on that script tag when the embedded assistant should start in a specific language. If you omit it, Gaia falls back to the channel, conversation, project, and default language rules automatically. - Add optional custom `data-*` attributes on the same script tag when the parent page needs to pass host-specific values into the embed script. Gaia keeps `data-lang` working exactly as before and also exposes the other script-tag values to **Custom JavaScript**. - Use `embed.getScriptData(name)` inside **Custom JavaScript** to read one script-tag value at a time. Gaia accepts either the dataset-style key such as `userEmail` or the raw attribute name such as `data-user-email`. - Use `embed.scriptDataset` when you want all parsed custom script-tag values as one object keyed the same way as standard browser `dataset` access. - Use **Custom JavaScript** when the generated embed script needs host-side behavior beyond the default launcher and frame controls. Gaia runs that code inside the generated installer with an `embed` helper so you can react to iframe readiness and forward structured params into the embedded app before or after the conversation finishes loading. - A typical pattern is: ```html ``` ```js embed.onIframeReady(() => { const userEmail = embed.getScriptData('userEmail'); const accountId = embed.getScriptData('data-account-id'); if (!userEmail) { return; } embed.setParams({ user: { email: userEmail, }, account: { id: accountId, }, }); }); ``` - Use `embed.setParams(payload)` after reading the script-tag values when the embedded conversation should receive structured host context. Use `embed.clearParams()` when the host page should explicitly remove that context for the current embed session. - Calls to `embed.setParams(payload)` now keep the latest payload in the active conversation's short-lived server cache as well as the iframe runtime, so channel tools can inspect the current embed parameters without enabling the external bridge integration flow. - Use **Embed param allowed origins** to restrict which parent-page origins are trusted to send `embed.setParams(payload)` and `embed.clearParams()` messages into the iframe. Leave it empty to trust the current embed parent origin automatically. Existing channels temporarily fall back to legacy Bridge allowed origins until this field is set. - Turn on **Reuse conversation across tabs** in the **Portal** tab when Portal preview browser tabs, direct end-user app tabs, and embedded iframe sessions for the same Text channel should stay on the same conversation. Leave it off to preserve the existing per-tab behavior. - Use **URL patterns** to decide which host-page URLs should show the floating launcher. Patterns are include-only, use simple `*` wildcards, and match only the host page's `origin + pathname` so query strings and hashes do not affect visibility. - Leave **URL patterns** empty when the launcher should appear on every page where the script is installed. - If the Text channel requires authentication, the embedded iframe still follows Gaia's normal sign-in rules or the configured channel auth policy. - Use **Text app color mode** to lock this channel to **Light** or **Dark** mode, independent of the platform user theme. - The **Downloadable packages** section on the **App** tab reserves the channel-level evidence fields for a PWA manifest, Windows package, macOS package, Android package, and iOS package. These fields are disabled until a packaged build is published for the channel; use them as the reference location for tender evidence, not as proof that packages are currently downloadable. - New Text channels default to **Light** mode. - Use the **Theme** section to configure channel-specific colors and logos. - The theme editor now has a **Conversation** tab and a **UI** tab. - Use **Conversation** to edit only the conversation experience: page canvas, top bar, assistant/user messages, composer shell, composer input, and conversation controls. - Leave a **Conversation** field blank to inherit the matching value from the **UI** theme. - Conversation overrides are surface-specific. For example, changing **Composer Input → Input text** or **Composer Input → Input border** does not change bubble colors. - Use **Conversation Theme -> Composer Input -> Input outer padding** to control padding around the full composer wrapper, including the textarea, send button, microphone, and attachment actions. Use **Input padding** in the same section only for spacing inside the textarea itself. - Use **Conversation Theme -> Interactive Controls -> Send button** when the portal composer Send icon needs a custom uploaded asset or asset URL, uploaded-color vs configured-color rendering, configurable width and height, or separate enabled and disabled background, border, and icon colors. The icon color fields accept `#hex`, `oklch(...)`, `rgb(...)`, `rgba(...)`, `hsl(...)`, `hsla(...)`, and `transparent`. - When **Apply configured icon color** is selected, Gaia renders uploaded SVG Send icons as single-color assets. Uploaded PNG and WebP icons keep their original uploaded colors. - The Send button preview in the same section shows both disabled and enabled states, and the live conversation preview lets you test empty, whitespace-only, valid, and over-limit composer states before you save. - Use **Composer Shell -> AI disclaimer text** when the portal footer disclaimer needs its own text color. Leave it blank to inherit Gaia's quiet secondary composer text color. - Use **Top Bar -> Header rounding** and **Conversation Actions -> Action rounding** when the conversation shell needs rounded surfaces that differ from the shared card rounding. - Keep the Portal header wording in **Messages** under `portal-header-title`. - Use **Conversation Theme -> Top Bar -> Header title typography** to style that localized Portal header title without editing the message content itself. - **Header title font size** accepts only `px` or `rem` values such as `16px` or `1rem`. Leave it blank to inherit Gaia's default header-title size. - **Header title font weight**, **Header title font style**, and **Header title text decoration** all support an inherited blank state, so clearing the value restores the default runtime rendering. - Use **Conversation -> Page Canvas -> Background layers** to stack decorative images behind the conversation header, transcript, and composer without changing dialogs, menus, or other shared UI surfaces. - Each background layer can use either a pasted URL/path or an uploaded image, plus its own **Fit** and **Anchor** settings so you can place corner or edge decorations without stretching them across the whole canvas. - Background layers render only inside the core conversation UI. In Personal Assistant they do not affect the left rail, folder drawer, or dialogs. - Use **UI** to edit the shared theme for dialogs, menus, cards, buttons, inputs, and selects outside the conversation surface. - Logo previews in Channel Settings are centered for Text and Personal Assistant channels. - If transparent logo edges look rough in preview, switch the preview background to white or black. - Use the preview panel to see a read-only **Text channel** conversation preview or a shared **UI** kit preview, with a Light/Dark toggle for both themes. - The **Conversation** preview uses the real conversation renderer in read-only mode, so heading colors, link colors, inline UI layouts, and the assistant thinking state appear the same way they do in the live channel. - Portal header title typography updates appear in the Light and Dark previews before you save, and the same typography applies to every localized value of `portal-header-title`. - The preview now shows contrast warnings for runtime text combinations that are hard to read, including the current text/background pair and a suggested readable text color. - Gaia blocks saves only when a new or edited theme still has critical conversation-theme contrast failures. If the channel already has critical theme issues and you save unrelated non-theme settings, Gaia keeps the warning visible but still saves the non-theme change. - Use **Assistant Bubble -> Assistant bubble border / metadata** when the assistant reply surface needs its own outline color or quiet metadata tone instead of inheriting the shared border token. - Use **Assistant Bubble -> Assistant bubble shadow** or **User Bubble -> User bubble shadow** when a bubble should use a custom CSS box shadow. Enter `none` to remove the shadow completely. - Use **Assistant Bubble -> Assistant bubble rounding** or **User Bubble -> User bubble rounding** when the message bubbles should not inherit the shared card rounding. - Use **Assistant Bubble -> Hide footer spacer when footer actions are hidden** when live Text conversations should remove the reserved empty space below assistant replies that do not show footer actions. The Conversation Theme preview keeps its existing spacer behavior until you save and open the live channel. - Use **Assistant Bubble -> Thinking text / dots** when you want the loading text and animated thinking dots to use a dedicated color instead of inheriting the normal assistant text color. - Use **Show thumbs** and **Show read-aloud** under **Conversation -> Assistant message footer** to keep the existing footer visibility behavior while revealing the new footer-icon controls only when each feature is on. - When **Show feedback button** is on, use **Feedback icon** to upload or paste a written-feedback icon asset, preview it, restore Gaia's default icon, and set **Feedback default color** independently from **Feedback active color**. - When **Show thumbs** is on, use **Thumbs icons** to upload or paste separate Like and Dislike icon assets, preview each asset, restore Gaia's default icon, and set **Like default color** and **Dislike default color** independently from the existing active-state colors. - When **Show read-aloud** is on, use **Read-aloud icon** to upload or paste the idle Read-aloud icon asset, preview it, restore Gaia's default icon, set **Read-aloud default color**, and keep the existing **Read-aloud model** behavior unchanged. - Use **Icon color mode** to decide whether Gaia preserves the uploaded asset colors or renders the custom icon as a single-color icon that uses the configured default color while idle and the existing active color when selected or playing. SVG is recommended when you want configured-color rendering for custom footer icons. - Use **Apply the same default color to all assistant footer icons** only as a shortcut in the editor; Gaia saves the resulting per-icon default-color fields for Feedback, Like, Dislike, and Read-aloud, not a separate shared toggle. - Gaia accepts SVG, PNG, and WebP footer icon assets up to 5 MB. SVG is recommended because it stays crisp at small sizes and works best with configurable icon coloring. - Use the **Preview state** options in the **Conversation** tab to inspect non-default conversation states such as hover and focus. - Assistant heading and link colors still fall back to the channel theme when you leave them blank. - Use the **Files** tab to control the paperclip button for this channel: - **Allow attach to model** exposes model attachments when the active configuration's primary model supports them. - **Allow upload to storage** exposes conversation storage uploads. - Each file is limited to 10 MB. One message can upload at most five files and 20 MB combined. - **Knowledge folders** attach shared background document folders at the channel level. - Mark channel knowledge folders as **Important** when they should be searched in the first pass with any linked work folder. - Mark channel knowledge folders as **Fallback** when Gaia should search them only after the first pass is weak or empty. - **Upload routing and metadata extraction** lets each rule target a direct workflow, a reusable registry extractor, or an inline extractor. - Use **File extractor presets** when you want Gaia to open the preset dialog for the common upload buckets: one general extractor for `txt` / `md` / `docx` / `odt`, one stronger extractor for `pdf`, and one spreadsheet extractor for `xlsx` / `ods` / `csv`. - **Add preset** creates any missing preset buckets and updates the existing wildcard rules or registry entries only when they already own the same supported file types. - After adding that preset, use **Open file extractor registry** if you want to inspect or fine-tune the generated extractors without rebuilding them by hand. - Use **Registry extractor** when you want the same extraction logic reused across channels. - Use **Inline extractor** when the extraction logic is specific to this channel only. - Inline AI and Agent extractors can now return a reserved `metadata` + `indexing` envelope. Gaia uses `indexing` hints to enrich folder retrieval labels, aliases, anchored sections, sheet summaries, and PDF visual-analysis decisions while keeping canonical text extraction in the core indexer. - Workflow contract for the first pipeline source: - Configure a **Context Storage** source with key `conversation_storage_upload`. - Gaia seeds each run with `conversationId`, `messageId`, `uploadedAt`, `channelSlug`, `ruleId`, optional `filenamePattern` / `fileTypes`, and a `files` array containing `{ name, path, url, contentType? }`. - Supported uploads (`docx`, `txt`, `md`, `pdf`, `xlsx`, `csv`) are expanded into records and enriched with `conversationId`, `messageId`, and `uploadedFile` metadata before the next pipeline stage runs. - Workflow contract for the last pipeline target: - Gaia does not wrap the record stream again after parsing. The last target receives exactly the transformed records emitted by the final stage. ## SIP (phone) The **SIP** channel is used for telephony integrations. It requires an agent with an active configuration that sets a realtime model. ## Webhook Use the **Webhook** channel to trigger a data workflow or a project-owned TypeScript processor via an inbound HTTP request. - Set a unique **Webhook key** for the URL path segment. - Choose either the **Workflow** to run or a **TypeScript webhook processor** from the project Tool Registry. - Copy the read-only **Webhook URL** (generated from the platform host configuration). - Gaia stores webhook workflow input as `{ "headers": { ... }, "payload": }` by default. - Update pipeline mappings and TypeScript transforms to read request fields from `payload.*`. - If you enable **Preserve raw body**, Gaia also stores `rawBody` so signature verification can hash the exact request body instead of a re-serialized JSON object. - If you use **JSON Array Path**, point it into `payload` (for example `payload.items`). - If that path resolves to an array, Gaia stores each element under indexed keys like `your-key-0`, `your-key-1`, and you should read them with a context pattern like `your-key-*`. - If that path resolves to a JSON object instead of an array, Gaia stores a single record at the exact webhook key (for example `your-key`, not `your-key-0`). - Use **Dynamic response** when you want webhook callers to receive a workflow-driven HTTP response instead of the default `202 Accepted`. - When **Dynamic response** is enabled, Gaia responds with: - HTTP status from workflow output or execution outcome. - JSON body in the shape `{ "status": , "data": }`. - Optional: set **Response context key** (default: `webhook_response`) if your workflow writes a custom response object at that key with the same `{ status, data }` shape. - A TypeScript webhook processor receives `input.request`, sanitized string-valued `input.headers`, and `input.files` as `{ name, type, size, base64 }`. Gaia removes credential-like headers before execution. - Gaia stores the selected registry ID together with its name and version. Runtime lookup falls back to name/version so project exports remain portable when registry UUIDs change between environments. - Return `{ status: "completed", response: }` to skip the agent and use `response` as the synchronous webhook data. A completed processor can also return `httpStatus` (an integer from 200 through 599) and `retryAfterSeconds` (an integer from 1 through 86400). Gaia uses the status for the HTTP response and emits `Retry-After` when supplied. Return `{ status: "continue", context?: }` to attach `processor_context` to the fallback agent request. - Use **Processor maximum input bytes** to constrain the sanitized request envelope plus combined decoded upload size. The default is 25 MiB and Gaia caps the setting at 100 MiB. - Keep vendor- and project-specific validation, extraction, and response contracts in the TypeScript registry tool. Gaia supplies only generic runtime primitives such as `fetch`, `decodeQrFromDocument`, `pdfToText`, and `pdfToPositionedText`. ## Twilio SMS Use the **Twilio SMS** channel to configure Twilio account credentials, sender number, and webhook security. ## WhatsApp Use the **WhatsApp** channel to configure provider details (Meta Cloud API or Twilio), sender identity, and webhook security. ## Viber Use the **Viber** channel to configure sender identity and webhook security. ## Email Use the **Email** channel to configure inbound (IMAP/POP) and outbound (SMTP) server settings, credentials, and sender defaults. ## MCP **MCP** channels let you configure a security policy and a list of capabilities. Capabilities can be tagged as tools, resources, or prompts. When a capability is an agent-routed tool, assign that capability to a specific agent. - Set the **MCP slug** to define the `/api/mcp/` endpoint for this channel. - Use `/api/mcp/` as the MCP server URL. - The slug `gaia` is reserved for Gaia's built-in `/api/mcp/gaia` endpoint and cannot be used for channel-defined MCP or ChatGPT routes. - MCP channels do not use a channel-level default agent. Each agent-routed capability must name its own agent. - In MCP `initialize`, Gaia returns the channel **Version** as the server `version`, so clients can identify which channel version is active. - Prefer project [service accounts](#doc-settings-service-accounts) when an MCP client needs Gaia project permissions. Gaia accepts both `X-API-Key` and `Authorization: Bearer ` for those credentials. - When a runtime MCP governance gateway is enabled for an agent configuration or contributed by approved Governance Policy metadata, MCP tool calls pass through gateway preflight before Gaia contacts the MCP server. Gateway decisions can block denied tools, require approval evidence for sensitive tools, enforce per-scope rate budgets, downgrade would-block decisions to review warnings, block or sanitize flagged MCP responses before the model sees them, and record schema fingerprint observations. Gateway interventions can appear in Governance Operations as runtime policy work items. When an observed tool schema or descriptor drifts from the accepted baseline, Gaia records the drift as Governance Discovery evidence for review. - Keep the channel-level static API-key option for cases where you explicitly want one shared secret at the channel boundary instead of a role-bound project identity. ## ChatGPT (MCP Apps) **ChatGPT** channels use the MCP Apps protocol. Configure your app metadata, security policy, and per-capability agent routing. - Set the **MCP slug** (optional) to define the `/api/mcp/` endpoint for this channel. - Use `/api/mcp/` as the MCP server URL. - The slug `gaia` is reserved for Gaia's built-in `/api/mcp/gaia` endpoint and cannot be used here. - ChatGPT channels do not use a channel-level default agent. Each agent-routed capability must name its own agent. - Use project [service accounts](#doc-settings-service-accounts) when the ChatGPT-side integration should have project-scoped Gaia permissions. ## Personal Assistant **Personal Assistant** channels provide a full-screen end-user assistant experience while still storing conversations as regular text conversations for platform tools, inside info, and evaluations. Interactive walkthrough: Open [Tutorials](/platform/support/tutorials) and select **Personal Assistant: Folders Setup**. The tutorial card includes a companion video if you want a quick visual pass before editing the channel. Recommended setup sequence: [Scenario: Folder-grounded Personal Assistant setup](#doc-conversations-scenarios-folder-grounded-personal-assistant-setup). - Set the **App slug** to define the `/apps/` end-user route for this channel. - Use **Default language** to override the project default for this channel when the app URL does not include `lang`. - Use **Authentication** to control access for this channel only. When the API client depends on a partner or institution identity boundary, align the channel with its channel policy in [Configurable authentication](#doc-settings-configurable-auth). - Use the **PII** tab to redact detected personal data from user message text before transcript storage, search indexing, model input, and tool input. File attachments and existing historical messages are not changed. Category controls can exclude noisy categories such as date/time or restrict detection to selected entity types only. - Use **Show feedback button** to show or hide only the written-feedback control under assistant messages. When disabled, Gaia hides the written-feedback icon and rejects new written-feedback submissions for the channel, but thumbs up/down remain available when their footer toggle stays on. - Use **Like active color**, **Dislike active color**, **Feedback active color**, and **Voice active color** to control the selected or submitted footer-action colors for this channel. - Use **Show assistant timestamps**, **Show assistant thumbs feedback**, and **Show assistant read-aloud** to control the assistant-message footer for this channel. Thumbs feedback remains available when the written-feedback button is hidden. When read-aloud is enabled, **Read-aloud model** can override the assigned agent's Voice tab TTS model for this channel; leave it set to the agent voice setting to inherit the agent configuration. - Use **Source citations** on the **Conversation** tab to show or hide citations, place them inline, at the end of the answer, or in both positions, and keep retrieval times hidden or expose them with the citation or only in source details. New and legacy Personal Assistant channels default to visible citations in both positions with hidden retrieval times. Folder-backed source rows remain openable whenever citations are shown. - Use **Feedback icon**, **Thumbs icons**, and **Read-aloud icon** under **Conversation -> Assistant message footer** to upload or paste per-channel Feedback, Like, Dislike, and idle Read-aloud icon assets, preview each icon, restore Gaia's default icon, and keep the existing footer toggles unchanged. - Use **Feedback default color**, **Like default color**, **Dislike default color**, and **Read-aloud default color** to control idle footer icon colors independently from the existing active-state colors. Use **Apply the same default color to all assistant footer icons** as an editor shortcut when the same idle color should populate all four fields. - Use **Icon color mode** to choose whether custom footer assets keep their uploaded colors or render as single-color icons that follow the configured idle/default color and the existing active color. - Use **Show dislike handoff button** to add the configured handoff label to the thumbs-down dialog. The button is hidden by default; when users click it, Gaia sends the visible button text as a normal user message instead of triggering a direct handoff action. Selecting **Incorrect information** or **Not relevant** saves that reason against the assistant message, shows the configured confirmation toast, and keeps the feedback available in the conversation review surfaces even when the written-feedback icon is hidden. Use **Dislike modal button colors** to set independent background and text colors for **Incorrect information**, **Not relevant**, and **Connect to live agent**. The button wording and the confirmation toast text stay configurable in the **Messages** tab. - Use **Show off-topic cause in visible reply** to decide whether Gaia appends the detector explanation for end users. **Inside Info** and the **Messages** page always show it for reviewers. - Use the **Avatars** section to enable user avatars and agent avatars separately. - User avatars reuse the standard Gaia user avatar by default, and anonymous users show a generic user icon until you configure a channel-specific avatar asset. - When **Show user avatars** is on, you can upload a supported User avatar asset or paste its URL, preview it, restore Gaia's default icon, choose whether Gaia keeps the uploaded colors or applies the configured icon color, and set User avatar background, border, and icon colors independently. Leave any color blank to keep Gaia's existing behavior. - Agent avatars show an AI badge with the assigned agent name below it until you configure a channel-specific Agent avatar asset. - When **Show agent avatars** is on, you can upload a supported AI Agent avatar asset or paste its URL, preview it, restore Gaia's default icon, choose whether Gaia keeps the uploaded colors or applies the configured icon color, and set Agent avatar background, border, and icon colors independently. Leave any color blank to inherit the channel theme defaults. - Personal Assistant channels do not support live chat bridge integration. Use a Text channel when a third-party live-support system needs takeover, provider transport events, or Bridge Agent routing. - Use **Host context TTL (seconds)** to decide how long Gaia keeps that host-provided metadata available before it expires automatically. - Personal Assistant stays full screen. Gaia does not expose **Portal view** or portal frame styling for this channel. - Use the **Files** tab to manage all end-user file behavior for this channel: - **Allow attach to model** and **Allow upload to storage** control the paperclip destinations. - **Knowledge folders** attach shared folder corpora at the channel level. Use them for channel-wide policy sets, standards, or background reference material. - Mark **Important** channel knowledge folders when they should be searched in the first pass together with any linked work folder. - Mark **Fallback** channel knowledge folders when they should be searched only if the linked folder plus important knowledge does not return strong enough evidence. - The **Folders** card keeps the main controls visible: **Show folder workspace**, **Retrieval mode**, **Primary full-text language**, and **Assistant result limit**. - Turning on **Show folder workspace** also turns on folder search for that channel. - **Assistant result limit** sets the default number of matches returned to `search_document_folder` when the assistant does not request an explicit limit. Gaia still caps assistant folder search at 20 results per call. - **Advanced folder indexing** is collapsed by default and groups pgvector readiness, multilingual rewrite model selection, hybrid-only embedding settings, model reranking, and PDF analysis tuning. - Gaia shows the embedding model selector only when the retrieval mode uses vectors: **Hybrid search** or **Structure Search + hybrid fallback**. - **Defer fallback embeddings** appears only for **Structure Search + hybrid fallback**. Use it when you want faster indexing and accept that the first weak structure/full-text conversation search may spend time and embedding tokens creating the missing document vectors before retrying hybrid retrieval. - **Fallback score threshold** also appears only for **Structure Search + hybrid fallback**. Use `0` for the default empty-or-weak fallback behavior, or set a higher raw structure-search score threshold when hybrid fallback should run more aggressively. - Use **Enable model reranking** when you want Gaia to run one bounded model pass over the strongest folder-search hits for ambiguous searches. Turn it off if you prefer pure score ordering or need the lowest possible retrieval latency. When reranking stays on, Gaia also lets you choose a preferred reranking model for that second pass. - **Automatic PDF visual analysis** is built into PDF indexing. Gaia starts with extracted PDF text and adds rendered-page analysis only when the text looks weak or some pages appear visually complex, such as slides, charts, tables, or scanned pages. Large PDFs are processed in small page batches when that extra pass is needed. You can optionally choose a preferred PDF model, but Gaia manages the batching automatically. File extractors can add PDF indexing hints, but Gaia still owns the automatic text-versus-visual decision. - **Upload routing and metadata extraction** lets each rule target a direct workflow, a reusable registry extractor, or an inline extractor. - Use **File extractor presets** to open a dialog that adds a lighter `txt` / `md` / `docx` / `odt` outline extractor, a stronger `pdf` outline extractor, and a spreadsheet extractor for `xlsx` / `ods` / `csv` without building those wildcard rules by hand. - **Add preset** creates any missing preset buckets and updates the existing wildcard rules or registry entries only when they already own the same supported file types. - After adding that preset, use **Open file extractor registry** if you want to inspect or fine-tune the generated extractors without leaving your unsaved routing edits behind. - Inline AI and Agent extractors can shape folder retrieval through structured `indexing` hints, but they do not replace Gaia's canonical extraction, chunking, or embedding logic. - When you change file extractor rules on a folder-enabled Personal Assistant channel, Gaia queues a project-wide folder reindex for active folders automatically. - When the retrieval mode includes **Hybrid search**, the Files tab still requires a pgvector-ready database and a valid embedding model before you can save the channel. - **Structure Search** uses the persisted document section tree. **Structure Search + hybrid fallback** searches that structure first and falls back to hybrid retrieval when the structural hits are weak, absent, or below the configured fallback score threshold. - Use **Personal Assistant color mode** to lock this channel to **Light** or **Dark** mode, independent of the platform user theme. - New Personal Assistant channels default to **Light** mode. - Use the **Theme** section to configure channel-specific branding (colors/logos) for the Personal Assistant experience. - The theme editor now has a **Conversation** tab and a **UI** tab. - Use **Conversation** to edit only the personal assistant conversation shell: app canvas, top bar, assistant/user messages, composer shell, composer input, and interactive controls. - Leave a **Conversation** field blank to inherit the matching value from the **UI** theme. - Conversation overrides are surface-specific. Changing **Composer Input** tokens, including the border, does not change assistant or user message colors. - Use **Conversation Theme -> Composer Input -> Input outer padding** to control padding around the full composer wrapper, including the textarea, send button, microphone, and attachment actions. Keep **Input padding** for spacing inside the textarea only. - Use **Conversation Theme -> Interactive Controls -> Send button** when the Personal Assistant composer Send icon needs a custom uploaded asset or asset URL, uploaded-color vs configured-color rendering, configurable width and height, or separate enabled and disabled background, border, and icon colors. The icon color fields accept `#hex`, `oklch(...)`, `rgb(...)`, `rgba(...)`, `hsl(...)`, `hsla(...)`, and `transparent`. - When **Apply configured icon color** is selected, Gaia renders uploaded SVG Send icons as single-color assets. Uploaded PNG and WebP icons keep their original uploaded colors. - The Send button preview in the same section shows both disabled and enabled states, and the shared conversation preview lets you test empty, whitespace-only, valid, and over-limit composer states in Personal Assistant mode before you save. - Use **Conversation -> App Canvas -> Background layers** when you want decorative artwork inside the core conversation canvas while keeping the surrounding shell chrome on the shared UI theme. - Each layer accepts either a pasted URL/path or an uploaded image plus a **Fit** and **Anchor** choice so you can pin artwork to a side or corner instead of forcing full-canvas coverage. - Use **UI** to edit the shared theme for dialogs, menus, drawers, workspace cards, buttons, inputs, and selects outside the conversation surface. - In Personal Assistant, every **Conversation** token is scoped to its own surface and falls back to the **UI** theme only when left blank. - Personal Assistant background layers apply only to the central conversation canvas. They do not style the left rail, folder drawer, or dialogs. - Use the preview panel to see a read-only **Personal Assistant** conversation preview or a shared **UI** kit preview, with a Light/Dark toggle. - The **Conversation** preview uses the live personal-assistant conversation renderer in read-only mode, so heading colors, link colors, inline UI layouts, and the assistant thinking state match the runtime channel shell. - The preview now highlights unreadable runtime combinations before you save, including the active text/background pair and a suggested readable text color. - Gaia blocks only new or edited critical conversation-theme contrast failures. If an existing app still has critical theme issues and you save unrelated non-theme settings, Gaia preserves the warning without blocking the non-theme save. - The **UI** preview shows the shared component kit plus the left and right drawers so shell-specific tokens are visible while you edit them. - Use **Assistant Bubble -> Hide footer spacer when footer actions are hidden** when live Personal Assistant conversations should remove the reserved empty space below assistant replies that do not show footer actions. The Conversation Theme preview keeps its existing spacer behavior until you save and open the live channel. - Use **Assistant Content -> Thinking text / dots** when you want the personal-assistant loading text and animated thinking dots to use a dedicated color. - Use the **Preview state** options in the **Conversation** tab to inspect non-default conversation states such as hover and focus. - New Personal Assistant conversations open with a centered **welcome screen** before the first user message. - Assistant replies in Personal Assistant mode use a **borderless message style** for a cleaner, chat-first layout. - Opening `/apps/` while signed out sends the visitor to the app login screen. Gaia keeps the branded app header visible there while the sign-in choices and supporting copy scroll underneath on smaller viewports. - The **Downloadable packages** section on the **App** tab reserves the channel-level evidence fields for a PWA manifest, Windows package, macOS package, Android package, and iOS package. These fields are disabled until a packaged build is published for the channel; use them as the reference location for tender evidence, not as proof that packages are currently downloadable. - On desktop, Personal Assistant keeps a permanent left rail with the **logo**, account avatar, search, conversations, folders, and quick actions such as **New** and **Project**. On mobile, the same navigation stays in a slide-over drawer opened from the conversation header. - When a canvas or artifact is open on mobile, the conversation header adds **Messages** and **Canvas** buttons so users can switch between chat and the workspace without a split pane. - Gaia resolves the current end-user avatar from the matching **App user** record when one exists for the signed-in person; otherwise it falls back to the signed-in project user or guest session. For authenticated app viewers and project members, the avatar menu exposes **Language**, **Edit project details**, and **Logout** so they can override the channel default language, rename the project, and update its description from the end-user shell. The language choice updates the app URL with `lang` so the server-rendered UI and assistant turns use the selected language. On desktop that avatar lives in the left rail, while mobile keeps quick account access near the drawer controls. - Conversation rows show who started the conversation when Gaia can display that attribution safely, and the active conversation header exposes **Rename conversation** for the currently open thread. - The conversation header stays focused on in-thread context such as the linked folder badge and artifact selector. - Desktop navigation can collapse to a slim rail that keeps the logo, an expand button below the logo, and the avatar visible, then expand back to the full navigation workspace. - On mobile, history still opens as a temporary **slide-over rail** above the conversation and closes when you pick an item or click outside. - When folders are enabled, that rail uses two states: - Default state: **Conversations** and **Folders** appear as tabs with one shared search field and independent **Load more** actions. - Folder-selected state: the rail switches to the selected folder’s conversation list and adds a back action to return to the split view. - End users can create a folder directly from the default rail using **New folder**; successful creation immediately opens that folder context. - Selecting a folder changes the conversation context only. It does not auto-open the management drawer. - When a conversation is linked to a folder but the app is not already in that folder scope, the header keeps the folder name as the scope shortcut and adds a separate drawer button beside it so users can open the folder contents directly. - Use the folder icon and name in the conversation header to open the right drawer for the active folder. - The right drawer now focuses on **Files**, **Search**, and **People** only: - **Files** keeps the storage manager scoped to `document-folders/`. - **Search** shows structured folder-search cards with an **Open preview** action for each matched document. - **People** manages members and assigned agents. - When an agent uses `search_document_folder`, the matching inside-info cards can open the same right-drawer file preview for the linked folder and now show citations/confidence metadata for the best passages. - When search results come from channel or config knowledge folders instead of the linked folder, Gaia labels the source folder, source scope, and mode so reviewers can distinguish working-folder evidence from background policy knowledge. - Markdown tables in Personal Assistant replies can be downloaded as CSV, XLSX, or Markdown from the table action menu. Generated document exports should appear as Gaia download/open controls; model-authored `sandbox:`, `file:`, `blob:`, and `data:` links are rendered as plain text instead of active links. - Use **Move conversation here** from the drawer overview to attach the current conversation to the active folder. - In platform admin, choosing this channel from **Conversations -> New** opens a create dialog so admins can start with **No folder**, an **Existing folder**, or a **New folder**. - To let an agent answer from folder files, enable at least `search_document_folder` and `document_folder_get_passages` on that agent configuration. Add `document_folder_list_files` as well when the agent needs to inspect which files are present in the linked folder. Add `document_folder_spreadsheet_query` when linked folders contain CSV/XLSX/ODS files that need structured workbook analysis. When the channel retrieval mode uses Structure Search, also enable `document_folder_get_structure`, `document_folder_get_section_content`, and `document_folder_expand_section`. Folder enabling alone does not add tools automatically. ## Alternative frontend **Alternative frontend** channels provide an API-first app channel for external/mobile clients. - Set the **App slug** used by `/api/apps//...` endpoints. - This channel is API-only and does not use the `/apps/` web route. - Use **Authentication** to control access for this channel only. - Use **Enable end-user feedback** to control whether the client can collect note, like, or dislike feedback. Disabled channels reject new feedback through the API as well as hiding controls in Gaia-provided clients. - Use **Show off-topic cause in visible reply** to decide whether Gaia appends the detector explanation for end users. **Inside Info** and the **Messages** page always show it for reviewers. - Use **Alternative frontend color mode** to lock channel-rendered UI previews to **Light** or **Dark** when shared with clients. - Use the **Theme** section to keep branding metadata aligned with your frontend client. --- # Channel Security and Access Use this guide when you publish a **Text** or **Personal Assistant** channel and want to understand who can enter it, what the assistant can access at runtime, and how document folder rights apply. Open channel settings from **Conversations -> Channels**, then select the channel you want to review. ## Key Ideas Gaia separates three kinds of access: - **Channel access:** who can open the published app or embedded conversation. - **Assistant runtime access:** what the assistant is allowed to read or do while it answers. - **Folder access:** which people and agents can see or work with a specific document folder. These controls work together, but they are not the same thing. A person can be allowed into a channel without receiving access to every project resource. Likewise, an assistant can use a runtime service account for approved internal reads without giving the end user direct project permissions. ## Channel Sign-In Modes Text and Personal Assistant channels use the same sign-in choices. | Mode | What it means | | ------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | **Required** | Users must sign in before Gaia opens the channel. Use this for private customer, employee, or partner experiences. | | **Optional** | Guests can start, and signed-in users can also enter. Use this when you want a low-friction entry point but still support known users. | | **Anonymous** | Gaia creates a guest app session when the visitor starts. Use this only when the channel content is safe for guests. | If a channel requires sign-in, Gaia checks the signed-in user or app session before revealing the project-backed app experience. If guests are allowed, Gaia creates a channel-scoped anonymous app session so the conversation can still be tied to a consistent app user. ## Assistant Runtime Service Accounts A **runtime service account** is the identity the assistant uses for server-side work such as tools, TypeScript handoff rules, common fragment reads, and data lookups. For production channels, configure a runtime service account intentionally: 1. Open **Settings -> Service accounts**. 2. Create or select a service account with only the permissions the assistant needs. 3. Open **Conversations -> Channels**. 4. Select the Text or Personal Assistant channel. 5. Set **Runtime service account** for that channel. 6. Save the channel. Gaia uses runtime service accounts in this order: 1. A service account explicitly supplied by a trusted internal workflow. 2. The service account configured on the channel. 3. The project default runtime service account. 4. No runtime service account, in which case some assistant actions may fail or use the current signed-in session where supported. Signing in as an app user or project user does not automatically replace the channel runtime service account for normal channel conversations. This keeps the assistant's operating permissions stable and auditable. ## Text Channels Text channels are best for chat widgets, website assistants, support entry points, and direct published conversation links. ### What Controls Access - The channel sign-in mode controls whether guests can enter. - The channel's selected agent and configuration control the conversation behavior. - The channel runtime service account controls what the assistant can do behind the scenes. - The conversation remains linked to the channel it came from, so Gaia can keep channel-specific settings, themes, and routing together. ### Recommended Setup 1. Choose **Required**, **Optional**, or **Anonymous** based on the sensitivity of the experience. 2. Assign the channel's runtime service account. 3. Review the service account role and remove permissions the assistant does not need. 4. Test the channel as: - a guest, if guests are allowed - an app user, if the channel has app users - a project user, if project members will use the app link ### Folder and Knowledge Access Text channels can use document knowledge when you attach folders through channel file settings, agent configuration, or folder-linked conversations. Before Gaia lets the assistant search folder knowledge, it checks which folders are available for the current conversation context. Folders that are not available are skipped instead of exposed to the assistant. ## Personal Assistant Channels Personal Assistant channels use the same sign-in and runtime service-account model as Text channels, but they add a private workspace experience. A Personal Assistant can show a folder rail, folder conversations, tasks, and folder-backed retrieval when those features are enabled. ### What Controls Access - The channel sign-in mode controls who can open the assistant. - The current app user controls which personal workspace items and folders appear. - The channel runtime service account controls the assistant's server-side tool and handoff permissions. - Document folder membership controls which folder files and folder conversations the user can open. ### Recommended Setup 1. Use **Required** sign-in for private assistants unless the workspace is intentionally guest-safe. 2. Configure a channel runtime service account with the assistant's required tool permissions. 3. Turn on folder features only when the assistant should expose folders in the app. 4. Share folders with the right app users and agents before asking users to rely on folder search. 5. Test with a user who has no folder membership to confirm private folders stay hidden. ## Document Folder Rights Document folders are protected separately from channel entry. A user can open a Personal Assistant channel and still see no folders if no folders have been shared with them. | Folder role | Who it is for | What they can do | | ----------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Owner** | Folder owners and administrators | Read and edit the folder, manage sharing, manage owner access, and keep responsibility for the folder. Gaia requires every folder to keep at least one owner. | | **Editor** | Teammates who maintain folder content | Read the folder, update folder details, manage files, archive the folder, and share non-owner access. | | **Viewer** | Teammates or app users who only need the content | Read folder details, files, structure, and search results. They cannot change folder settings, files, or membership. | | **Agent** | Assistant agents that should participate in folder conversations | Lets the agent participate in linked folder conversations. It is separate from human owner/editor/viewer access. | Project users with folder administration permissions can manage folders across the project, but normal users and app users only see folders where they are members. ## Folder Conversations and Participants When a folder is linked to a conversation, Gaia keeps folder participants and conversation participants aligned: - Sharing a folder with an app user can also add that app user to existing folder-linked conversations. - Adding an agent to a folder can also add that agent to existing folder-linked conversations. - Removing folder access should be treated as removing access to the folder-backed conversation context as well. Conversation-only participants are different. Inviting someone to a standalone conversation does not grant access to a document folder or its files. Manage folder access from the folder sharing controls. ## Common Review Checklist Use this checklist before publishing or changing a channel: - The channel sign-in mode matches the sensitivity of the experience. - The channel runtime service account is set and uses a narrow role. - The project default runtime service account is not accidentally broader than needed. - Guest access has been tested separately from signed-in access. - Personal Assistant folder features are enabled only when needed. - Folder owners, editors, viewers, and agent participants are reviewed. - A user without folder membership cannot see or search private folders. - The assistant can still answer expected questions when using the configured runtime service account. ## Troubleshooting - **A guest can open the channel but the assistant cannot read fragments or data:** Check the channel runtime service account and its role permissions. - **A signed-in user cannot open the channel:** Check the channel sign-in mode, app authentication policy, and whether the user is an app user or project member for that project. - **A Personal Assistant user does not see a folder:** Check that folder features are enabled and that the app user is a folder member. - **The assistant cannot search a folder:** Check folder membership, folder indexing status, and whether the folder is linked or attached as channel/agent knowledge. - **A user can chat but cannot access files:** Conversation access and folder access are separate. Share the folder with the user or add them through folder participants. --- # UI Layouts UI Layouts let you design the visual experiences—forms, dashboards, detail pages—that agents can open in the split canvas or publish as standalone apps. Open this page from **Conversations -> UI Layouts**. Although it now lives inside the Conversations workspace, the layouts you build here also power published apps, portal surfaces, and non-chat screens. ## Choose the right delivery mode Gaia now supports four distinct ways to use UI layouts. Pick the lightest one that fits the job. | Delivery mode | Best for | What persists | | ------------------------------ | ------------------------------------------------------ | --------------------------------------------- | | **Saved UI layout** | reusable forms, dashboards, and app surfaces | the layout definition | | **Inline UI response** | one-off forms or dashboards inside a reply | nothing unless you later save it | | **Entity canvas** | editing a business record in split view | the entity record and its linked saved layout | | **Runtime UI canvas artifact** | split-canvas sessions with conversation-specific state | the runtime artifact document | Quick rule of thumb: - Use **Saved UI layout** when the layout should be reused, organized in folders, or published. - Use **Inline UI response** when the interaction should stay attached to one reply. - Use **Entity canvas** when the UI should open a specific record with linked layout bindings. - Use **Runtime UI canvas artifact** when the conversation needs a side-canvas session that carries live state across turns. ## Before you rely on runtime canvas artifacts Use this setup check when the assistant should reopen or continue a live split-canvas session across turns. 1. If the setup is already live but the canvas flow feels incomplete, start with **Delivery Management -> Overview** or ask Gaia for a **project setup diagnosis** so it checks the runtime tool and skill bundle first. 2. In **AI Agents -> Configurations -> Tools**, enable: - `artifact_list_for_conversation` - `artifact_create` - `artifact_open` - `artifact_read` - `artifact_update` 3. In **AI Agents -> Skills -> Internal**, attach **ui-layout artifact runtime canvas**. 4. Also attach **ui layout intent routing** when the same agent may choose between inline UI, entity canvas, saved layouts, and runtime canvas sessions. 5. Follow [Scenario: Runtime UI canvas artifact workflow](#doc-conversations-scenarios-runtime-ui-canvas-artifact-workflow) for the full setup path, prompt starter, and runtime document example. ### Example: inline UI response block Use this when the assistant should answer with an embedded interactive surface instead of opening the side canvas. ```gaia-ui-layout { "type": "ui-layout", "title": "Customer review", "layoutSpec": { "root": { "id": "root", "type": "card", "children": [ { "id": "heading", "type": "text", "props": { "text": "Review customer" } }, { "id": "approved", "type": "checkbox", "props": { "label": "Approved" } }, { "id": "notes", "type": "textarea", "props": { "placeholder": "Notes" } } ] } }, "values": { "customer": { "id": "cust-1", "name": "Acme Corp" } } } ``` ### Example: runtime UI canvas artifact document Use this when the assistant should open the side canvas and keep the runtime state with the conversation. ```json { "kind": "ui-layout-canvas", "version": 1, "title": "Customer escalation review", "layout": { "source": "reference", "layoutId": "layout-customer-review" }, "state": { "mode": "transient", "values": { "customer": { "id": "cust-1", "riskScore": 92 } } } } ``` ## How the editor is organized When you open a layout, the editor is split into three working areas: - **Outline** on the left: the node tree for your layout. Select a row, card, text node, data table, input, checkbox, switch, radio group, or other component here. - **Preview** in the center: a live rendering of the current layout. - **Properties panel** on the right: three tabs named **NODE**, **DATA**, and **LAYOUT**. The most common source of confusion is that **NODE** and **DATA** apply to the currently selected node, while **LAYOUT** applies to the layout as a whole. ## What each tab does | Tab | Scope | Use it for | | ---------- | ------------- | -------------------------------------------------------------------------------------------------------- | | **NODE** | Selected node | Content, component-specific options, layout classes, spacing, colors, sizing, and other visual behavior | | **DATA** | Selected node | Visibility rules, binding scenarios, repeat behavior, field binding, and write-back/update settings | | **LAYOUT** | Whole layout | Layout name, description, tags, root data source, preview mode, dummy data, and top-level update binding | ## Which tab should I use? Use **NODE** when you want to change what a selected component is or how it looks. Examples: - Change button text, link URL, or image source - Configure a data table's rows path, columns, empty state text, and table behavior - Configure field placeholders, checkbox or switch labels, radio-group orientation, and select or radio options - Turn a row into a column or grid - Adjust padding, gap, width, height, overflow, colors, or typography - Set the **Value source** for a text node Use **DATA** when the selected node needs runtime data or save behavior. Examples: - Show or hide a node with **Show If** - Repeat a card or text node for each item in a list - Bind an input, checkbox, switch, or other field control to an entity property - Mark a node as an update root for write-back Use **LAYOUT** when you are configuring the layout shell rather than one specific node. Examples: - Rename the layout or update its tags - Choose whether preview uses live data, no data, or dummy data - Attach an **Entity Query** or **Manual JSON** data source to the whole layout - Set a top-level update binding so nested inputs save through a shared parent context ## What you can do - **Organize layouts in folders.** The tree view supports drag-and-drop and folder creation. - **Create layouts from templates.** Start with a default layout or duplicate an existing one. - **Edit visually.** The layout editor supports drag-and-drop components, data bindings, and live previews. - **Bind to entities.** Reference entity fields so layouts display live data when agents open them during a conversation. - **Render assistant cards.** Saved layouts can also render assistant JSON blocks when the block uses the layout name as its `type`, for example `OffersInfo`. - **Publish or share.** Mark layouts as default or shareable so end users can access them. ## Related Topics - [Data Binding](#doc-conversations-ui-layouts-data-binding) — Learn how to connect components to entity data using paths and expressions. - [Scenario: Inline UI layout responses](#doc-conversations-scenarios-inline-ui-layout-responses) — Use inline `gaia-ui-layout` blocks when the UI should stay inside the reply. - [Scenario: Runtime UI canvas artifact workflow](#doc-conversations-scenarios-runtime-ui-canvas-artifact-workflow) — Use `ui-layout-canvas` artifacts for split-canvas runtime sessions. - [UI Layout Component Reference](../../../handbook/ch05-channel-and-experience-design/05-ui-layout-component-reference.md) — Use the handbook when you need the full current component catalog instead of the quick-start workflow. ## Build or edit a layout 1. Open **Conversations -> UI Layouts**. 2. Select a layout and click the pencil icon (or choose **New layout** to start fresh). 3. Use the **Outline** to select the node you want to edit. 4. Use **NODE** to shape the selected node. For text and truncated text nodes, choose a **Value source** such as **Static text**, **From path**, or **Expression**. For containers, use **Layout**, **Overflow**, **Position & Size**, and **Spacing** to control structure. In the style-related sections, use the color picker controls to set custom background, border, ring, and text colors. Text nodes also expose typography toggles for italic, underline, strikethrough, and overline. Row, column, and card nodes also support background images and inherited typography options. Image nodes support **Fixed size** and **Fill parent container**, plus **Fit** and **Position** controls. 5. Use **DATA** only when the selected node should read or write runtime data. Start with **Binding Scenario** for common setups such as a single value, repeating a list, or editable write-back. When preview data is available, pick detected record-id paths and item fields from the selector instead of typing `item.*` or `items[0].*` by hand. If the node is already inside a repeated list, turn on **Use current item for detected paths** so the editor stores alias-based paths such as `row.id` instead of full `items[0].*` paths. Use **Advanced (raw fields)** only when scenario mode is too limited for the case you are building. 6. Use **LAYOUT** to configure the layout itself. Pick an entity query or manual JSON for previewing, switch preview mode, and set any top-level update binding. The layout-level update binding also includes the same detected record-id picker, so you can choose a path from preview data instead of typing it manually. 7. In the **Preview** header, choose **Platform** or a **Text channel** theme to preview with that palette. 8. Save. The grid refreshes, and the layout becomes available for agents to render. ## Walkthroughs ### Walkthrough 1: Build a simple bound form Use this when one layout should display and edit a single record such as a contact, case, or profile. 1. Open or create a layout with a simple form structure such as a card containing a label, input, and submit button. 2. Select the root node or keep nothing special selected, then open **LAYOUT**. 3. In **Data Binding**, choose a preview source. Use **Entity Query** when the layout should load real records. Use **Manual JSON** when you want a controlled test payload first. 4. In **Update Binding (optional)**, choose the entity that should receive updates. 5. In **Record Id expression (optional)**, pick the detected record id path from the selector instead of typing it by hand. 6. Select the input node in the **Outline** and open **DATA**. 7. Set **Binding Scenario** to **Editable field (write-back)**. 8. Choose the same entity, select the detected record id path, and choose the property to edit. 9. Preview the layout and type into the field. 10. Confirm the preview resolves the record id and the input now points at the expected property. Use this pattern for fields such as `name`, `email`, `status`, `approvalDecision`, or `owner` where one node maps to one property on one record. ### Walkthrough 2: Build a repeated offers card Use this when the layout should render one card per item in a list, such as offers, incidents, or recommended actions. 1. Start with a container node that will repeat, such as a card, row, or column. 2. Open **LAYOUT** and choose a preview source that returns a list. 3. Select the container node in the **Outline** and open **DATA**. 4. Set **Binding Scenario** to **Repeat list of objects**. 5. Choose the detected list path for the offers array. 6. Keep the alias as `row` unless you already have another repeat scope and need a different name. 7. Select a child text node inside the repeated container and open **NODE**. 8. Set **Value source** to **From path** and point it to a field on the repeated item, such as `row.title` or `row.summary`. 9. Repeat that pattern for the other child nodes, for example `row.price`, `row.ctaLabel`, or `row.expiryDate`. 10. Use the preview count message in **DATA** to confirm that the repeated container resolves to the expected number of items. Best practice: put the repeat on the container card, not on every child node. That keeps the layout easier to reason about and gives all children a shared alias such as `row`. ### Walkthrough 3: Use current-item paths inside a repeated node Use this when you are editing a node that already sits inside a repeated container and you want bindings like `row.id` instead of absolute paths such as `items[0].Offer.id`. 1. Select a node that lives inside a repeated container. 2. Open **DATA**. 3. Turn on **Use current item for detected paths**. 4. Pick a detected record id path from the selector. 5. Confirm that the saved path uses the repeat alias such as `row.id` or `row.Offer.id`. 6. If you open **Advanced**, confirm the same alias-based value appears in the raw field. Use this mode whenever the node should stay bound to the current repeated item even if the surrounding list path changes later. ### Walkthrough 4: Build a full editable form with root update binding Use this when several inputs in one form should save into the same record and you want one shared save target at the layout root. 1. Create or open a layout with a form container and multiple fields such as `name`, `email`, `status`, and `notes`. 2. Open **LAYOUT**. 3. In **Data Binding**, load preview data for one real or sample record. 4. In **Update Binding (optional)**, choose the entity that the whole form should update. 5. Pick the detected record id path from the selector. 6. Choose the save mode for the full form. Use **Instant** when every change should save immediately. Use **Debounced** when you want short delays while the user is typing. Use **Manual** when a separate save action should control persistence. 7. Select the first input node and open **DATA**. 8. Set **Binding Scenario** to **Editable field (write-back)**. 9. Choose the property for that field. 10. Repeat the same property-binding step for the other inputs in the form. 11. Preview the layout and confirm that each field resolves against the same record while editing a different property. The important idea is that the root update binding decides where the form saves, while each input still defines which property it edits. ## A quick mental model - **NODE** answers: "What is this selected component and how should it look?" - **DATA** answers: "Where does this selected component get its data and how does it save?" - **LAYOUT** answers: "What data context and metadata does this whole layout use?" ## Real-life example > The compliance team built a “Case review” layout with a summary card, a related incidents data table, and approval buttons. When an agent flags a risky conversation, it opens this layout in the [Conversations](#doc-conversations) canvas so reviewers can approve or request follow-up. ## Tips - Use consistent naming and tags so you can find layouts quickly in the grid. - Take advantage of the **Duplicate** action to experiment without affecting the original layout. - Preview your layout with different screen sizes using the editor’s responsive controls. - Link layouts to entities in the [Data Model](#doc-data-model-entities) dialog so agents know which UI to open. - To activate split-canvas usage in conversations, ensure the layout is linked to an entity and follow [Activate and use the canvas](#doc-conversations-activate-and-use-the-canvas). ## Troubleshooting - **I do not know which tab to open:** Use **NODE** for appearance and component options, **DATA** for runtime binding on the selected node, and **LAYOUT** for the whole layout. - **I changed tabs but the wrong thing moved:** Check which node is selected in the **Outline**. **NODE** and **DATA** always apply to that current selection. - **Layout not appearing in conversations:** Ensure it’s linked to the relevant entity or referenced in the agent’s configuration. - **Drag-and-drop not working:** Confirm you’re in edit mode and that no modal dialogs are open. - **Component shows no data:** Check the binding in the **Data** tab; sample data might be empty or field names may not match the entity schema. If detected paths are available, re-select the record id or item field from the picker so the path matches the current preview payload. --- # Data Binding in UI Layouts Data binding connects UI components to runtime data so your layout can display or update entity records. ## LAYOUT vs DATA Before you configure bindings, decide which level you are working at: | Where you are working | Tab | What it controls | | --------------------- | ---------- | ------------------------------------------------------------------------------------- | | Entire layout | **LAYOUT** | The root data source, preview mode, dummy data, and optional top-level update binding | | Selected node | **DATA** | Visibility, repeat behavior, field binding, and node-specific write-back settings | Use **LAYOUT** first when the whole layout needs a data context, such as an entity query or manual JSON payload. Use **DATA** after that when one specific node needs to: - read a field from the current data context - repeat over a list - hide or show conditionally - save changes back to an entity record If you are unsure where to start, open **LAYOUT** to set the layout-level data source, then return to **DATA** on individual nodes that need special behavior. ## Start with Scenarios In the node **DATA** tab, use **Binding Scenario** first. It configures the low-level fields for you. | Scenario | Best for | What it configures | | ------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------ | | **Single value** | One field in one node | Clears repeat and helps you choose entity, record id, and property | | **Repeat list of text** | Array of strings (`["A","B","C"]`) | Sets `repeat.path`, aliases, and text value path (`item`) | | **Repeat list of objects** | Array of objects (`[{name:"A"}]`) | Sets repeat + item alias + property path (for example `row.name`) | | **Editable field (write-back)** | Input/checkbox/switch/radio-group/select/textarea updates | Sets bind target + update root (write-back) | | **Advanced (manual)** | Full custom setup | Use raw repeat/bind/format/parse fields directly | When preview data is available, scenario mode shows detected paths so you can choose from the current payload instead of hand-writing `item.*`, `row.*`, or `items[0].*` expressions. If the selected node is already inside a repeat scope, enable **Use current item for detected paths**. The picker then converts absolute preview paths such as `items[0].Author.id` into alias-based paths such as `row.Author.id`. ### Example: repeat one text node for each array item 1. Select a **Text** node. 2. Open **DATA**. 3. Set **Binding Scenario** to **Repeat list of text**. 4. Set **Array path** from the detected list (for example `items[0].Movie.actors`). 5. Keep alias as `item`. The node renders once for each `items[]` entry. Scenario mode keeps your selected list path. This is useful when you intentionally bind to context aliases such as `row.entity.actors` inside nested repeat scopes. ## Value Source (Text/Truncated Text) In the **NODE** tab, text nodes now have a **Value source**: - **Static text**: plain text - **From path**: path-based value (for example `row.Author.name`) - **Expression (JSON)**: full expression object This separates simple use cases from advanced expression editing. ## Preview Validation When preview data is available, the editor shows detected paths so you can select instead of typing paths manually. They also show quick validation: - whether a list path exists - whether it resolves to an array - which fields exist on the first repeated item - which record-id paths look valid for the current payload - how many items will render - whether a record-id path resolves (for write-back scenarios) ## Walkthrough: bind one input to one record This is the safest starting point when you want one field control to edit one record property. 1. In **LAYOUT**, load preview data for the record. 2. If the whole form should save through one shared parent, set the root **Update Binding (optional)** first. 3. Select the input, checkbox, switch, radio-group, select, or textarea node and open **DATA**. 4. Choose **Editable field (write-back)**. 5. Select the target entity. 6. Pick the record id from the detected path selector. 7. Choose the property to bind. 8. Check the preview message under the scenario. It should show that the record id resolves. If the preview does not resolve, stop there. Fix the preview payload or re-select the record id path before styling the field further. ## Walkthrough: repeat a list of offers This is the most common list-based UI Layout pattern. 1. Select the container node that should repeat, such as a card. 2. Open **DATA** and choose **Repeat list of objects**. 3. Pick the detected offers array. 4. Leave the alias as `row` unless you have a reason to rename it. 5. Select a child text node inside the repeated container. 6. In **NODE**, set **Value source** to **From path**. 7. Point that text node to the offer field you want, such as `row.title`. 8. Repeat for the remaining child nodes, for example `row.summary`, `row.price`, or `row.ctaLabel`. This is easier to maintain than repeating each text node separately because one repeated container defines the whole item context. ## Walkthrough: configure root update binding for a multi-field form Use this when several inputs should save into one shared record. 1. Open **LAYOUT** and load preview data for the target record. 2. In **Update Binding (optional)**, choose the entity and pick the detected record id path. 3. Choose the save mode for the form. 4. Select the first input node and open **DATA**. 5. Use **Editable field (write-back)**. 6. Bind the field to the property it should edit. 7. Repeat that setup for each other input in the form. The nearest ancestor update binding controls the save target. Each child input still needs its own field binding so Gaia knows which property to update. Example pattern: - Root **LAYOUT** update binding: `Contact` + `items[0].Contact.id` - Name input: property `name` - Email input: property `email` - Email notifications checkbox: property `emailNotificationsEnabled` - Published switch: property `isPublished` - Approval radio group: property `approvalDecision` - Status select: property `status` - Notes textarea: property `notes` This is the preferred setup for editable profile forms, approval forms, and record editors because it keeps one shared record target and avoids repeating form-level save settings on every field. ## Walkthrough: convert detected paths to the current item This walkthrough matters when you are already inside a repeated container and want stable alias-based bindings. 1. Select a node inside the repeated container. 2. Open **DATA**. 3. Turn on **Use current item for detected paths**. 4. Pick a detected path such as the record id. 5. Confirm the path is stored with the active alias, for example `row.id` instead of `items[0].Offer.id`. 6. Open **Advanced** if you need to verify the raw field or continue with a manual expression. Use this whenever you want the binding to clearly mean “the record for this repeated card” rather than “the first item in the preview payload.” ## Advanced Fields Use **Advanced (raw fields)** only when scenario controls are not enough. Advanced bind and update sections still allow raw expressions, but they now include the same detected record-id picker so you can insert a preview-backed path first and only switch to manual JSON when needed. The **LAYOUT** tab uses the same assisted picker for the root-level update binding. ### Repeat | Field | Description | | ------------ | --------------------------------- | | **Path** | Path to the array to iterate | | **As** | Item alias inside each iteration | | **Index As** | Index alias inside each iteration | ### Bind | Field | Description | | ------------------ | -------------------------------------- | | **Entity** | Target entity type | | **Record Id Path** | Path/expression resolving to record id | | **Property** | Entity property to read/write | | **Format** | Read transform (display) | | **Parse** | Write transform (before save) | ## Paths Paths support: - dot notation: `row.Author.name` - array indexing: `items[0].title` - mixed paths: `row.Author.books[0].title` Common variables in scope: - `value`: current bound value - `row`: current repeated object (common alias) - `item`: current repeated item (common alias) - `index`: current repeated index - `items`: common top-level list from data source For entity-query rows, `entity` is also supported as a convenience alias when a row contains a single entity object (for example `items[0].entity.actors`). Outside repeat scope, legacy `row.*` or `item.*` paths resolve against the first result row (`items[0]`) for compatibility. ## Expression Syntax Expressions are JSON: ```json { "op": "operator", "args": [arg1, arg2] } ``` Or: ```json { "op": "operator", "left": value1, "right": value2 } ``` Variable reference: ```json { "var": "value" } ``` ## Useful Operators | Operator | Purpose | | ----------------------------------------- | -------------------------------- | | `concat` | Join strings | | `join` | Join array values with separator | | `upper` / `lower` / `trim` | String transforms | | `if` | Conditional output | | `default` | Fallback when null/undefined | | `path` | Read nested field | | `eq` / `ne` / `gt` / `lt` / `gte` / `lte` | Comparisons | ## Tips 1. Use **scenario mode first**, then switch to **Advanced** only if needed. 2. Prefer detected path pickers over typing `item.*` or `items[0].*` manually. 3. If you must type a custom path, confirm it resolves in preview before styling the node. 4. For list rendering, validate the list path in preview before styling. 5. If text renders as `[object Object]`, switch value source to **From path** and select a concrete field. 6. For write-back, always confirm **Entity + Property + Record Id path** resolve in preview. --- # Document Folders Document Folders provide a shared workspace for files, folder-scoped conversations, and folder-grounded search. They are also the only indexed knowledge primitive used by Gaia's multi-scope document knowledge model. Open this page from **Conversations -> Folders**. For Microsoft-managed external retrieval deployments, see [Azure AI Search Adapter](#doc-conversations-document-folders-azure-ai-search-adapter). For Databricks-backed customer data or retrieval-index evidence, see [Databricks data platform](#doc-data-model-databricks-data-platform). Interactive walkthrough: Open [Tutorials](/platform/support/tutorials) and select **Document Folders: Collaboration Basics** for the admin workspace flow, or **Personal Assistant: Folders Setup** for the end-user desktop rail and mobile drawer flow. Both tutorial cards now include a companion video for passive review before you run the guided steps. For the full admin setup path, use [Scenario: Folder-grounded Personal Assistant setup](#doc-conversations-scenarios-folder-grounded-personal-assistant-setup). ## What you can do - Create named folders for a project. - Choose whether a new folder is project-level or channel-defined. - Configure folder indexing directly on the folder page. - Share folders with App Users and AI agents. - Assign owners, editors, and viewers. - Start folder-linked conversations. - Open the Conversations workspace already filtered to one folder. - Upload single files, bulk files, or ZIP archives. - Re-run indexing, review indexing failures, and retry one failed file without reindexing the whole folder. - Search indexed folder content with keyword, hybrid, or Structure Search retrieval. - Open a structural tree of indexed sections and inspect anchored section content directly. ## Recommended setup Document Folders work best when the agent path is configured before users start uploading files. For the guided path, select a folder in **Conversations -> Folders** and use **Activate**. The wizard can create or repair the Personal Assistant channel, agent, active configuration, structured-document extractor routing, folder participant link, indexing settings, and channel runtime service account. If you select an existing channel or agent, Gaia updates that configuration instead of creating a duplicate. Model suggestions prefer the available GPT 5.4 family, usually `gpt-5.4` for the assistant and `gpt-5.4-mini` for extraction and indexing support. Recommended setup order: 1. Turn on **Show folder workspace** on the target Personal Assistant channel. Gaia enables folder search automatically for enabled folders. 2. Configure any channel-level **Knowledge folders** that should always be available as background policy/reference knowledge. 3. Configure file extractor rules if uploads should enrich retrieval. 4. Add the **Folder Retrieval** common fragment to the agent instructions. 5. Attach the **Document knowledge grounding** validator to the agent configuration. 6. Optionally attach config-level **Knowledge folders** when one agent configuration needs extra background material that other configs on the same channel should not inherit. 7. Enable `search_document_folder` and `document_folder_get_passages`. `search_document_folder` is the default evidence-discovery tool across indexed text and spreadsheet content in the conversation knowledge scope. Add `document_folder_get_structure`, `document_folder_get_section_content`, and `document_folder_expand_section` when the folder uses a Structure Search retrieval mode. Add `document_folder_list_files` when the agent needs to enumerate the files currently stored in the linked folder. Add `document_folder_spreadsheet_query` when structured workbook analysis matters after the relevant file or sheet is known. 8. Create folders and link conversations. For the full sequence, use [Scenario: Folder-grounded Personal Assistant setup](#doc-conversations-scenarios-folder-grounded-personal-assistant-setup). ## Access and ownership - Gaia supports two folder modes: channel-defined folders and project-level folders. - Channel-defined folders inherit indexing, retrieval, file-extractor routing, and PDF visual-analysis settings from their assigned channel. - Channel-defined folders stay read-only on the folder page until you use **Convert to project-level** from the folder header or indexing dialog. - From **Conversations -> Folders**, choose **Channel-defined folder** when the folder should follow one Personal Assistant channel instead of owning its own indexing settings. - Folders created from the Folders workspace are project-level resources. The same folder can be attached from multiple configs and channels. - Project-level folder indexing, retrieval mode, language, multilingual rewrite model, reranking, hybrid-only embeddings, and PDF visual-analysis settings are configured on the folder page itself. Project-level folders keep search enabled by default, so the folder page no longer asks for a separate search toggle. - Project-level folder settings own their own file extractor rules. Configure them from the folder's **Indexing settings** dialog under **Folder file extractors**. - Those project-level extractor rules stay with the folder anywhere the folder is attached, including agent-config knowledge-folder attachments. - Channel-defined folders still inherit extractor rules from their assigned channel until you convert them to project-level. Converting copies the current channel extractor rules into the folder so you can continue editing them there. - Use **File extractor presets** from either the channel Files tab or the folder settings dialog to create reusable registry extractors for `txt` / `md` / `docx` / `odt`, `pdf`, and `xlsx` / `ods` / `csv` uploads and bind the matching wildcard rules. - Project roles control project-wide folder administration. Use **Manage folders** when a project user should administer every folder without being added to each one. - App users can create folders from folder-enabled app channels. The creator becomes a folder owner automatically. - Folder access is controlled at the folder level. Uploaded files, ZIP-extracted files, linked conversations, and folder-published artifacts inherit the folder ACL automatically, and those folder ACLs are what usually govern app-user access across shared knowledge folders. - Folder participants are also synced into linked conversations as inherited conversation participants. They appear in the conversation participants dialog with a **Folder** badge, can be mentioned in the composer, and must be removed from the folder participants UI rather than from the conversation. - If the linked Personal Assistant channel has **Allow collaboration** turned off, inherited participants still come from the folder ACL, but the conversation participant control, mention autocomplete, and invited-agent reactions are unavailable in that channel. - Human collaborators can be assigned one of three roles: `Owner`, `Editor`, or `Viewer`. - Owners can manage every folder setting, including other owners. - Editors can upload, rename, move, and delete files, start or attach folder conversations, publish artifacts into the folder, request reindexing, and manage non-owner members, but cannot remove owner access. - Viewers can read files, previews, downloads, search results, folder-published artifacts, and linked conversations, but cannot change membership or upload content. - A folder can have multiple owners, and Gaia always preserves at least one owner. - Removing a folder participant also removes their access to folder-linked conversations synced from the folder. ## Create and link conversations ### From the Document Folders workspace - Use **Create conversation** to open a new conversation already linked to the selected folder. When you are already inside a folder-linked conversation, the platform **New** action and the Personal Assistant **New** action start the next conversation in the same folder. - Use **View conversations** to jump to **Conversations** with that folder filter applied. ### From Personal Assistant - End users create or select a folder from the left rail. - The folder workspace drawer now exposes **Edit details** at the top of the panel, which is where folder editors rename the folder and update its description. - When a conversation is linked to a folder but the user is not already in that folder scope, the header keeps the folder name as the scope shortcut and adds a separate button to open the drawer directly. - Linked folders attached to the current conversation stay visible in the left rail even when they were not part of the initial folder page. - The right drawer opened from the folder icon and name in the header is where they manage files, search, people, and **Move conversation here**. ### From platform admin - In **Conversations**, choosing a folder-capable Personal Assistant channel from **New** now opens a create dialog. - Admins can start a conversation with **No folder**, an **Existing folder**, or a **New folder** in one flow. ## Search and indexing behavior - Folder indexing starts automatically after upload and is retried by background recovery paths when needed. - The upload banner shows live browser-to-server progress while the file transfer is still in flight, then switches to a server-processing state before indexing starts. Large uploads and ZIP bundles should no longer look stuck while Gaia is still receiving or unpacking them. - Folder indexing overviews identify whether the active indexing policy comes from the folder itself or from a channel-defined folder configuration. - The folder header keeps channel-defined folders compact: inherited folders expose **Convert to project-level**, while **Indexing settings** appears only after the folder owns its own policy. - Supported folder documents include `.pdf`, `.doc`, `.docx`, `.pptx`, `.md`, `.txt`, `.csv`, and `.xlsx`, plus ZIP bundles that Gaia uploads and extracts into the folder. - `search_document_folder` is the default search path across those indexed text and spreadsheet documents. Depending on the folder retrieval mode, it may return direct snippets, structural section hits, or fallback matches with diagnostics that explain what Gaia used. - When the retrieval mode is **Structure Search + hybrid fallback**, **Fallback score threshold** can force hybrid fallback when the best raw structure-search score is below the configured value. Leave it at `0` to use only the default empty-or-weak structure fallback behavior. - Search telemetry and per-result retrieval diagnostics include the retrieval backend id, capability path, and ranking profile id. Search telemetry also records the configured backend, effective backend, fallback backend, selection source, selection reason, and strict-mode posture. Use those fields to distinguish PostgreSQL keyword, hybrid, Structure Search, Structure Search fallback, and configured Azure AI Search retrieval evidence. - The workspace search action is labeled **Search folder index**, and the Personal Assistant drawer exposes the same indexed search from its **Search** tab. - The folder header also exposes **Folder structure**, which opens the persisted section tree for Structure Search-ready folders. The per-file **Structure** dialog shows extractor spans together with the persisted page or section nodes stored for that indexed source, with PDF page chunks grouped under a single page node, recorded per-file indexing AI usage when available, a **View AI calls** action for per-call model/token/cost timestamps, and a text preview when indexed content is available. - Newly uploaded files show indexing state in the folder file list. - Failed files keep their failure state and show the recorded reason inline. - The indexing failure dialog also lets you retry one failed file directly when only a small subset needs another pass. - The indexing summary now keeps a recent run history with trigger source, attempted/indexed/failed counts, partial-failure state, sample failed files, and recorded AI usage so you can review what happened without leaving the folder page. - The folder file-list search box is a file browser filter. It narrows visible file and folder names or paths and ignores accents in names such as Greek filenames; use **Search folder index** or the folder search tab to test the same indexed-content retrieval path available to the assistant. - Long documents are indexed in chunks so search can return the most relevant section instead of only whole-document matches. - Search also matches indexed metadata such as relative path, file name, MIME type, document type, language, keywords, section titles, and the indexing source label. - Folder-published artifacts are registered as folder files under the `artifacts/` path, inherit the folder ACL, and trigger the same indexing pipeline as uploaded files. - When the user asks in a different language from the uploaded files, Gaia can add a small set of cached multilingual query rewrites before retrieval. The original wording is still searched first, and the added rewrites help bridge folders that mix languages, such as Greek policy text with English technical terms. Advanced folder indexing lets you choose a preferred multilingual rewrite model; if none is selected, Gaia uses the platform default text model. - Search cards now lead with a short outcome sentence such as `Found directly in the structure index.` or `No structure hit. Found by hybrid retrieval.` so you can see what actually happened without decoding engine labels. When the indexed record came from a channel configuration, the badge uses the channel name directly, for example `indexed via channel "main"`. - Score badges now separate structure or full-text contribution from vector contribution, so hybrid results make it clear when semantic ranking participated. - Search matching is accent-insensitive across structure and text retrieval, so a query such as `ογκος` can still match indexed content that contains `όγκος`. - Search cards now also show the source folder, source scope (`Linked folder`, `Agent config`, or `Channel`), and `Important` / `Fallback` mode when the result came from attached background knowledge instead of the linked work folder. - Search results include **Open preview** so you can jump directly into the file preview. When the hit comes from Structure Search retrieval, cards also expose **Open section** to inspect the structural node directly. - Legacy Word files (`.doc`) use the same inline preview path as `.docx`, so folder reviewers can inspect older documents without downloading them first. - File preview renders supported spreadsheets inline as a read-only workbook view, and very large XLSX/ODS files fall back to a bounded summary table instead of showing raw binary content. - Presentation files render in the file preview through the same slide canvas used for artifacts. PPTX preview and import use bounded OOXML extraction for slide background colors, simple text boxes, basic shapes, connectors, and embedded images; charts, tables, grouped objects, animations, master layouts, and advanced effects may be simplified or omitted with an import warning. In a folder-linked conversation, ask the assistant to create or open a presentation artifact from a PPTX source, edit supported slide content in canvas, then export the deck back to PPTX. - If the first hit is promising but too short, the agent can call `document_folder_get_passages` to expand the cited evidence before answering. - When a result comes from a config- or channel-attached knowledge folder, Gaia returns the source folder metadata so follow-up tools can keep working against the right corpus. - When Structure Search retrieval is enabled, the assistant can browse the structure tree with `document_folder_get_structure`, drill into child nodes with `document_folder_expand_section`, and fetch exact section content with `document_folder_get_section_content`. When a structural branch has no direct text of its own, Gaia returns bounded child content so multi-page articles, clauses, or textbook sections can still be reviewed as one logical unit. ## Control-plane evidence Use Document Folders as the primary Gaia evidence surface for ingestion, retrieval, and source grounding: - **Ingestion policy:** capture whether the folder is project-level or channel-defined, the active indexing settings, file extractor rules, retrieval mode, language settings, PDF visual-analysis posture, hybrid search settings, and reranking settings. - **Index lifecycle:** capture the folder index status, recent index run history, attempted/indexed/failed counts, failed-file reasons, per-file retry evidence, and reindex trigger source. - **Knowledge scope:** capture folder members, linked conversations, attached channel or config knowledge folders, and whether a result came from a linked folder, important background folder, or fallback background folder. - **Retrieval evidence:** run **Search folder index** for reviewer prompts and capture result cards, search diagnostics, backend id, capability path, ranking profile id, score badges, source folder, citation markers, open preview, open section, and source excerpts. - **Quality evidence:** pair representative searches with [Evals](#doc-evals) when the review requires a repeatable retrieval-quality dataset, thresholds, or regression report. Retrieval-quality evidence should use the same query set, expected sources, citation spans, and access-control expectations across runs. Gaia's offline retrieval-quality fixture scores `Recall@k`, `Precision@k`, `MRR`, `nDCG`, citation-span accuracy, ACL false positives, search latency, indexing freshness, and cost per query so reviewer-facing reports do not depend on provider-native scores. For an enterprise control-plane review, combine this page with [Control Plane Evidence](#doc-control-plane-evidence) so retrieval proof is linked to model usage, governance, audit, and dashboard evidence. ### Index lifecycle evidence checklist Use the folder page and Evals reports together when a reviewer needs repeatable proof for index lifecycle and retrieval quality: 1. Open the folder and capture the current indexing setup, retrieval mode, language, file extractor rules, hybrid settings, reranking settings, and PDF visual-analysis posture. 2. Open the indexing summary and capture the latest run state, trigger source, attempted/indexed/failed counts, failed-file samples, and any recorded indexing AI usage. 3. Retry one failed file or re-run indexing for the folder when the review requires recovery evidence, then capture the updated run history and status. 4. Run representative **Search folder index** prompts and capture backend id, capability path, ranking profile id, fallback state, score badges, citations, and preview or section links. 5. Pair the same prompt set with Evals or an offline retrieval-quality report when the review requires threshold evidence for recall, precision, ranking, citation spans, ACL filtering, latency, freshness, or cost. Provider comparisons should use the same sources, prompts, expected citations, and access-control expectations for every backend. Compare ranked outcomes and task-level quality rather than provider-native scores. The offline provider fixture can compare PostgreSQL compact, Azure AI Search, and Databricks Vector Search captures without calling external services during CI. ## Hybrid search, spreadsheets, and PDFs - When folder indexing enables hybrid search and the database is pgvector-ready, Gaia stores embeddings for semantic ranking. - Deployments that need a Microsoft-managed external retrieval backend can enable the optional [Azure AI Search document-folder adapter](#doc-conversations-document-folders-azure-ai-search-adapter). Deployments that need Databricks as the customer data platform should record the intended Databricks SQL Warehouse, Unity Catalog, Vector Search, export, or connector profile in [Databricks data platform](#doc-data-model-databricks-data-platform). Gaia has a contract-first Databricks Vector Search helper for configuration, bounded query payload construction, filter shaping, and candidate mapping; live routing still needs the customer-approved Databricks index schema, metadata filters, ACL projection, credentials, and fallback posture. Gaia still keeps folder scope, access checks, citation shaping, Structure Search behavior, and result diagnostics in Gaia, while external backends route the selected candidate retrieval or data-access path. - Multilingual query expansion is independent of hybrid search: it improves the wording sent into keyword, hybrid, and Structure Search retrieval. Enable hybrid retrieval when semantic similarity matters across paraphrases, concepts, or weak lexical overlap; rely on multilingual expansion for bounded language bridging around the same evidence request. - Folder indexing overviews summarize the active folder indexing configuration, including retrieval mode, reranking policy, language, and any active hybrid or PDF visual-analysis settings. - Folder indexing overviews also surface recorded indexing AI usage for the current folder, including request count, token volume, and spend from embedding/indexing runs, PDF visual analysis, and AI file extractors when those calls logged folder attribution. - Individual file structure inspectors also show recorded indexing AI usage for that source when Gaia logged file-level attribution during indexing. - The overview also shows search diagnostics from the stored index rows, which helps distinguish "configured for hybrid" from "embeddings actually present". - The embedding model selector appears only when the retrieval mode uses vectors: **Hybrid search** or **Structure Search + hybrid fallback**. When model reranking is enabled, Gaia also shows a preferred reranking model selector for the bounded second-pass search. - In **Structure Search + hybrid fallback**, **Defer fallback embeddings** skips document-vector creation during indexing. If structure search and full-text fallback are both weak during a conversation, Gaia creates the missing document vectors then retries hybrid retrieval and reports the extra timing, token, and cost diagnostics in the search result. - Large CSV, XLSX, and ODS files that exceed the interactive spreadsheet grid limits still remain searchable through row-chunked indexing. - Spreadsheet search results preserve sheet names and row ranges when possible. - Use `document_folder_spreadsheet_query` after `search_document_folder` identifies the relevant workbook or when the spreadsheet file is already known. It supports exact A1 `range_read` queries, paged spreadsheet windows, grouped totals, and aggregations. For large `table_rows`, `group_sum`, or `aggregate` requests, keep the page size small with `pageSize` (or `limit`) and continue with `window.nextOffset` only when more rows are needed. - PDF indexing treats scanned and visually complex PDFs as first-class inputs. When plain text extraction is weak or specific pages look layout-heavy, Gaia automatically switches to rendered-page PDF analysis to recover retrieval text and does that work in small page batches for large PDFs. - When a PDF includes a readable table of contents or clear page-top headings, Gaia now infers chapter and section spans during indexing so large manuals, textbooks, and policy packets can expose a richer Structure Search tree without requiring custom extractor hints. - PDF visual analysis now folds notable figures, graphs, charts, and mathematical formulas back into the searchable page text so visually encoded evidence is easier to retrieve. - Folder and channel PDF analysis settings now focus on the preferred PDF-capable model only. Gaia starts with extracted PDF text, adds rendered-page analysis only when it is warranted, and handles any large-PDF batching automatically. File extractors can influence that decision with indexing hints, but they do not replace Gaia's canonical PDF analysis flow. - Short-lived embedding throttling is retried automatically during folder indexing, so occasional provider `429` responses are less likely to leave hybrid search only partially populated. ## File extractors and retrieval hints - Inline AI and Agent extractors can enrich retrieval with structured indexing hints such as aliases, logical document spans, anchored section labels, sheet summaries, and PDF visual-analysis preferences. - Use `indexing.documentStructure.spans` when a file's reader-facing units cross page or chunk boundaries. The spans are generic and can describe articles, chapters, clauses, lessons, or any other content-neutral outline produced by the extractor. - Gaia treats extractor hints as additive. Canonical extraction, chunking, retrieval boundaries, and evidence safety checks remain in Gaia's core indexer. - Hints that cannot be anchored safely to the visible file content are ignored. - When linked registry extractors or Personal Assistant file workflow rules change, Gaia reindexes active folders so retrieval stays aligned with the new extractor contract. See [File extractor registry](#doc-conversations-file-extractor-registry) for extractor details. ## Operational notes - Folder features follow project membership and folder permissions. Guest sessions can use folders when they are already provisioned into the project with the required role. - Conversation artifacts created in folder-linked conversations remain conversation-scoped until a user explicitly adds them to folder files. Markdown, spreadsheet, presentation, PDF annotation, p5, and UI layout canvas artifacts keep their canonical artifact format when published to the folder. - When an artifact is added to folder files, Gaia stores and indexes it like any other folder file. - If the indexing overview reports that folder indexing is incomplete, open **Indexing settings** on the folder page and save a usable configuration before relying on folder search. - The create and indexing dialogs are wider and scrollable because project-level folders expose the same folder search controls used on channels, including assistant result limits, model selectors, hybrid-search status, PDF visual-analysis settings, and folder-owned file extractors. - After **Re-run indexing**, the indexing popover closes automatically because the trigger button becomes the live progress indicator. ## Related docs - [Control Plane Evidence](#doc-control-plane-evidence) - [Databricks data platform](#doc-data-model-databricks-data-platform) - [Scenario: Folder-grounded Personal Assistant setup](#doc-conversations-scenarios-folder-grounded-personal-assistant-setup) - [Channels](#doc-conversations-channels) - [File extractor registry](#doc-conversations-file-extractor-registry) - [Agent Configuration](#doc-agents-configs) - [Guardrails](#doc-agents-guardrails) --- # Azure AI Search Adapter Use the Azure AI Search adapter when a deployment requires Microsoft-managed document retrieval while keeping Gaia's document-folder experience, access checks, citations, and diagnostics. The adapter is optional. If it is not enabled, Document Folders continue to use Gaia's built-in PostgreSQL/pgvector-backed retrieval and Structure Search. ## What the adapter does When enabled, Gaia can route document-folder keyword or hybrid candidate retrieval to a configured Azure AI Search index. Gaia still owns: - project and folder access checks before search; - folder scope and result shaping; - citation labels, excerpts, page, line, sheet, and row metadata; - source folder and knowledge-scope metadata; - result diagnostics shown in folder search and conversation tool results; - Structure Search behavior and fallback decisions. The adapter is designed for deployments where Azure AI Search is the approved external retrieval backend, while Gaia remains the system of record for folder membership, permissions, files, conversations, and evidence presentation. ## Deployment configuration A platform operator enables the adapter for the Gaia instance with these settings: ```text GAIA_DOCUMENT_FOLDER_RETRIEVAL_BACKEND=azure-ai-search GAIA_DOCUMENT_FOLDER_AZURE_AI_SEARCH_ENABLED=1 GAIA_DOCUMENT_FOLDER_AZURE_AI_SEARCH_ENDPOINT= GAIA_DOCUMENT_FOLDER_AZURE_AI_SEARCH_INDEX= GAIA_DOCUMENT_FOLDER_AZURE_AI_SEARCH_API_KEY= ``` Optional settings: ```text GAIA_DOCUMENT_FOLDER_RETRIEVAL_BACKEND=postgres|azure-ai-search|gaia-internal GAIA_DOCUMENT_FOLDER_AZURE_AI_SEARCH_STRICT=1 GAIA_DOCUMENT_FOLDER_AZURE_AI_SEARCH_QUERY_TYPE=simple|full|semantic GAIA_DOCUMENT_FOLDER_AZURE_AI_SEARCH_SEMANTIC_CONFIGURATION= GAIA_DOCUMENT_FOLDER_AZURE_AI_SEARCH_API_VERSION= GAIA_DOCUMENT_FOLDER_AZURE_AI_SEARCH_PROJECT_ID_FIELD= GAIA_DOCUMENT_FOLDER_AZURE_AI_SEARCH_FOLDER_ID_FIELD= GAIA_DOCUMENT_FOLDER_AZURE_AI_SEARCH_CONTENT_FIELDS= GAIA_DOCUMENT_FOLDER_AZURE_AI_SEARCH_TITLE_FIELDS= ``` By default, Gaia filters Azure AI Search queries by `projectId` and `folderId`. Set a field override when the index uses different names. Set a field value to `-` only when the external index is already isolated for one project or folder and no filter should be sent for that dimension. If `GAIA_DOCUMENT_FOLDER_RETRIEVAL_BACKEND` is not set, Gaia keeps PostgreSQL/pgvector as the compact default unless the Azure adapter is fully enabled. Set it to `postgres` when the deployment should force Gaia's built-in retrieval even while Azure settings are present for testing. `gaia-internal` is reserved for Gaia-owned retrieval-engine deployments and falls back to PostgreSQL until that engine is storage-backed. ## Expected index fields The adapter can map flexible index schemas, but the strongest evidence comes from storing these fields: | Field | Purpose | | --------------------------------- | -------------------------------------------------------- | | `projectId` | Restricts results to the Gaia project. | | `folderId` | Restricts results to the Gaia document folder. | | `id` or `unitId` | Stable result and citation ID. | | `sourceId` | Source document ID when available. | | `storagePath` | Gaia source path or external storage path. | | `relativePath` | Human-readable file path. | | `citationText` | Text shown in citations and excerpts. | | `title` or `pathLabel` | Label for the citation. | | `pageStart`, `pageEnd` | Page citation anchors for PDFs and page-based documents. | | `lineStart`, `lineEnd` | Line citation anchors for text documents. | | `sheetName`, `rowStart`, `rowEnd` | Spreadsheet citation anchors. | | `keywords`, `sectionTitles` | Optional search and display metadata. | | `metadata` | Optional source metadata preserved with the result. | ## Validate the adapter 1. Enable the adapter settings in the target environment. 2. Upload or index a known document into the corresponding Azure AI Search index. 3. Open **Conversations -> Folders**. 4. Search the folder for a phrase that should hit the known document. 5. Confirm that the result appears with citation text and source metadata. 6. Open a folder-linked conversation and ask the same question. 7. Confirm that the tool result shows the Azure AI Search route and the answer cites the returned source. If `GAIA_DOCUMENT_FOLDER_AZURE_AI_SEARCH_STRICT` is not enabled and Azure AI Search returns an error, Gaia logs the adapter failure and falls back to built-in Gaia retrieval. Enable strict mode when the deployment must fail closed instead of falling back. ## Evidence to capture For a reviewer, capture: - the deployment configuration showing the adapter enabled; - the selected retrieval backend and whether fallback or strict mode is configured; - the folder search result with Azure AI Search route diagnostics; - the conversation tool result showing Azure AI Search retrieval; - cited source excerpts with page, line, sheet, or row anchors; - a fallback or strict-mode test if the deployment policy requires it. ## Troubleshooting - **No results appear:** Check the project and folder filter fields in the Azure AI Search index. - **Results appear without citations:** Add `citationText`, `title` or `pathLabel`, and page/line/sheet anchors to the index projection. - **The route falls back to Gaia retrieval:** Check the platform logs for the Azure AI Search error, or enable strict mode to surface the error directly. - **Semantic search does not run:** Set `GAIA_DOCUMENT_FOLDER_AZURE_AI_SEARCH_QUERY_TYPE=semantic` and configure `GAIA_DOCUMENT_FOLDER_AZURE_AI_SEARCH_SEMANTIC_CONFIGURATION`. --- # Workflow Actions The Workflow Actions tab is the human-in-the-loop queue for data workflows. Use it when a workflow run pauses and requires an approval, a decision, or operator-supplied input before execution can continue. Open this queue from **Conversations -> Actions**. Gaia uses **Actions** consistently for workflow-generated human reviews. **Tasks** is a separate delivery-management surface for planned work, ownership, and follow-up. For published apps that use personal-assistant channels, signed-in end users can open the in-app **Actions** rail tab. Open reviews appear when the workflow step is routed to that app user directly or to an app user role they currently hold. The tab remains visible when the queue is empty so reviewers always know where human-review work appears. ## What appears here - **Approvals:** Requests that ask a user to approve or reject the next step. - **Decisions:** Requests that require a user to choose an outcome explicitly. - **Input requests:** Requests that need structured operator input before the workflow can proceed. - **Assignments:** Requests can be left unassigned, routed to one app user, or routed to an app user role such as `Approval Officer` or `Credit Manager`. - **Custom review layouts:** Human-action nodes can render a read-only context preview layout, an editable response layout, or both when the workflow author configured them. ## Review a pending action 1. Open **Conversations -> Actions**. 2. Filter the queue by **Status**, **Assignment**, or the search box. 3. Select a request to open its details. 4. Review the linked workflow run, node ID, due date, and response surface. 5. If needed, click **Claim** to take ownership. 6. Review any **Context preview** section first. It can include workflow context, referenced entity records, and document-folder evidence from the paused workflow run. 7. Fill in the rendered response UI. Gaia uses the workflow's saved response UI Layout when one is configured, otherwise it renders the schema-driven form. Requests without either surface still use the raw JSON payload editor. 8. Use **Complete**, **Reject**, or **Cancel** to record the outcome. Resolved requests automatically resume the paused workflow run when it is waiting on that action. ## Personal-assistant app flow 1. Sign in to the published app with a user who matches the assigned app user or assigned app role. 2. Open the personal-assistant channel. 3. Open the **Actions** rail tab. Its badge shows the number of open reviews assigned to you. 4. Select an action. Gaia keeps the conversation open and shows a compact, scrollable review workspace on the right side on desktop, or as a full-screen workspace on mobile. 5. Review the human-readable context and any linked document-folder evidence, then use the configured review layout. Internal workflow and node identifiers are intentionally hidden from end users. 6. Use **Accept** or **Reject** for approvals and decisions, or **Submit** for input requests. Resolving an action automatically resumes the paused workflow when it is waiting at that human-action checkpoint. 7. Open **Recent** to revisit resolved actions and download retained artifacts such as generated DOCX files. ## Tips - Workflow action notifications link directly into this queue when a specific request ID is available. - If a request is assigned directly to an app user who is linked to a platform user, Gaia notifies that platform user. - If a request is assigned to an app role, **Assigned to me** matches any user currently mapped to that same app role. - Unassigned actions remain available to project operators under **Conversations -> Actions**, but are not exposed to arbitrary end users in a published app. - Form-driven requests show a JSON preview so you can confirm the exact payload that will be submitted. - Context preview layouts are read-only. Response layouts submit layout state as the workflow action response JSON, optionally mapped into the response path configured on the human-action node. - Response layouts default to submit-only behavior. Workflow authors can opt into live entity writes for bound fields when the review surface is meant to update records during review. - Raw payload responses still have to be JSON objects. Arrays or plain strings are rejected. - Use the linked workflow run ID to jump into run details and inspect logs before resolving the action. ## Real-life example > A nightly customer onboarding workflow pauses after extracting records from a spreadsheet. The workflow asks an operations user to approve the staged records before publish. The reviewer opens Workflow Actions, inspects the run, fills in the approval form, and completes the request so the workflow automatically resumes. ## Troubleshooting - **End-user Actions is empty:** Confirm that the human-action node is assigned to the signed-in app user or one of their app roles. Unassigned actions are project-operator work. - **Project queue is empty:** The current filters may hide resolved items. Switch Status to **All**. - **Claim is disabled:** The request is already claimed or resolved. - **Complete fails:** Check that all required form values are valid. Raw payload requests still require a valid JSON object. - **Workflow stays paused after an end-user decision:** Inspect the workflow run logs. Gaia normally resumes the matching human-action checkpoint automatically; manual administrator resume is a recovery path, not the expected review flow. --- # File extractor registry The **File extractor registry** is the shared catalog for metadata extractors that can be reused by conversation-storage upload rules and by project-level document folders. Use it when you want a file-handling policy once and then reuse it across multiple Text or Personal Assistant channels, or across multiple project-level folders, instead of redefining the extraction logic each time. It lives in the Conversations workspace because it controls how uploaded files and indexed folder files are classified, enriched, and routed. Open this page from **Conversations -> File Extractors**. For the full folder-grounded assistant setup path, use [Scenario: Folder-grounded Personal Assistant setup](#doc-conversations-scenarios-folder-grounded-personal-assistant-setup). ## What you can do - Create reusable extractors for conversation-storage uploads and project-level folder files. - Choose the extractor mode: - **Workflow:** send matching uploads into a workflow. - **Inline AI:** run a model directly with instructions and an optional response schema. - **Agent:** run a selected agent as the extractor. - Limit extractors to specific file types or filename patterns. - Add reusable prompt fragments and link common fragments. - Start from platform starter templates: - **Generic Text Extractor** for text, markdown, PDF, DOCX, and ODT. - **Structured Document Outline Extractor** for documents whose logical sections may span pages or chunks. - **Generic Spreadsheet Extractor** for CSV and Excel uploads. - Return either legacy metadata-only JSON or the newer reserved envelope: - `metadata`: diagnostic/output fields for downstream automation. - `indexing`: optional document-folder retrieval hints such as title, summary, keywords, aliases, logical document spans, section anchors, sheet aliases, and `pdf.preferVisualAnalysis`. ## Extractor output contract Gaia now accepts two inline extractor output shapes: - Legacy shape: any JSON object. Gaia treats the full object as metadata only. - Envelope shape: a JSON object with `metadata` and/or `indexing`. Use the envelope when the extractor should influence document-folder retrieval. Today, only **Inline AI** and **Agent** extractors can customize folder indexing. **Workflow** extractors remain asynchronous and metadata-oriented. Gaia merges `indexing` hints additively: - scalar fields such as `title`, `summary`, `documentType`, and `language` override built-in analysis when non-empty, - `keywords` and `searchAliases` are merged into lexical retrieval metadata, - `documentStructure.spans` can define a generic outline for logical sections that cross page or chunk boundaries, - `sections` are used only when their `matchPhrases` can be anchored safely in the canonical text, - `spreadsheet.sheets` enrich matching sheet summaries, aliases, and keywords, - `pdf.preferVisualAnalysis` can force the PDF OCR/visual-analysis path for that file during indexing. ## Typical workflow 1. Open **Conversations -> File Extractors**. 2. Click **Add extractor**. 3. Start from a blank extractor or choose a starter template. 4. Configure the mode, file filters, and instructions. 5. Save the extractor. 6. Open **Conversations -> Channels** to select the extractor from a conversation-storage upload rule, or open **Conversations -> Folders** and edit a project-level folder's **Folder file extractors**. When you update a registry extractor that is linked from folder-enabled Personal Assistant channels or from project-level folder rules, Gaia queues a folder reindex for active project folders automatically so retrieval stays in sync with the new definition. ## When to use registry extractors vs inline extractors - Use a **registry extractor** when the same extraction logic should be reused across multiple channels or project-level folders. - Use an **inline extractor** when the rule is specific to one channel upload policy or one project-level folder. - Use a **direct workflow target** when you only need workflow routing and do not need a reusable extractor definition. ## Real-life example > A finance team creates one spreadsheet extractor that summarizes sheet names, measures, and date ranges from uploaded workbooks. They reuse the same extractor in both a public Text channel and an internal Personal Assistant channel, so both entrypoints classify uploads the same way. ## Related docs - [Channels](#doc-conversations-channels) - [Scenario: Folder-grounded Personal Assistant setup](#doc-conversations-scenarios-folder-grounded-personal-assistant-setup) - [Workflows](#doc-data-model-workflows) - [Tool registry](#doc-data-model-tool-registry) - [Skill registry](#doc-agents-skills) --- # Agent Config Checklist for Canvas and Document Workflows Use this page when you want a configuration-level checklist only: model, tools, limits, and prompts. If the problem spans more than one surface, do not start here. Open **Delivery Management -> Overview** and review **Project configuration overview** or ask Gaia for a **project setup diagnosis** first, then come back to this checklist once the owning gap is clearly in the agent configuration. If you also need entity/layout setup, follow the scenario playbooks in [Conversation scenarios](#doc-conversations-scenarios). ## Scenario selector - Use **Entity canvas** when you want the split right-side panel with a UI Layout. - Use **Inline UI response** when the assistant should render a one-off interactive UI directly in the reply body. - Use **Runtime UI canvas artifact** when you want a `ui-layout-canvas` artifact in the split right-side panel with live runtime state. - Use **Document editing** when a user uploads a file (for example PDF/DOCX/ODT/MD/TXT/CSV/XLSX/ODS/PPTX/ODP) and expects AI-assisted edits plus export/download. ## Shared checklist (all scenarios) 1. Open **AI Agents → Configurations → General** and select a **Primary model**. 2. Verify the primary model can run your tool workflow (for attachments, Responses-capable models are required). 3. In **General → File uploads**, set: - **Allow attach to model** = on (for user-uploaded files in conversation) - **Allow upload to storage** = optional (only if your flow also needs direct storage uploads) - Note: direct model attachment supports a subset of file types. Unsupported files (for example `DOCX`, `ODT`, `XLSX`, or `ODS`) are routed to artifact source storage and should be handled with artifact tools. 4. Confirm **Max Tool Calls** is at least `1` (recommended `5+` for multi-step flows). 5. In **Tools**, enable all required tools for your chosen scenario. 6. In **Instructions**, add a short rule telling the agent when to call the scenario tools (do not rely on implicit behavior). If the same agent may choose between inline UI, entity canvas, saved layouts, or runtime canvas sessions, add an explicit routing rule or reusable routing fragment so the model infers the correct mode from user intent. 7. (Optional) In **Post-steps**, add preset or custom post-turn processing when you want conversation assessment, topic extraction, or memory consolidation. ## Prompt examples (copy/paste starters) ### Example: entity canvas behavior ```md When the user asks to open, inspect, or edit a business record in the side panel: 1. Resolve the target entity and record. 2. Call `entity_open` so the canvas opens with the correct layout. 3. Confirm the canvas is open before continuing with edits. If entity, record, or layout is unclear, ask one clarification question and continue in chat. ``` ### Example: document and p5 artifact behavior ```md When the user asks for document edits or an interactive artifact: 1. Create new work with `artifact_create`, or import uploads with `artifact_create_from_attachment`. 2. Open split canvas with `artifact_open` when side-by-side editing is useful. 3. Read current content with `artifact_read`. 4. For spreadsheet artifacts, use `artifact_spreadsheet_query` for summaries, exact A1 `range_read` reads, filtered row previews, grouped totals, multi-column aggregations, distinct counts, medians, percentiles, and date-bucketed analysis, page large row or grouped result sets with `window.nextOffset`, and prefer `artifact_spreadsheet_mutate` for editable cells, formulas, styles, rows, columns, and sheet changes. If an uploaded spreadsheet opens as a read-only workbook preview, Gaia can still query exact ranges and structured reads while keeping mutation disabled. 5. Apply edits with `artifact_update` for markdown and p5, or when you intentionally need a full canonical-content replacement. 6. Export with `artifact_export` when the user requests artifact download (default export is DOCX for markdown, JS for p5, XLSX for editable spreadsheet artifacts, PPTX for presentation artifacts, and the original spreadsheet format for read-only workbook previews). Use the conversation **Export** action when the user needs the transcript itself as DOCX or PPTX. If the canvas has unsaved local edits, save first. Gaia resolves saved revision conflicts with merge-or-review semantics instead of explicit locks. ``` ### Example: inline UI response behavior ```md When the best answer is a one-off interactive UI in the reply body: 1. Infer the layout structure from the request. 2. Reply with a fenced `gaia-ui-layout` JSON block that includes `layoutSpec` and the `values` needed for this turn. 3. Keep it inline unless the user explicitly asks to save it or open a runtime canvas session. ``` ### Example: UI layout intent routing behavior ```md When the user asks for an interactive UI, infer the lightest viable delivery mode from intent: 1. Use entity canvas for opening or editing a specific record in the side panel. 2. Use inline `gaia-ui-layout` for one-off reply-local forms, dashboards, and review surfaces. 3. Use `ui_layout_*` for reusable saved layouts that should be organized or published. 4. Use `ui-layout-canvas` artifacts for split-canvas runtime sessions with live state across turns. 5. Ask a clarification question only when the intent does not clearly distinguish these modes. ``` ### Example: runtime UI canvas artifact behavior ```md When the user needs an interactive runtime UI in the split canvas: 1. Reuse an existing `ui-layout-canvas` artifact for the conversation when possible. 2. Otherwise create one with `artifact_create` and open it with `artifact_open`. 3. Keep live data in the artifact document state and update it with `artifact_update` as the session changes. 4. Use `ui_layout_*` only if the stored layout definition itself must change. ``` ### Example: persisted UI layout authoring behavior ```md When the user wants to create or refine a reusable saved layout: 1. Inspect existing layouts when relevant. 2. Draft the `layoutSpec` from the request. 3. Validate it before saving. 4. Create or update the layout only after validation succeeds. ``` ## Tool-level checklist: Entity canvas scenario Required tools: - `entity_open` Recommended tools: - `search_across_entities` (find candidate records before opening) - `entity_record_get`, `entity_record_update` (or equivalent entity tools in your project) Expected behavior: 1. Agent resolves target record. 2. Agent calls `entity_open`. 3. Conversation receives a canvas `uiUpdate` and opens split view. ## Tool-level checklist: Inline UI response scenario Required tools: - No special tool is strictly required for rendering itself. Recommended tools: - `ui_layout_component_help` - `ui_layout_reusable_component_list` - `ui_layout_validate` - whichever data-retrieval tools supply the runtime values Expected behavior: 1. Agent gathers the data needed for the turn. 2. Agent replies with a fenced `gaia-ui-layout` block containing `layoutSpec` and `values`. 3. Conversation renders the UI inline in the reply body. ## Tool-level checklist: Runtime UI canvas artifact scenario Required tools: - `artifact_list_for_conversation` - `artifact_create` - `artifact_open` - `artifact_read` - `artifact_update` Recommended tools: - `ui_layout_get` when the runtime session references a saved layout Internal skills: - `ui-layout artifact runtime canvas` - `ui layout intent routing` when the same agent may choose between inline UI, entity canvas, saved layouts, and runtime canvas sessions Expected behavior: 1. Agent reuses or creates a `ui-layout-canvas` artifact. 2. Agent opens it in the split canvas. 3. Agent keeps runtime values in the artifact document instead of rewriting the saved layout. ## Tool-level checklist: Document editing scenario Required tools: - `artifact_list_for_conversation` - `artifact_create` - `artifact_create_from_attachment` - `artifact_open` - `artifact_read` - `artifact_pdf_annotation_list` - `artifact_pdf_annotation_add` - `artifact_pdf_annotation_update` - `artifact_pdf_annotation_delete` - `artifact_spreadsheet_mutate` - `artifact_update` - `artifact_export` Recommended tools: - no additional tools are required beyond the bundle above Internal skills: - `document artifact editing` - keep `ui-layout artifact runtime canvas` separate for `ui-layout-canvas` sessions instead of overloading the document-editing path Expected behavior: 1. User uploads a file via **Attach to model**. 2. Agent imports it into a conversation artifact. 3. Agent/user applies revision-based updates. If the canvas is dirty, save before asking the assistant to edit. For spreadsheets, agents should query large workbooks with `artifact_spreadsheet_query` and prefer structured spreadsheet mutations instead of full workbook rewrites. For PDF annotation artifacts, agents should use the `artifact_pdf_annotation_*` tools, while users can place note markers and highlight boxes on the PDF canvas and refine saved annotations from the side panel; both paths revision annotations separately from the source PDF. 4. Agent exports and returns a download URL. ## Validation checklist before going live 1. Run one manual conversation for each scenario and confirm the expected tools are called. 2. Confirm failures are understandable (missing model capability, missing tool, missing layout, revision conflict). 3. Save config and test again using **Save & Test** in both **text** and **personal-assistant** channels (if both are used). ## Use Internal skill templates for the supported setup Use reusable presets so UI-layout routing is explicit instead of being rebuilt ad hoc in each prompt: 1. Open **AI Agents → Skills**. 2. Click **Internal**. 3. Create: - **ui layout intent routing** - **entity canvas operations** - **inline ui layout responses** - **ui layout authoring** - **ui-layout artifact runtime canvas** - **document artifact editing** 4. In **AI Agents → Configurations → Skills**, add these skills and define rules. Example skill rules: - `ui layout intent routing`: apply when the user asks for an interactive UI and the agent must choose between inline UI, entity canvas, saved layouts, or runtime canvas sessions from intent. - `entity canvas operations`: apply when user asks to open/view/edit a specific entity record in side panel or canvas. - `inline ui layout responses`: apply when the best answer is a one-off interactive UI rendered inside the reply body instead of a saved layout or runtime canvas artifact. - `ui layout authoring`: apply when user asks to create, validate, or update a reusable saved UI layout definition. - `ui-layout artifact runtime canvas`: apply when user asks for a split-canvas runtime UI session with live state in the conversation. - `document artifact editing`: apply when user uploads a file and asks for edits, rewrite, or export. --- # Conversation Scenarios These playbooks document practical, end-to-end conversation workflows. Use them after you complete the configuration checks in [Agent Config Checklist for Canvas and Document Workflows](#doc-conversations-agent-config-checklist). ## Available scenarios - [Scenario: Live-agent bridge takeover workflow](#doc-conversations-scenarios-live-agent-bridge-takeover-workflow) - [Scenario: Folder-grounded Personal Assistant setup](#doc-conversations-scenarios-folder-grounded-personal-assistant-setup) - [Scenario: Inline UI layout responses](#doc-conversations-scenarios-inline-ui-layout-responses) - [Scenario: Entity canvas workflow](#doc-conversations-scenarios-entity-canvas-workflow) - [Scenario: Runtime UI canvas artifact workflow](#doc-conversations-scenarios-runtime-ui-canvas-artifact-workflow) - [Scenario: Document upload, edit, and download workflow](#doc-conversations-scenarios-document-editing-workflow) --- # Scenario: Live-agent bridge takeover workflow Use this playbook when you want a Text channel to hand a conversation to a live-support system, keep Gaia paused while a human or external workflow is active, and then resume the assistant with a clean summary. This guide covers the recommended end-to-end flow: 1. Configure the channel bridge and Bridge Agent. 2. Enable host context for embedded experiences when the bridge needs session-specific JSON. 3. Test the embedded bridge path from **Portal view**. 4. Forward the Gaia transcript and bridge context from a TypeScript tool. 5. Feed queue, assignment, and session events back into Gaia through the transport route. 6. Resume Gaia with a summary after the live agent is done. For a field-by-field explanation of the Bridge Agent form, use [Bridge Agent Settings](#doc-agents-live-chat-bridge-agent). ## Before you start - You need a **Text** channel with an assigned agent. - You need access to **Conversations**, **Channels**, and **AI Agents**. - If the live-support integration is project-owned, you also need access to the TypeScript tool editor or the workflow surface that will call the vendor. - The published app or embedded iframe should already be reachable to the intended end users. ## Step 1: Configure the bridge on the channel and Bridge Agent 1. Open **Conversations -> Channels**. 2. Open the target **Text** or **Personal Assistant** channel. 3. In **External participants**: - turn on **Enable external bridge**, - configure **Allowed origins** if the bridge or iframe host should be restricted, - choose or create the **Bridge Agent** that owns provider settings, actors, routing, and hooks. 4. Save the channel. 5. Open the Bridge Agent settings. 6. Configure at least one named external actor. 7. Choose the Bridge Agent **Provider**: - **Custom** is the default. Use it when your integration sends normalized transport envelopes and owns vendor-specific outbound logic. - **Genesys** reveals Genesys-specific runtime fields and enables Gaia's reference Genesys transport adapter. Bridge TypeScript should use provider dispatch or credential-scoped SDK setup for outbound provider calls. 8. If you choose **Genesys**, choose **Auth mode** for server-to-server bridge calls: - **API key** accepts `X-API-Key` or `Authorization: Bearer ...` using the configured credential reference. - **Signed webhook** verifies an HMAC SHA-256 signature over the exact request body. The default signature header is `X-Gaia-Signature`, and values may be plain hex or `sha256=`. 9. Choose **User turn routing** when some end-user turns should bypass Gaia and go straight to the provider or when custom TypeScript should decide per turn. 10. Leave **Require resume summary** on unless you have a strong reason to resume Gaia without operator context. User-turn routing modes behave as follows: - **Takeover only** keeps Gaia paused only while active takeover state owns user turns. - **Always use Gaia orchestrator** sends user turns through Gaia even if takeover metadata is still present. - **Always use external provider** sends user turns to the Bridge Agent runtime whenever the bridge is enabled and bound. - **Custom TypeScript decision** runs the routing script for each turn and honors its `gaia` or `external` result. The named actor becomes the visible identity Gaia uses when a live agent or external workflow speaks in the conversation. ## Step 2: Enable host context for embedded experiences If the channel runs inside a portal, CRM, or other host application, expose host context for the current embedded session only. 1. Stay on the same channel. 2. Turn on **Allow iframe host context**. 3. Set **Host context TTL (seconds)** to the window you want Gaia to keep that host-provided JSON available. 4. Save the channel. Use host context for session-local metadata such as customer IDs, ticket IDs, account tier, or locale. Gaia keeps that JSON out of the conversation transcript. ## Step 3: Test the embedded bridge path from Portal view 1. Open **Conversations** and choose a thread on the target channel. 2. Click **Portal view**. 3. On the preview page, use the **Embedded bridge tools** card above the floating assistant. 4. Enter the simulated host origin. 5. Paste or edit a JSON object with the host metadata you want bridge-aware tools to see. 6. Open the floating assistant and wait for the preview page to show that the iframe session is ready. 7. Click **Send JSON**. The simulator lives on the preview surface instead of inside the popup so you can keep the full assistant panel available while you test. ## Step 4: Forward transcript and bridge context from Gaia The live-support handoff logic usually starts inside a project-owned TypeScript tool. In that tool, use the bridge-aware utility surface to collect: - the current conversation transcript from `getCoreConversationMessages()` - any ephemeral host metadata from `getHostContext()` - durable bridge correlation state from `getIntegrationContext()` If you want the routing code itself to forward the turn to your provider adapter, use `context.utils.externalBridge.dispatchProviderRequest(...)`. Gaia wraps your project-specific payload inside a standard `bridge` envelope that already includes conversation ID, channel info, latest user turn, transcript, host context, and correlation or session IDs. When Genesys bridge TypeScript needs to call a provider adapter, use `context.utils.externalBridge.dispatchProviderRequest(...)` so Gaia builds the normalized bridge envelope; this works with portable context v2. Lower-level SDK code using `context.utils.liveAgent.loadLibrary('genesys')` requires context v1 with Legacy Node.js. Avoid host-scoped access tokens; `getAuthenticatedClient('genesys')` remains blocked by default. Forward only the data the external system needs. Keep the outbound payload focused on transcript, customer context, and correlation fields. For the tool setup details, use [Engineering reference: TypeScript tools](#doc-agents-typescript-tools). ## Step 5: Feed queue and assignment events back into Gaia Split inbound bridge traffic into two surfaces: - Use the conversation bridge route when the external system is intentionally changing authorship or transcript state, such as `start`, `message`, or `resume`. - Use the provider-facing transport route when a vendor webhook only needs to update queue, assignment, or session lifecycle state. Recommended transport-route usage: 1. Send the channel slug. 2. Either send a normalized transport envelope with the external `system` name, or use the reference adapter path with `provider: "genesys"` plus the raw provider payload. 3. Include at least one stable transport identifier such as `correlationId` or `sessionId` when you send normalized transport state directly. 4. Send queue position, assignment details, status, and references through that route. 5. If the Bridge Agent uses **Signed webhook**, sign the raw JSON body with the configured secret and send the signature in the configured header. Gaia resolves the matching conversation from the channel plus the transport identifiers before it updates the stored transport state. If the transport route returns a `suggestedBridgeAction` for a resume-like vendor event, treat that as a recommendation and then call the conversation bridge route with the explicit `resume` action. Gaia does not auto-resume from the transport route. Resume-like events include the human agent leaving unexpectedly, a provider disconnect event, or a scheduled shift ending while the customer has not replied in time. In the default takeover-only routing mode, new end-user messages still stay in the conversation transcript, but Gaia does not start another assistant run for them. Gaia also forwards the latest end-user turn through the Bridge Agent's outbound provider dispatch path, so the external operator or workflow can keep receiving customer replies until the explicit `resume` call succeeds. If you need more granular control, set **User turn routing** to **Always use Gaia orchestrator** for a full Gaia override, **Always use external provider** for a direct-provider policy, or **Custom TypeScript decision** for per-turn logic. The routing script can inspect the latest user turn, the clean user and assistant transcript, host context, and normalized transport state before returning `gaia` or `external` for that specific message. The same script can also call the shared provider-dispatch helper when the `external` branch should forward the normalized bridge envelope to your adapter immediately. ## Step 6: Resume Gaia with a summary When the live-agent session ends: 1. Send the operator or workflow summary back through the conversation bridge route using `resume`. 2. Keep the summary concise and user-relevant. 3. Confirm Gaia resumes only after the summary is accepted. If **Require resume summary** is enabled, Gaia will block resume attempts that do not include one. For interrupted handoffs, make the summary explicit about why control is returning. Examples include “the assigned agent disconnected unexpectedly” or “the support shift ended while waiting for the customer.” That gives Gaia enough context to continue the thread without pretending the human completed the work. ## Validate the full workflow Run this check before handing the integration to real users: 1. Start a conversation in the published app. 2. Trigger the project-owned bridge tool. 3. Confirm the tool can read transcript and host context. 4. Send a `start` or `message` action from the integration layer and verify the external participant appears in the conversation. 5. Send at least one provider transport event such as queue or assignment. 6. Confirm Gaia stays paused during takeover. 7. Send one more end-user message during takeover and confirm the UI records it without starting a fresh Gaia response. 8. Simulate a human drop or provider disconnect and confirm the integration produces a resume recommendation instead of silently leaving the conversation paused. 9. Simulate the live agent's service window ending while the customer is idle, then explicitly resume Gaia with a short shift-end summary. 10. Send `resume` with a summary and confirm Gaia replies again afterward. 11. If you use custom **User turn routing**, send at least one message that should stay with Gaia and one that should go directly to the provider, then confirm both paths behave as configured. ## Related docs - [Conversations](#doc-conversations) - [Channels](#doc-conversations-channels) - [Engineering reference: TypeScript tools](#doc-agents-typescript-tools) - [Scenario: Folder-grounded Personal Assistant setup](#doc-conversations-scenarios-folder-grounded-personal-assistant-setup) --- # Scenario: Folder-grounded Personal Assistant setup Use this playbook when you want a Personal Assistant channel to answer from shared folder files instead of relying only on chat history or direct attachments. Interactive walkthrough: Open [Tutorials](/platform/support/tutorials) and select **Personal Assistant: Folders Setup** for the guided version of this flow. The tutorial card also exposes a companion video when you want to preview the channel setup path first. This guide covers the full recommended setup path: 1. Turn on **Show folder workspace** on the channel. 2. Configure any channel-level knowledge folders that should always be available as background policy/reference material. 3. Configure file extraction when uploads should enrich retrieval. 4. Add the reusable folder-retrieval common fragment. 5. Attach the Document knowledge grounding validator. 6. Enable the folder tools on the target agent. 7. Create or link conversations to folders from end-user UI or platform admin. ## Before you start - You need a **Personal Assistant** channel with an assigned agent. The channel agent can be a specialist or an orchestrator, as long as it has an active configuration with the folder tools you need. - You need access to **Conversations**, **AI Agents**, and the **Validators** and **File Extractors** registries. - Folder-grounded retrieval is for authenticated Personal Assistant sessions only. ## Step 1: Configure folder access on the channel 1. Open **Conversations -> Channels**. 2. Open the target **Personal Assistant** channel. 3. Go to the **Files** tab. 4. In the **Folders** card: - turn on **Show folder workspace**, - folder search is enabled automatically for that channel, - choose the search mode and default language, - set **Assistant result limit** if you want a non-default retrieval budget for assistant turns, - review the advanced indexing options if you need a preferred multilingual rewrite model, hybrid-only embeddings, bounded reranking with a preferred reranking model, automatic PDF visual analysis, or the **File extractor presets** dialog for reusable document and spreadsheet extractors. 5. Save the channel. Channel-defined folders created under this Personal Assistant channel inherit this policy. That policy controls indexing behavior, file-extractor routing, retrieval defaults, multilingual query rewrites, and how Gaia automatically handles PDF analysis during indexing. The embedding selector appears only for hybrid-capable retrieval modes, while the reranking model selector appears only when reranking stays enabled. ## Step 2: Configure channel knowledge folders If every conversation on this channel should search shared policy, standards, or reference folders, attach them before users start chatting. 1. Open **Conversations -> Channels -> Personal Assistant -> Files**. 2. In **Knowledge folders**, attach any shared folders that should always be available. 3. Mark each attached folder as: - **Important** when it should be searched in the first pass with the linked work folder. - **Fallback** when Gaia should search it only if the linked folder plus important knowledge returns weak or empty results. 4. Save the channel. Use channel knowledge folders for material that should apply to every conversation on this channel. ## Step 3: Configure file extraction for folder uploads If uploaded files should add better titles, aliases, section anchors, spreadsheet hints, or PDF visual-analysis preferences, configure extractor rules before users start uploading. 1. Open **Conversations -> File Extractors** if the same extractor should be reused across channels. 2. Create or edit an extractor. 3. For retrieval-aware extractors, return the reserved envelope with `metadata` and `indexing`. 4. Go back to **Conversations -> Channels -> Personal Assistant -> Files**. 5. Add or update the upload routing rule so the channel uses the extractor. Use **Workflow** extractors for downstream automation only. Use **Inline AI** or **Agent** extractors when the extractor should influence document-folder retrieval. ## Step 4: Add the folder-retrieval common fragment The recommended prompt setup is to add the reusable common fragment instead of rewriting the folder behavior in every config. 1. Open **AI Agents -> Configurations** and edit the active configuration for the channel agent. 2. Go to **Instructions**. 3. Add a prompt fragment. 4. Link it to the common fragment template **Folder Retrieval**. 5. Save the configuration draft. That fragment tells the assistant to treat the linked folder as the primary work context, to search attached important knowledge folders in the same first pass, and to fall back to secondary knowledge folders only when the first pass is weak or empty. It also positions `search_document_folder` as the default evidence-discovery tool across indexed text and spreadsheet content before the assistant reasons from snippets alone. ## Step 5: Attach the Document knowledge grounding validator The common fragment tells the agent what to do. The validator enforces that the agent actually grounded the answer in folder evidence on substantive turns. 1. Open **AI Agents -> Guardrails**. 2. Create or reuse a validator from the **Document knowledge grounding** template. 3. Open the target agent configuration again. 4. In **General -> Guardrails**, attach that response-validation guardrail. 5. Save the configuration. Use agent-specific override text only when the assistant has stricter grounding rules than the shared default. ## Step 6: Enable the folder tools Folder linking does not auto-enable tools. In the same agent configuration, go to **Tools** and make sure these are enabled: - `search_document_folder` - `document_folder_get_passages` `search_document_folder` is the default search tool for indexed text and spreadsheet content across the linked folder and any attached knowledge folders. If the folder uses **Structure Search** or **Structure Search + hybrid fallback**, also enable: - `document_folder_get_structure` - `document_folder_get_section_content` - `document_folder_expand_section` Also enable `document_folder_spreadsheet_query` if the assistant needs structured workbook analysis from linked folder spreadsheets after the relevant file or sheet has been identified. Also enable `document_folder_list_files` if the assistant needs to enumerate which files are currently stored in the linked folder. ## Step 7: Create folders and link conversations ### From the end-user Personal Assistant UI 1. Open the Personal Assistant app. 2. Open the history rail. 3. Create or select a channel-defined folder. 4. Select the folder icon and name in the header. 5. Use **Move conversation here** when the current conversation should be attached to that folder. For shared project-level knowledge folders, use **Conversations -> Folders** first and then attach those folders to the relevant configs or channels. ### From platform admin 1. Open **Conversations**. 2. Click **New** and choose the Personal Assistant channel. 3. In the create dialog, choose one of: - **No folder** - **Existing folder** - **New folder** 4. Create the conversation. Use the admin flow when the conversation should start in a controlled folder context from the first message. Conversations created from this flow keep the selected Personal Assistant channel as their source. That means folder lists, channel knowledge folders, and the initial assistant configuration follow the channel you picked instead of falling back to another active Personal Assistant channel. If the folder content currently lives in Microsoft storage, export the files locally first and then upload them from the **Folder files** pane inside **Conversations -> Folders**. ## Validate the setup Run this quick check before handing the channel to users: 1. Create a folder under the channel. 2. Upload one representative file. 3. Wait for indexing to finish. 4. Start a linked conversation. 5. Ask a question whose answer is only in the uploaded file. 6. Confirm the assistant calls folder search and answers from folder evidence. If the assistant answers from general knowledge instead of folder evidence, check the common fragment, validator attachment, and tool enablement first. ## Related docs - [Document Folders](#doc-conversations-document-folders) - [Channels](#doc-conversations-channels) - [File extractor registry](#doc-conversations-file-extractor-registry) - [Agent Configuration](#doc-agents-configs) - [Guardrails](#doc-agents-guardrails) --- # Scenario: Inline UI layout responses Use this scenario when the assistant should return a compact interactive UI directly inside the reply instead of opening the side canvas or saving a layout first. Typical fits: - a one-off approval form - a quick KPI dashboard - a generated checklist or intake wizard for the current turn ## Goal The assistant answers with an embedded interactive UI block that renders inside the conversation transcript. ## When this is the right option Choose this path when all of these are true: - the UI is useful only for the current turn or short exchange - you do not need artifact revision history - you do not need the right-side split canvas - you do not need to publish or organize the layout in **UI Layouts** yet If you need a reusable saved definition, follow [UI Layouts](#doc-conversations-ui-layouts). If you need a right-side runtime session, follow [Scenario: Runtime UI canvas artifact workflow](#doc-conversations-scenarios-runtime-ui-canvas-artifact-workflow). ## Prerequisites 1. Complete the [agent configuration checklist](#doc-conversations-agent-config-checklist). 2. Decide whether the agent should also have access to entity or search tools that provide the runtime data for the inline UI. 3. Add a short prompt rule telling the agent when to answer with an inline UI block. Recommended setup: - add the **ui layout intent routing** internal skill when the same agent may need to choose between inline UI, entity canvas, saved layouts, and runtime canvas sessions from user intent - add the **inline ui layout responses** internal skill when the agent should infer `layoutSpec` from natural-language product requests and answer inline - add the **ui layout authoring** internal skill when the same agent should also persist reusable layouts - add the **UI Layout Intent Routing** common fragment when you want reusable routing guidance in the prompt layer - add the **Inline UI Layout Blocks** common fragment when you want a reusable prompt starter for the fenced response format ## Prompt starter Add an instruction such as: ```md When the best answer is a one-off interactive UI inside the reply, respond with a fenced `gaia-ui-layout` JSON block that includes the full `layoutSpec` and the `values` needed for this turn. Use this for inline forms, dashboards, and short-lived review surfaces. Do not claim the layout was saved unless you actually persisted it. If the same agent can also open canvases or save reusable layouts, pair this instruction with a routing rule that distinguishes inline UI from entity canvas, saved layout authoring, and runtime canvas sessions. ``` ## Recommended response shape ```gaia-ui-layout { "type": "ui-layout", "title": "Customer review", "description": "Confirm the generated customer summary before approval.", "layoutSpec": { "root": { "id": "root", "type": "card", "children": [ { "id": "heading", "type": "text", "props": { "text": "Review customer" } }, { "id": "status", "type": "checkbox", "props": { "label": "Approved" } }, { "id": "notes", "type": "textarea", "props": { "placeholder": "Reviewer notes" } } ] } }, "values": { "customer": { "id": "cust-1", "name": "Acme Corp", "segment": "Enterprise" } } } ``` ## Example 1: Approval form User request: "Show me a quick approval form for the generated onboarding summary." Expected behavior: 1. The agent gathers the current summary data. 2. The agent replies with an inline `gaia-ui-layout` block. 3. The form renders directly in the reply without opening the side canvas. ## Example 2: Inline KPI dashboard User request: "Give me a quick dashboard for the three highest-risk accounts and the recommended next actions." Expected behavior: 1. The agent fetches or computes the ranked data. 2. The reply includes cards, text, and optionally a `data-table` inside an inline UI block. 3. The user can review the dashboard in place without navigating away from the transcript. ## Tips - Keep the inline payload focused on the current task instead of reproducing your full entity schema. - Include `values` whenever the layout depends on runtime data. - Use the optional `components` map only when the inline UI references reusable component nodes and should stay self-contained. - Move to a saved layout when the same inline UI keeps reappearing across conversations. ## Troubleshooting - Inline UI does not render: confirm the reply uses a fenced `gaia-ui-layout` block and valid JSON. - The reply shows raw JSON instead of UI: check that the payload includes `layoutSpec`, not only prose or unrelated JSON. - The UI should have been reusable: move the design into [UI Layouts](#doc-conversations-ui-layouts) and keep the inline block for truly ephemeral surfaces only. --- # Scenario: Entity canvas workflow This scenario is for teams that want split view in Conversations: - left panel: chat - right panel: UI Layout bound to entity data ## Goal A user asks to open or edit a business record, and the assistant opens that record in the right-side canvas. ## Prerequisites 1. Complete the [agent configuration checklist](#doc-conversations-agent-config-checklist). 2. Confirm you can edit entities in **Data Model**. 3. Confirm at least one UI Layout exists for the target entity. ## Step 1: Prepare the entity 1. Open **Data Model → Entities**. 2. Open the target entity. 3. Verify the entity is configured for UI usage. 4. Save if you changed anything. ## Step 2: Attach a layout to the entity 1. On the entity page, open the **Layouts** tab. 2. Attach at least one layout. 3. In **UI Layouts**, verify fields are bound to entity properties. 4. Save the layout. ## Step 3: Configure the agent tools 1. Open **AI Agents → Configurations → Tools**. 2. Enable `entity_open` (required). 3. Enable `search_across_entities` and record tools (recommended) so the assistant can find and update records. 4. Save the configuration. Recommended setup: - Create the **ui layout intent routing** internal skill in **AI Agents → Skills → Internal**. - Create the **entity canvas operations** internal skill and attach both skills to the agent config in the **Skills** tab. ## Step 4: Add instruction for canvas behavior In **Instructions**, add a clear policy such as: ```md When a user asks to open/view/edit a specific entity record, locate the record and call `entity_open` so the canvas opens. If the same agent can also answer with inline UI or runtime canvases, route those requests separately instead of forcing entity canvas for every interactive UI request. ``` Save again. ## Step 5: Run the conversation 1. Start a conversation in **text** or **personal-assistant** channel. 2. Ask for a concrete record, for example: - “Open the Renewal Opportunity for account ACME-102.” 3. Confirm the conversation splits into two panels. ## Step 6: Validate write-back 1. Edit values in the right panel. 2. Save/update through the layout controls. 3. Re-open the same record to confirm persisted values. ## Troubleshooting - Canvas does not open: verify `entity_open` is enabled in the active config. - “No UILayout found” behavior: attach a layout to the entity. - Canvas opens but no saved changes: verify layout field bindings and record update permissions. --- # Scenario: Runtime UI canvas artifact workflow Use this scenario when the assistant should open a right-side interactive UI session with live state for the current conversation. This guide covers the full recommended setup path: 1. Confirm the agent configuration is the right place to fix the problem. 2. Enable the runtime canvas artifact tools. 3. Attach the dedicated internal skill and optional routing skill. 4. Add the prompt rule that tells the agent when to use runtime canvas. 5. Reuse or create the `ui-layout-canvas` artifact during the conversation. This is different from: - [Inline UI layout responses](#doc-conversations-scenarios-inline-ui-layout-responses), which stay inside the reply body - [UI Layouts](#doc-conversations-ui-layouts), which manage reusable saved layout definitions ## Goal The assistant creates or reuses a `ui-layout-canvas` artifact, opens it in the split canvas, and keeps its runtime values in sync as the session evolves. ## When this is the right option Choose this path when you need at least one of these: - a right-side split canvas instead of an inline reply block - runtime session state that should survive multiple turns in the same conversation - artifact revision behavior around the runtime document - workflow progress or action-button state associated with the current canvas session ## Prerequisites 1. Complete the [agent configuration checklist](#doc-conversations-agent-config-checklist). 2. Enable the artifact tools used for runtime canvas sessions: - `artifact_list_for_conversation` - `artifact_create` - `artifact_open` - `artifact_read` - `artifact_update` Use `artifact_list_for_conversation` when the agent should reopen or continue an existing runtime session instead of always creating a new artifact. 3. If the runtime canvas should reference an existing saved layout, confirm that the layout already exists in [UI Layouts](#doc-conversations-ui-layouts). 4. If the setup already exists but behavior is inconsistent, open **Delivery Management -> Overview** or ask Gaia for a **project setup diagnosis** before editing prompts. Gaia surfaces runtime canvas artifact gaps under **Agent Runtime**. Recommended setup: - create the **ui layout intent routing** internal skill when the same agent may need to distinguish runtime canvas sessions from inline or saved-layout requests - create the **ui-layout artifact runtime canvas** internal skill and attach it to the configuration - keep **document artifact editing** separate when the same agent also edits uploaded markdown, spreadsheet, or p5 artifacts - use the artifact common fragment template when the agent already handles other artifact types in the same workflow - use the **UI Layout Intent Routing** common fragment when you want reusable prompt-level guidance for choosing the right UI mode from user intent ## Prompt starter ```md When the user needs an interactive runtime UI in the split canvas, create or reuse a `ui-layout-canvas` artifact, keep the live state in the artifact document, and open it with `artifact_open`. Use `ui_layout_*` only when the stored layout definition itself must change. If the same agent also supports inline or saved-layout responses, pair this instruction with a routing rule so the model chooses runtime canvas only when the user intent really requires a split-canvas session. ``` ## Runtime document example ```json { "kind": "ui-layout-canvas", "version": 1, "title": "Customer escalation review", "layout": { "source": "reference", "layoutId": "layout-customer-review", "layoutName": "Customer review" }, "state": { "mode": "transient", "values": { "customer": { "id": "cust-1", "name": "Acme Corp", "riskScore": 92, "nextAction": "Executive follow-up" } } } } ``` ## Example workflow User request: "Open a review workspace for the escalation and let me approve or reject the recommendation." Expected behavior: 1. The agent checks the conversation artifacts with `artifact_list_for_conversation` and reuses a matching `ui-layout-canvas` artifact when one already exists. 2. If not, it creates one with a layout reference or snapshot plus the initial `state.values`. 3. The agent opens the artifact in the side canvas. 4. When the runtime session changes, the agent updates the artifact document instead of rewriting the stored layout definition. The reopened personal-assistant conversation above shows the three v1 recovery surfaces together: the artifact selector label, the running-workflows rail for the current conversation, and the canvas status text. ## Tips - Use a layout reference when the runtime session should follow the latest saved layout definition. Gaia v1 does not add separate drift warnings, version pins, or rebase prompts for reference-backed runtime artifacts. - Use a snapshot when the current conversation should stay pinned to a specific layout version. - Put user-editable runtime data in `state.values`. - In personal-assistant channels, the running-workflows rail is scoped to active artifacts in the current conversation, not a cross-conversation queue. - Keep layout authoring and runtime state separate. Saved layouts live in **UI Layouts**; session values live in the artifact document. ## Troubleshooting - Canvas opens with no UI: confirm the artifact content is a valid `ui-layout-canvas` document and the layout reference is valid. - The canvas always starts a new session instead of reopening the current one: confirm `artifact_list_for_conversation` is enabled and the runtime canvas skill tells the agent to reuse matching artifacts first. - Runtime data looks stale: inspect the artifact with `artifact_read` and confirm the latest `state.values` were written. - The agent keeps modifying the stored layout by mistake: tighten the prompt so runtime sessions stay in the artifact flow unless the user explicitly asks to redesign the layout. --- # Scenario: Document upload, edit, and download workflow This scenario is for conversation-native document work: 1. user uploads a file 2. assistant edits it through saved revisions 3. user downloads the updated export ## Goal Support document editing without requiring an entity/UI Layout canvas. This flow uses conversation artifacts and tools directly in chat. If you specifically need a runtime `ui-layout-canvas` artifact instead of markdown, p5, or spreadsheet editing, follow [Scenario: Runtime UI canvas artifact workflow](#doc-conversations-scenarios-runtime-ui-canvas-artifact-workflow). ## Prerequisites 1. Complete the [agent configuration checklist](#doc-conversations-agent-config-checklist). 2. In config **General → File uploads**, set **Allow attach to model** = on. If the workflow is already configured but document editing still feels incomplete, start with **Delivery Management -> Overview** or ask Gaia for a **project setup diagnosis** so Gaia checks the runtime artifact bundle first. 3. Ensure required artifact tools are enabled: - `artifact_create` - `artifact_create_from_attachment` - `artifact_list_for_conversation` - `artifact_open` (recommended for split canvas editing) - `artifact_read` - `artifact_spreadsheet_mutate` (recommended for spreadsheet edits) - `artifact_update` - `artifact_export` Alternative: - Create the **document artifact editing** internal skill in **AI Agents → Skills → Internal**, then attach it to the agent config in the **Skills** tab. - That skill should sit alongside the same core tool bundle: `artifact_list_for_conversation`, `artifact_create`, `artifact_create_from_attachment`, `artifact_open`, `artifact_read`, `artifact_update`, and `artifact_export`. This skill is for markdown, p5, spreadsheet, PDF annotation, and presentation artifact workflows. Use the dedicated runtime UI canvas skill for `ui-layout-canvas` sessions. ## Step 1: Start conversation (optional upload) 1. Open a conversation in text or personal-assistant channel. 2. If you want to edit an existing file, click the paperclip. 3. Choose **Attach to model**. 4. Upload the document. 5. Gaia always mirrors supported uploads into conversation artifact storage so the canvas workflow remains available. When the active runtime supports the file type, Gaia also sends the file to the model in parallel; otherwise it falls back to artifact-only handling automatically. ## Step 2: Create artifact 1. Ask the assistant to start editing. 2. For new work (no upload), assistant calls `artifact_create`. 3. For uploaded files, Gaia usually creates the conversation artifact automatically after the upload finishes. The artifact will appear in the **Artifact** selector even if the canvas stays closed. 4. If no matching artifact exists yet, the assistant can still call `artifact_create_from_attachment`. 5. Confirm artifact creation succeeded and revision history started. For PDF annotation workflows, the assistant should call `artifact_create_from_attachment` with `importMode: "pdf-annotation"`. This keeps the uploaded PDF as an immutable source revision and stores annotation state separately as `pdf-annotations-json`. Omit that mode for the normal PDF-to-markdown editing path. Once a PDF annotation artifact exists, assistants can use `artifact_pdf_annotation_list`, `artifact_pdf_annotation_add`, `artifact_pdf_annotation_update`, and `artifact_pdf_annotation_delete` to manage highlight and note annotations. Users can also place note markers directly on the PDF page, drag highlight boxes over the page, and update or delete saved annotations from the PDF canvas side panel. These paths save annotation revisions; they do not rewrite the uploaded PDF. For PowerPoint workflows, upload a `.pptx` file or ask the assistant to create a new deck. Gaia stores presentation artifacts as `slides-json`: an editable canonical deck with slides, text boxes, basic shapes, lines, images, locked fallback elements, notes, and import warnings. PPTX import and folder preview use bounded OOXML extraction for slide background colors, simple text boxes, basic shapes, connectors, and embedded images. Charts, tables, grouped objects, animations, master layouts, and advanced effects may be simplified or omitted with a visible warning. The original PPTX stays available as source context, while the editable deck opens in the canvas and exports back to `.pptx`. ## Step 3: Apply edits 1. Ask for targeted edits (sections, tone, structure, etc.). 2. If artifacts exist for the conversation, use the **Artifact** selector at the top of the conversation to choose one to show (or **None** to hide the panel). 3. Assistant can open split canvas with `artifact_open` for side-by-side editing. 4. Assistant reads current content (`artifact_read`) and writes updates. - For spreadsheets, prefer `artifact_spreadsheet_mutate` for cells, formulas, styles, rows, columns, and sheet operations. - For presentations, update the full `slides-json` document or open the canvas so the user can edit supported slide text, shapes, positions, sizes, and slide order directly. - Use `artifact_update` when you intentionally need to replace the full canonical artifact content. - Assistant edits are based on the latest saved revision. If Gaia reports a revision conflict, review the newest revision in **Revisions** and retry from that saved state. 5. For `p5-js` artifacts, the canvas opens in read-only preview by default. When opened in editable mode, it shows the live sketch preview at the top and code editor at the bottom. 6. Use the **Revisions** button in the artifact canvas to inspect history: - select a revision on the left, then open the **Current revision** tab for read-only markdown preview - pick two revisions, then open the **Diff** tab to compare highlighted markdown changes - merged saves are labeled in the revision list so you can see when Gaia reconciled concurrent saved edits 7. Repeat until the draft is approved. For spreadsheet analysis, agents can use `artifact_spreadsheet_query` to fetch sheet summaries, exact A1 `range_read` coordinate cells, filtered row previews, grouped totals, multi-column aggregations, distinct counts, medians, percentiles, and date-bucketed analysis without streaming raw workbook JSON back through the model. For large row or grouped result sets, continue with `window.nextOffset`. Spreadsheet canvas examples: ## Step 4: Handle concurrent edits Gaia uses saved revisions instead of explicit lock/unlock controls: 1. If the canvas has unsaved local changes, save them before asking the assistant to apply edits. 2. Assistant writes use the latest saved revision as their base. 3. If another saved revision landed first, Gaia attempts a safe merge automatically. 4. If Gaia cannot merge the revisions safely, it keeps the current head unchanged and asks you to review the latest revision before retrying. 5. If a newer saved revision arrives while your local draft is still unsaved, Gaia keeps your local draft visible and shows a banner that a newer saved revision is available. 6. Use **Review changes** to compare **Current draft** against the **Latest saved revision**. 7. From that review flow, choose one of these paths: - **Combine both versions** if Gaia can safely merge your unsaved draft with the assistant's newer saved revision - **Keep only my draft** if you want to continue with your current local text and ignore the assistant's newer text in the editor - **Use latest saved version** if you want to discard the unsaved local draft and switch to the assistant's newer saved revision - **Decide later** if you want to keep editing and return to the review flow afterward ## Step 5: Export and download 1. Ask the assistant to export. 2. Assistant calls `artifact_export` with the requested format. 3. User downloads from the returned URL. Export is available only when the artifact is editable in canvas mode. ## Format notes - Import support: `PDF`, `DOCX`, `ODT`, `ODP`, `MD`, `TXT`, `CSV`, `XLSX`, `ODS`, `PPTX` - Editable canonical formats: `markdown`, `p5-js`, `grid-json` (spreadsheets), `slides-json` (presentations) - PDF annotation artifacts use `pdf-annotations-json`, open the immutable source PDF in canvas, render saved note/highlight overlays, and support page-click note placement plus drag-created highlight boxes. - Presentation artifacts use `slides-json`, open in a slide canvas for supported text, background, shape, connector, and image edits, preserve unsupported source content as visible import warnings or locked fallback warnings, and export to `PPTX`. - Export support: - markdown artifacts: `DOCX`, `MD` - p5 artifacts: `JS` - spreadsheet artifacts: `XLSX` (default), `CSV` (active sheet export) - presentation artifacts: `PPTX` - Spreadsheet fidelity tier: high-fidelity practical. Existing workbook features are preserved where possible during XLSX exports, but advanced features can degrade in edited structural regions. - No entity is required for this scenario. ## Variations - PDF input to DOCX output: import as source, edit in canonical form, export DOCX. - Markdown input/output: upload `.md`, iterate, export `.md`. - Spreadsheet input/output: upload `.csv` or `.xlsx`, edit in canvas across sheets, apply structured spreadsheet mutations in conversation, export `.xlsx` or `.csv`. - Presentation input/output: upload `.pptx` or create a new `slides-json` deck, edit supported text and shapes in canvas, export `.pptx`. --- # Give feedback on a reply The **Give feedback** dialog lets you annotate any assistant message with notes that travel with the conversation record. Feedback is threaded per message, so multiple teammates can add comments and see each other’s entries. The same assistant-message footer can also expose quick **thumbs up/down** reactions and a **read aloud** control when the channel enables them. ## When to use it - The response is unclear, incorrect, incomplete, or off-tone. - You want to flag good behavior for analytics (“Great summary, keep this style.”). - You need to capture extra context so the team can improve prompts or tools. ## Who can use it? Any authenticated project member with conversation access can add feedback unless your organization has disabled the feature. Users with **Manage conversations** permission can also triage conversations with review states and tags. ## Open the dialog 1. Hover over the assistant message. 2. Click the feedback icon in the assistant-message footer. ## Quick reactions - Click **Thumbs up** when the reply is useful and should count as positive feedback without adding a note. Gaia marks the thumb as active and shows a short thank-you toast. - Click **Thumbs down** when the reply is poor. Gaia marks the thumb as active and opens a structured feedback dialog. - Click the same thumb again to remove that rating. - Thumb reactions are separate from note feedback. The written-feedback icon can be hidden per channel without disabling thumbs-down reasons. The dialog keeps showing only written notes. - When **Read aloud** is enabled on the channel, click the megaphone icon to generate spoken audio for the assistant reply. ## Structured dislike flow 1. Click **Thumbs down** in the assistant-message footer. 2. In the dialog, pick one of the structured reasons: - **Wrong information** - **Not relevant** 3. Gaia saves the selected reason against that assistant message and shows the channel-configured confirmation toast. 4. Optional: click the channel-configured handoff button if it is enabled for this channel. Gaia sends the button text as a normal user message, so handoff rules can handle it the same way they handle a typed request. 5. Close the dialog when you are done. The negative thumb stays selected until you remove it manually. ## Submit feedback 1. Type your comments in the text area. Be specific—call out the sentence, number, or tool output that needs attention. 2. Optional: Suggest how to fix it (“Use the Renewal Policy data instead of Customer history”). 3. Click **Save**. Your comment is appended to the message thread with your name and timestamp. The message shows a filled feedback icon so teammates know feedback exists. ## Delete feedback 1. Open the same message's **Give feedback** dialog. 2. In the feedback thread, click the trash icon next to the entry you want to remove. 3. Confirm the entry disappears from the thread. The filled feedback icon remains as long as at least one entry still exists for that message. ## Feedback and review state are independent - Notes and thumb reactions are end-user feedback signals. Adding, changing, or removing them does not change the conversation review state or decision. - Authorized reviewers explicitly move conversations through **For review**, **In review**, **In progress**, and **Addressed** from the conversation header. - An **Addressed** conversation remains addressed when new feedback arrives. Use feedback filters and counts to find new signals, then reopen the review explicitly when triage determines that more work is required. - In the project conversation view, the **Review** section also keeps running counts for assistant bubbles with thumbs up, thumbs down, and written feedback. - Use the **Previous** and **Next** buttons in that same **Review** section to jump between assistant bubbles that already have feedback, while the position label shows where you are in the reviewed set. ## Real-life example > During onboarding, a compliance analyst noticed the agent skipped the latest policy clause. She clicked **Give feedback**, wrote “Missing 2024 clause about GDPR transfer,” and saved. Later that day the admin reviewed the note, updated the [AI Agent prompt](#doc-agents), and confirmed the fix in an [eval turn review](#doc-evals-dialogs-human-review). ## Tips - Reference external tickets or URLs if your process allows it. Admins can search feedback text when auditing. - Pair feedback with the [Timeline](#doc-conversations-dialogs-timeline) to see which tools ran during the turn. ## Troubleshooting - **No feedback icon:** Your role might not allow feedback, or the feature was disabled. Ask an admin to confirm your access. - **Save keeps spinning:** Check your connection. Refreshing the page usually restores any draft feedback. - **Feedback vanished after reopening:** Refresh once. If it still does not appear, verify you're opening the same conversation and message turn, then contact your admin. ## Keyboard shortcuts - `Esc` closes the dialog. - `Tab` / `Shift+Tab` move between the editor and action buttons. --- # View a conversation timeline The timeline dialog reveals the exact sequence of events for each turn: tool calls, handoffs, duration, and token or cost usage. ## When to open it - A response feels slow or timed out—you want to see which step took longest. - You’re auditing a regulated workflow and need to show which data sources were accessed. - You’re tuning prompts and want to compare how different configurations behave under the same input. ## Who can open the timeline? Project admins always see the **Timeline** button. Maintainers may also see it if your policy allows. Viewers typically do not. ## Open the dialog 1. In the conversation header, click **Timeline** (clock icon). 2. The dialog expands so you can focus on the chart without distractions. ## Explore the data 1. Each row represents a conversation turn. Bars show elapsed time; colors indicate assistant vs. tool work. 2. The **waterfall visualization** shows the precise sequence of operations, including when the first token was received from the model. 3. Hover a bar to see timestamps, token counts, cached tokens, cost, and **first streaming token time** for that step. 4. Use your mouse wheel, trackpad pinch, or on-screen controls to zoom in and out. 5. Switch between turns using the list on the left side of the dialog. ## Real-life example > After enabling a new CRM connector, the support lead noticed response times jump to 18 seconds. The timeline showed the initial data lookup was fast, but a downstream sync step took 12 seconds. They raised the issue with the integration team and temporarily disabled the extra action in [AI Agents](#doc-agents). ## Tips - Long red bars usually indicate errors. Click the bar to read the details. - When a logical deployment pool is involved, pair the timeline with the assistant reply's **Inside Info → Model routing** block. The timeline explains when the AI work occurred; Model routing explains which target was tried, provider retries within that target, whether Gaia failed over, and the final outcome. - Pair the timeline with [Update Statistics](#doc-conversations-dialogs-update-statistics) after bulk changes so your dashboard reflects the newest data. ## Troubleshooting - **Timeline button missing:** Make sure you’re viewing a conversation (not voice-only) and that you have admin permissions. - **Chart is empty:** The conversation needs at least one assistant response. Send a message and try again. - **Zoom controls not responding:** Click inside the chart first; some browsers block scroll actions until the chart has focus. ## Keyboard shortcuts - `Esc` closes the dialog. - Arrow keys scroll horizontally. Hold `Shift` for faster movement. --- # Update project statistics Use the **Update Statistics** dialog to rebuild the aggregate numbers that power the [Dashboard](#doc-dashboard) and related analytics. It refreshes conversation totals, token usage, and other derived metrics in one batch job. ## When to run it - The dashboard looks stale after importing historical conversations. - You bulk-edited records and want token counts and costs to reflect the change. - You just migrated a project and need to clean up empty conversations or refresh derived analytics. ## Who can run it? Only **project admins** see the **Update Statistics** button in the Conversations and Dashboard headers. ## Start the update 1. Click **Update Statistics**. 2. Review the summary so you know which metrics will be recalculated. 3. Select **Start Update**. 4. Keep the tab open. The dialog shows a progress bar and a live log of steps so you can monitor progress. 5. When you see “Done” and the bar reaches 100%, close the dialog and refresh the dashboard to confirm the new numbers. ## Real-life example > After importing six months of legacy tickets, the ops team ran **Update Statistics**. The progress log walked through the dashboard rebuild and empty-conversation cleanup. Four minutes later the dashboard reflected the spike in historical usage. ## Tips - Large projects may take several minutes. Consider running during off-peak hours. - You can leave the dialog open while working elsewhere; it keeps updating in the background. If you close it, the job continues and a toast confirms completion. - Conversation assessments are managed through agent post actions, not this dialog. ## Troubleshooting - **Button missing:** Make sure you have admin rights and that you’re on the Conversations or Dashboard page (not the voice-only view). - **Log stops updating:** Check your network connection. Reopening the dialog reconnects to the running job. - **Errors in log:** Each line includes a timestamp. Share it with your admin or engineering partner so they can investigate. --- # Start a voice conversation Voice mode lets you talk naturally with your agent. You speak, the assistant replies out loud, and the full transcript stays in Conversations for later review. ## Requirements - A Chromium-based browser (Chrome, Edge) or Safari 16.4+ with microphone access enabled. - A project that includes a voice-ready agent (admins configure this in [AI Agents](#doc-agents)). - A transcription model configured in the agent Voice tab so Gaia can display live user transcripts. - Either a realtime voice model, or an Azure Speech transcription model paired with a primary response model and TTS model. - Stable internet (5 Mbps or higher recommended) and a quiet environment. ## Start a session 1. In Conversations, click **New → Voice conversation**. 2. Allow microphone access when prompted. 3. The voice controls announce their current state. Before the session is ready, Gaia reports setup or connection status. Once it is ready, click the microphone button to start recording. 4. Speak at a natural pace. The assistant streams replies, plays synthesized audio through your speakers or headset, and keeps the transcript in the same accessible message log as typed conversations. 5. Click the stop icon to end the turn. Gaia announces recording, welcome playback, and reconnecting states as they happen, so you can tell whether the session is listening or responding. ## During the call - The configuration bar remains available so you can switch agents or languages mid-session. - The transcript updates after every turn, giving you a searchable text record powered by the configured transcription service. - Agent responses are converted to natural-sounding speech using text-to-speech (TTS), including Azure Speech TTS when that model is selected in the agent Voice tab. - Voice buttons expose spoken names for start, stop, and setup states, so screen readers can identify the current action without relying on icon shape alone. - When the system evaluates handoffs or tool usage, it may briefly acknowledge the pause (for example, “Give me a moment to check”) before responding. - A status indicator shows the realtime connection; if it drops, the session automatically falls back to uploading audio and streaming the response. ## Real-life example > A field technician in a warehouse started a voice conversation on a tablet and asked, “What’s the maintenance checklist for pump P-204?” The agent read the checklist aloud and opened the relevant record on the side panel. She confirmed completion without typing a word. ## Tips - Use a USB headset to reduce echo and keep both hands free. - If you switch browsers, re-grant microphone permissions (look for the camera icon near the address bar). - For longer sessions, keep an eye on network quality. The status indicator turns orange when latency rises. ## Troubleshooting - **Redirected to text conversations:** The agent you selected doesn’t support voice yet. Ask an admin to assign either a realtime-capable model, or Azure Speech transcription together with primary response and TTS models. - **Microphone blocked:** Click the browser permission icon, allow microphone access, then refresh. - **No transcript appears:** Ensure the agent’s Voice tab includes a Transcription Model. Without it, realtime sessions cannot transcribe user speech. For Azure Speech, confirm the model locale matches the expected spoken language. - **No assistant audio:** Check your output device and make sure autoplay isn’t blocked. Clicking the microphone button counts as the interaction most browsers require. - **Dropped connection:** The UI displays “Reconnecting.” Move closer to your router or switch to wired internet and try again. ## Privacy Voice turns are stored with the conversation, including audio usage and timing. Follow your organization’s retention policy and let users know when recording. --- # Gaia Gaia is your always-on in-product assistant. Click the lightning icon (⚡) in the left sidebar to open a side panel that can answer questions, jump to pages, and perform quick actions for you. ## What it can do - **Answer “how do I” questions.** It understands the structure of the platform and can walk you through tasks (“How do I add a pipeline?”). - **Ground answers in the right documentation.** It uses the User Guide for feature-level UI steps and the Handbook for sequencing, operating model, and build methodology. - **Jump to pages.** Ask it to open Data Model entities, Settings tabs, or UI layouts and the main view will navigate for you. - **Understand what you're viewing.** The assistant knows what page or resource you're currently looking at. Ask questions like "Tell me about this entity" or "What are the properties of this agent?" without needing to specify which one. - **Run quick diagnostics.** Request a stats refresh or guidance for entity schema sync without leaving your current screen (schema sync is applied via **Sync Database** / **Sync Graph** on the entity page). - **Work with governance records.** Ask it to list, inspect, draft, review, approve, publish, or retire governance risks, policies, controls, obligations, classifications, regulatory updates, explainability artifacts, and related evidence links. - **Draft delivery evidence.** Provide the artifact instructions and it can suggest titles, descriptions, and section responses you can paste into the evidence dialog. - **Coordinate full build work.** For higher-level requests, Gaia can move from planning into execution and verification using Delivery Process, Tasks, Milestones, Evals, governance evidence, document folders, and UI layouts as the working system of record. - **Diagnose broad setup gaps.** Ask questions such as "what is missing", "why is this agent weak", or "what should I fix first" and Gaia checks the live project overview across agent runtime, channels, knowledge, governance, evals, and delivery, then groups findings by owning surface, evidence, priority, and recommended next action. For agent runtime, channel, and knowledge issues, it can also inspect active config shape, model/tool/artifact-skill/validator/post-step counts, runtime canvas and document-artifact tool bundles, channel capability bindings, upload-routing rules, extractor and workflow references, document folders, indexing state, and unresolved knowledge links before suggesting whether the fix should be a project-spec proposal, manual UI repair, eval, governance, delivery, documentation, or no-change follow-up. When a project-spec proposal is appropriate, Gaia generates the smallest RFC 6902 patch against the current spec, shows a human-readable review card and migration plan, waits for approval before apply, then reruns readiness checks for the affected sections. - **Design new projects directly from Teams.** On the Teams page, use the bottom-right **Ask Gaia** button to open the team-scoped design panel. Gaia uses the selected team as grounding context so you can reason through a new system before any project exists. It keeps the architecture in a persisted design session, compiles the supported subset into preview/spec artifacts, surfaces the latest unresolved design questions in the panel, and waits for approval before provisioning. - **Bootstrap and evolve projects through project specs.** Ask Gaia to scaffold a new project from a brief or to revise a live project after testing conversations. Gaia captures the current canonical project spec, prepares the smallest reviewed patch for the requested change, previews the resulting diff, and waits for explicit approval before it applies managed configuration changes. - **Run generative Plan-stage intake.** It drafts template content from your freeform brief, asks only targeted follow-up questions, then shows preview before explicit save. - **Extract from discussions on demand.** You can ask it to synthesize one selected discussion topic and comments into a draft, suggest section text, then ask only targeted follow-up questions before save. - **Manage evals.** Ask it to create eval task sets, draft tasks, generate security evals, create graders, start runs, and summarize run metrics. - **Analyze linked folder files.** In conversations linked to a shared folder, it can search indexed documents for evidence and answer CSV or Excel questions such as workbook structure, grouped totals, row previews, and aggregations. - **Work with canvas artifacts.** It can open generated documents, spreadsheets, PDF annotation artifacts, and presentation decks in the conversation canvas, then export trusted download controls instead of relying on model-written file links. - **Administer document folders directly.** Ask it to create folders, attach conversations, share access, inspect indexing, reindex, or manage folder-scoped memory without leaving chat. - **Maintain a separate context.** It keeps its own assistant history inside the current project so you can experiment without affecting customer-facing agents. ## Start a session 1. Click the ⚡ icon on the left sidebar. 2. The Gaia pane slides open. Use the microphone button for voice or type directly into the input box. 3. Ask a question—the response streams just like a regular conversation. 4. Need more space? Click the fullscreen button in the assistant header. 5. Want a hard copy? Click the print button in the assistant header to print the current thread. ## How Gaia handles bigger requests When the request spans multiple Gaia surfaces, Gaia uses a `Plan -> Execute -> Verify` pattern: This is a staged conversation pattern, not a [workflow graph](#doc-data-model-workflows). Use [Protocols](#doc-agents-protocols) when the agent itself should work in visible stages, and use workflow graphs when the underlying evidence-gathering, routing, or approval path should run as reusable automation. 1. **Plan:** Gaia creates or resumes a delivery process, captures the brief, assumptions, and intended outputs as delivery evidence, and when project setup is involved it prepares the reviewed project-spec patch before anything changes. 2. **Execute:** Gaia applies the approved project changes, such as entities, workflows, UI layouts, document folders, artifacts, tasks, and milestones. For project configuration work, this happens through the approved spec or migration plan rather than one-off hidden edits. 3. **Verify:** Gaia runs the relevant eval, workflow, browser, folder-indexing, or evidence checks and records readiness or gaps before it concludes the task. This keeps the conversation as your command channel while the project truth stays inside Gaia’s delivery, evidence, task, milestone, and governance records. When staged execution is active and your role can view agent configurations, the main project **Conversations** view also offers an **Execution** toolbar toggle. It reveals a compact execution summary with the current stage, waiting-for-user state, the latest checkpoint summary, and any typed checkpoint outputs captured for that stage. Expand **Review details** when you need the full checkpoint. If Gaia is waiting for confirmation, reply with an explicit approval such as "continue" or "approved, move on". If the stage is blocked, reply with the missing input or evidence. **Cancel** and **Restart** remain in **AI Agents -> Agent Configuration -> Execution**. ## Real-life example > While configuring a new project, an admin said, “Show me the IncidentReport entity,” and Gaia opened the entity page directly. After making edits, they asked, “Create a new conversation with the orchestrator,” and Gaia started a test thread without leaving the current page. > A user was viewing the Customer entity properties and simply asked, "What's the data type of the email field?" Gaia automatically understood which entity was being referenced and provided the answer without needing to specify "in the Customer entity." > After a pilot run exposed a weak escalation path, the product manager asked Gaia to add a specialist review agent and keep the live conversation history intact. Gaia showed the proposed project-spec diff first, then applied the approved migration in place. ## Tips - The assistant follows your project’s default language. Change the language in [Project settings](#doc-settings) if you need another locale. - Use the left assistant rail to start a **New** conversation when you switch topics. On desktop the rail stays docked and can collapse to a slim logo-and-avatar strip; on mobile the same tools stay in the slide-over drawer. - When a conversation is linked to a shared folder, the assistant header shows that folder so you can re-enter the folder context without searching for it again. - For linked folders, ask normal file-grounded questions first. When the answer should come from a spreadsheet in that folder, describe the workbook, sheet, metric, grouping, or filter you need rather than pasting the raw file contents. - Gaia remembers your scroll position in the current thread when you navigate away and come back. - When Gaia navigates to a new page, the in-app help pane updates with the matching article automatically. - If you ask for the handbook, Gaia can open handbook pages in the same in-app documentation surfaces used for the User Guide. - While editing a modal dialog, use the **Help** (book) or **Assistant** (sparkles) buttons in the dialog header to open a side utility panel without closing your work. - For governance work, name the record type and intent clearly, such as “list open obligations”, “review this policy”, or “publish the approved control”. - For delivery planning templates, ask Gaia to "start intake" and answer one question at a time. Ask for "preview" before "commit". - To draft from an existing delivery discussion, ask Gaia to list topics, select one, and run discussion extraction. It will generate a first pass and then ask only missing-field follow-ups before preview/commit. - On **Teams**, pick the target team first, then open the bottom-right **Ask Gaia** button only when you want Gaia to reason through a new project architecture, keep a durable pre-project design session, review the latest unresolved questions in the panel, and provision only after approval. This Teams-page panel is not the entry point for changing an existing live project. - For new projects where you already know you want a single starter scaffold immediately, use **Ask Gaia** in the create-project dialog. - For live projects, open the project first, ask Gaia for the target change, and review the diff before you approve. This is the existing-project path and the safest way to evolve configuration without losing runtime data. ## Troubleshooting - **Gaia doesn’t open:** Check your permissions. Access may be limited based on your project role. - **Gaia or Help pane is not clickable behind a dialog:** Use the dialog header utility buttons (book/sparkles) to open them in the side utility panel. - **No navigation happened:** Try phrasing the request more clearly (“Open the Data Model → Entities page for Customer”). - **Gaia answered too narrowly to a broad quality complaint:** Ask for a **project setup diagnosis** or ask "what is missing in this project?" Gaia will start from the cross-resource overview instead of guessing at one config. - **Audio unavailable:** Voice mode needs microphone permissions just like [voice conversations](#doc-conversations-dialogs-voice-conversation). --- # Memory Workspace The **Memory** workspace gives builders and project admins one place to inspect shared project memory, review pending memory proposals, and manage lifecycle actions such as suppression, correction, and expiry. Open it from the **Memory** tab in the **Conversations** workspace at `/projects/[projectId]/tools/conversations/memory`. ## What this workspace is for Use the Memory workspace when you need to: - review durable project memory that Gaia can reuse across conversations - confirm or dismiss agent-proposed shared memory - inspect suppressed, expired, or superseded records - track forget requests before approval or execution This workspace is intentionally read-first. It exposes project-scoped shared memory and governed lifecycle actions without turning every conversation into a raw memory debugger. ## Permissions The Memory workspace is intended for builders and admins. You normally need one of these project permissions: - `modify-conversations` - `modify-project-settings` ## Tabs ### Shared memory The **Shared memory** tab shows active project-scoped memory records that remain eligible for default retrieval. Use it to: - search current shared memory by key, title, value, or source - add a new shared memory record - inspect provenance and source conversation links - correct a record when the current version is wrong - suppress or expire a record when it should stop influencing retrieval ### Proposals The **Proposals** tab shows shared-memory proposals that still require review. Use it to: - inspect what an agent proposed - confirm the proposal and persist it as durable shared memory - dismiss the proposal without saving it If you arrive here from a conversation, Gaia can pre-filter the queue to proposals sourced from that conversation. ### Lifecycle The **Lifecycle** tab groups: - inactive records such as suppressed, expired, or superseded memory - forget requests that are waiting for review or execution Use it to: - inspect why a record became inactive - reactivate a suppressed record - correct a superseded project record - approve a forget request - execute an approved forget request ## Conversation surface When a builder is inside a conversation, Gaia may show a **Remembered context** panel near the conversation controls. That panel can show: - conversation-level thread memory already stored for the current conversation - pending private memory proposals sourced from that conversation It also links back to the Conversations-owned Memory workspace for broader review. ## Common tasks ### Add shared memory manually 1. Open **Conversations**. 2. Switch to **Memory**. 3. Stay on **Shared memory**. 4. Click **Add shared memory**. 5. Enter a title and value. Add a key when you want a stable lookup key. 6. Save the record. ### Review a proposal 1. Open **Conversations**. 2. Switch to **Memory**. 3. Switch to **Proposals**. 4. Select the proposal. 5. Choose **Confirm** to persist it or **Dismiss** to reject it. ### Stop a record from being used 1. Open **Conversations**. 2. Switch to **Memory**. 3. Select the record in **Shared memory**. 4. Choose **Suppress** if you may want to reactivate it later. 5. Choose **Expire** if the record should become inactive because it is no longer valid. ### Correct a bad record 1. Open **Conversations**. 2. Switch to **Memory**. 3. Select the record you want to fix. 4. Choose **Correct**. 5. Save the corrected value. Gaia keeps the old record visible in lifecycle history as a superseded record and creates a corrected successor. ## Related guides - [Conversations](#doc-conversations) - [Document Folders](#doc-conversations-document-folders) - [Governance State & Memory](#doc-governance-state-memory) - [Audit Trail](#doc-audit) --- # AI Agents Use the **AI Agents** workspace to design how each assistant behaves. Every agent blends a model, prompt guidance, tool access, and guardrails so you can tailor conversations to different audiences. ## Related pages - [Agent Configuration](#doc-agents-configs) - [Model Tier Routing](#doc-agents-model-tier-routing) - [Code execution](#doc-agents-code-execution) - [Bridge Agent Settings](#doc-agents-live-chat-bridge-agent) - [Fragments](#doc-agents-fragments) - [Protocols](#doc-agents-protocols) - [Guardrails](#doc-agents-guardrails) - [Skills](#doc-agents-skills) - [Engineering reference: TypeScript tools](#doc-agents-typescript-tools) - [Conversations](#doc-conversations) ## Who can access this page? Only **project admins** and **team admins** see the star icon that opens AI Agents. If it’s missing from your sidebar, ask an admin to adjust your role. ## What you can configure - **Orchestrator agent:** Choose the default agent that greets users and hands off requests. You can open a visual map to check whether your handoff rules make sense before saving. - **Model tier routing:** Use orchestrator handoff rules to route prompts automatically to tier-specific agents or configurations such as T1, T2, and T3. See [Model Tier Routing](#doc-agents-model-tier-routing). - **Code execution:** Enable provider-managed code execution or code-interpreter capability when the selected model supports it. See [Code execution](#doc-agents-code-execution). - **Agent admission guardrails:** Configure max requests per minute, max estimated tokens per minute, and estimated tokens per request on any agent. Orchestrators additionally expose a time limit and the legacy per-turn token cap. Request and estimated-token windows protect shared provider capacity; AI FinOps budget controls remain cost-based in the shared budget editor. When admission is limited, Gaia returns the retry time and binding constraint so clients can wait and retry. - **Agent configurations:** Each agent can have multiple configurations with different settings, models, prompts, and tool access. See [Agent Configuration](#doc-agents-configs) for detailed guidance. - **Execution protocols:** Agent configurations can optionally add visible staged execution flows such as `Plan -> Execute -> Verify` for governed work. - **Protocol registry:** Save reusable protocol templates in **Protocols** so multiple agents can start from the same staged workflow and bundled starter skills/tools. - **Agent runtime:** Use Gaia's native runtime for AI agents or the Live Chat Bridge runtime for agents that own external live-agent handoff. - **Bridge Agent runtime:** Configure live chat provider behavior, external actors, routing, and bridge hooks for agents that own live-agent handoff. See [Bridge Agent Settings](#doc-agents-live-chat-bridge-agent) for field-level guidance. - **Agent prompt & tone:** Fine-tune the system instructions, add warmup messages, and choose tone presets so the assistant speaks in the right voice. - **Allowed tools:** Enable or disable tools per agent to control which actions they can run during a turn. - **MCP server registry:** Define remote HTTP/SSE MCP servers once, then attach them to agent configurations for runtime tool discovery. - **Guardrail registry:** Define reusable conversation-scope, instruction-confidentiality, and response-validation controls, then attach exact versions in agent configurations. - **Skill registry:** Define reusable skill bundles once, then selectively enable them in agent configurations. - **Post-steps:** Configure post-turn processing (presets or custom AI/TypeScript steps) for scoring, topic extraction, or memory consolidation. - **Cross-project reuse:** Use **Copy from project** on the agents list when you want to bring an agent into the current project together with its active handoff-linked configs, fragments, skills, and registry tool dependencies. - **Safety levers:** Set moderation thresholds or add fallback messages to keep responses on policy. - **Fragments registry:** Reuse shared prompt snippets across agents for consistent guidelines. Each fragment has a simple version label (default `1.0`) so you can track iterations. Use the **Fragments** tab to browse the registry, start from built-in templates, and branch variations with **Duplicate**. ## Step-by-step 1. Open **AI Agents** from the sidebar. The list on the left shows every agent in your project. 2. Select the agent you want to adjust. The configurations panel on the right shows all versions for that agent. 3. Click the pencil icon next to a configuration to open the configuration editor in a new page. 4. Update prompts, models, tool access, post-steps, execution stages, safety settings, handoff rules, or voice settings using the tabs. See [Agent Configuration](#doc-agents-configs) for detailed tab descriptions. 5. Click **Save** to apply your changes, or **Cancel** to return to the agents page without saving. 6. Select **Diff/Merge** from the agents page if you want to compare two configurations side-by-side. Choose the agent and version for each side, then transfer individual fields or reset them back to their original values. 7. Use **Copy from project** when you want to reuse an agent from another project. Gaia previews the related active configs and asks you to approve any compatible target-tool mappings or enter a new tool version before it copies the bundle. 8. Use the **Fragments**, **Protocols**, **Guardrails**, and **Skills** tabs when you want to manage shared registries outside an individual configuration. 9. Head to [Conversations](#doc-conversations) and start a quick test turn to see the new behavior in action. ### Deleting a configuration Gaia only allows deleting agent configurations that are **Inactive**. If a configuration is active, the **Delete** button is intentionally hidden. If the configuration has been used, Gaia may also delete related records (shown in the confirmation dialog), such as **conversations**, **eval conversations**, and **evaluation runs** that depend on that configuration. To delete a configuration: 1. From **AI Agents**, open the configuration you want to delete. 2. If it is active, make it inactive: - Toggle **Is active** off and **Save**, or - Activate a different configuration for the same agent (which automatically deactivates the current one), then **Save**. 3. Re-open the now-inactive configuration. 4. Click **Delete** and confirm the action if prompted. Review the confirmation dialog carefully—deletes are permanent. ### Diff/Merge basics - **Launch the dialog:** Click **Diff/Merge** from the configuration toolbar. The dialog opens with the active version on the left and the most recently edited version on the right by default. - **Pick what to compare:** Each side lets you choose any agent and saved version. Active versions are marked so you do not overwrite them by mistake. - **Review changes:** Differences are grouped by topic (prompts, tools, handoff rules, fragments, models). Expanding a row shows the old and new values with highlights for deletions and additions. - **Copy or reset values:** Use the arrow buttons to copy a field from one side to the other, or the undo/redo icons to revert a field back to the original saved value. - **Save deliberately:** Saving affects only the side you modified. If you edit both sides, save each one separately so the right version stays in sync. ## Real-life example > A customer support team created two agents: a friendly orchestrator and a billing specialist. They enabled the billing tool only for the specialist and added a rule that routes invoice questions there. After saving, they opened a conversation, asked _“Can I download last month’s invoice?”_, and watched the orchestrator hand off automatically. ## Tips - Use the **Duplicate** button (shown when viewing a configuration) to create a snapshot before making experimental changes. Gaia no longer auto-duplicates on save, so you control when versions are preserved. - Need to restore a complex change? The **Diff/Merge** dialog lets you pull back just the pieces you need instead of rolling back the entire configuration. - The **Visualize agents** button opens a diagram that shows handoffs, tool access, and active versions at a glance. - Cross-project copy is best for bootstrapping a similar workflow in a new project. If Gaia suggests a compatible target tool, confirm the mapping only when the parameter contract matches the behavior you want to preserve. - Keep agent descriptions clear—they appear in dropdowns across Gaia, including voice and evaluation workflows. - After major changes, consider running [security tasks](#doc-evals-dialogs-generate-security-evals) to confirm policy adherence. ## TypeScript tools (engineering reference) If your agent configuration enables TypeScript tools, see the exact handler signature, inputs/outputs, and available helpers: - [Engineering reference: TypeScript tools](#doc-agents-typescript-tools) ## Troubleshooting - **“Save failed” toast:** Check for missing required fields or confirm you still have admin access. - **Agent missing in conversations:** Make sure the configuration you edited is marked active so it appears in the conversation switcher. - **Delete not available:** The configuration is active. Deactivate it (or activate a different configuration) and save—**Delete** only appears for inactive configurations. --- # Model Tier Routing Use model tier routing when one published assistant should choose between several model tiers automatically instead of asking the user to pick a model manually. This pattern uses normal Gaia agent orchestration: 1. Create one orchestrator agent that receives the user turn. 2. Create one specialist agent or active configuration for each submitted tier, such as `T1 Flagship`, `T2 Balanced`, and `T3 Efficient`. 3. Assign the submitted model for each tier in that tier's active configuration. 4. Add handoff rules on the orchestrator so Gaia routes each prompt to the right tier before answer generation. 5. Validate the route from conversation details, behavior traces, and AI usage records. When the project exposes configurations or agents labelled `T1`, `T2`, and `T3`, the conversation header also shows a **Model tier** selector. Use that selector for manual reviewer tests that must prove a visible chat-level tier choice. Automatic routing still uses the orchestrator handoff rules described below. ## When to use it Use this setup when a contract, governance policy, or cost policy requires a visible routing policy such as: - route complex research, legal, scientific, or multi-document synthesis requests to `T1`; - route normal drafting, summarization, and analysis to `T2`; - route short classification, rewrite, extraction, or FAQ turns to `T3`; - keep restricted or high-risk prompts on an approved tier only; - preserve logs showing which agent/config/model answered the turn. ## Build the tier agents 1. Open **AI Agents**. 2. Create or choose the orchestrator agent that owns the channel. 3. Create three specialist agents, or three clearly named configurations, for the submitted tiers. 4. Open each tier configuration and set: - **Name/Persona** to the tier label, for example `T1 Flagship`. - **Model** to the exact model submitted for that tier. - **Fast Model** only when that tier needs quick checks before the main answer. - **Tools** to the capabilities allowed for that tier. - **Validators** to any tier-specific grounding, safety, or evidence checks. 5. Save and activate the configuration that should serve that tier. Keep the tier labels identical to the names used in the tender model list, pricing form, and compliance form. ## Add the routing policy Open the orchestrator configuration and add **Handoff** rules in policy order. Use a **Text condition** rule when the routing policy is readable and stable. Example tier policy: ```text Route to T1 Flagship when the request needs multi-step reasoning, deep research, legal or policy synthesis, high-stakes accuracy, multi-document comparison, or a final answer with citations across several sources. Route to T2 Balanced when the request needs normal drafting, summarization, translation, analysis, coding help, or document-grounded answers that are not high risk. Route to T3 Efficient when the request is short, low risk, and mostly extractive, such as grammar cleanup, short classification, simple FAQ answers, title generation, or format conversion. ``` Use a **Regex pattern** rule for deterministic routing tokens, such as `tier:T1`, `tier:T2`, or `tier:T3`, when reviewers need repeatable test cases. Use a **TypeScript rule** when the tier policy must combine several conditions, such as channel, app-user segment, prompt length, file presence, known institution policy, or host context. ## Test prompts After saving the orchestrator, run a small route test set from the target channel: | Test prompt | Expected tier | | -------------------------------------------------------------------- | ------------- | | Summarize this short announcement in Slovenian. | T3 | | Compare these two policy documents and cite the differences. | T1 | | Draft a normal email response based on this conversation. | T2 | | Extract the deadline and contact person from this notice. | T3 | | Build a sourced implementation plan from the attached specification. | T1 | If a route is wrong, adjust the orchestrator handoff rule before changing tier model settings. ## Evidence to capture Use these surfaces as hard evidence that automatic tier selection is active: - the conversation header **Model tier** selector when manual chat-level tier choice is part of the claim; - the orchestrator **Handoff** tab showing the T1/T2/T3 rules; - the tier configurations showing the submitted model selected for each tier; - a conversation turn where the orchestrator hands off to the expected tier agent; - **Inside Info** or behavior trace evidence showing the selected agent/config and tools; - the Platform Dashboard **AI usage CSV** showing the model used for the reviewed turn. For enterprise control-plane reviews, also record the business reason for each tier, the sensitivity or risk condition that selects it, the fallback rule when the preferred tier is unavailable, and any approval or exception record. If the policy must enforce spend or quota limits, pair this page with [Usage Billing And Quotas](#doc-platform-dashboard-usage-billing-and-quotas). When a formal AI FinOps workload policy owns the route, define the workload class, allowed tiers, preferred tier, fallback tier, business justification, and approval requirement in the relevant AI budget settings surface. Pending, rejected, expired, or misconfigured policies appear in [Governance Operations](#doc-governance-operations), where temporary exceptions require an expiry timestamp. At runtime, a configured allowed fallback tier can be used instead of the requested tier; otherwise the policy blocks before the model call. ## Real-life example > A public-sector assistant routes short grammar and format fixes to `T3 Efficient`, everyday drafting to `T2 Balanced`, and document-grounded policy comparison to `T1 Flagship`. Reviewers can run the same prompt set after every configuration change and confirm that the selected tier still matches the approved policy. ## Troubleshooting - **Every prompt stays on the orchestrator:** Confirm the handoff rules are enabled and point to active tier agents. - **The wrong tier answers:** Put the stricter rule earlier in the handoff list or use a TypeScript rule for deterministic policy checks. - **A tier uses the wrong model:** Open that tier's active configuration and verify the **Model** field. - **Evidence does not show the selected model:** Export AI usage from Platform Dashboard for the same date range and check the model column. --- # Code execution Some AI models can run provider-managed code execution or code-interpreter tools during a conversation. Gaia exposes this as a model capability that must be enabled on the selected model and agent configuration. This is different from a Gaia-hosted operating-system sandbox. Use this page to verify model/provider code execution capability, uploaded-file handling, and generated outputs. ## Configure code execution 1. Open **Platform Settings -> Models** and confirm the selected model lists a code execution or code interpreter built-in tool. 2. Open **AI Agents -> Agent Configuration**. 3. Select the model that supports code execution. 4. Enable the relevant built-in tool for that configuration. 5. Save the configuration and make it active for the target agent. 6. Open a conversation with that configuration. 7. Upload a supported file if the provider requires one, then ask for a small analysis or generated output that requires code execution. ## What Gaia records - The selected model and configuration used for the turn. - Visible tool or execution output returned by the provider. - Generated files or artifacts when the provider returns them through the conversation. - Transcript export evidence when the output is included in the conversation history. Provider-managed code execution follows the provider's runtime, retention, and file-handling boundaries. Do not treat it as a Gaia-managed isolated Python notebook unless your deployment has a separate Gaia-hosted sandbox service. ## Evidence to capture - Model settings screenshot showing the code execution or code interpreter capability. - Agent configuration screenshot showing the built-in tool enabled. - Conversation screenshot showing a code execution result or generated file. - Transcript export when the execution result must be shared outside the product. ## Related pages - [Agent Configuration](#doc-agents-configs) - [Conversations](#doc-conversations) - [File extractor registry](#doc-conversations-file-extractor-registry) --- # Common Fragments The **Fragments** tab in **AI Agents** opens the **Common Fragments** registry, which stores reusable prompt snippets that multiple agent configurations can link to. ## When to use it Use **Fragments** when you want one prompt block to stay consistent across several agents, skills, validators, or file extractors. Common examples: - shared tone or policy language - reusable artifact instructions - visual-output guidance such as diagrams or charts - project-wide formatting or response rules Each fragment has a version label so you can keep older variants available while introducing newer instructions. ## What you can do - **Browse the registry:** Search by name and review every saved version. - **Create from scratch:** Add a new reusable fragment with name, version, tags, description, and markdown text. - **Start from templates:** Use the built-in **Templates** menu to bootstrap common artifact and visual guidance patterns. - **Duplicate versions:** Copy an existing fragment to branch a new variation. - **Edit or delete:** Maintain the shared catalog without opening an individual agent configuration first. ## How it connects to agent configurations Inside **AI Agents -> Agent Configuration -> Instructions**, each prompt fragment can either contain inline text or link to a saved fragment from this registry. When a configuration links to a saved fragment: - Gaia reuses the shared text instead of copying it inline. - You can switch versions without unlinking the fragment. - Multiple configurations can stay aligned on the same instruction set. Editor-level dialogs still use the label **Common Fragments**, but they now act as lightweight pickers. Full create/edit management happens on the **Common Fragments** pages instead of inside nested dialogs. ## Prompt library evidence For a governance or tender review, treat **AI Agents -> Fragments** as the reusable prompt library evidence surface: - **Library structure:** use fragment names, descriptions, tags, and versions to show the approved prompt families. - **Versioning:** keep older fragment versions available when active configurations still depend on them, and duplicate a fragment when a new variant needs review without changing existing agents. - **Parameter binding:** document runtime placeholders in the linked [Agent Configuration](#doc-agents-configs) variables tab so reviewers can see which values are supplied by the configuration, channel, role, or deployment context. - **Controlled reuse:** open the linked configuration to show which agents use the fragment and which fragment version they select. - **Approval evidence:** link the fragment or configuration to governance policies, delivery evidence, tasks, or review records when the review needs formal sign-off beyond the prompt text itself. Fragments are reusable prompt assets. They do not by themselves prove runtime enforcement; pair them with configuration, validator, governance, and eval evidence when the review asks for guardrails or approval controls. ## Step-by-step 1. Open **AI Agents -> Fragments**. 2. Search the registry or click **New Fragment**. 3. Enter a **Name** and **Version**. 4. Add an optional **Description** and **Tags** to make the fragment easier to find later. 5. Write the fragment text, or start from **Templates**. 6. Click **Save**. 7. Open an agent configuration and link the fragment from the **Instructions** tab when you want to reuse it. ## Tips - Keep fragment names stable and use the version field to track changes. - Use tags for topic or capability grouping, such as `policy`, `artifact`, or `diagram`. - Duplicate before making an experimental rewrite if older configurations still depend on the current version. ## Related pages - [Control Plane Evidence](#doc-control-plane-evidence) - [AI Agents](#doc-agents) - [Agent Configuration](#doc-agents-configs) --- # Protocols The **Protocols** tab in **AI Agents** is the shared registry for reusable execution protocol templates. ## What execution protocols are An execution protocol is an optional staged operating model for an agent configuration. Instead of handling a request as one open-ended turn, Gaia can move the agent through named stages such as `Plan -> Execute -> Verify` or `Clarify -> Research -> Synthesize -> Verify -> Finalize`. Gaia treats the protocol as visible operating behavior, not hidden reasoning. In today's product, protocol stages advance through an ordered sequence. Gaia runs one active stage at a time, narrows the instructions, skills, and tools for that stage, then records a checkpoint that decides what happens next. Each stage can define: - focused instructions that are added to the runtime prompt - allowed skills and allowed tools for that stage - expected outputs and exit criteria - typed structured checkpoint outputs - whether the stage should pause for user approval before continuing - an advisory max-turn budget for operator review - the session lifecycle that controls whether the protocol runs once, restarts after completion, or resets every turn During a live conversation, Gaia keeps a durable execution session for the staged run. At the end of a stage turn, the agent records a checkpoint with a summary, any structured outputs, and a stage status: - `in_progress` keeps the current stage active - `ready_for_transition` moves to the next stage, or pauses in **waiting for user** when confirmation is required - `blocked` records open questions or failed prerequisites and keeps the run available for review and resume Execution protocols are visible product behavior, not hidden reasoning. Gaia stores stage summaries, typed outputs, and session history so operators can review what happened. ## When to use a protocol Use an execution protocol when the main question is, "What should this agent do next in this conversation, and what should stay visible to the operator?" Execution protocols are a good fit when: - the order of work changes risk, quality, or accountability - the agent should pause for approval before it continues - later stages depend on a checkpoint or structured outputs from earlier stages - the same governed sequence should be reused across multiple agents - the operator should be able to inspect where the run stands without reading the whole conversation Do not add a protocol just because the task sounds complicated. A normal agent turn is often enough when: - a strong prompt plus ordinary tool access already produces a good result - the work does not need explicit review gates or stage-by-stage visibility - the stage labels would not meaningfully narrow what the agent is allowed to do ## How a staged run behaves A staged run does not mean Gaia tries to finish every stage in one reply. The current stage governs the current turn. During that turn, Gaia can still use its normal tool loop, but it stays inside the active stage until it writes a checkpoint. That checkpoint decides the next state: - `in_progress`: stay in the same stage for the next turn - `ready_for_transition`: mark the stage complete and either move on automatically or pause in **waiting for user** until someone explicitly approves the next stage - `blocked`: keep the same stage active because Gaia still needs missing input, evidence, or a prerequisite decision In practical terms: - **waiting for user** means the current stage is complete and Gaia is waiting for approval before entering the pending next stage - **blocked** means the current stage is not complete yet, and Gaia should continue the same stage after you provide the missing input or evidence ## Execution protocols vs workflow graphs Execution protocols and workflow graphs solve different problems. | Question | Execution protocol | Workflow graph | | ---------------------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | | What it governs | one agent's staged behavior inside a conversation | repeatable automation across pipelines, tools, agents, human actions, and control blocks | | Where you configure it | **AI Agents -> Protocols** and **AI Agents -> Agent Configuration -> Execution** | **Data Model -> Workflows** | | Shape | ordered stages with checkpoints and optional approval pauses | graph-based runs with branches, loops, named ports, and run logs | | Best when | the agent itself should work in visible stages | the automation itself should branch, loop, route, or prepare data every time it runs | | What operators review | stage summaries, structured outputs, waiting or blocked state, and session history | workflow runs, node outputs, routing behavior, and execution logs | Choose an execution protocol when the main design problem is governing the agent's conversation. Choose a workflow graph when the main design problem is orchestrating reusable automation. Use both when the automation should prepare or approve evidence before a staged agent analyzes it. For example, a workflow graph can gather documents, run pipelines, and route approval steps, while a protocol governs how the research agent clarifies the question, synthesizes findings, verifies them, and finalizes the answer. ## Session lifecycle modes Every protocol template includes a **Session lifecycle** choice: - **One run per conversation:** Use this when the staged run should stay attached to one governed conversation thread. After the session completes, later turns fall back to the normal runtime unless an operator restarts the protocol manually. - **Restart after completion:** Use this when the same specialist may need to repeat the same governed flow more than once in the same conversation. After a run completes, the next user turn starts again from the initial stage. - **Reset every turn:** Use this when each user turn should be treated as an isolated pass through the initial stage. Gaia cancels any unfinished run from the previous turn before starting the next one. For most governed delivery or review agents, **One run per conversation** is the right default. For repeatable specialist tasks such as exam generation, grading, or other fresh-request flows, **Restart after completion** is usually the better fit. ## Registry vs configuration Two surfaces work together: - **AI Agents -> Protocols** stores reusable templates that teams can apply to multiple agents. - **AI Agents -> Agent Configuration -> Execution** is where a specific agent configuration actually runs with staged behavior. When you apply a saved protocol from the registry, Gaia copies the protocol into the current configuration together with any bundled starter skills and tools. After that, the configuration remains editable. The registry entry is a starting point, not a live lock. ## What this page is for Use protocol templates when multiple agents should start from the same staged workflow or when you want the team to standardize how governed work is sequenced. Each template can include: - the execution protocol itself, including ordered stages, instructions, typed outputs, and stage-level skill/tool limits - the session lifecycle that determines how the staged run restarts later in the same conversation - a starter set of skills to add to any agent config that applies the template - a starter set of tools to add to any agent config that applies the template Typical use cases include: - planning work before implementation begins - separating research from synthesis and verification - pausing between risky stages so a reviewer can approve the next step - keeping reusable multi-stage flows consistent across multiple agents Avoid using a protocol when a simple conversational assistant only needs good prompts, light tool policy, and no explicit review gates. ## Create and apply a template 1. Open **AI Agents → Protocols**. 2. Click **Add protocol**. 3. Fill in the template name, version, description, and tags. 4. Open the **Protocol** tab. New templates start with one generic custom stage so you can build an arbitrary sequence from scratch. 5. Add, rename, reorder, or delete stages as needed. If you want a faster scaffold, apply one of the built-in presets from the **Built-in preset** picker. 6. Open **Skills** and **Tools** if this template should give agents a ready-made starter set. 7. Save the template. 8. In **AI Agents → Agent Configuration → Execution**, choose the saved protocol and click **Apply**. 9. Review the copied stages, skills, and tools, then customize anything specific to that agent before saving the config. ## Worked example: delivery implementation agent One strong use of `Plan -> Execute -> Verify` is a delivery implementation agent that handles scoped platform-change requests such as: > Add a risk-review step to the onboarding workflow and update the release checklist. A good protocol for that role looks like this: | Stage | What the agent does | What stays limited | | --------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | `Plan` | scopes the request, identifies impacted Gaia surfaces, lists assumptions, and asks for approval before any write work begins | keep the stage mostly read-first: discovery, search, inspection, and documentation context | | `Execute` | updates the approved workflow, task, layout, or governance records and summarizes what changed | avoid broad new planning; focus on the approved implementation batch | | `Verify` | runs the relevant checks, captures evidence, and states whether the change is ready or still has gaps | avoid turning verification into another implementation pass unless the operator explicitly starts a new batch | Typical structured outputs for that protocol: - `Plan`: plan summary, dependencies, open questions - `Execute`: changed resources, implementation notes, remaining blockers - `Verify`: checks run, evidence, readiness summary This works well because the approval gate sits between planning and implementation, and the final stage stays evidence-focused instead of quietly expanding scope. ## Worked example: deep research Deep research is a good way to decide whether you need a protocol, a workflow graph, or both. ### Light version: protocol only Use a protocol by itself when the research mainly happens inside one governed conversation thread. Example: > Compare three internal policy memos with two public regulatory summaries and tell me where our draft guidance is still weak. In that case, the built-in **Deep Research** preset is a strong fit: - `Clarify`: turn the question into a research brief and confirm the scope - `Research`: gather evidence notes and citations - `Synthesize`: compare sources and draft the working conclusion - `Verify`: challenge the draft and record remaining risks - `Finalize`: deliver the final answer with references and residual uncertainty Choose this version when the main need is staged reasoning, visible checkpoints, and operator review inside the conversation itself. ### Full version: workflow graph plus protocol Use both capabilities when the research procedure also needs reusable automation before the staged conversation begins or while it is in progress. Example: > Every week, collect market updates, ingest approved analyst notes, route any restricted-source review through a human action, then ask a research agent to produce the final competitive briefing. In that setup: - the **workflow graph** handles the repeatable collection, enrichment, routing, and approval steps - the **execution protocol** governs how the research agent turns that prepared evidence into a controlled final briefing Choose this version when the source-gathering and approval path should run as a reusable automation, while the agent's analysis should still stay staged and reviewable. ### Quick rule of thumb - Use only a normal conversation when the research request is short and does not need explicit stages. - Use a protocol when the research itself should stay visible and reviewable from one stage to the next. - Add a workflow graph when the research also depends on repeatable branching, looping, approvals, or data preparation outside the conversation. ## What operators see during live runs After a configuration with staged execution is active, operators can review the run in two places: - **Recent execution sessions** inside the configuration editor, where they can filter sessions by status or event type, inspect the latest checkpoint, cancel a stuck run, or restart a fresh run from the initial stage - the compact execution summary inside a live conversation in the main project **Conversations** workspace, where they can see the current stage, waiting state, latest checkpoint summary, typed outputs, and blocked guidance after opening **Execution** in the toolbar and expanding **Review details** When a stage is waiting for confirmation, reply with an explicit approval such as "continue", "approved", or "go ahead" to move into the pending next stage. When a stage is blocked, reply with the missing input or evidence to continue the same stage. Use the configuration editor, not the conversation thread, for **Cancel** and **Restart**. ## Notes - Stage-level **Allowed skills** and **Allowed tools** use a tag input plus searchable command picker. You can type names directly or browse the available options. - Saved templates do not lock the configuration. After applying one, you can rename stages, add or remove outputs, change approval gates, and change the bundled skills/tools without affecting the original template. - Saved templates copy their lifecycle mode into the configuration. You can change the copied lifecycle later without affecting the template. - Built-in presets are optional quick scaffolds. Applying one replaces the current stage list inside the editor, so use it before or during editing when that is faster than building the flow manually. - If a bundled skill or tool comes from a registry entry, Gaia keeps its registry link when the configuration is saved. - Keep stages concrete. A good stage usually does one kind of work and has clear exit criteria. ## Related pages - [AI Agents](#doc-agents) - [Agent Configuration](#doc-agents-configs) - [Skills](#doc-agents-skills) - [Guardrails](#doc-agents-guardrails) - [Workflows](#doc-data-model-workflows) - [Tool registry](#doc-data-model-tool-registry) --- # Agent Configuration Each agent in Gaia can have multiple configurations, allowing you to experiment with different settings, models, prompts, and tool access without affecting your active configuration. This page helps you understand how to create, edit, and manage agent configurations. ## Who can access this page? Only **project admins** and **team admins** can edit agent configurations. If you don't see the edit option, ask an admin to adjust your role. ## Configuration basics A configuration defines how an agent behaves during conversations: - **Model selection:** Choose which AI model powers the agent - **System prompts:** Define the agent's personality, tone, and instructions - **Variables:** Resolve `{{variables}}` used inside prompt fragments - **Tools:** Enable or disable specific tools the agent can use - **Knowledge folders:** Attach document folders as config-level knowledge, marking each one as `Important` or `Fallback` - **Post-steps:** Run AI or TypeScript processing after each turn (for example assessment, topics, or memory extraction) - **Execution protocols:** Optionally govern the agent with explicit ordered stages such as `Plan -> Execute -> Verify` or a custom sequence you define yourself - **Safety settings:** Configure guardrails like moderation and off-topic handling - **Voice settings:** Configure text-to-speech voices and transcription models - **Handoff rules:** Define when and how the agent transfers conversations to other agents For tiered model portfolios, use [Model Tier Routing](#doc-agents-model-tier-routing) to connect orchestrator handoff rules to tier-specific configurations such as T1, T2, and T3. ## Prompt management evidence For tender evidence, use **AI Agents -> Agent Configuration** to show managed system prompts, prompt fragments, variables, skills, model settings, and active/default configuration assignment. Admins can maintain shared prompt fragments and templates from **AI Agents -> Fragments** and attach them to one or more configurations. User- or audience-specific behavior should be evidenced by the configuration, channel, and app role that selects the prompt bundle for that audience. Treat this as governed prompt management, not unmanaged source-code customization. For control-plane evidence, capture these configuration items together: - active configuration name, version, description, and active/default assignment; - model, fast model, realtime, transcription, TTS, and embedding-related settings that apply to the agent path; - linked prompt fragments and the selected fragment versions; - variables used for parameter binding inside prompts; - enabled tools, MCP servers, manual MCP tools, workflows, and TypeScript tools; - validators such as **Document knowledge grounding**; - attached document knowledge folders and whether they are `Important` or `Fallback`; - handoff rules or model-tier routing policy; - post-steps, assessment, memory, and execution protocol settings; - configuration diff or import evidence when reviewers need to compare versions. Use [Control Plane Evidence](#doc-control-plane-evidence) to combine configuration proof with retrieval, dashboard, audit, eval, and governance evidence. ## How conversations work Understanding how Gaia processes conversations helps you configure your agents effectively. When a user sends a message, Gaia follows a structured flow that applies your configuration settings at each step. ### Welcome message When a conversation starts, your agent greets the user with the **welcome message** you configured in the General tab. This message is shown only once at the beginning of a conversation and can be customized for different languages to match your user base. When you add a new language, Gaia now asks whether you want to translate the existing English message immediately. If you choose translation, pick one of the available generative or reasoning models and Gaia fills the new language slot before you save. ### Message simplification If you've configured a **translation prompt** (in the Language tab), Gaia can use your fast model to simplify or normalize the user's message before processing. This step is controlled by the **Enable translation** switch (disabled by default). - Complex or verbose user inputs - Messages that need language normalization - Requests that benefit from clarification The simplified version is used internally while the original message remains visible in the conversation history. ### On-topic checking Before generating a response, Gaia can check if the conversation is on-topic using the **on-topic rules** you defined in the Language tab. This guardrail is controlled by the **Enable off-topic detection** switch (disabled by default). When enabled, the fast model evaluates the entire conversation context against your rules. For orchestrators, these rules can act as the team-level boundary for every user turn, even when the previous visible reply came from a specialist agent. If the conversation is off-topic: - The user receives your configured **off-topic message** - The active **channel** decides whether Gaia also appends the detector's **off-topic cause** to that visible reply - **Inside Info** and the **Messages** page always show the detector explanation for reviewers - No further processing occurs for that turn - The conversation can continue with new messages This guardrail ensures your agent stays focused on its intended purpose and doesn't waste resources on irrelevant requests. ### Handoff logic In orchestrator-plus-specialist setups, Gaia applies guardrails and routing in this order: 1. Gaia runs the orchestrator's on-topic policy on every user turn, even if the conversation is currently continuing with an assumed specialist. 2. If the orchestrator-level check fails, Gaia stops the turn immediately and returns the configured off-topic reply. 3. If the orchestrator-level check passes, Gaia evaluates the orchestrator's **handoff rules** (configured in the Handoff tab) to decide which agent should handle the turn. 4. If the selected specialist has its own on-topic policy, Gaia runs that narrower specialist check after routing. 5. Gaia prefers routing the turn to the best matching specialist before it falls back to an off-topic reply for a narrower specialist scope. 6. Gaia shows only one visible off-topic reply to the user, while review surfaces still preserve the underlying guardrail decision details. After the global boundary passes, Gaia evaluates your **handoff rules** (configured in the Handoff tab) to determine if a specialized agent should handle the request. Gaia supports three handoff rule types: - **Text condition:** A natural-language routing rule evaluated against the conversation context - **Regex pattern:** A deterministic pattern match evaluated against the extracted conversation context - **TypeScript rule:** A deterministic script that can inspect the cloned messages array, use standard transform utilities, and append hidden handoff notes for the transfer Rules run in the order shown in the Handoff tab. The first matching rule wins. TypeScript handoff rules can also use the shared conversation storage helpers. Values written there are available to later TypeScript tools, Bridge Agent hooks, and Bridge Agent routing scripts in the same conversation. The system can: - **Transfer to another agent** if a handoff condition matches - **Ask for clarification** if the request is too ambiguous - **Continue with the current agent** if no handoff is needed When a handoff occurs, the new agent takes over with its own configuration, system prompts, and tools. This enables you to build teams of specialized agents that collaborate seamlessly. Handoffs can chain across multiple agents (up to 5 levels deep) to handle complex workflows, but be careful to avoid circular handoff rules that could create loops. ### Execution protocol If you enable the **Execution** tab for a configuration, Gaia runs the conversation under an explicit staged protocol instead of relying only on the normal turn-by-turn prompt. Use an execution protocol when the conversation itself should move through visible stages. If you need repeatable branching, looping, approvals, or data preparation across automation runs, use [Workflows](#doc-data-model-workflows) instead. For the fuller decision guide and worked examples, see [Protocols](#doc-agents-protocols). In a staged configuration: - one stage is active for the current turn - the active stage adds focused instructions to the system prompt - the runtime narrows the available skills and tools for that stage - Gaia can still use its normal tool loop inside that stage before it checkpoints the turn - the agent writes a structured checkpoint before finishing the turn - stages can optionally require typed structured outputs inside that checkpoint - Gaia keeps a durable execution session, and the protocol lifecycle decides whether that session runs once, restarts after completion, or resets every turn Each staged turn ends with a checkpoint that records the stage summary, any structured outputs, and one of three outcomes: - `in_progress` keeps the current stage active - `ready_for_transition` marks the stage complete and moves to the next stage, or pauses in **waiting for user** when that stage requires approval before Gaia enters the pending next stage - `blocked` records open questions or failed prerequisites so the same stage can continue after the missing input or evidence arrives Each protocol also has a **Session lifecycle** setting: - **One run per conversation:** Start the protocol once for the conversation. After it completes, later turns use the normal runtime unless an operator restarts the session. - **Restart after completion:** After one execution run completes, the next user turn starts a fresh run from the initial stage. - **Reset every turn:** Every user turn starts from the initial stage, and Gaia cancels any in-flight session from the previous turn. Use **One run per conversation** for governed multi-stage work that should stay attached to one durable operating thread. Use **Restart after completion** for repeatable specialist flows such as generation, scoring, or delivery tasks that should begin cleanly each time the user asks again. Use **Reset every turn** only when every turn should be treated as a fresh, self-contained pass. Operators can inspect the same staged run from the **Recent execution sessions** panel in the configuration editor and from the compact execution summary opened with **Execution** in the main project conversation toolbar. When you enable staged execution for a configuration, Gaia starts from **Plan -> Execute -> Verify** by default, but you can replace it with another built-in preset such as **Deep Research** or a saved protocol template. This is useful when you want an agent to: - plan first and wait for approval before implementation - run a research procedure with distinct clarification, evidence, synthesis, verification, and finalization stages - separate evidence gathering from final synthesis - keep verification distinct from broad new build work Execution protocols are visible product behavior, not hidden reasoning. Gaia stores stage summaries, checkpoints, and session history rather than private chain-of-thought. ### Response generation and tool use Once the right agent is selected, Gaia generates a response using your configured **primary model** and **system prompts**. During this phase, the agent: 1. **Analyzes the request** using the system prompt fragments you assembled in the Instructions tab 2. **Decides if tools are needed** based on the tools you enabled in the Tools tab 3. **Calls tools** if necessary to fetch data, perform actions, or delegate to other agents 4. **Generates a response** incorporating tool results and conversation context The tool execution loop continues until the agent has all the information it needs or reaches your configured **max tool calls** limit. Tools can: - Search your data entities for relevant information - Navigate the user interface to different pages - Remember information across conversations - Perform calculations or external lookups - Delegate subtasks to other specialized agents If you enabled **parallel tool execution**, multiple independent tools can run simultaneously to speed up responses. Otherwise, tools execute sequentially. ### Response delivery The final response is delivered to the user through the conversation interface. If voice mode is active, Gaia also generates audio using your configured **TTS model** and **voice** settings from the Voice tab. Throughout this entire flow, your configuration settings control: - Which models handle each step (fast model for checks, primary model for responses) - What guardrails apply (on-topic rules, handoff conditions) - What capabilities are available (enabled tools) - How the agent behaves (system prompts, model settings like temperature) ### Post-step processing After each turn is completed, Gaia queues any enabled **Post-steps** from your configuration. These steps are useful for background processing such as scoring conversation quality, extracting topics, or consolidating memory. They run asynchronously, so they do not extend the user-facing turn response. - Post-steps run in the order they appear in the tab. - Results are saved to the conversation for later analysis. - Each step records its own run state and is retried after a failure without repeating steps that already succeeded. - Locking a conversation queues a final conversation-level pass. Project admins can also schedule **Process locked conversation post-events** to recover any final steps that have not succeeded. Understanding this flow helps you configure agents that are both powerful and focused, with appropriate safety measures and efficient routing between specialized agents. ## Real-life example > A support team duplicates their active configuration, adds a billing tool and a stricter off-topic rule, then runs a few test conversations before marking the new version active. ## Configuration tabs ### General Configure the core settings: - **Name/Persona:** A descriptive name for this configuration variant - **Version:** Track different iterations (e.g., "1.0", "1.1", "experimental") - **Description:** Short plain-text note describing what this version contains, what changed, or its purpose - **Active:** Mark this configuration as the one currently used in conversations. If the Organization license has an active-agent limit, Gaia checks capacity before saving a newly activated configuration and shows the license-limit message instead of silently changing the runtime default. - **Temperature (model settings):** Control response creativity (0 = focused, 2 = creative). Hidden for reasoning models. - **Max Tool Calls:** Limit how many tool calls the agent can make in a single turn. Model-level advanced settings now support higher ceilings for intentionally long tool chains. - **Parallel Tool Execution:** Allow multiple tools to run simultaneously - **Model:** Primary AI model for generating responses - **Knowledge folders:** Attach document folders that this configuration should search by default. Gaia searches them through `search_document_folder` across indexed text and spreadsheet content. Use `Important` for always-on policy or standards folders, and `Fallback` for secondary corpora that Gaia should search only when the first pass is weak or empty. - **File uploads:** End-user upload behavior is now configured on the **channel**, not in the agent configuration. Use **Conversations -> Channels -> Text/Personal Assistant -> Files** to expose the paperclip, storage uploads, shared folders, and workflow routing. - **Fast Model:** Optional lighter model for quick tasks like translation or off-topic detection - **Reasoning Effort, Summary & Verbosity:** For reasoning models, control thinking depth (including **Extra high**), whether to request a provider-generated reasoning summary (**Auto/Concise/Detailed/None**), and output detail - **Anthropic Runtime (Claude):** For Anthropic models, choose the hosted transport or compatibility fallback and optional Claude-specific controls (reasoning mode, thinking budget, tool-choice mode, parallel-tool behavior, web-search max uses) - **Related Entities:** Link data entities to automatically include their context in prompts - **Guardrails:** Attach exact versions of shared conversation-scope, instruction-confidentiality, or response-validation controls and choose their enforcement mode and priority - **Welcome Message:** Greeting shown when users start a conversation (multilingual) - **Thinking Message:** Message displayed while the agent is processing (multilingual) Agent configurations still control the model side of uploads: if a channel allows **Attach to model**, Gaia checks the active configuration's primary model before exposing that option to end users. In the configurations list, Gaia also shows a **Description** column so teams can quickly scan what each saved version represents without opening it first. Keep these descriptions short and specific. Long descriptions are truncated in the list. Guardrail assignments are managed in two places: - Create immutable reusable definitions in [AI Agents → Guardrails](#doc-agents-guardrails). - In the agent configuration, attach exact versions and choose assignment-level enablement, priority, and enforcement mode. Response-validation guardrails retain two distinct validator parts: - **Trigger:** the condition that decides whether Gaia should run the validator for the current turn. - **Validation:** the actual acceptance check, either AI-based or deterministic depending on the validator definition. For document-grounded assistants, attach the **Document knowledge grounding** validator when you want Gaia to enforce document search before the agent answers substantive turns. With a linked folder, the validator behaves strictly and requires search before substantive answers. With config- or channel-attached knowledge folders only, Gaia applies the same validator more selectively to likely document-, policy-, rule-, text-, or spreadsheet-backed requests. This keeps the behavior under platform-user control at the configuration layer instead of hard-coding it for every conversation. Pair this validator with the **Folder Retrieval** common fragment and the folder search tools so `search_document_folder` runs before the assistant guesses from indexed text or spreadsheet evidence. See [Scenario: Folder-grounded Personal Assistant setup](#doc-conversations-scenarios-folder-grounded-personal-assistant-setup). When users attach document files, Gaia keeps them available for both model answers and artifact workflows: - `.pdf` attachments are mirrored to conversation storage, attached to eligible runtimes, and text is extracted for reliable document Q&A and artifact import. - `.doc` attachments are mirrored for artifact import. Runtimes that support markdown attachments receive a converted markdown/text variant for the model, while PDF-only attachment runtimes keep legacy Word files artifact-only. - `.docx` attachments are mirrored for artifact import. OpenAI-style runtimes that support DOCX receive the original file; Anthropic native runtimes receive a converted markdown/text variant for the model while Gaia still keeps the artifact workflow available. - `.md` and `.txt` attachments are mirrored, attached to eligible runtimes, and can be imported directly into artifacts. - `.csv` and `.xlsx` attachments are mirrored and can be imported into spreadsheet artifacts. Files that fit the interactive grid limits stay editable as `grid-json` artifacts with CSV/XLSX export. Oversized spreadsheets now import as read-only workbook-preview artifacts instead of failing outright, preserving the original source file for later export while Phase 2 structured querying catches up. OpenAI Responses runtimes can also receive the original spreadsheet file directly; PDF-only attachment runtimes keep spreadsheets artifact-only, and Anthropic keeps spreadsheets artifact-only. For supported document and spreadsheet uploads, Gaia also creates the conversation artifact in the background after the message is sent so it becomes available in the conversation’s **Artifact** selector without opening the canvas automatically. For spreadsheet artifacts, agents should prefer spreadsheet query tools for summaries, exact A1 range reads, and aggregations instead of reading the full workbook payload into the model context. Those tools return compact `table.schema` + `table.records` projections for tabular reasoning and coordinate cells for `range_read`. Read-only workbook-preview artifacts are import-safe, exportable, and queryable for structured reads. For an exact tool-level setup list, use [Agent Config Checklist for Canvas and Document Workflows](#doc-conversations-agent-config-checklist). ### Language Control how the agent handles language and topic boundaries. On the configuration page, open the Language tab — this is where you'll find the On-topic rules field between the translation prompt and the off-topic message editors: - **Enable translation:** Toggle whether user messages are simplified/translated before processing (disabled by default) - **Translation prompt:** Instructions for simplifying user requests before processing - **Enable off-topic detection:** Toggle whether on-topic rules are enforced (disabled by default) - **On-topic rules:** Define what subjects the agent should handle - **Off-topic message:** Response when users ask about unrelated topics (multilingual) - **On-topic check prompt:** Advanced template (collapsed by default) When you add a new language to the **Off-topic message** editor, Gaia can translate the existing English response into that language on demand. This authoring-time translation step is separate from the **Enable translation** setting above, which affects how live user messages are simplified or normalized during conversations. When a configuration belongs to an orchestrator, treat its on-topic rules as the broad system boundary. Use specialist on-topic rules only when you want a narrower scope after routing. Visible off-topic-cause text is configured on the channel, not in the agent configuration. Use **Conversations -> Channels** for Text, Personal Assistant, or Alternative frontend channels when you want end users to see the detector explanation in the reply itself. ### Variables Use this tab to define how placeholders inside prompt fragments are resolved at runtime. - **Placeholder format:** `{{variable_name}}` (for example `{{customer_name}}`) - **AI resolver:** Choose a model, write a resolver prompt, and select what input is available to that prompt: - clean messages list - session memory (all keys or selected keys) - user memory (all keys or selected keys) - In your resolver prompt, refer to these exact section names: `## Clean messages list`, `## Session memory`, and `## User memory` - **TypeScript resolver:** Write resolver code (same editor style as TypeScript tools). The resolver receives: - clean messages list - selected session memory values - selected user memory values TypeScript variable resolvers expose an **Execution runtime** selector with a visible security classification and an optional **Execution timeout (ms)** override. Existing scripts without a saved runtime identifier remain on the high-risk legacy Node.js runtime, while newly authored TypeScript resolvers, handoff rules, tools, and post-steps start on QuickJS WebAssembly. QuickJS provides a reduced-risk worker/WASM boundary; test the configuration after switching because Node-specific behavior may be incompatible. Leave the timeout blank to use Gaia's default limit. The adjacent **Context API** selector keeps existing definitions on context v1 and starts new definitions on portable context v2. Changing the runtime does not automatically migrate the context contract. If a variable resolver is missing or fails, Gaia leaves the original placeholder text unchanged. ### Instructions Build the agent's core instructions using prompt fragments: - **System prompt fragments:** Modular text blocks that form the agent's instructions. Fragments are **collapsible** so you can focus on one at a time when the prompt gets long. - **Common fragments:** Shared snippets that can be reused across multiple agents - **Entity model prompts:** Automatically generated context about linked entities (shown when entities are selected and the search_across_entities tool is enabled) Each fragment supports comments for team collaboration and version history. In **AI Agents -> Fragments**, use the **Templates** menu to bootstrap reusable fragments, including artifact workflow starters (markdown, p5-js, spreadsheet `grid-json` with CSV/XLSX import/export), a UI-layout intent-routing starter for choosing between inline UI, saved layouts, entity canvas, and runtime canvas sessions, inline UI layout starters for `gaia-ui-layout` reply blocks, and visual-block starters that keep true diagrams inline as Mermaid while routing chart requests to inline `gaia-chart` blocks instead of image-style outputs. The **Common Fragments** dialog inside editors is now picker-only; use it to link a saved fragment, and open the registry page in a new tab when you need to create or edit shared fragments. When a prompt fragment is linked to a common fragment, use the version selector (for example `@1.0`) to switch to another saved version of the same fragment without unlinking. ### Handoff Define rules for transferring conversations to other agents: - **Rule type:** Choose between text, regex, and TypeScript routing - **Condition or description:** Record the operator-facing explanation for the rule - **Target Agent:** Choose which agent should take over, and optionally pin a specific configuration version - **Regex details:** Provide the pattern and optional flags when you need deterministic lexical matching - **TypeScript details:** Write deterministic routing logic that can inspect the cloned messages array, call standard transform utilities, and append hidden handoff notes for the next agent TypeScript handoff rules expose the same runtime selector, security classification, and optional **Context API** selector plus **Execution timeout (ms)** override. Test the handoff path after switching either setting. Leave the timeout blank to use Gaia's default limit. TypeScript handoff rules share durable conversation storage with later TypeScript tools and Bridge Agent scripts. Prefix storage keys by purpose, such as `handoff:` or `bridge:`, when multiple scripts coordinate on the same conversation. Handoffs let you create specialized agents (support, sales, technical) that seamlessly collaborate. Arrange rules from most specific to most general because Gaia evaluates them top to bottom and stops at the first match. Use the up and down arrow controls in each rule row to change that priority without reopening the rule. Keep broad text rules below narrower regex or TypeScript rules unless you intentionally want them to take priority. The **handoff check prompt** is tucked into a collapsible section for occasional edits and still applies to text-condition rules. If you use orchestrators with specialist-local on-topic rules, design the handoff tab as the routing step between the broad orchestrator boundary and the narrower specialist boundary. That keeps valid in-domain requests moving to the right specialist instead of being rejected too early. ### Skills The **Skills** tab lets you enable a curated set of **registry skills** for this configuration. - **Skills Model:** The model used for skill selection. - **Skills prompt:** Template that decides which skills should be enabled for the current turn (collapsed by default). - Placeholders include `{{SKILL_RULES}}` and `{{CONVERSATION_CONTEXT}}`. - **Skills list:** Pick skills from the registry and optionally add a **Rule** for each skill describing when it should be used. Skills come from the [Skills tab](#doc-agents-skills) in the AI Agents workspace. If you can’t find a skill in the picker, create it in the registry first. When a configuration may respond with multiple UI-layout modes, the supported pattern is to use **ui layout intent routing** plus the execution skills that actually handle inline replies, saved layout authoring, runtime canvas sessions, or entity canvas operations. Do not keep older direct-only prompt setups that bypass routing when the agent supports more than one UI mode. ### Tools Enable or disable tools the agent can use during conversations: - **Custom tools:** Project-specific integrations (configured in this tab) - **Tool registry:** Shared tools stored in a central registry (select from the registry to reuse the same tool across multiple configurations) - **Agent tools:** Other agents this agent can delegate tasks to (configured in this tab) - **Built-in tools:** Model-native capabilities like web search and code interpreter (configured in the AI Model settings, not here) Each tool can be enabled/disabled individually. Use the tool description to understand what it does. Click **Test** to open the **tool testing dialog** where you can run the tool with sample arguments and see the output—handy for validating payloads or debugging parameter formats without switching to a conversation. The tool editor includes an **Execution tier** field for governance-aware runtime policy. Existing tools default to **Standard**. Use **Read only**, **Privileged**, or **Admin** when the tool's effect should be distinguishable by approved Governance Policies. TypeScript tools expose the same runtime and **Context API** selectors plus an optional **Execution timeout (ms)** override. Use the tool test flow after switching to QuickJS WebAssembly. Leave the timeout blank to use Gaia's default limit, or raise it when the tool does heavier synchronous work. Workflow tools now expose the execution controls that determine whether the agent waits for the workflow or lets it finish in the background: - **Context Key:** Gaia fills a default key automatically, so you do not need to hand-enter one for every workflow tool. You can still use placeholders such as `{{requestId}}` or `{{topic.slug}}` when the workflow should write to a request-specific context location. - **Execution Mode:** Choose **Return immediately** when the workflow should start in the background and hand control back to the conversation right away. Choose **Wait for completion** when the tool should block until the workflow finishes and then return the final result to the model in the same turn. - **Result Context Key:** When you use **Wait for completion** or want Gaia to deliver the final result later, point this field at the workflow storage key that will hold the finished answer. - **Append final result to conversation:** Use this for long-running workflows, such as deep research or large ingestion-and-analysis runs. Gaia will append the finished result as a later assistant message when the workflow completes, so the output is still visible if you leave the conversation and come back later. Common actions in this tab: - **Add tool:** Create a new tool directly in the configuration. - **From registry:** Add one or more tools that are already defined in the shared [Tool registry](#doc-data-model-tool-registry) before closing the dialog. The picker highlights the currently linked version, disables the exact-current row as **Added**, and exposes alternate saved versions with explicit **Switch to vX.Y** actions. - **Copy tools from:** Copy the tools list from another configuration of the same agent. When you add a tool via **Tool registry**, Gaia links the configuration tool back to the registry entry so updates to the registry tool definition can be picked up without manually copying changes into every config. The main Tools table now includes a **Version** column so registry-linked tools show the attached version directly in the configuration, while tools created only inside the configuration show `-`. Project-available internal tools, including document-folder tools, can be added to regular project agents; Gaia-assistant-only registry tools show as unavailable and cannot be added from this picker. You can also use **Test** in the Tools tab to run a tool definition with sample parameters and review the output before trying it in a conversation. Object and array parameters use the structured JSON editor, and the paste action accepts a JSON object of parameter values. **Note:** Built-in tools (web_search, code_interpreter) are now configured at the model level on the top-header **Models** page, not in the conversation configuration. For Anthropic native runtimes, Gaia maps built-in web search to Claude's native web-search tool when enabled. ### MCP Servers Use this tab to attach remote HTTP/SSE MCP servers to the agent configuration. Gaia discovers enabled remote tools at runtime and exposes them to the model with stable names prefixed by the server key. Common actions in this tab: - **Add from registry:** Copy a shared server from [AI Agents → MCP Servers](#doc-agents-mcp-servers) into this configuration. - **Add server:** Define a server that belongs only to this agent configuration. - **Presets:** Fill common server settings, starting with the Microsoft Enterprise MCP server. Use allowlists and denylists when the remote server exposes more tools than this agent should use. Manual MCP tools in the Tools tab are still available for pinned aliases or one-off overrides. ### Post-steps Use this tab to configure actions that run automatically after each conversation turn. In the configuration editor, it appears between **Tools** and **UI Messages**. - **Configured post-steps:** Review all enabled/disabled steps in one list. - **Add preset:** Add platform presets: - **Assessment** (scores conversation quality) - **Topic Extraction** (captures key topics with confidence) - **Memory Consolidation** (extracts reusable conversation/user memory) - Each preset can be added once per configuration. Already-added presets are disabled in the picker. - **Add custom:** Create a custom **AI step** or **TypeScript step**. TypeScript post-steps expose the same runtime selector, security classification, and optional **Context API** selector plus **Execution timeout (ms)** override. Test the full conversation path after switching because the post-step runs after each completed turn. Leave the timeout blank to use Gaia's default limit. Per step, you can configure: - **Name, Type, Enabled:** Basic identity and on/off control. - **Delete:** Remove a step from the configuration list. - **Model:** Select the model for preset or AI steps. - **Prompt:** Edit the default preset prompt or write a custom prompt. - **TypeScript code:** Define custom post-processing logic for TypeScript steps. - **Inputs:** Control available context for AI/TypeScript steps: - Clean messages list - Session memory input (`none`, `all`, or selected keys) - User memory input (`none`, `all`, or selected keys) Use presets when you need a quick starting point, then customize prompt/model settings only where needed. ### Execution Use this tab to define a staged execution protocol for the configuration and inspect recent sessions that ran under it. - **Tool result compaction:** Gaia assigns each known internal tool a concrete **Model result mode**. Document search/read tools use semantic previews, mutation/list tools use status and handles, and custom tools send full output first while allowing compact retry on context failure. Tool authors can explicitly choose semantic preview, status and handles, full output with compact retry, full output with no safety retry, or omit from model context. - **Enable staged execution:** Turn the protocol on or off for this configuration. - **Template:** Start from the default `Plan -> Execute -> Verify` flow or apply a deeper research-oriented template. - **Saved protocol:** Apply a reusable template from [AI Agents → Protocols](#doc-agents-protocols). Gaia copies the stages plus any bundled starter skills and tools into the current config. - **Protocol name and version:** Label the protocol independently from the rest of the config so changes are reviewable. - **Initial stage:** Choose which stage governs the first turn of a new execution session. - **Stages:** Add, remove, or reorder the linear stage list. Gaia automatically derives the next-stage transition from the order you set here. Per stage, you can define: - **Stage label and id:** Human-readable label plus a stable machine reference. - **Description and instructions:** The stage objective and the guidance that becomes part of the runtime prompt. - **Allowed skills and allowed tools:** Narrow the execution surface for the current stage with a tag input plus searchable command picker. - **Expected outputs and exit criteria:** Make stage completion explicit and reviewable. - **Structured outputs:** Optional typed checkpoint fields such as strings, arrays, booleans, numbers, or objects. Gaia validates required fields and value types before accepting the checkpoint. - **Requires user confirmation:** Pause after a completed stage until the user approves moving on. - **Keep always-on tools:** Retain navigation, help, memory, and checkpoint tools even when the stage is otherwise narrow. - **Max turns:** Advisory upper bound for how long Gaia should stay in the stage before the operator reviews it. The same tab also shows **Recent execution sessions** for this config, including: - session status such as active or waiting for user - status filtering so you can isolate active, waiting, completed, cancelled, or failed runs - current stage and pending next stage - latest checkpoint summary - latest structured checkpoint outputs for the active stage - open questions captured by the current stage - recent session events, with event-type filtering when you need to focus on one part of the lifecycle - **Cancel** to stop an active staged run without deleting its audit trail - **Restart** to create a fresh staged run for the same conversation from the protocol's initial stage For live conversations in the main project **Conversations** workspace, the toolbar's **Execution** button opens the same run as a compact summary above the transcript. It is read-first: Gaia shows the current stage, any pending next stage, the latest checkpoint summary, and any typed checkpoint outputs once you expand **Review details**. If a stage is waiting for confirmation, advance it by replying with an explicit approval such as "continue" or "approved, move on". If a stage is blocked, reply with the missing input or evidence so Gaia can continue the same stage. Session administration such as **Cancel** and **Restart** still lives in **Recent execution sessions**. A staged session follows a predictable lifecycle: - Gaia starts at the configured **Initial stage** when a conversation enters the protocol. - The active stage narrows the prompt, skills, and tools for the current turn. - The turn is not complete until Gaia records a stage checkpoint. - A completed stage either advances immediately or pauses for approval, depending on **Requires user confirmation**. - Blocked runs stay reviewable instead of silently resetting, and operators can cancel or restart them without losing the session history. This is the main place to configure staged behavior for Gaia and for ordinary project agents. ### UI Messages Customize error and UI messages shown to users: - **Error messages:** Responses for different error scenarios (multilingual) - **UI messages:** Labels and prompts shown in the interface (multilingual) The localized **prompt-injection-refusal** error message controls the exact reply used when a user asks the assistant to ignore protected instructions or reveal a hidden prompt. Gaia selects the value using the conversation's active language, and project administrators can customize each language in the Error messages grid. All messages support multiple languages to match your user base. The messages grid shows **Name**, **English**, and one selected language by default, with an optional **Compare with** language column for side-by-side review. Use the grid-level **Add language** control to add a new language across the whole catalog. Gaia asks whether you want to translate all missing English-backed keys immediately, and if you agree you can choose the model for that one translation run. When a selected UI language is missing an English-backed message, Gaia queues a background autofill job and saves the generated translation back to the owning agent configuration or channel. Conversations use saved translations immediately and only fall back to English while the background job is still pending or failed. This keeps customer sessions from running translation work while still filling new message codes that arrive in a Gaia update. You can still review and edit those saved translations directly in the configuration or channel **Messages** tab. ### Voice Configure voice interactions: - **Realtime Model:** Dedicated model for real-time voice conversations (WebRTC) - **Realtime instructions:** Guidance applied to realtime voice responses (WebRTC) - **TTS Model:** Model used for text-to-speech conversion - **Voice and language:** Choose from the voices and languages published by the selected audio or realtime model definition. Gaia uses the conversation/channel language first, then falls back to the model selector language when generating speech. - **Instructions:** Guide how the TTS should speak (e.g., "cheerful and energetic") - **Transcription Model:** Model for converting speech to text (required for realtime user transcripts) - Some managed realtime deployments require the transcription model to live in the same resource and region as the realtime model. - Azure Speech transcription can be paired with a primary response model and a TTS model when you want Azure Speech for microphone transcription while Gaia keeps the existing response and read-aloud pipeline. - **Test tools:** Upload audio to test transcription and translation ## Working with configurations ### Creating a configuration 1. Navigate to **AI Agents** from the sidebar 2. Select the agent you want to configure 3. Click **Add Configuration** in the configurations panel 4. Fill in the basic settings (name, version) 5. Configure each tab according to your needs 6. Click **Save** when ready ### Editing a configuration 1. Find the configuration in the list 2. Click the pencil icon to open the configuration page 3. Make your changes across any tabs 4. Click **Save** to apply changes The system no longer auto-duplicates on save—you control when versions are created. ### Duplicating a configuration Use the duplicate button to create a copy: 1. Click the duplicate icon next to a configuration 2. Enter a new name and version 3. The copy opens automatically for editing This is useful for experimenting without affecting your active version. ### Making a configuration active Only one configuration per agent can be active at a time: 1. Open the configuration you want to activate 2. Toggle the **Is active** switch 3. Save the configuration The previously active configuration is automatically deactivated. ### Deleting a configuration Deletion is documented in the main AI Agents guide: see [Deleting a configuration](#doc-agents-deleting-a-configuration). (In short: you can only delete **inactive** configurations, so **Delete** is hidden while a configuration is active; deleting may also remove related conversations/evals shown in the confirmation dialog.) ### Export and Import - **Export:** Download a JSON backup of your configuration (including linked skills/tools metadata). - **Import:** Restore a previously exported configuration. On save, Gaia matches linked skills/tools to the destination project's registries by `name + version`; if missing, Gaia creates the registry entries and relinks the configuration automatically. Use these features to: - Back up important configurations - Share settings between projects - Roll back to previous versions ## Tips - **Test before activating:** Create a new configuration, test it in conversations, then mark it active - **Validate post-steps quickly:** After enabling a post-step, run one conversation turn and confirm the expected assessment/topics/memory updates were written for that conversation. - **Keep stages concrete:** A stage should describe one kind of work. If a stage mixes planning, implementation, and verification, split it. - **Use descriptive versions:** Name versions like "production-v1", "experimental-high-temp", "testing-new-tools" - **Document changes:** Use the version field or comments to track what changed - **Compare with Diff/Merge:** Use the Diff/Merge dialog (from the agents page) to compare configurations side-by-side. Text fields show **visual diff highlighting** with inline additions and deletions for quick review. - **Use code editor controls:** TypeScript editors include copy, format, and expand controls. Use **Format code** or the editor shortcut to apply Gaia's TypeScript formatting to the editable script body. - **Start minimal:** Begin with a simple configuration and add complexity as needed - **Use confirmation gates intentionally:** Require user confirmation only when the pause improves control, for example before moving from planning into implementation. - **Test voice settings:** Use the built-in TTS and transcription testing tools before deploying. For Azure Speech, test both the transcription locale and the selected voice/language pair. ## Troubleshooting - **"Save failed":** Check that all required fields are filled and you have admin permissions - **Configuration not showing in conversations:** Verify the configuration is marked as active - **Tools not appearing:** Some tools require specific model types or API support - **Post-step output missing:** Confirm the step is enabled and that at least one conversation turn completed after you saved the configuration - **Execution stage will not advance:** Confirm the current stage checkpoint is complete and, if the stage requires confirmation, that the user explicitly approved continuing - **Execution protocol save error:** Check for duplicate stage ids, missing instructions, or an initial stage that does not match the configured stages - **Temperature is hidden:** Reasoning models automatically use internal temperature control - **Built-in tools not available:** Built-in tools (web_search, code_interpreter) are now configured on AI models from the top-header **Models** page, not in conversation configurations --- # Bridge Agent Settings Bridge Agent settings define how Gaia hands a conversation to an external live chat system and how Gaia receives updates while the handoff is active. Open this page from **AI Agents** by selecting a live chat Bridge Agent, or from a Text channel by using **Open Bridge Agent Settings** in the live chat bridge controls. ## Related pages - [Channels](#doc-conversations-channels) - [Scenario: Live-agent bridge takeover workflow](#doc-conversations-scenarios-live-agent-bridge-takeover-workflow) - [Engineering reference: TypeScript tools](#doc-agents-typescript-tools) ## Bridge runtime Use **Bridge runtime** to choose the provider behavior and copy the inbound URLs that the external live chat system uses. - **Bound channel webhooks** lists the active Text channels currently bound to this Bridge Agent. - **Transport webhook** is the channel-level callback URL for provider status, assignment, typing, message, disconnect, and resume-style updates. - **Conversation webhook template** is the conversation-specific callback URL pattern for starting or resuming external ownership of one conversation. - **Provider** defaults to **Custom**. Use **Custom** when your integration sends Gaia's normalized bridge envelope or when project-owned TypeScript handles the provider mapping. Choose **Genesys** when you want Gaia's reference Genesys adapter and Genesys-specific controls. When **Provider** is **Genesys**, these additional fields appear: - **Adapter mode** describes how the external connection is expected to work. Use **Webhook** for callback-driven integrations, **SDK** for SDK-driven bridge logic, and **Hybrid** when both patterns are involved. - **Provider base URL** stores the provider API base URL when your scripts or adapter settings need one. - **Auth mode** controls how provider callbacks are authenticated. **None** accepts the request without an API-key or signature check, **API key** checks a configured API key, and **Signed webhook** verifies a signature over the incoming request body. - **API key credential reference** is used only when **Auth mode** is **API key**. Prefer a project reference such as `credential:live-chat/api-key` from **Project Settings -> Credentials**. - **Signing secret credential reference** is used only when **Auth mode** is **Signed webhook**. Prefer a project reference such as `credential:live-chat/webhook-secret`. - **Signature header** names the request header that carries the signed-webhook signature. ## Actor registry Use **Actor registry** to define the external participants Gaia can show in the conversation while the bridge is active. - **Add actor** creates another external participant entry. - **Actor name** is the visible participant name shown in the conversation. - **Participant type** controls the participant's runtime semantics and the Gaia default icon used when no custom icon is configured. - Each actor now includes an **Avatar** subsection: - **Avatar icon URL** accepts an absolute `http` or `https` asset URL, or a previously uploaded Gaia asset URL. - **Upload icon** accepts `SVG`, `PNG`, and `WebP`. Gaia sanitizes uploaded SVG assets before storing them. - **Preview** updates before save and reflects the current icon source, background, border, icon color, and icon-color mode. - **Use default icon** clears the custom icon and returns the actor to the Gaia default participant-type icon. - New unsaved actors preview a selected file immediately and upload it when you save Bridge Agent settings. - Saved actors upload replacement icons immediately. - **Avatar background** styles the avatar container behind the icon. - **Avatar border color** styles the actor avatar border. Leave it blank to preserve the current border behavior. Use `transparent` to hide the border. - **Avatar icon color** applies to Gaia's default participant icon and to compatible custom icons when **Icon color mode** is **Apply configured icon color**. - **Icon color mode** chooses whether Gaia preserves the uploaded icon's embedded colors or renders it as a single-color icon using the configured icon color. When Gaia applies the configured icon color, custom `SVG`, `PNG`, and `WebP` actor avatars render through the shared configurable image renderer instead of CSS masking. - **Description** explains what the external participant represents. - **Allow runtime actor overrides** lets the bridge runtime provide a participant identity at runtime when the actor registry does not contain an exact match. - Runtime actor overrides do not replace admin-configured actor avatar visuals. When Gaia resolves a configured actor, the registry-owned icon, background, border, and icon-color mode remain authoritative. - **Require resume summary** requires the external bridge to provide a summary before Gaia resumes ownership after live-agent takeover. ## User-turn routing Use **User-turn routing** to decide what happens when an end user sends a new message while live chat bridge behavior is enabled. - **Takeover only** keeps the default behavior. Gaia routes normally until an external takeover is active; during takeover, new end-user turns stay in the transcript and are available to the bridge without starting another Gaia assistant response. - **Always use Gaia orchestrator** keeps user turns with Gaia even when bridge metadata exists. - **Always use external provider** sends user turns through the Bridge Agent runtime whenever the channel is bound to the Bridge Agent. - **Custom TypeScript decision** runs your routing script for each user turn and lets the script return whether the turn should use Gaia or the external provider. - **Routing TypeScript** appears only for **Custom TypeScript decision**. Use it when routing depends on transcript content, host context, transport status, or provider dispatch logic. - **Execution runtime** shows the selected runtime and its security classification. New routing scripts start on reduced-risk QuickJS WebAssembly; existing scripts without a saved runtime identifier remain on high-risk Legacy Node.js until explicitly switched and tested. - **Context API** keeps existing routing scripts on v1 and starts new scripts on portable v2. - **Execution timeout (ms)** limits how long the routing script can run. Leave it blank to use Gaia's default timeout. Routing scripts use the same storage helpers as TypeScript tools, handoff rules, and bridge hooks. For live chat bridge correlation data, routing scripts and hooks share a channel-scoped bridge storage namespace. This lets an outbound hook or routing script store a durable lookup record such as `genesysConversationId -> gaiaConversationId`, and then lets the next routing script or incoming hook read it before Gaia resolves the conversation. ## Bridge hooks Use **Bridge hooks** when the external system needs payload shaping before or after Gaia stores bridge events. - **Outgoing hook TypeScript** runs when Gaia is preparing a bridge-owned outbound request. Use it to shape the payload sent to your integration layer or to dispatch it to an external provider service. - **Incoming hook TypeScript** runs on the channel-level transport webhook before Gaia loads the conversation. Use it to parse raw provider callbacks, return the target `conversationId`, and emit canonical ingress events such as transport, message, presence, or resume-suggestion updates. - **Execution runtime** uses the same security-classified selector as routing scripts. New hooks start on QuickJS WebAssembly, while existing hooks retain their stored or legacy runtime. - **Context API** uses the same v1 compatibility and v2 portable defaults as routing scripts. For message ingress events, return a stable `eventId`, the provider source time as `occurredAt`, and an optional numeric `sequence`. Gaia serializes updates per conversation, suppresses retries by `eventId`, and orders rapid messages by source time, sequence, then event identity. Messages arriving more than two minutes behind the latest ordered bridge message are appended and logged as late instead of rewriting older transcript history. Conversation-specific `message` actions accept the same fields. - **Execution timeout (ms)** limits how long each hook can run. Leave it blank to use Gaia's default timeout. Outgoing and incoming bridge hooks share the same channel-scoped storage namespace for the bound channel, and routing scripts use that same bridge storage namespace as well. That lets an outgoing hook or user-turn routing script persist provider correlation records such as `genesysConversationId -> gaiaConversationId`, and then lets the incoming hook read those records before Gaia knows the target conversation. Incoming hook `input` still stays limited to ingress-real data such as the webhook payload, channel, agent, and participant details when available, but the execution context exposes the normal utility surface, including project-scoped search/entity helpers and storage helpers. Conversation-specific bridge callbacks continue to use their explicit `action` payloads and do not run the incoming hook. For Genesys scripts, prefer `externalBridge.dispatchProviderRequest(...)`; this is the portable context-v2 path. Lower-level SDK code using `liveAgent.loadLibrary('genesys')` is available only in context v1 with Legacy Node.js. The host-scoped `liveAgent.getAuthenticatedClient('genesys')` helper remains blocked by default because the SDK client is process-global. ## Save behavior Click **Save Bridge Agent Settings** after changing runtime, actor, routing, or hook fields. Gaia requires TypeScript routing and hook code to be compiled before it can be saved. --- # Guardrails The **Guardrails** tab in **AI Agents** is the shared registry for versioned controls that run around an agent turn. Use guardrails for real-time conversation scope, instruction confidentiality, and response validation. Validators are therefore one guardrail kind, not a separate control system. ## Guardrail kinds - **Conversation scope** runs before routing or model generation and can allow, flag, or block an out-of-scope request. This is where off-topic detection lives. - **Instruction confidentiality** blocks requests that try to obtain protected system or developer instructions. It is an explicit runtime control rather than a hidden prompt clause. - **Response validation** checks a draft response after model generation. It supports Gaia's deterministic and AI validator definitions. Each definition declares its runtime phases, supported channels, failure mode, and default enforcement mode. Config assignments pin an exact registry version and may override enablement, priority, phases, and enforcement mode. ## Enforcement modes - **Shadow** records what the guardrail would decide without changing the turn. - **Review** records a review finding without enforcing a block or retry. - **Enforced** applies blocks, retries, or transforms to the live turn. - **Disabled** keeps the assignment but does not execute it. Use shadow mode before enforcement when introducing a broad scope or validation rule. Guardrail decisions include the guardrail and version, phase, outcome, latency, and linked governance policy identity when configured. ## Create and assign a guardrail 1. Open **AI Agents → Guardrails**. 2. Select **Add guardrail**. 3. Choose the kind, runtime phases, failure mode, and default enforcement mode. 4. Enter the kind-specific JSON definition. For response validation, include the validator definition. 5. Optionally link the guardrail to a governance policy. 6. Save the immutable version. 7. Open [Agent Configuration](#doc-agents-configs), find **Guardrails**, and attach the version to the configuration. 8. Choose its assignment mode and priority, then save the configuration. To change executable behavior, create a new version and update assignments deliberately. Existing versions only allow metadata and governance-policy linkage changes. ## Governance relationship Guardrails are runtime enforcement mechanisms. Governance policies describe why a control exists, its ownership, review posture, and evidence expectations. Linking a policy does not replace the guardrail definition; it makes runtime decisions traceable to the governance record. ## Access requirements - **View guardrails** opens the registry and allows guardrail assignments to be inspected. - **Modify guardrails** creates versions, updates metadata, links policies, and deletes unassigned entries. - Governance-policy visibility is required to select a linked policy. ## Related docs - [Agent Configuration](#doc-agents-configs) - [Governance policies](#doc-governance-policies) - [Evals](#doc-evals) - [Document folders](#doc-conversations-document-folders) --- # Skill registry The **Skills** tab in **AI Agents** is the centralized catalog of reusable skills for a project. Interactive walkthrough: Open [Tutorials](/platform/support/tutorials) and select **Registry Basics: Skill Registry**. It demonstrates a complete flow: define instructions, link a registry tool, and duplicate the saved skill into a new version. A _skill_ is a bundle of: - **Prompt fragments**: ordered instructions the agent can follow when it decides to use the skill. - **Tools**: a curated set of tools that the skill relies on. Skills are defined once in the registry and then linked into agent configurations via the **Skills** tab inside a configuration. This page describes Gaia runtime skills used by agents inside Gaia projects. For external coding-agent adapters, see [Coding agents](#doc-coding-agents). ## What it’s for - Create a shared skills library your team can reuse across multiple agents. - Keep skill behavior consistent as you iterate on instructions or tool lists. - Organize capabilities into coherent packages such as customer lookup, order troubleshooting, or entity search. ## How it connects to agent configs In **AI Agents → Agent Configuration → Skills** you select which registry skills an agent is allowed to use. Each configured skill also has an optional **Rule** describing when it should be used. At runtime, Gaia evaluates your **Skills prompt** together with the conversation context and those skill rules to decide which skills to enable. For the configuration-side controls, see [Agent Configuration](#doc-agents-configs). ## Create and edit a skill 1. Open **AI Agents → Skills**. 2. Click **Add skill**. 3. Use the tabs to fill in the definition: - **General**: name, version, description, and tags. - **Instructions**: the skill’s prompt fragments. - **Tools**: the tools that this skill can use. 4. Click **Save**. ## Duplicate a skill into a new version Use the duplicate action in the grid when you want a new version of an existing skill: 1. Find the saved skill in the registry. 2. Click the duplicate button in the **Actions** column. 3. Gaia creates a new registry entry with the same name and the next available version. 4. Open the new version with **Edit** if you want to refine instructions or tools. ## Related docs - [AI Agents](#doc-agents) - [Agent Configuration](#doc-agents-configs) - [Coding agents](#doc-coding-agents) - [Tool registry](#doc-data-model-tool-registry) - [Agent Config Checklist for Canvas and Document Workflows](#doc-conversations-agent-config-checklist) ## Access requirements - You need **View skill registry** to open this tab. - You need **Manage skill registry** to create, update, or delete skills. --- # MCP server registry The **MCP Servers** tab in **AI Agents** is the shared catalog for remote HTTP/SSE Model Context Protocol servers that Gaia agents can use. An MCP server is configured once in the registry and then added to one or more agent configurations. At runtime, Gaia discovers the server's remote MCP tools and exposes them to the model with stable Gaia-safe names. ## What it’s for - Reuse the same remote MCP server settings across multiple agents. - Keep server URLs, auth mode, and allow/deny lists consistent. - Avoid creating one manual MCP tool record for every remote server tool. - Keep manual MCP tools available only for pinned aliases or one-off overrides. ## Create and edit a server 1. Open **AI Agents → MCP Servers**. 2. Click **Add MCP server**. 3. Fill in the server name, key, transport, URL, and auth settings. 4. Use **Tool allowlist** or **Tool denylist** when only part of the remote server should be available. 5. Click **Save**. The server key becomes the stable namespace for generated tool names. Use short lowercase keys such as `microsoft-enterprise`. Use an absolute HTTP(S) URL with a static origin. Runtime discovery and tool calls are restricted to that exact origin, and every redirect is checked again. Gaia blocks hosts that resolve to local, private, link-local, metadata, or other special-use addresses. A Gaia deployment operator can approve a legitimate private service by adding its exact origin to `GAIA_AI_EGRESS_PRIVATE_ORIGINS`; this is a host-level exception, not an agent or project setting. ## Presets The MCP server dialog includes a **Presets** menu. The first preset is **Microsoft Enterprise MCP server**, which fills: - name: `Microsoft MCP Server for Enterprise` - server key: `microsoft-enterprise` - URL: `https://mcp.svc.cloud.microsoft/enterprise` - transport: `HTTP` - session auth: enabled Before testing that preset, the Microsoft Entra application used by Gaia must be granted access to the Microsoft Enterprise MCP server in the customer tenant. For Azure deployment operator steps, see [Azure Hosting and Deployment](../../installation-guide/cloud-providers/azure-hosting-and-deployment.md#microsoft-enterprise-mcp-server-permission-grant). ## Add servers to an agent 1. Open **AI Agents** and edit the target agent configuration. 2. Open the **MCP Servers** tab. 3. Click **Add from registry** to copy a shared server into the agent, or click **Add server** for an agent-specific definition. 4. Save the configuration. Agent-specific servers are stored only on that configuration. Registry servers copied into a configuration are runtime settings for that agent; generated remote tools are not persisted as normal tool registry records. ## Related docs - [AI Agents](#doc-agents) - [Agent Configuration](#doc-agents-configs) - [Tool registry](#doc-data-model-tool-registry) - [Azure Hosting and Deployment](../../installation-guide/cloud-providers/azure-hosting-and-deployment.md) ## Access requirements - You need **View agents** to open this tab. - You need **Manage agents** to create, update, delete, or attach MCP servers. --- # Engineering reference: TypeScript tools Gaia tools can be implemented in **TypeScript** and enabled per agent configuration. This lets engineering users build project-specific tool behavior without deploying new backend code. This page documents the **exact runtime contract** for TypeScript tools. ## What Gaia executes Gaia stores: - `codeTs`: the TypeScript you edit. - `codeJs`: the compiled JavaScript executed at runtime. The tool editor exposes an **Execution runtime** selector and its security classification: - **Legacy Node.js — High risk:** the compatibility default for existing tools. It executes inside Gaia's Node.js process and should be limited to trusted scripts. - **QuickJS WebAssembly — Reduced risk:** executes in a QuickJS WebAssembly context on a worker thread. Gaia capabilities cross an explicit bridge instead of being passed into the script as Node.js host objects. This reduces risk but still shares Gaia's process. New TypeScript tools start on QuickJS WebAssembly. Existing tools that predate runtime selection remain on Legacy Node.js until an owner explicitly switches and tests them. The adjacent **Context API** selector is versioned separately: - **Context v1 · Native compatibility** preserves existing definitions and native-object helpers. - **Context v2 · Portable** exposes transport-safe Gaia capabilities in either runtime and is the default for new tools. Missing context-version metadata resolves to v1. Select v2 before moving scripts that use portable capabilities to QuickJS. Native SDK and library objects remain v1 plus Legacy Node.js-only. Switching runtimes does not rewrite the tool. Use **Test** after selecting QuickJS and before production use. Standard JavaScript, asynchronous Gaia utilities, `Buffer`, timers, and the allowlisted hash/HMAC crypto surface are supported. Node-specific behavior and utilities that return SDK client objects can require a script change. Project owners are responsible for the risk of the runtime they select. Both runtimes apply these compatibility rules: - `require()` is allowlisted to built-in `crypto` only (`'crypto'` / `'node:crypto'`). - TypeScript `import ... from "crypto"` is supported (compiled to allowlisted `require`). - Imports from npm packages and other Node modules are not supported. - Use `context.utils` for platform-provided capabilities (fetch, storage, entities, graph, etc.). - The tool editor also exposes an optional **Execution timeout (ms)** field. Leave it blank to keep Gaia's default limit, or set a higher value for heavier work. When you set a value, Gaia applies it to both synchronous execution and awaited async work. - Use **Format code** in the TypeScript editor, or the editor shortcut, to apply Gaia's TypeScript formatting to the editable script body before saving. ## Handler function name Gaia attempts to call one of these entrypoints (in order): 1. `execute(context, input)` 2. `transform(context, input)` If neither is defined, execution fails. ## Inputs - `input` is the parsed JSON arguments passed by the model when calling the tool. - `context.original` is also set to the same object as `input`. You should validate `input` defensively because the model can send unexpected shapes. ## Output Your handler must return a **JSON-serializable object**. ### Conversation appends (optional) If a TypeScript tool wants to add an assistant-visible note to the current conversation, it can return `appendToConversation`. Gaia materializes these entries after the tool loop completes, keeps them out of the model-facing tool output, and persists them as assistant messages in the conversation history. Supported shapes: - `appendToConversation: 'Text to add'` - `appendToConversation: { content: 'Text to add', name: 'Display name' }` - `appendToConversation: [{ ... }, '...']` Example: ```ts export async function execute(context: any, input: any) { return { result: { forwarded: true }, appendToConversation: { content: 'Transcript forwarded to the live support queue.', name: 'Genesys bridge', }, }; } ``` ### UI updates (optional) If your tool returns an object containing a `uiUpdate` property, Gaia forwards it to the UI. Example: ```ts export async function execute(context: any, input: any) { return { uiUpdate: { page: 'projects', tab: 'configs', }, result: 'Navigated', }; } ``` ## State and storage TypeScript tools get both: - `context.state`: in-memory state for the current execution. - Scoped storage helpers via `context.utils.*StorageData`: - `readStorageData(key)` - `writeStorageData(key, data)` - `queryStorageData(keyPattern)` - `deleteStorageData(key)` When code runs inside a conversation, storage is shared across all user-authored TypeScript for that conversation. TypeScript tools, TypeScript handoff rules, Bridge Agent outgoing hooks, and Bridge Agent routing scripts can read and write the same stored objects. Bridge Agent incoming hooks also keep the shared utility surface, including project-scoped data/search helpers and storage helpers, but their `input` does not include conversation transcript or transport fields yet. Bridge hooks and bridge routing scripts use a shared channel-scoped storage namespace for the bound channel, so routing, outgoing hooks, and incoming hooks can exchange provider correlation records before Gaia resolves the conversation. Use clear key prefixes such as `tool::`, `handoff:`, or `bridge:` so separate scripts do not overwrite each other's values. Draft, preview, and standalone test runs that are not attached to a conversation still use isolated storage scopes. If an explicit execution timeout expires, Gaia stops waiting for the tool result and blocks later writes through the guarded `context` object. Any external request that has already been sent may still complete outside Gaia, so set appropriate request-level timeouts when calling systems that need tighter cancellation behavior. ## Utilities (`context.utils`) Tools receive the same `context.utils` surface documented in: - [Engineering reference: TypeScript in data pipelines](#doc-data-model-typescript-pipelines) In practice, most tools use: - `fetch` for HTTP - `downloadUrl` for fault-tolerant, size-bounded PDF or binary downloads with abortable timeouts, retries, content-type checks, and optional file-signature validation - `getCoreConversationMessages` for the current user/assistant transcript without system, handoff, or tool-call noise - `getHostContext` for ephemeral JSON provided by an embedding host page for the current conversation session - `getIntegrationContext` for bridge metadata such as host-context origin/session details and external transport correlation state - `externalBridge.dispatchProviderRequest` when a live-support adapter needs the latest user turn plus a normalized bridge envelope without rebuilding transcript and correlation fields by hand - Context v1 with Legacy Node.js: `liveAgent.loadLibrary('genesys')` plus `await liveAgent.resolveCredential(...)` when a Genesys Bridge Agent hook needs lower-level SDK access with an explicit project credential reference - `searchAcrossEntities` / `getEntityRecord` / `upsertEntityRecord` for data access (`searchAcrossEntities` text filters support `$like` and `$not-like` with `*` or `%`) - `markdownToChunks` / `htmlToText` / `htmlToMarkdown` for text preparation - `decodeQrFromDocument` for generic QR decoding from base64 PDF, PNG, or JPEG documents - `pdfToPositionedText` for deterministic PDF extraction that needs page and row/column metadata - `compareDocumentVisuals` for generic page-count and visual-similarity metrics; the project tool remains responsible for domain-specific thresholds and rejection decisions For resilient file retrieval, prefer `downloadUrl` over hand-written retry loops: ```ts const downloaded = await context.utils.downloadUrl(sourceUrl, { method: 'GET', maxAttempts: 3, timeoutMs: 10_000, maxResponseBytes: 20 * 1024 * 1024, allowedContentTypes: ['application/pdf'], expectedContent: 'pdf', }); if (!downloaded.ok) { return { retryable: downloaded.error?.retryable ?? false, attempts: downloaded.attempts, }; } const pdfBase64 = downloaded.base64; ``` Attempt metadata contains status, timing, content type, size, and a normalized outcome. It does not contain the URL, request headers, response body, authorization data, or cookies. Keep service-specific session establishment, token refresh, and rejection semantics in the project tool. `getCoreConversationMessages()` returns the current in-memory conversation view for the active tool call. It includes only `user` and `assistant` turns, and strips system messages, handoffs, tool calls, tool results, off-topic markers, and error turns. `getHostContext()` returns the latest validated host-provided JSON object for the current embedded conversation session, or `null` when the app is not running inside a host bridge. `getIntegrationContext()` returns a structured object with: - `hostContext`: the same ephemeral JSON object returned by `getHostContext()` - `hostContextOrigin`: the validated origin that supplied that host context - `hostContextSessionId`: the current host bridge session ID - `externalTransport`: durable bridge transport state such as correlation IDs, queue state, assignment state, and lifecycle status `externalBridge.dispatchProviderRequest()` sends a POST request by default and wraps your project payload inside a standard `bridge` object that contains: - `projectId` - `conversationId` - `channel` - `latestUserMessage` - `transcript` - `hostContext` - `integrationContext` - `correlationId` - `sessionId` Use it when the provider needs a stable envelope for the current routed turn, but you still want to control the destination URL, auth, and any project-specific `payload` fields. For provider calls that can safely be retried, add `retry.maxAttempts`, `retry.backoffMs`, and optional `retry.retryStatuses`. Gaia returns `attempts` and `telemetry` on the dispatch result so the hook can inspect the final status, attempt count, retryable failures, and bridge correlation identifiers. Do not pass host-scoped Genesys access tokens through `liveAgent.getAuthenticatedClient('genesys')`. The legacy helper is blocked by default because the Genesys SDK client is process-global. Context v2 scripts should use `externalBridge.dispatchProviderRequest(...)`. Lower-level `liveAgent.loadLibrary('genesys')` SDK access is limited to context v1 with Legacy Node.js. ## Pattern: project-authored live-support adapters Gaia now includes a reference Genesys transport adapter on the provider-facing transport route. The intended pattern is still: - bind the channel to a Bridge Agent and keep channel-local bridge controls limited to origins and host context - configure provider auth, actors, routing, incoming hooks, and outgoing hooks on the Bridge Agent - keep vendor-specific outbound logic in your own TypeScript tool or workflow - keep vendor-specific webhook and polling orchestration in your own integration surface, using Gaia's dispatch retry option only for safe outbound retries - use Gaia's provider-facing transport route either with a reference adapter such as `provider: "genesys"` or with your own normalized transport envelope This keeps Gaia's runtime generic while giving projects a concrete reference adapter for webhook normalization without forcing Gaia to own every vendor-specific outbound workflow. In practice, most projects split responsibility like this: - the TypeScript tool or routing script sends transcript, host context, and correlation metadata to the vendor - the vendor integration service sends explicit takeover actions back to Gaia on the conversation bridge route and sends queue, assignment, or session webhook updates on the transport route Generic bridge route shape: - `POST /api/apps//conversations//external` Provider-facing transport route shape: - `POST /api/apps//external/transport` Useful bridge actions: - `start` to begin takeover - `message` to append an external participant message - `event` to update queue, assignment, status, correlation, or session metadata without necessarily appending a visible message - `resume` to end takeover and optionally add the summary Gaia should retain Use the provider-facing transport route when the vendor webhook knows the channel plus a transport identifier such as `correlationId` or `sessionId`, but does not know Gaia's conversation ID. Gaia resolves the conversation from the channel, `system`, and the provided transport identifier before it merges the normalized transport state. Bridge Agent auth can use API-key mode or signed-webhook mode. Signed webhooks use an HMAC SHA-256 signature over the exact request body. Gaia accepts signatures in the configured header as either hex or `sha256=` and returns stable error codes such as `external_bridge_signature_invalid` or `external_bridge_provider_unsupported` when verification or provider normalization fails. Example provider-facing transport payload using a Genesys-style outbound `StructuredMessage` body: ```json { "provider": "genesys", "providerPayload": { "type": "message", "class": "StructuredMessage", "code": 200, "body": { "direction": "Outbound", "id": "message-123", "channel": { "time": "2026-04-16T10:00:00Z", "messageId": "message-123", "from": { "id": "participant-789", "nickname": "Taylor Agent" } }, "metadata": { "correlationId": "conversation-123", "sessionId": "session-456" }, "type": "Text", "text": "How can I help?", "originatingEntity": "Human" } } } ``` The reference Genesys adapter also accepts messaging conversation snapshots with `participants` for queue and assignment updates. Example normalized `event` payload sent from your own integration layer when you are not using a built-in adapter: ```json { "action": "event", "eventType": "assignment", "transport": { "system": "genesys", "correlationId": "conversation-123", "sessionId": "session-456", "status": "assigned", "assignment": { "id": "agent-789", "participantName": "Taylor Agent" }, "references": { "vendorConversationId": "conversation-123" } } } ``` That payload updates Gaia's durable external transport state so later TypeScript tools can read it from `context.utils.getIntegrationContext()`. When a provider transport event implies Gaia should resume, Gaia returns a `suggestedBridgeAction` in the transport-route response. Treat that as a recommendation. The actual resume still happens through the conversation bridge route so transcript-affecting behavior stays explicit. `searchAcrossEntities` operator quick reference: - `text` / `normalized-text` / `enum`: direct value, `$eq`, `$ne`, `$like`, `$not-like`. - vector-capable text fields can also use similarity-style direct values. - `number` / `date` / `timestamp` / `time`: `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$between`. - any type: `{ empty: true }`, `{ "not-empty": true }`. Entity record writes (`createEntityRecord` / `updateEntityRecord` / `upsertEntityRecord`) also support an optional `relationships` parameter so you can set FK-based links atomically when needed. ## Example: entity lookup tool ```ts export async function execute(context: any, input: any) { const entityName = String(input.entityName || '').trim(); const id = String(input.id || '').trim(); if (!entityName || !id) { return { error: 'entityName and id are required' }; } const record = await context.utils.getEntityRecord(entityName, id); return { record }; } ``` ## Example: live-agent bridge tool ```ts export async function execute(context: any, input: any) { const bearer = await context.utils.liveAgent.resolveCredential( 'credential:live-support/dispatch-bearer', ); const response = await context.utils.externalBridge.dispatchProviderRequest({ url: 'https://example.invalid/live-support', headers: bearer ? { Authorization: `Bearer ${bearer}` } : {}, retry: { maxAttempts: 3, backoffMs: 250, retryStatuses: [408, 429, 500, 502, 503, 504], }, payload: { queue: 'billing', source: 'gaia-typescript-tool', }, }); return { result: response.data, attempts: response.telemetry.attemptCount, appendToConversation: { content: 'Transcript forwarded to live support.', name: 'Genesys bridge', }, }; } ``` This example is intentionally generic. Replace the outbound URL, auth, and project-specific payload fields with your own adapter logic. Gaia fills the shared `bridge` envelope automatically so you do not have to rebuild transcript, channel, and correlation metadata inside each tool. For lower-level SDK usage in context v1 with Legacy Node.js, load an approved live-agent package with `context.utils.liveAgent.loadLibrary(...)`, resolve a `credential:` project reference, then configure the SDK client in your hook code. Context v2 intentionally omits SDK factories; use `externalBridge.dispatchProviderRequest(...)` for the portable path. ## Troubleshooting - If execution fails with “TypeScript code must define a function named…”, ensure you exported or defined `execute`. - If you need HTTP, use `context.utils.fetch` rather than trying to import a client. --- # Validators moved to Guardrails Response validators are now the **Response validation** kind in the [Guardrails registry](#doc-agents-guardrails). Existing validator records and configuration fields remain supported for compatibility, while new controls should be created and assigned through **AI Agents → Guardrails**. See [Guardrails](#doc-agents-guardrails) for runtime phases, enforcement modes, versioning, governance-policy linkage, and permissions. --- # Data Model The **Data Model** workspace lets admins define the structured data that agents read from and write to. It brings together everything you need to manage entities, data flows, automations, tool definitions, and run history in one place. Interactive walkthrough: Open [Tutorials](/platform/support/tutorials) and start the tab-specific Data Model tutorial for the area you need (Entities, Storage, Pipelines, Workflows, Runs, Tool registry, Composite tools, or Scheduled Jobs). ## Tabs at a glance - **Entities:** Define schema (properties, exclusions), decide which data appears in conversations, and attach UI layouts. Supports both **relational** (SQL tables) and **graph** (Apache AGE property graph) entity types. See [Entities](#doc-data-model-entities). - **Storage:** Organize project files in blob storage, preview supported formats, and manage uploads or deletions. See [Storage](#doc-data-model-storage). - **Databricks:** Configure the project Databricks readiness profile, evidence references, and current readiness status. See [Databricks data platform](#doc-data-model-databricks-data-platform). - **Pipelines:** Configure scheduled or on-demand data flows between sources and targets. See [Pipelines](#doc-data-model-pipelines). - **Workflows:** Compose automations either in the workflow graph editor or in the workflow dialog for legacy pipeline-list definitions. See [Workflows](#doc-data-model-workflows). - **Runs:** Monitor execution history, status, and logs so you can troubleshoot quickly. See [Runs](#doc-data-model-runs). - **Tool registry:** Manage shared tools that can be reused across agent configurations. See [Tool registry](#doc-data-model-tool-registry). - **Composite:** Open a composite-only view of the registry when you want to focus on multi-step reusable actions without paging through every other tool type. See [Tool registry](#doc-data-model-tool-registry). - **Scheduled:** Define scheduled jobs (tool calls or internal operations) that run on a recurring schedule. See [Scheduled](#doc-data-model-scheduled). When the customer data platform is Databricks, open **Data Model -> Databricks** to capture the selected SQL warehouse, Unity Catalog, Vector Search, export, connector, or external-agent evidence path. ## Toolbar buttons The Entities toolbar includes additional actions: - **Visualize:** Opens a dedicated visualization page showing entity relationships. - **Similarities:** Explores semantic similarities across entity records. - **View Data:** Opens a dedicated data-viewer page for browsing relational entity records. - **View Graph:** Opens a dedicated Graph Data Viewer page for querying graph entities using Cypher. ## Access requirements - Only **project admins** can open the Data Model tools from the sidebar. Maintainers can still view entity data through conversations but cannot change the schema. - Destructive actions (such as deleting entities or dropping tables) always ask for confirmation before they apply. ## Typical workflow 1. Open **Data Model → Entities** to define or edit your schema. 2. (Optional) Attach a [UI Layout](#doc-conversations-ui-layouts) so end users can view or edit entity data inside conversations or published apps. 3. (Optional) Upload reference files or generated outputs in **Storage** so they stay versioned alongside your entities. 4. Configure **Pipelines** to populate or transform the data. 5. Use **Workflows** to orchestrate multi-step operations, either through graph-based routing and control blocks or by maintaining older pipeline-list workflows. 6. Watch **Runs** to ensure everything stays healthy. 7. If a run pauses for human approval or input, open **Conversations -> Actions**. ## Walkthrough snapshots ## Real-life example > An insurance operations team created an Incident Report entity with fields for policy number, severity, and notes. They connected a pipeline that ingests reports from a spreadsheet and a workflow that enriches each record with risk scores. The orchestrator agent now surfaces incidents in [Conversations](#doc-conversations) and writes updates back to the same entity. ## Related docs - [Entities](#doc-data-model-entities) - [Storage](#doc-data-model-storage) - [Databricks data platform](#doc-data-model-databricks-data-platform) - [Pipelines](#doc-data-model-pipelines) - [Workflows](#doc-data-model-workflows) - [Runs](#doc-data-model-runs) - [Tool registry](#doc-data-model-tool-registry) - [AI Agents](#doc-agents) - [Guardrail registry](#doc-agents-guardrails) - [Skill registry](#doc-agents-skills) - [UI Layouts](#doc-conversations-ui-layouts) for custom forms based on entity data. - [File extractor registry](#doc-conversations-file-extractor-registry) for reusable upload extraction tied to channel workflows. ## Troubleshooting - **Missing tabs:** Refresh the page. If you're redirected to Conversations, you may not have admin rights for the Data Model. - **Schema changes not showing up:** Open the entity page and click **Sync Database** (relational) or **Sync Graph** (graph) to apply the updates. - **View Graph button shows no entities:** Only graph-type entities appear in the Graph Data Viewer. Create a graph entity first or convert an existing entity. --- # Databricks data platform Use this page when Databricks is the customer data and agent platform for a Gaia project and the review needs proof that Gaia can connect to governed data or Databricks-hosted agents without bypassing the customer boundary. Databricks integration evidence should stay explicit about the access path. Gaia can treat Databricks as a governed source of structured data, a retrieval backend, an external agent platform, or an external evidence system depending on the selected project design. ## Integration profiles | Profile | Gaia evidence path | What to capture | | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | SQL warehouse read path | Project service account, Databricks service principal or connector principal, workspace ref, SQL warehouse, catalog, schema, view | Read-only query test, row limit, allowed tables/views, allowed query-pattern refs, query timeout, result shape, audit or lineage row, and delivery task. | | Unity Catalog governance path | Databricks catalog/schema/table or view permissions plus Gaia project role and governance evidence | Principal mapping, object scope, allowed privileges, data classification, access review date, and offboarding owner. | | Vector Search retrieval path | Document Folder retrieval backend posture plus Databricks Vector Search endpoint and index | Index name, source Delta table or direct index source, metadata filters, hybrid/vector mode, retrieval-quality eval, and fallback. | | Databricks agent path | Databricks Agent Framework, Mosaic AI agent endpoint, managed MCP server, external MCP server, or connector | Agent endpoint or app, tool scope, MCP/server list, model endpoint, evaluation result, trace/monitoring link, Gaia handoff, audit. | | Delta export or file ingest | Databricks-managed export into a Gaia-supported file or object-storage handoff | Export owner, freshness SLA, checksum or version marker, file extractor/index run, failed-row handling, and re-run evidence. | | External agent action path | Microsoft Copilot-style, Salesforce-style, RPA, or custom middleware action that calls Gaia and Databricks | Connector principal, allowed action, schema/action discovery, test invocation, validation gate, telemetry, audit, and support owner. | Use the narrowest profile that satisfies the workflow. Do not grant broad warehouse, catalog, or workspace access when a governed view, export, or Vector Search index is enough. ## Readiness checklist Open **Data Model -> Databricks** to record the project-level readiness profile. The page stores the selected profile, customer references, evidence links, and readiness result with the project settings. It does not require a live Databricks credential, and blocked saves prevent literal secret material from being stored in the project. Before marking a Databricks integration ready, collect: - the Databricks workspace host, workspace reference, cloud, region, and environment name; - the Gaia project, service account, connector principal, and project role; - the selected identity model and identity evidence reference; - the Databricks principal and credential posture, without exposing secret values; - the network posture and network evidence reference, such as Private Link, peering, public internet, customer-managed connector, or no direct runtime access; - the chosen integration profile and excluded profiles; - the SQL warehouse, catalog, schema, tables, views, volumes, Vector Search indexes, agent endpoints, or Databricks Apps in scope; - the access-control evidence for Unity Catalog or the customer-approved connector; - the data classification and masking/redaction expectations; - the query, export, or retrieval test result; - the retry, timeout, row-limit, freshness, and fallback posture; - the Gaia audit, dashboard, eval, delivery, or governance evidence link; - the rotation owner, access review date, and offboarding owner. Record the readiness result as `ready`, `needs customer details`, or `blocked`. A blocked result should only be used for issues that must be fixed before evidence capture can continue, such as literal secret material, an invalid workspace host, or an unsupported agent direction. ## SQL warehouse readiness Use the SQL warehouse path when Gaia needs structured records from Databricks but does not need Databricks to own retrieval ranking. Evidence to capture: 1. Create or choose a Databricks principal for Gaia or the customer connector. 2. Grant only the Unity Catalog privileges needed for the selected catalogs, schemas, views, or tables. 3. Use a SQL warehouse dedicated to the integration or clearly shared under a customer-approved policy. 4. Record the allowed query-pattern references before any runtime path uses the warehouse. 5. Run a read-only smoke query with a small row limit. 6. Store the query shape, expected columns, timeout, row limit, masking expectations, and audit or lineage reference in the delivery evidence. 7. Link the Gaia service account, audit row, dashboard signal, and delivery task that prove the integration was tested. If the workflow needs write-back, treat it as a separate approval path. Record the write target, idempotency key, validation rule, and rollback plan before enabling it. ## Vector Search readiness Use the Vector Search path when Databricks should host the customer-managed retrieval index and Gaia should keep orchestration, access checks, citations, evals, and evidence. Evidence to capture: 1. Identify the Vector Search endpoint, index, source table or direct index source, embedding source, metadata fields, and filter fields. 2. Confirm how Gaia project/folder ACLs map to Databricks metadata filters or customer-managed views. 3. Set the deployment retrieval backend posture to `databricks-vector-search` when the Databricks adapter is the intended evidence path. 4. Keep a safe fallback posture until the adapter, index, and eval threshold are accepted. 5. Run the same retrieval-quality dataset used for the Gaia fallback backend. 6. Capture backend id, capability path, ranking profile, query latency, top-k citations, ACL false positives, freshness, and cost. Databricks Vector Search should not replace Gaia evidence. Gaia still needs the proposal row to point to the user-guide page, folder/search diagnostics, eval report, audit evidence, and any deployment caveat. ## Databricks agent readiness Use the Databricks agent path when the Lot B vendor or customer team plans to build or operate agents inside Databricks Agent Framework and Gaia needs to interoperate with those agents. Choose the direction explicitly: - **Databricks agent calls Gaia:** the Databricks agent uses a Gaia MCP endpoint, API action, webhook, or customer connector to reach Gaia-controlled project context, evidence, or tools. - **Gaia calls Databricks agent:** Gaia treats the Databricks agent endpoint, Databricks App, or customer middleware as an external governed action. - **Shared certification only:** Gaia and Databricks agents are tested against the same eval, delivery, audit, and support handoff evidence without direct runtime calls. Evidence to capture: 1. Identify the Databricks agent, serving endpoint, Databricks App, or middleware endpoint. 2. Record whether the Databricks agent uses managed MCP servers, external MCP servers, Unity Catalog functions, Vector Search, SQL, REST APIs, or custom tools. 3. Capture the Gaia project, service account, MCP skill scope, webhook, or API action exposed to Databricks. 4. Capture the Databricks principal, Unity Catalog permissions, model endpoint, tool scope, and credential owner. 5. Run a read-only tool or conversation smoke test in the chosen direction. 6. Pair the smoke test with a Gaia eval or Databricks evaluation result, plus audit, trace, dashboard, or delivery evidence. 7. Record the owner for escalation, access review, credential rotation, and offboarding. Do not treat a Databricks-hosted agent as automatically governed by Gaia. Gaia evidence needs the explicit integration boundary, permitted actions, eval result, audit trail, and support handoff. ## Connector and external-agent readiness Use this profile when Databricks is reached through Microsoft Copilot, Salesforce, RPA, middleware, or a customer-managed connector rather than directly from Gaia. Evidence to capture: - the external platform and connector identity; - the accountable connector owner; - the Gaia service account or API principal used by the connector; - the Databricks principal or delegated customer-approved access path; - the allowed actions, schemas, and payload shapes; - one read-only discovery or test invocation; - the validation, eval, or human-review gate; - telemetry and audit evidence from Gaia and the customer connector; - the support handoff and offboarding owner. Pair this page with [Lot B interoperability evidence](#doc-coding-agents-lot-b-interoperability-evidence) when the Databricks path or Databricks agent is owned by the external Lot B vendor. ## Related pages - [Data Model](#doc-data-model) - [Document Folders](#doc-conversations-document-folders) - [Control Plane Evidence](#doc-control-plane-evidence) - [Service accounts](#doc-settings-service-accounts) - [Evals](#doc-evals) - [Audit Trail](#doc-audit) --- # Entities Manage schema, properties, and UI bindings for the structured records your agents rely on. The Entities tab brings everything together so you can design and maintain data models with confidence. Interactive walkthrough: Open [Tutorials](/platform/support/tutorials) and select **Data Model Basics: Entities**. The walkthrough now creates an entity end-to-end, adds a property, and saves the definition. ## Entity types Gaia supports two entity types, each suited to different data patterns: | Type | Description | Best for | | -------------- | ------------------------------------------------ | ------------------------------------------------------------------------ | | **Relational** | Traditional table-based storage with SQL | Transactional records, structured forms, filters/sorts, reporting, joins | | **Graph** | Property graph storage using Apache AGE (Cypher) | Multi-hop relationships, lineage/impact, recommendations, traversals | Choose the type when creating an entity. Relational entities store data in PostgreSQL tables; graph entities store data as nodes (vertices) and edges in a property graph, enabling relationship-first queries. If your primary questions are “find related records within $n$ hops” or “trace paths,” prefer graph; otherwise, relational is the default choice. ## What you can do - **Create or edit entities.** Define names, descriptions, choose the entity type (relational or graph), and decide whether the platform auto-generates starter layouts. - **Manage properties.** Add fields with types, validation rules, and default values. Use the **Filtered Properties** tab to hide fields from search. - **Define unique constraints.** Use the **Unique Constraints** tab to specify property combinations that must be unique across all records—helpful for preventing duplicates during imports or upserts. - **Review relationships.** See how this entity connects to others—handy when coordinating cross-entity tools. Graph entities support first-class edge relationships with labels. - **Export/import entities (including relationships).** Export an entity definition as JSON and import it later. Imported relationship definitions are applied when you save the entity, and only succeed when the referenced entities exist in the target project. - **Sync database schema.** Click **Sync Database** inside a relational entity page, or use **Sync All** in the Entities toolbar when several relational entities need to be applied together. Gaia creates missing tables first and then applies relationship changes in a safe order. Graph entities still use **Sync Graph** from their entity page. You do not need (and typically do not have) direct database access. - **Attach UI layouts.** Link the entity to existing layouts or create a new one without leaving the entity page. Linked layouts appear in the split canvas inside [Conversations](#doc-conversations). - **Preview and explore data.** Open the **Data** tab to inspect records with advanced features: - **Table view** for spreadsheet-style browsing with sortable columns. - **JSON view** for inspecting full record structure. - **XLSX export** to download filtered results to Excel (with automatic truncation for large text fields). - **Empty/not-empty operators** for filtering nullable fields. - **Related entities support** to filter by connected records. - **Pagination** with skip and limit controls for large datasets. - **User-configurable result limits** to control how many records load at once. - **Global sorting** to order results by any property across multiple entities. - **SQL query viewer** to inspect the generated PostgreSQL query for debugging. - **Query graph data.** Use the **View Graph** button in the toolbar to open the Graph Data Viewer for building and executing Cypher queries against graph entities. ## Step-by-step ### Creating a relational entity 1. Open **Data Model → Entities**. 2. Click **New entity** or select an existing row and choose the pencil icon. 3. Complete the **General** tab (name, description, layout settings). Leave the entity type as **Relational** (the default). 4. Add properties and relationships as needed. 5. (Optional) Open the **Unique Constraints** tab to define property combinations that must be unique. 6. Select **Save changes**. If structural updates are required, Gaia shows a **schema change confirmation dialog** listing exactly what will change (columns added, removed, or modified) before applying them. 7. (Optional) Visit the **Layouts** tab to connect a form or dashboard to this entity. ### Bulk syncing multiple relational entities Use the toolbar-level **Sync All** action when you have several relational entities with related schema changes, especially when they reference each other. 1. Open **Data Model → Entities**. 2. Create or update the relational entities you need, then save them without syncing if you want to review the full batch first. 3. Click **Sync All** in the toolbar. 4. Review the combined change list or full DDL. Gaia batches relational entities together, creates missing base tables first, and then applies relationship DDL. 5. Click **Sync Database** in the dialog to apply the batch. `Sync All` only covers persistent relational entities. Graph entities and other non-relational definitions are skipped and continue to use their entity-level sync actions. ### Required setup for conversation canvas To make this entity appear in the split canvas during conversations: 1. Open the entity and verify it is configured for UI usage. 2. On the entity page, attach at least one UI Layout in the **Layouts** tab. 3. Save entity changes. 4. In [Conversations](#doc-conversations-activate-and-use-the-canvas), ask the assistant to open a record from this entity. ### Creating a graph entity 1. Open **Data Model → Entities**. 2. Click **New entity**. 3. On the **General** tab, enter a name and description, then change the **Type** to **Graph**. 4. Add properties. These become node properties in the property graph. 5. Add relationships to other **graph** entities. These become edge labels in the graph (note: graph entities can only relate to other graph entities). 6. Select **Save changes**. Gaia will prompt you to sync the graph schema, creating the vertex label and any edge labels. 7. Use the **View Graph** button in the toolbar to query your graph data. ## Real-life example > A customer success team created a Renewal Opportunity entity with fields for customer segment, risk score, and next action date. They attached a layout with a call script and then asked Gaia to open the entity for a specific account. During follow-up, the agent filled the form directly from the conversation canvas. ## Property naming rules and reserved fields When defining entity properties, be aware of **reserved field names** that the system uses automatically: ### System-reserved fields The platform automatically adds these fields to every entity. **Do not create properties with these names:** - `id` — UUID primary key for each record - `createdBy` — UUID of the user who created the record - `createdAt` — Timestamp when the record was created - `updatedBy` — UUID of the user who last updated the record - `updatedAt` — Timestamp of the last update ### Relationship-generated fields When you create relationships between entities, the system automatically generates foreign key fields. Avoid property names that could conflict with these patterns: - **One-to-many and many-to-one relationships (no properties):** The system adds a `{targetEntityName}_id` field to store the foreign key reference (unless you explicitly set `sourceField` / `targetField` on the relationship) - Example: A relationship from `Order` to `Customer` creates a `Customer_id` field on the Order table (or your explicit `sourceField`, e.g. `customer_id`) - **Many-to-many relationships, or any relationship with properties:** The system creates a junction table with `{sourceEntityName}_id` and `{targetEntityName}_id` fields - Example: A many-to-many relationship between `Student` and `Course` creates fields `student_id` and `course_id` in the junction table - Example: A one-to-many relationship with properties between `Author` and `Book` creates an `AuthorBook` junction table with `author_id`, `book_id`, and the relationship property columns ### Data pipeline TypeScript types When using entities in data pipelines (source, transform, target), the generated TypeScript types include: - All custom properties you define - System-reserved fields (`id`, `createdBy`, `createdAt`, `updatedBy`, `updatedAt`) - Relationship fields following the patterns above **Example TypeScript interface for a Customer entity with an order relationship:** ```typescript interface Source { id: string; name: string; email: string; order_id?: string; // Generated from one-to-many relationship to Order createdBy: string; createdAt: Date; updatedBy: string; updatedAt: Date; } ``` Use these exact field names when writing transformation code or mapping data between systems. Important: relationship-generated FK columns are strict. You must use the exact column name (for example `Cinema_id` or an explicit `sourceField` like `cinema_id`). Aliases such as `cinemaId` are not supported. ## Graph entities Graph entities use **Apache AGE** (A Graph Extension) to store data as nodes and edges in a property graph. This enables powerful relationship-based queries using **Cypher**, the declarative graph query language. ### Key concepts - **Nodes (vertices):** Each graph entity type becomes a vertex label. Entity records are stored as nodes with properties. - **Edges:** Relationships between graph entities become edge labels. Unlike relational foreign keys, edges are first-class citizens with their own properties. - **Properties:** Stored as `agtype` (AGE's JSON-like format). All standard property types are supported. - **Indexes:** Automatically created for entity properties to optimize query performance. ### Graph vs. relational | Aspect | Relational | Graph | | -------------- | ----------------------------------- | ---------------------------------- | | Storage | PostgreSQL tables | Property graph (AGE) | | Relationships | Foreign keys | First-class edges | | Query language | SQL | Cypher | | Best for | CRUD + analytics on structured data | Traversals, pathfinding, influence | | Sync action | Sync Database | Sync Graph | ### Relationship restrictions Graph entities can **only** relate to other graph entities. Similarly, relational entities can only relate to other relational entities. This ensures consistent storage and query patterns within each data paradigm. ## Entity Data Viewer The **Entity Data Viewer** provides a powerful query builder for exploring relational entity data. ### Opening the viewer 1. Navigate to **Data Model → Entities**. 2. Click the **View Data** button in the toolbar for relational entities. 3. The Entity Data Viewer page opens. ### Building queries The left panel contains the **Query Builder** with these sections: #### Entity filters Click **Add Entity** to add entities to your query. For each entity: - **Properties** and **Relationships** sections are collapsible. Use the chevron to expand or collapse each section as needed. - **Entity Name:** Select the entity to query. - **Property Filters:** Add conditions to filter records. Each filter includes: - **Property:** Select from available properties (supports dot notation for nested JSON properties). - **Operator:** Operators depend on property type: | Property type | Operators in UI | | ------------------------------------------------------ | ------------------------------------------------------------------- | | `text`, `normalized-text`, `enum` | `=`, `!=`, `like`, `not-like`, `empty`, `not-empty` | | `text`, `normalized-text`, `enum` with vectors | `=`, `!=`, `like`, `not-like`, `~`, `empty`, `not-empty` | | `number`, `date`, `timestamp`, `time` | `=`, `!=`, `>`, `>=`, `<`, `<=`, `between`, emptiness | | `text-vector`, `embedding-vector` | `~`, `empty`, `not-empty` | | `array` with item type `text`/`normalized-text` | `contains-any`, `contains-all`, `equals`, fuzzy variants, emptiness | | `array` with item type `object` | `elem-match`, `~`, emptiness | | `object`, non-text `array`, `point`, `boolean`, `uuid` | `~`, `empty`, `not-empty` | `like` and `not-like` support `*` and `%` wildcards. `~` appears only when the selected field is vector-capable (either a vector field itself or a source field used by a vector property). For text arrays: - `contains-any` / `contains-all` / `equals` are normalized exact matching (case/diacritics-insensitive). - `contains-any-fuzzy` / `contains-all-fuzzy` / `equals-fuzzy` use similarity matching. - Values can be entered as comma-separated text or JSON array syntax. For arrays of objects: - `elem-match` expects a JSON criteria object and maps to `$elemMatch` in query JSON. - Nested array criteria can be expressed with nested `$elemMatch` blocks. - **Value:** Enter the comparison value. - **Logic:** Combine multiple property filters with AND or OR logic. - **Relationship Property Filters:** Add conditions on junction-table properties (relationships that have their own fields). Each filter includes: - **Relationship:** Select the relationship name. - **Property:** Choose a relationship property to filter. - **Operator/Value:** Same operators as regular properties. - When used, the results include a top-level object named after the relationship (e.g., `ScreenMovies`). - **Selected Relationship Properties (optional):** Include relationship properties in results without filtering. Choose a relationship and property; the results include a top-level object named after the relationship. - **Selected Properties:** Optionally specify which properties to return (useful for reducing result size). #### Sort by Add global sorting to control the order of results: - **Entity:** Select which entity the sort property belongs to. - **Property:** Choose a property to sort by. - **Order:** Select ascending or descending. - Add multiple sort criteria for multi-level sorting. #### Query options - **Number of Results:** Maximum records to return per query (minimum 1, no hard 1000 cap). - **Skip (Offset):** Number of records to skip for pagination. - **Include Related Entities:** Toggle to include data from related entities. ### Executing and viewing results 1. Click **Execute Query** to run the SQL query. 2. The right panel shows results in two views: - **JSON View:** Hierarchical JSON structure of the results. - **Table View:** Spreadsheet-style grid with sortable columns. 3. Click the code icon () to view the generated PostgreSQL SQL query. 4. Use the **XLSX** button (available in Table View) to export results to Excel. ### Query import/export - **Copy Query:** Copies the current query configuration as JSON to your clipboard. - **Paste Query:** Opens a dialog to paste and restore a previously copied query. - **Apply Filters:** When used with UI layouts, applies the current filters back to the layout binding. Copied query JSON may be either: - A bare filters array (legacy): `[{ "entityName": "Product", "properties": { ... } }]` - An object with filters and options (current): `{ "filters": [...], "options": { "limitOverride": 25, "skipOverride": 0, "includeRelatedEntities": true } }` ### XLSX export When exporting to Excel: - Primary entity data appears on the first sheet. - Secondary entities (from multi-entity queries) appear on separate sheets. - Related entities (when "Include Related Entities" is enabled) appear on sheets prefixed with "Related\_". - Long text values are automatically truncated to comply with Excel's cell character limits. - Filenames include a timestamp for easy identification. ## Graph Data Viewer The **Graph Data Viewer** provides a visual query builder for exploring graph entity data using Cypher queries. ### Opening the viewer 1. Navigate to **Data Model → Entities**. 2. Click the **View Graph** button in the toolbar (graph icon). 3. The Graph Data Viewer page opens. ### Building queries The left panel contains the **Graph Query Builder** with these sections: #### Nodes Click **Add Node** to add nodes to your query. For each node: - **Variable:** A short name (e.g., `n`, `u`) used to reference the node in the query. - **Label (Entity Type):** Select a graph entity or leave as "Any" to match all node types. - **Properties:** Add property filters to match specific values. Multiple filters within a node can be combined with AND or OR logic. - **Selected Properties:** Optionally specify which properties to return for this node (useful for reducing result size). #### Relationships When you have two or more nodes, click **Add Relationship** to connect them: - **From/To:** Select which nodes to connect. - **Direction:** Choose outgoing (→), incoming (←), or both (↔). - **Relationship Type:** Optionally specify the edge label. - **Min hops / Max hops:** Optionally configure variable-length path matching. #### Sort by Add sorting to control the order of results: - Enter a sort expression (for example `n.title` or `count(r)`). - Select ascending or descending order. - Add multiple sort criteria for multi-level sorting. #### Return Control what is returned by the query: - Add one or more free-form return expressions (for example `n`, `labels(n) AS labels`, `count(r) AS cnt`). - If no return expressions are configured, Gaia returns the matched node variables by default. #### Pagination - **Limit:** Maximum number of results to return (default: 1). - **Skip:** Number of results to skip (for pagination). - **Depth:** How many relationship hops to include for related nodes (1 = no expansion, higher values include related nodes up to that depth). ### Executing and viewing results 1. Click **Execute Query** to run the Cypher query. 2. The right panel shows results in two views: - **Graph View:** Interactive visualization with nodes and edges. Click a node to view its properties in a resizable side panel. Use zoom and fullscreen controls. - **JSON View:** Raw query results as hierarchical JSON data. - When a query returns scalar/tabular data without graph nodes/edges, Gaia automatically switches to **JSON View**. 3. Click the code icon to view the generated PostgreSQL/AGE SQL query. 4. Use the **XLSX** button to export results to Excel (available in both views). ### Properties panel When viewing graph results, click on any node to open the properties panel: - Displays all properties of the selected node in a JSON viewer. - The panel is resizable—drag the left edge to adjust width. - Click the X button or select another node to close/switch. ### Query import/export - **Copy Query:** Copies the current query as JSON to your clipboard. - **Paste Query:** Opens the structured JSON editor for a previously copied query JSON, executes it immediately, updates the results panel, and hydrates the visual builder with all supported fields. - **Required shape:** Pasted JSON must be a valid `GraphQuery` object with non-empty `match` and `return` arrays. - **Not supported:** Shorthand formats such as `{ "nodes": [...], "relationships": [...] }`. - **Minimal valid example:** ```json { "match": [ { "patterns": [{ "nodes": [{ "var": "n", "labels": ["Book"] }] }] } ], "return": ["n"], "limit": 25 } ``` ### Reverse sync Use the **Sync Schema from Graph** button to analyze the graph database and update your entity definitions based on the actual data structure. This is useful when: - Data was imported directly into the graph without entity definitions. - You want to discover properties that exist in the data but aren't defined in entities. ## Syncing database schema When you modify an entity's properties or relationships, Gaia detects the schema changes and helps you apply them to the database. Important: project admins apply schema updates from the Gaia UI using **Sync Database** / **Sync Graph**. Platform users are not expected to connect to PostgreSQL or run migrations manually. ### Schema sync dialog When you click **Save & Sync** or **Sync Database** / **Sync Graph**: 1. Gaia compares your entity definition against the current database schema. 2. A dialog appears showing detected changes: - **Changes tab:** Lists each modification with a description and the DDL/Cypher that will be executed. - **Complete DDL / Graph Operations tab:** Shows the full script for reference. 3. Changes that may cause data loss are marked with a warning icon. 4. Click the sync button to apply all changes in a transaction. ### Unsaved changes warning If you have unsaved changes when clicking Sync Database, Gaia prompts you to save first. This ensures the schema matches your latest edits before syncing. ## Tips - Keep entity names singular and descriptive. They appear in tool names and layout bindings. - Use **Search result limit** to control how many records the assistant surfaces when users ask broad questions. - Document critical fields in the description; it shows up while editing prompts in [AI Agents](#doc-agents). - Avoid naming properties with reserved field names or potential relationship field patterns to prevent conflicts. - Use the **POINT** property type for geographic coordinates (latitude/longitude). Point properties support **comparison radius** filters so agents can find records within a specified distance. - For graph entities, design your node types around the relationships you need to traverse. Think "find all friends of friends" rather than "join table A to table B." - Graph entities work well for hierarchies (org charts), networks (social graphs), and any data where the connections matter as much as the records themselves. ## Troubleshooting - **Save button disabled:** Ensure the entity name is unique and all required fields are complete. - **Sync failed:** Review the error message. It may indicate missing permissions or an incompatible change (such as shrinking a column). Adjust the schema and retry. - **Graph sync failed:** Check that the Apache AGE extension is installed and the graph exists. The error message will indicate whether you need admin permissions or if there's a Cypher syntax issue. - **Cannot create relationship between entities:** Graph entities can only relate to other graph entities, and relational entities can only relate to other relational entities. Check that both entities are the same type. - **Layouts list empty:** Create a layout in [UI Layouts](#doc-conversations-ui-layouts) or use **Create layout** inside the dialog to generate a starter version. - **Graph query returns no results:** Verify that you've synced the graph schema and that data exists. Check that node labels match your entity names (case-sensitive). --- # Storage Keep project assets, exports, and supporting documents in one place. The Storage tab gives authorized users a tree view over the files that live in Gaia's project-scoped blob storage for the current project. Interactive walkthrough: Open [Tutorials](/platform/support/tutorials) and select **Data Model Basics: Storage**. ## What you can do - **Browse a project-scoped tree.** Gaia stores every blob under `gaia//`. The explorer groups those blobs into folders so you can keep specs, schemas, and generated outputs together. - **Create folders anywhere.** Use **New Folder** from the toolbar or the row actions to create nested folders. Gaia drops a hidden `.keep` marker so the folder persists in object storage even if it's empty. - **Upload files.** Start an upload from the toolbar or a folder row. You can override the file name before it lands in storage. **Drag and drop multiple files** directly onto folders to upload several assets at once from your filesystem. Gaia proxy/local uploads accept files up to 20 MB; Azure-backed projects send files from 10 MB upward directly to Blob Storage so larger uploads do not pass through Gaia's application process. - **Download entire folders.** Select a folder to enable **Download Folder**. Gaia compresses the folder (keeping the nested structure and filenames) into a `.zip` so you can grab everything in one go. - **Preview supported formats.** Select a file to open the preview pane. JSON/JSONL and XML/HTML render with streaming line numbers for large payloads. PDFs open in a paginated viewer with zoom controls. Text files (`.txt`) and Word documents (`.doc`, `.docx`) also render inline with download buttons. Other types show a friendly message so you know to download them outside Gaia. - **Search and refresh.** Filter the tree by name or path fragments and reload the view with **Refresh** if someone else just made changes. - **Delete files and folders.** Remove obsolete assets from the row action menu. Gaia asks for confirmation because deletes cannot be undone. ## Access requirements - Only users with **Storage** permissions can open the Storage tab or make changes. - Permissions cascade to every action (list, upload, delete, create folder). If you can see the tab you have the rights you need. ## Step-by-step 1. Open **Data Model → Storage** inside your project. 2. Use the left tree to navigate to the folder you need. 3. Click **Upload** to add a file or **New Folder** to organize assets. Row-level buttons let you operate within a specific folder without changing selection. 4. **Drag and drop** files from your desktop onto any folder row to bulk-upload multiple items at once. 5. Select a folder to reveal **Download Folder** and pull a `.zip` of everything inside. Select a file to open the preview pane. Resize the pane by dragging the divider if you want more room. 6. Use the **Refresh** button whenever you upload outside Gaia or expect updates from teammates. ## Preview behaviors - **Large JSON and XML:** Content streams in chunks so you can start reading immediately, even for multi-megabyte files. Scroll to fetch more lines. - **PDF:** Gaia fetches the full file and renders it with page navigation and zoom. File size appears in the header. - **Text and Word:** Plain text files and Word documents (`.doc`, `.docx`) render inline with a download button for local editing. - **Unsupported types:** You'll see a placeholder message. Download the blob from Gaia's API or your storage console if you need to inspect it. ## Real-life example > A data engineering team uploads nightly CSV exports into a "raw" folder, stores AI summaries in a "processed" folder, and uses **Download Folder** to share the latest bundle with stakeholders. ## Tips - Mirror the folder names you use in pipelines and workflows so it's easy to map files back to automations. - Keep raw ingests and enriched outputs in separate folders to avoid confusion during troubleshooting. - Delete `.keep` marker files only if you're sure you no longer need the folder; otherwise the empty path may disappear. - Use multi-file drag-and-drop when migrating assets from another system to speed up bulk imports. ## Troubleshooting - **Tab missing:** Verify you have Storage permissions for the project. Ask an admin if you need access. - **Folder creation failed:** Check that the name is unique at that level and contains only URL-safe characters. - **Upload stalled, slow, or rejected as too large:** Proxy/local uploads are limited to 20 MB. Azure-backed projects automatically use direct Blob Storage upload for files from 10 MB upward. For another storage provider, use its native upload path for larger assets. - **Preview shows "Preview not available":** The file type isn't supported yet. Download the blob and open it locally. --- # Pipelines Pipelines describe how data moves into, through, or out of Gaia. Use them to collect information from external systems, transform records, route context into workflows, or publish updates to entities. Interactive walkthrough: Open [Tutorials](/platform/support/tutorials) and select **Data Model Basics: Pipelines**. This walkthrough now covers two concrete scenarios end-to-end so the resulting pipelines are ready to use in a workflow run. ## Capabilities - **Create new pipelines.** Define sources (entities, uploads, webhooks, TypeScript generators) and targets (entities, TypeScript handlers), then decide how often they run. - **Crawl websites.** Start from a sitemap, explore on-site links, and ingest pages as HTML or Markdown for downstream transforms. - **Edit existing pipelines.** Adjust schedules, filters, or field mappings whenever your data changes. - **Rearrange transforms.** Drag transform steps to reorder them without recreating the pipeline. - **Duplicate for experiments.** Clone a pipeline to test new logic without jeopardizing production runs. - **Delete safely.** You'll always confirm before removing a pipeline from future runs. - **Review downstream impact before delete.** Gaia shows how many workflows and workflow runs are affected before you confirm a pipeline deletion. If a graph workflow still references the pipeline, Gaia blocks the delete until you remove that reference manually. - **Jump to related actions.** From the grid you can open associated workflows or inspect recent activity in the [Runs](#doc-data-model-runs) tab. ## Build or edit a pipeline 1. Go to **Data Model → Pipelines**. 2. Click **New pipeline** or select one from the list and choose the pencil icon. 3. Enter the basic details (name, description) and configure the **Source** and **Target** sections. 4. Edit JSON objects such as filters, headers, parameters, request bodies, and response schemas in the structured JSON editor. Invalid drafts stay local until corrected. 5. Add transformations or field selectors if needed. Use the preview to confirm your mappings look right. 6. (Optional) Set a **batch size** to control how many records are processed in each chunk. Smaller batches use less memory; larger batches can improve throughput. 7. Save. The dialog closes and the grid refreshes with the latest status. ## Tutorial scenarios (recommended order) 1. **Scenario #1: Context-triggered pipeline** 2. Configure **Source → Context Storage** and set a key pattern (for example `orders-*`). 3. Configure **Target → None (Store in Context)** so later pipelines can consume the output. 4. Save the pipeline. 5. **Scenario #2: Enrichment pipeline** 6. Create a second pipeline, add at least one transform step (for example JSONata), and save. 7. Continue with [Workflows](#doc-data-model-workflows) to chain both scenarios and run them. ## Real-life example > The marketing team built a pipeline named “Leads nightly sync.” It pulls JSON files from cloud storage, normalizes email addresses, and writes the results to the Lead entity. They duplicated the pipeline to test a new enrichment step without touching the production version. ## Tips - Keep descriptions clear—workflow builders rely on them when chaining pipelines together. - Use tags or naming conventions to group related pipelines (for example, `crm/` vs `billing/`). - After editing, visit the [Runs](#doc-data-model-runs) tab to watch the next execution and make sure it succeeds. - To trigger workflows from external systems, set the source to listen for context keys and use the [Ingestion Webhook](#doc-data-model-ingestion-webhook). - Website sources only ingest HTML pages. Non-HTML URLs (images, PDFs, scripts, ASPX, and other document files) are skipped automatically. ## TypeScript scripting (engineering reference) If you use TypeScript sources, transforms, or TypeScript targets, see the detailed runtime contract and the full list of available helpers: - [Engineering reference: TypeScript in data pipelines](#doc-data-model-typescript-pipelines) For deeper, scenario-based docs with examples per case: - [TypeScript in pipelines (split reference)](#doc-data-model-typescript) ### Context sources When a pipeline listens for context keys, the pattern you choose controls how incoming data is interpreted: - Wildcards (such as `orders-*`) treat each matching key as its own record. - Exact keys send the entire payload as a single record. Arrays are processed item by item, while individual objects stay intact. - Webhook-triggered context records are stored as `{ headers, payload }`. Read original request fields from `payload.*`, and point any `jsonArrayPath` into `payload` (for example `payload.items`). Array results are stored under indexed keys like `orders-0`, `orders-1`; object results stay as a single record under the exact webhook key. ## Troubleshooting - **Cannot save:** Check that every source and target field is filled in and that you have admin permissions. - **Pipeline missing from workflow builder:** Confirm it’s published and not deleted or in draft. - **Delete blocked for a pipeline:** Open the listed graph workflows, remove the pipeline reference there first, and then retry the delete. - **Duplicate dialog empty:** Wait a moment for the full configuration to load before trying again. --- # Engineering reference: TypeScript in data pipelines Gaia pipelines support **TypeScript** for three stages: - **Source (TypeScript generator):** produce records by implementing `generate()`. - **Transform (TypeScript step):** transform or filter records by implementing `transform(context, input)`. - **Target (TypeScript handler):** write records by implementing `write(context, output)`. This page is a high-level entrypoint to the runtime contract, with links to more detailed per-case pages. ## Split reference pages (recommended) - [Index: TypeScript in data pipelines](#doc-data-model-typescript) - [Record formats (what sources emit)](#doc-data-model-typescript-record-formats) - [TypeScript source (generator)](#doc-data-model-typescript-source) - [TypeScript transform](#doc-data-model-typescript-transform) - [TypeScript target (writer)](#doc-data-model-typescript-target) - [AI transform aggregation (chunking + PDF batches)](#doc-data-model-typescript-ai-transform-aggregation) - [Sharing data between pipelines in the same workflow run](#doc-data-model-typescript-workflow-context-sharing) ## What Gaia executes Gaia stores two versions of your code: - `codeTs`: the TypeScript you edit in the UI. - `codeJs`: the compiled JavaScript that Gaia executes at runtime. Each TypeScript stage also has an **Execution runtime** selector: - **Legacy Node.js — High risk:** preserves the existing behavior and compatibility, but executes in Gaia's Node.js process. Existing definitions continue to use this runtime unless you change them. - **QuickJS WebAssembly — Reduced risk:** runs the JavaScript in a QuickJS WebAssembly context on a worker thread and exposes Gaia utilities through an explicit capability bridge. It still shares Gaia's operating-system process and is not equivalent to an isolated service. New TypeScript sources, transforms, aggregators, and targets start on QuickJS WebAssembly. Existing pipeline scripts without a saved runtime identifier continue using Legacy Node.js until explicitly switched and tested. Each stage also has a **Context API** selector: - **Context v1 · Native compatibility:** preserves existing scripts. Its `markdownTools.loadHtml(...)` and `markdownTools.createConverter(...)` methods return native Cheerio and Turndown objects, so those methods require Legacy Node.js. - **Context v2 · Portable:** exposes Gaia-owned functions with plain, transport-safe arguments and results. It works in QuickJS and Legacy Node.js and is the default for newly authored scripts. Definitions without a saved context version continue using v1. Changing the execution runtime does not silently change the context API; choose v2 before moving native-object code to QuickJS. The selected runtime and its security classification are stored with the script. Changing the runtime does not change the TypeScript source. Test or run the affected pipeline after switching, because Node-specific behavior and utilities that return SDK client objects may not be compatible with QuickJS. The security label communicates comparative technical risk; project owners remain responsible for enabling and reviewing executable scripts. Both runtimes apply the following compatibility rules: - `require()` is allowlisted to built-in `crypto` only (`'crypto'` / `'node:crypto'`). - TypeScript `import ... from "crypto"` is supported (compiled to allowlisted `require`). - Imports from npm packages and other Node modules are not supported. - Use the `context` object (especially `context.utils`) for platform-provided capabilities. - Source, transform, target, and custom AI aggregator editors expose an optional **Execution timeout (ms)** field. Leave it blank to use Gaia's default limit, or raise it for heavier processing. When you set a value, Gaia applies it to both synchronous execution and awaited async work. - Use **Format code** in the TypeScript editor, or the editor shortcut, to apply Gaia's TypeScript formatting to the editable script body before saving. ## Common runtime model Across pipeline TypeScript stages, Gaia provides a `context` object with this shape: ```ts type ExecutionContext = { contextVersion: 'v1' | 'v2'; utils: { // Many helpers are available; see “Utilities reference” below. [key: string]: unknown; }; state: Record; // Mutable per-run state original?: Record; // The original record (see “Original record”) }; ``` ### Utilities reference (`context.utils`) These helpers are available to pipeline transforms and targets, and are also available in TypeScript tools. - `fetch(url, method?, payload?, headers?, auth?)` → `{ ok, status, headers, text, data }` - Resolves environment variables embedded in the URL or bearer token. - `auth` supports `{ bearer?: string }`. - `scrapePage(url, options?)` → structured scrape result - `htmlToMarkdown(html)` → markdown string - `htmlToMarkdown(html, { includeParagraphs: true })` → `{ content, paragraphs }` where `paragraphs` is an array of text blocks - `htmlToText(html)` → plain text string - Context v2: `markdownTools.queryHtml(html, selector, options?)` → plain matches with `html`, `text`, and `attributes` - Context v2: `markdownTools.transformHtml(html, operations, options?)` → cleaned HTML using declarative `remove`, `unwrap`, attribute, text, or HTML operations - Context v2: `markdownTools.htmlToMarkdown(html, options?)` → GFM markdown, optionally after the same declarative operations - Both versions: `markdownTools.pdfToMarkdown(base64Pdf, options?)` → an advanced result with `markdown`, `status`, `messages`, and `stats`; conversion defaults to 100 pages and 60 seconds and caps overrides at 250 pages and 120 seconds - Context v1 only: `markdownTools.loadHtml(html)` and `markdownTools.createConverter(options?)` return native Cheerio and Turndown objects and therefore require Legacy Node.js - `markdownToChunks(markdown, options?)` → array of chunks - `formatDate(date, format)` → formatted date string - `currentDate()` → `Date` - `uuid()` → uuid string - `parseJSON(text)` → parsed value (returns `{}` on parse failure) - `stringifyJSON(obj)` → JSON string - `reciprocalRankFusion(lists, maxElements?, k?)` → merge ranked lists into a single ranking Storage (scoped to the workflow run or tool call scope): - `readStorageData(key)` → stored object or `null` - `writeStorageData(key, data)` → boolean success - `queryStorageData(keyPattern)` → array of `{ key, projectId, scopeId, data, createdAt, updatedAt }` - `deleteStorageData(key)` → boolean success Entity utilities (relational entities): - `searchAcrossEntities(filters, options?)` - `getEntityRecord(entityName, id)` - `createEntityRecord(entityName, data, relationships?)` - `updateEntityRecord(entityName, id, data, relationships?)` - `deleteEntityRecord(entityName, id)` → `true` - `upsertEntityRecord(entityName, data, uniquePropNames?, relationships?)` - `createEntityRecordRelationship(args)` - `deleteEntityRecordRelationship(args)` - Text wildcard filters in `searchAcrossEntities` support `$like` and `$not-like` with either `*` or `%` (example: `{ entityName: "Company", properties: { name: { $not-like: "Acme*" } } }`). - `searchAcrossEntities` operators by property type: - `text` / `normalized-text` / `enum`: direct value, `{ $eq: ... }`, `{ $ne: ... }`, `{ $like: "..." }`, `{ $not-like: "..." }`. - vector-capable text fields (source for `text-vector`/`embedding-vector`): can also use direct similarity-style search values. - `number` / `date` / `timestamp` / `time`: `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$between`. - `array`: `{ $elemMatch: { ... } }` for element-level matching, including nested `$elemMatch`. - any supported type: `{ empty: true }`, `{ "not-empty": true }`. Relationship property filters (searchAcrossEntities): - Filters can include `relationshipProperties` to filter by junction-table relationship property values (keyed by relationship name). - Example: `{ entityName: "Author", relationshipProperties: { AuthorBooks: { role: "editor" } } }` - Example (array on relationship property): `{ entityName: "Movie", relationshipProperties: { ScreenMovies: { days: { $elemMatch: { and: [{ or: [{ name: "Δευτ" }, { also: { "$contains-any": ["Δευτ"] } }] }, { times: { $elemMatch: { hour: { $gte: "18:00" } } } }] } } } } }` #### Inline relationships during record write (optional) When creating, updating, or upserting a record, you can optionally establish **FK-based** relationships in the same operation by passing a `relationships` array. This is useful for composite unique constraints that include a foreign key column (for example, `UNIQUE(law_id, articleNumber)`). Relationship object shape: ```ts type InlineRelationship = { targetEntityId?: string; // UUID or unique entity name (recommended: name) targetEntityName?: string; // Alias for targetEntityId when you only know the name targetRecordId: string; relationshipId?: string; relationshipName?: string; data?: Record; // junction table property values }; ``` Example (set `Law` relationship while creating `LawArticle`): ```ts await context.utils.createEntityRecord( 'LawArticle', { articleNumber: 1, content: 'Article I...' }, [{ targetEntityId: 'Law', targetRecordId: lawId }], ); ``` Notes: - Inline relationships apply to both FK-based and junction-table relationships. - Junction-table relationships (many-to-many or relationships with properties) are applied after the record write; use `data` to set relationship properties. - If multiple relationships exist between the same entities, supply `relationshipId` or `relationshipName` to disambiguate. Geocoding: - `addressToGeocode(address, fuzzy?, countrySet?, language?)` - `geocodeToAddress(lat, lon, language?)` Model call helper: - `askModel(aiModel, messages, temperatureOrOptions?, legacyResponseFormat?)` Common fragments: - `getCommonFragments(options?)` - `getCommonFragment(fragmentId)` - `updateCommonFragment(fragment)` - `createCommonFragment(fragment)` Project file storage (blob storage): - `uploadFile(fileName, data, folderPath?, contentType?)` → `{ success, url?, error? }` - `downloadFile(filePath)` → `{ success, data?, error? }` - `listFiles(folderPath?, maxResults?)` → `{ success, files?, error? }` - `deleteFile(filePath)` → `{ success, error? }` Graph utilities (graph entities): - `searchGraph(filters, options?)` - `getGraphNode(entityName, id)` / `createGraphNode(...)` / `updateGraphNode(...)` / `deleteGraphNode(...)` - `listGraphNodes(entityName, filter?, limit?, skip?)` - `upsertGraphNode(entityName, data, uniquePropNames?)` - `createGraphEdge(edgeLabel, sourceNodeId, targetNodeId, properties?)` - `getGraphEdge(edgeId)` / `updateGraphEdge(edgeId, properties)` / `deleteGraphEdge(edgeId)` - `listGraphEdges(edgeLabel, sourceNodeId?, targetNodeId?, limit?, skip?)` - `getNodeEdges(nodeId, direction?, limit?)` ### Logging (`console.*`) In TypeScript stages, `console.log/info/warn/error/debug` is captured into the run logs with a prefix identifying the stage (source/transform/target) and (for transforms) the transform index. ### Execution timeout behavior Blank timeout fields use Gaia's default runtime limit. Explicit timeout values are enforced as a wall-clock budget for the stage, including awaited async work such as delayed helper calls. If the budget expires, Gaia stops waiting for the script result and prevents later writes through the guarded `context` object or source `pass()` callback. External requests already sent by your code may still complete outside Gaia's runtime, so use request-level timeouts when the remote system must also stop work promptly. ### Original record (`context.original`) For pipeline transforms, Gaia sets `context.original` to the **original record for that transform step**, so you can compare the current `input` to the original. ## TypeScript source: `generate()` A TypeScript source must define an **async** `generate()` function. ### Signature Gaia supports these invocation patterns based on the number of declared parameters: - `generate()` - `generate(context)` - `generate(context, pass)` ### Producing records with `pass(records)` Inside `generate()`, call `pass([...])` with an array of records. - If an element is a plain object, it is emitted as-is. - If an element is a primitive (string/number/boolean/etc), Gaia wraps it as `{ value: }`. If you call `pass()` with a non-array, Gaia throws an error. ### Example ```ts export async function generate(context: any, pass: (rows: unknown[]) => Promise) { const res = await context.utils.fetch('https://example.com/api/leads', 'GET'); if (!res.ok) { throw new Error(`Fetch failed: ${res.status}`); } const leads = Array.isArray(res.data) ? res.data : []; await pass( leads.map((lead: any) => ({ email: lead.email, source: 'example', collectedAt: context.utils.currentDate().toISOString(), })), ); } ``` ### Example: customize HTML cleanup and Markdown conversion Use context v2 for portable code: ```ts export async function transform(context: any, input: any) { const html = String(input.html || ''); const markdown = context.utils.markdownTools.htmlToMarkdown(html, { operations: [ { type: 'remove', selector: '.cookie-banner, nav, footer' }, { type: 'remove', selector: 'a[href^="#"]' }, ], }); return { ...input, markdown, }; } ``` For an existing context-v1 script, keep Legacy Node.js while it uses `loadHtml(...)` or `createConverter(...)`. Migrate the DOM edits to v2 operations before selecting QuickJS. ### Example: advanced PDF-to-Markdown conversion ```ts export async function transform(context: any, input: any) { const result = await context.utils.markdownTools.pdfToMarkdown(String(input.content || ''), { includeMetadata: true, yamlFrontMatter: true, maxPages: 25, }); return { ...input, content: result.markdown, conversionStatus: result.status, conversionWarnings: result.messages.filter((message: any) => message.severity === 'warning'), }; } ``` ## TypeScript transform: `transform(context, input)` A TypeScript transform must define a `transform(context, input)` function. ### Signature ```ts export async function transform(context: any, input: Record) { // ... return { ...input }; } ``` ### Return value rules - Return a **plain object** to keep the record. - Return `undefined` / `null` / `{}` to **drop** the record from the pipeline. - Gaia keeps a transformed record only if it is truthy and has at least one key. ### State (`context.state`) and stateful transforms - `context.state` is a mutable object that persists for the duration of the workflow run. - If the transform configuration sets `stateProperty`, Gaia retains only `context.state[stateProperty]` between transform steps to reduce memory usage. ### Example: normalize + filter ```ts export async function transform(context: any, input: any) { const email = String(input.email || '') .trim() .toLowerCase(); if (!email) { return; // drop } return { ...input, email, normalizedAt: context.utils.currentDate().toISOString(), }; } ``` ## TypeScript target: `write(context, output)` A TypeScript target must define an **async** `write(context, output)` function. ### Signature - Gaia requires the function to accept **both** arguments: `(context, output)`. - Gaia also provides `record` as an alias of `output` inside the sandbox. ### Example: upsert into an entity ```ts export async function write(context: any, output: any) { await context.utils.upsertEntityRecord('Lead', output, ['email']); } ``` ## Troubleshooting - If you see an error like “`require() only supports allowlisted built-in modules...`”, use `crypto` only or replace direct imports with `context.utils.*` helpers such as `context.utils.markdownTools`. - If QuickJS reports that it cannot serialize a host function after a `markdownTools` call, the script is using a native context-v1 object. Select Legacy Node.js temporarily or migrate the script to context v2's `queryHtml`, `transformHtml`, and `htmlToMarkdown` functions. - Workflow run logs include TypeScript line numbers when available. - If a transform output is unexpectedly empty, confirm you are returning a plain object with at least one key. --- # Engineering reference: TypeScript in data pipelines Gaia pipelines let engineers script **TypeScript** at three different points: - **TypeScript Source**: generate records (`generate()`) - **TypeScript Transform**: map/filter records (`transform(context, input)`) - **TypeScript Target**: write records (`write(context, output)`) This reference is split into focused pages with examples and the exact runtime assumptions. ## Quick links - [Record formats (what sources emit)](#doc-data-model-typescript-record-formats) - [TypeScript source (generator)](#doc-data-model-typescript-source) - [TypeScript transform](#doc-data-model-typescript-transform) - [TypeScript target (writer)](#doc-data-model-typescript-target) - [AI transform aggregation (chunking + PDF batches)](#doc-data-model-typescript-ai-transform-aggregation) - [Sharing data between pipelines in the same workflow run](#doc-data-model-typescript-workflow-context-sharing) ## What Gaia executes Gaia stores two versions of your code: - `codeTs`: the TypeScript you edit in the UI. - `codeJs`: the compiled JavaScript executed at runtime. Your code runs in a restricted sandbox: - `require()` is allowlisted to built-in `crypto` only (`'crypto'` / `'node:crypto'`). - TypeScript `import ... from "crypto"` is supported (compiled to allowlisted `require`). - Imports from npm packages and other Node modules are not supported. - Use `context` (especially `context.utils`) for platform-provided capabilities, including `context.utils.markdownTools` when you need parser-level HTML or PDF conversion control. The adjacent **Context API** selector controls the shape of `context`: - **Context v1 · Native compatibility** is the fallback for existing definitions. Native Cheerio and Turndown objects require Legacy Node.js. - **Context v2 · Portable** uses plain arguments and results in both runtimes. New scripts default to QuickJS plus v2. ## Common runtime model Across pipeline TypeScript stages, Gaia provides a `context` object with this shape: ```ts type ExecutionContext = { contextVersion: 'v1' | 'v2'; utils: Record; // platform helpers state: Record; // mutable per-run state original?: Record; // original record for the current transform step }; ``` ### Logging (`console.*`) `console.log/info/warn/error/debug` is captured into workflow-run logs with a prefix indicating the stage. ### Original record (`context.original`) For pipeline transforms, Gaia sets `context.original` to the **original record for that transform step**. ## Utilities reference (`context.utils`) These helpers are available to pipeline transforms and targets, and are also available in TypeScript tools. HTTP + scraping: - `fetch(url, method?, payload?, headers?, auth?)` → `{ ok, status, headers, text, data }` - Resolves environment variables embedded in the URL or bearer token. - `auth` supports `{ bearer?: string }`. - `downloadUrl(url, options?)` → a bounded base64 file result with sanitized per-attempt metadata - Defaults to three attempts, a 10-second abortable timeout per attempt, exponential backoff with jitter, and a 25 MiB response limit. - Retries transport failures and HTTP `408`, `425`, `429`, `500`, `502`, `503`, and `504` by default, honoring `Retry-After` when present. - Supports `method`, `payload`, `headers`, `auth`, retry/timeout/size overrides, `allowedContentTypes`, and `expectedContent` (`json`, `pdf`, `png`, `jpeg`, or `zip`). - A successful HTTP response with an empty body, disallowed content type, malformed expected JSON, or invalid expected file signature is retryable by default. Project code remains responsible for authentication/session workflows and business decisions. - `scrapePage(url, options?)` → structured scrape result - `htmlToMarkdown(html)` → markdown string - `htmlToMarkdown(html, { includeParagraphs: true })` → `{ content, paragraphs }` where `paragraphs` is an array of text blocks - `htmlToText(html)` → plain text string - Context v2: `markdownTools.queryHtml(...)`, `transformHtml(...)`, and `htmlToMarkdown(...)` use JSON-safe values and declarative HTML operations - Both versions: `markdownTools.pdfToMarkdown(...)` returns an advanced PDF conversion result - Context v1: `markdownTools.loadHtml(...)` and `createConverter(...)` expose native library objects in Legacy Node.js only - `pdfToMarkdown(base64Pdf)` → extracted markdown/text from a base64-encoded PDF - `pdfToText(base64Pdf)` → extracted plain text from a base64-encoded PDF - `decodeQrFromDocument({ base64, name?, type?, maxPdfPages? })` → the first decoded QR value and optional PDF page number, or `null` (PDF, PNG, and JPEG) - `pdfToPositionedText(base64Pdf, { maxPages? })` → PDF text grouped by page with `{ text, pageNumber, row, column }` items, including coordinate projection for rotated text - `compareDocumentVisuals(source, target, options?)` → page-count and per-page aspect/structure/edge/ink similarity metrics for base64 PDF, PNG, or JPEG documents; projects choose their own acceptance thresholds Text helpers: - `markdownToChunks(markdown, options?)` → array of chunks - `pdfToChunks(base64Pdf, options?)` → parse PDF, then split into chunks (same options as `markdownToChunks`) - `formatDate(date, format)` → formatted date string - `currentDate()` → `Date` - `uuid()` → uuid string - `parseJSON(text)` → parsed value (returns `{}` on parse failure) - `stringifyJSON(obj)` → JSON string - `reciprocalRankFusion(lists, maxElements?, k?)` → merge ranked lists into a single ranking Storage (scoped to the workflow run): - `readStorageData(key)` → stored object or `null` - `writeStorageData(key, data)` → boolean success - `queryStorageData(keyPattern)` → array of `{ key, projectId, scopeId, data, createdAt, updatedAt }` - `deleteStorageData(key)` → boolean success Entities (relational entities): - `searchAcrossEntities(filters, options?)` - `getEntityRecord(entityName, id)` - `createEntityRecord(entityName, data, relationships?)` - `updateEntityRecord(entityName, id, data, relationships?)` - `deleteEntityRecord(entityName, id)` → `true` - `upsertEntityRecord(entityName, data, uniquePropNames?, relationships?)` - `createEntityRecordRelationship(args)` - `deleteEntityRecordRelationship(args)` - Text wildcard filters in `searchAcrossEntities` support `$like` with either `*` or `%` (example: `{ entityName: "Company", properties: { name: { $like: "Acme*" } } }`). - Text array filters support semantic operators: `$contains-any`, `$contains-all`, `$equals`, plus fuzzy variants (`$contains-any-fuzzy`, `$contains-all-fuzzy`, `$equals-fuzzy`). Values may be arrays or comma-separated strings. Relationship property filters (searchAcrossEntities): - Filters can include `relationshipProperties` to filter by junction-table relationship property values (keyed by relationship name). - Example: `{ entityName: "Author", relationshipProperties: { AuthorBooks: { role: "editor" } } }` Inline relationships (optional): - `relationships` is an array of `{ targetEntityId?, targetEntityName?, targetRecordId, relationshipId?, relationshipName?, data? }` - `targetEntityId` accepts an entity UUID or an entity name. - `targetEntityName` is an alias for `targetEntityId` when you only know the name. - `data` supplies junction table property values when the relationship has properties. - FK-based relationships are set inline; junction-table relationships (many-to-many or relationships with properties) are applied after the record write. Geocoding: - `addressToGeocode(address, fuzzy?, countrySet?, language?)` - `geocodeToAddress(lat, lon, language?)` Model call helper: - `askModel(aiModel, messages, temperatureOrOptions?, legacyResponseFormat?)` Common fragments: - `getCommonFragments(options?)` - `getCommonFragment(fragmentId)` - `updateCommonFragment(fragment)` - `createCommonFragment(fragment)` Tool registry: - `tools.list(options?)` → `{ tools, totalCount }` - `tools.get(toolId)` → registry summary - `tools.call(toolIdOrName, args?, { version? })` → `{ success, data?, error? }` - `args` becomes the workflow context payload for workflow tools. - Provide `version` when multiple registry entries share the same name. Project file storage (blob storage): - `uploadFile(fileName, data, folderPath?, contentType?)` → `{ success, url?, error? }` - `downloadFile(filePath)` → `{ success, data?, error? }` - `listFiles(folderPath?, maxResults?)` → `{ success, files?, error? }` - `deleteFile(filePath)` → `{ success, error? }` Graph (graph entities): - `searchGraph(filters, options?)` - `getGraphNode(entityName, id)` / `createGraphNode(...)` / `updateGraphNode(...)` / `deleteGraphNode(...)` - `listGraphNodes(entityName, filter?, limit?, skip?)` - `upsertGraphNode(entityName, data, uniquePropNames?)` - `createGraphEdge(edgeLabel, sourceNodeId, targetNodeId, properties?)` - `getGraphEdge(edgeId)` / `updateGraphEdge(edgeId, properties)` / `deleteGraphEdge(edgeId)` - `listGraphEdges(edgeLabel, sourceNodeId?, targetNodeId?, limit?, skip?)` - `getNodeEdges(nodeId, direction?, limit?)` ## Custom Markdown Conversion Pattern When a project needs more than Gaia's default `htmlToMarkdown(...)` or `pdfToMarkdown(...)` helpers, use `context.utils.markdownTools` instead of importing packages directly. ```ts export async function transform(context: any, input: any) { const markdown = context.utils.markdownTools.htmlToMarkdown(String(input.html || ''), { operations: [{ type: 'remove', selector: '.cookie-banner, nav, footer' }], }); return { ...input, markdown, }; } ``` ```ts export async function transform(context: any, input: any) { const result = await context.utils.markdownTools.pdfToMarkdown(String(input.content || ''), { includeMetadata: true, yamlFrontMatter: true, }); return { ...input, markdown: result.markdown, conversionStatus: result.status, }; } ``` --- # Record formats (sources → transforms → targets) In pipelines, everything is processed as a stream of **records**, where a record is a JSON object: - Each stage receives a `JsonObject` (key/value map) - Returning/producing a primitive is generally coerced into `{ "value": }` This page documents the important differences between record shapes for different source types. ## Key rule: keep your records compatible A **TypeScript source** should emit records that look like what other sources emit: - Plain objects with stable field names - Values that are JSON-serializable (string/number/boolean/null/arrays/objects) That makes it easy to swap a source (e.g., Table → TypeScript) without rewriting downstream transforms/targets. ## Table source Table sources stream rows from a database table. **Record shape** - One record per DB row - Keys are column names - Values are the row values (strings/numbers/booleans/JSON fields depending on the column) ## Entity source Entity sources stream rows from an entity’s underlying table. **Record shape** - One record per entity record - Keys are entity property names (which are also columns in the entity table) - Optional `propertyMapping` can rename fields on output ## API source API sources fetch data from an HTTP endpoint (JSON or XML) and yield records. ### JSON format - If the response payload is an array: yields **one record per element**. - If the response payload is an object: yields a **single record**. - If a response element is a primitive (string/number/boolean/null): yields `{ "value": }`. If `jsonArrayPath` is set: - Gaia tries to locate that nested path (dot notation like `data.items`). - If the path exists and is an array → yields one record per element. - If the path exists and is an object/primitive → yields a single record (object as-is, primitive as `{ value }`). - If the path does not exist → falls back to the entire response payload. ### XML format XML responses are parsed into JSON-like objects. - Attributes become top-level fields. - Text content is stored as `value` or `_text` depending on whether the element has children. If `parentTag` is set, Gaia attempts to extract an array of records at that tag. ## Page source Page sources scrape a URL with selectors and return structured results. **Record shape** - Always yields an array of objects from the scraper - Keys are the configured field names (`fieldSelectors[].field`) - Values are strings (usually) ## File source (blob storage) File sources download blobs and parse them into records. Important: supported file types are: - `json`, `xml`, `excel`, `doc`, `docx`, `txt`, `pdf` ### JSON files - If file content is an array: yields one record per element. - If file content is an object: yields a single record. - If the content (or an element) is a primitive: yields `{ "value": }`. If `jsonArrayPath` is set: - Gaia extracts that nested path (dot notation like `data.items`) and uses it as the record list. ### XML files - Records are extracted by `parentTag` (default varies by config; some configs use `'*'` to treat each root element as a record). - Output is JSON-like and may include: - Attribute fields - Nested objects/arrays for children - `_text` or `value` for text nodes ### Excel files - Each row becomes one record - Keys come from the header row ### DOC and DOCX files By default, Gaia converts Word content into markdown. Legacy `.doc` files are converted through LibreOffice first, then processed through the same markdown path as `.docx` files. **Record shape (default)** ```json { "content": "# Title\n\n...markdown...", "filename": "my.docx", "mimeType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document" } ``` If `documentMode: 'base64'`, the record contains base64 instead of markdown. For legacy `.doc` files, Gaia keeps the original filename and uses `application/msword` as the MIME type. ### TXT files **Record shape** ```json { "content": "...text...", "filename": "notes.txt", "mimeType": "text/plain" } ``` ### PDF files PDF records default to base64 payloads. **Record shape (default)** ```json { "content": "...base64...", "filename": "report.pdf", "mimeType": "application/pdf", "encoding": "base64" } ``` If `documentMode: 'markdown'`, Gaia extracts text and returns markdown in `content` instead. PDF parsing always uses **libpdf**. - If `documentMode: 'markdown'`, Gaia returns extracted text in `content`. - If `documentMode: 'base64'`, Gaia still validates parsing with libpdf first, then returns raw base64 content. ### Conversation upload expansion (when file records come from context) When a context payload represents a conversation upload, Gaia can expand it into file-derived records. Those records are the same shapes above, plus: - `conversationId` - `messageId` - `uploadedFile` metadata See [workflow context sharing](#doc-data-model-typescript-workflow-context-sharing) for details. ## Context source Context sources stream records previously written into run-scoped storage. ### Exact key mode If `keyPattern` is an exact key (no `*`): - If stored data is an array → yields **one record per element**. - If stored data is an object → yields a **single record**. - If stored data is a primitive → yields `{ "value": }`. ### Pattern mode If `keyPattern` contains a wildcard (`*`): - Each matching key is treated as one record. - Stored objects are yielded as records. If a matched record is a conversation upload payload, it is expanded as described above. ## TypeScript source TypeScript sources emit records via `pass([...])`. - Plain objects are emitted as-is. - Primitive elements are wrapped as `{ "value": }`. See [TypeScript source](#doc-data-model-typescript-source) for best practices on emitting compatible records. --- # TypeScript source (generator) A TypeScript source produces records by implementing an **async** `generate()` function. ## Goal: emit records compatible with other sources Downstream transforms and targets work best when your TypeScript source emits the same kinds of records that built-in sources emit: - A stream of plain JSON objects - Stable field names (don’t change shape per record unless you also handle it downstream) - JSON-safe values If you ever want to swap a TypeScript source for a Table, Entity, API, or File source, this compatibility is what makes that refactor painless. ## Signature Gaia supports these invocation patterns (based on your declared parameters): - `generate()` - `generate(context)` - `generate(context, pass)` ## Producing records with `pass(records)` Inside `generate()`, call `pass([...])` with an array of records. - If an element is a plain object, it is emitted as-is. - If an element is a primitive (string/number/boolean/etc), Gaia wraps it as `{ value: }`. If you call `pass()` with a non-array, Gaia throws an error. ## Example: API → normalized records This example emits records shaped like a typical “table/entity row”. ```ts export async function generate(context: any, pass: (rows: unknown[]) => Promise) { const res = await context.utils.fetch('https://example.com/api/leads', 'GET'); if (!res.ok) { throw new Error(`Fetch failed: ${res.status}`); } const leads = Array.isArray(res.data) ? res.data : []; await pass( leads.map((lead: any) => ({ email: String(lead.email || '') .trim() .toLowerCase(), source: 'example', collectedAt: context.utils.currentDate().toISOString(), })), ); } ``` ## Example: generate work items for a file/AI pipeline A common pattern is to emit “file work items” that downstream transforms understand. ```ts export async function generate(context: any, pass: (rows: unknown[]) => Promise) { const list = await context.utils.listFiles('documents/', 100); if (!list.success) { throw new Error(list.error || 'Failed to list files'); } const pdfs = (list.files || []).filter((f: any) => String(f.name || '').endsWith('.pdf')); await pass( pdfs.map((f: any) => ({ path: f.name, kind: 'pdf', })), ); } ``` Downstream, you can download and process those PDFs in a transform (TypeScript) or feed them into an AI transform (see [AI transform aggregation](#doc-data-model-typescript-ai-transform-aggregation)). ## Notes - `require()` is allowlisted to built-in `crypto` only (`'crypto'` / `'node:crypto'`). - npm imports and other Node modules are not supported. - Prefer `context.utils.*` helpers for network, storage, entity operations, AI calls, and parser-level content conversion via `context.utils.markdownTools`. --- # TypeScript transform A TypeScript transform runs once per record and can: - Normalize or enrich fields - Convert between record shapes - Filter records out of the pipeline ## Signature ```ts export async function transform(context: any, input: Record) { // ... return { ...input }; } ``` ## Input record formats vary by source The `input` record is whatever the source emitted (or whatever the previous transform returned). - For file/context sources, the record shape depends heavily on file type and configuration. - For table/entity sources, it looks like a database row. Use this reference to write transforms that correctly handle file records: - [Record formats](#doc-data-model-typescript-record-formats) ## Return value rules (filtering) - Return a **plain object** to keep the record. - Return `undefined` / `null` / `{}` to **drop** the record from the pipeline. - Gaia keeps a transformed record only if it is truthy and has at least one key. ## Stateful transforms (`context.state`) - `context.state` persists for the duration of the workflow run. - If the transform config sets `stateProperty`, Gaia retains only `context.state[stateProperty]` between transform steps to reduce memory usage. ## Example: normalize + filter (table/entity-shaped input) ```ts export async function transform(context: any, input: any) { const email = String(input.email || '') .trim() .toLowerCase(); if (!email) return; return { ...input, email, normalizedAt: context.utils.currentDate().toISOString(), }; } ``` ## Example: file transform that handles PDFs This transform keeps only PDF records and produces a simplified “document record” for downstream steps. ```ts export async function transform(context: any, input: any) { const mimeType = String(input.mimeType || ''); if (mimeType !== 'application/pdf') { return; // drop non-PDFs } // Default PDF format is base64 content const content = String(input.content || ''); const filename = String(input.filename || ''); return { documentId: context.utils.uuid(), filename, mimeType, content, encoding: input.encoding || 'base64', }; } ``` If the source emits base64 PDF content, you can extract text inside the transform: ```ts export async function transform(context: any, input: any) { if (String(input.mimeType || '') !== 'application/pdf') return; const base64Pdf = String(input.content || ''); const markdown = await context.utils.pdfToMarkdown(base64Pdf); const chunks = await context.utils.pdfToChunks(base64Pdf, { enableAiLabeling: true }); return { ...input, content: markdown, chunkCount: chunks.length, }; } ``` ## Example: portable HTML cleanup and GFM conversion When the project needs more control than Gaia's default `htmlToMarkdown(...)` helper, use context v2's `context.utils.markdownTools` functions. ```ts export async function transform(context: any, input: any) { const html = String(input.html || ''); const markdown = context.utils.markdownTools.htmlToMarkdown(html, { operations: [ { type: 'remove', selector: '.cookie-banner, nav, footer' }, { type: 'remove', selector: 'img.icon, .sr-only' }, ], }); return { ...input, markdown, }; } ``` The internal converter is prewired with GFM support, so HTML tables, task lists, and strikethrough markup are preserved without exposing a runtime-specific converter object. ## Example: advanced PDF-to-Markdown conversion ```ts export async function transform(context: any, input: any) { if (String(input.mimeType || '') !== 'application/pdf') return; const result = await context.utils.markdownTools.pdfToMarkdown(String(input.content || ''), { includeMetadata: true, yamlFrontMatter: true, maxPages: 25, }); return { ...input, content: result.markdown, conversionStatus: result.status, conversionWarnings: result.messages.filter((message: any) => message.severity === 'warning'), }; } ``` Direct npm imports remain unsupported in pipeline scripts, so use `context.utils.markdownTools` instead of importing `cheerio`, `turndown`, or PDF conversion packages inside TypeScript stages. Context-v1 `loadHtml(...)` and `createConverter(...)` remain available for existing Legacy Node.js scripts. Replace their DOM mutations with v2 operations before moving those scripts to QuickJS. ## Example combinations These are common “source → TypeScript transform → target” shapes: - **File (pdf/docx/txt/json/excel) → TS transform → Entity target** - TS transform standardizes the varying file shapes into consistent entity fields. - **Context (exact key array) → TS transform → API target** - Context emits one record per array element; TS transform reshapes to the API payload. - **TypeScript source → TS transform → TypeScript target** - Useful when you want full control over data generation, mapping, and persistence. --- # TypeScript target (writer) A TypeScript target receives pipeline output records and writes them wherever you choose. ## Signature A TypeScript target must define an **async** `write(context, output)` function. - Gaia requires the function to accept **both** arguments: `(context, output)`. - Gaia also provides `record` as an alias of `output` inside the sandbox. ```ts export async function write(context: any, output: any) { // persist output somewhere } ``` ## What the target receives The `output` object is the record produced by the previous stage: - If you have transforms, it is the **last transform output**. - If you have no transforms, it is the **source record**. So the “target input format” is entirely defined by your own transforms plus the source record shape. To understand source shapes (especially files and context), start here: - [Record formats](#doc-data-model-typescript-record-formats) ## Example: upsert into an entity ```ts export async function write(context: any, output: any) { // Unique key: email await context.utils.upsertEntityRecord('Lead', output, ['email']); } ``` ## Example: write intermediate results for another pipeline A powerful workflow pattern is: - Pipeline A writes intermediate artifacts into run-scoped storage - Pipeline B reads them via a Context source ```ts export async function write(context: any, output: any) { // Accumulate under a stable key const key = 'intermediate/leads'; const existing = (await context.utils.readStorageData(key)) || []; const next = Array.isArray(existing) ? [...existing, output] : [output]; await context.utils.writeStorageData(key, next); } ``` See [workflow context sharing](#doc-data-model-typescript-workflow-context-sharing) for exact context-source semantics. ## Built-in targets (non-TypeScript) and their expectations If you are not using a TypeScript target, built-in targets have their own requirements: - **Entity target** - Uses `propertyMapping` to map record fields into entity properties - Uses `keyProperties` to upsert (deduplicate) - **Table target** - Uses `fieldMapping` to map record fields into table columns - **API target** - Sends the entire record as a JSON request body A good rule of thumb: if your transforms emit a stable “row-like” object, you can swap targets without changing upstream stages. --- # AI transform aggregation (chunking + PDF batches) Gaia’s **AI transform** stage can optionally aggregate results across: - **Array chunking** (`enableChunking`) - **PDF batch processing** (automatic when PDF payloads are detected) Aggregation can be: - **Default**: merge JSON objects using a built-in strategy - **Custom**: provide a TypeScript/JavaScript aggregator implementing `aggregate()` This matters because it changes what “the AI step output” looks like when the AI transform is applied to arrays or PDFs. ## How AI transforms choose input (`fieldPath`) AI transforms start from the current pipeline record and choose the data to send to the model: - If `fieldPath` is empty → AI sees the full record. - If `fieldPath` is set (dot notation like `payload.items`) → AI sees the value at that path. - If the extracted value is an object/array → passed as-is. - If it’s a primitive → wrapped as `{ "value": }`. ## Array chunking (`enableChunking`) If `enableChunking` is true and the selected input is an array: - Gaia calls the model once per array element - Each model response must be a JSON object (or text, which Gaia wraps as `{ content: "..." }`) - Gaia aggregates chunk outputs into a single object ### Default merge for chunking The default behavior is a **shallow merge**: - Later chunks override earlier keys with the same name - Nested objects are not deep-merged in chunking mode ### Custom aggregator for chunking If `useAggregator` is true and `aggregatorCodeJs` is provided, Gaia runs your `aggregate()` function instead of the fallback merge. ## PDF batching If the selected input contains one or more PDF payload objects, Gaia processes PDFs in batches: - The PDF is split into page ranges (default batch size is 10 pages) - Each batch is sent to the model as an attachment - Batch results are aggregated into a single JSON object ### Default merge for PDFs The default PDF merge is **deep-ish**: - Objects are merged recursively - Arrays are concatenated - Primitive values overwrite ## Custom aggregator contract Implement an `aggregate(context, input)` function. ### Input shape Gaia calls your aggregator multiple times. Each call provides: ```ts type AggregatorInput = { chunk: Record; // model output for this chunk/batch metadata: Record; // describes the chunk/batch previousResult?: Record; // your previous aggregated result aiContext?: Record; // your previous aiContext (if you returned it) }; ``` ### Return shape Your function must return an object containing: - `result`: a JSON object (required) - `aiContext`: a JSON object or null/undefined (optional) ```ts export async function aggregate(context: any, input: any) { const prev = input.previousResult || {}; const next = input.chunk || {}; // Example: collect results into an array const items = Array.isArray(prev.items) ? prev.items : []; const out = { ...prev, items: [...items, next], }; return { result: out, aiContext: { lastChunkIndex: input.metadata?.chunkIndex, }, }; } ``` ### Metadata fields you can rely on - For chunking (`enableChunking`): - `source: 'chunk'` - `chunkIndex`, `totalChunks` - `fieldPath` (if configured) - For PDFs: - `source: 'pdf'` - `chunkIndex`, `totalChunks` - `payloadIndex`, `label`, `filename`, `sourcePath` - `startPage`, `endPage`, `totalPages` ## Practical examples ### Example: summarize per-row, then aggregate into one report - Source emits an array (or `fieldPath` selects an array) - AI transform runs per element - Aggregator collects outputs into a single JSON object ### Example: PDF extraction with cross-batch memory - PDF is processed batch-by-batch - Aggregator returns `aiContext` to carry forward state (e.g., a glossary or “already extracted keys” list) --- # Sharing data between pipelines in the same workflow run Gaia workflows often chain multiple pipelines. Within a single workflow run, you can pass intermediate results between pipelines using **run-scoped storage** and **Context sources**. This page documents the exact semantics of context storage and how record shapes change depending on key patterns. Webhook-triggered records use a context envelope: `{ headers, payload }`. If a workflow starts from an ingestion webhook, read the original request body from `payload.*` and request metadata from `headers.*`. ## Storage is scoped to a workflow run `context.utils.*StorageData` helpers read and write data scoped to: - the current project - the current workflow run This makes it a safe way to move intermediate results between pipelines that execute as part of the same run. ## Writing intermediate data From a TypeScript transform or target: ```ts export async function transform(context: any, input: any) { const key = 'intermediate/leads'; const existing = (await context.utils.readStorageData(key)) || []; const next = Array.isArray(existing) ? [...existing, input] : [input]; await context.utils.writeStorageData(key, next); return input; } ``` ## Reading intermediate data with a Context source A Context source reads from storage using `keyPattern`. ### Exact key (no `*`) If `keyPattern` is an exact key: - If stored value is an array → yields **one record per element**. - If stored value is an object → yields a **single record**. - If stored value is a primitive → yields `{ value: }`. This is ideal for “Pipeline A writes an array, Pipeline B processes items.” ### Wildcard pattern (`*`) If `keyPattern` includes `*`: - Gaia queries all matching keys - Each matching key is treated as its own record This is ideal when Pipeline A writes to multiple keys, such as: - `intermediate/leads/2025-01-01` - `intermediate/leads/2025-01-02` and Pipeline B wants to process each key’s payload independently. ## Conversation upload expansion When a context payload represents a **conversation storage upload**, Gaia can expand it into file-derived records. - For supported files (`.docx`, `.pdf`, `.txt`, `.json`, `.xlsx`, `.xls`), Gaia parses the file into records (see [record formats](#doc-data-model-typescript-record-formats)). - It enriches each record with: - `conversationId` - `messageId` - `uploadedFile` metadata For unsupported uploads, Gaia yields a minimal record with `type: 'uploaded_file'` and `uploadedFile` metadata. ## End-to-end example: multi-pipeline workflow ### Pipeline A - Source: API - Transform: normalize - Target: TypeScript target writes array to `intermediate/leads` ### Pipeline B - Source: Context (`keyPattern = 'intermediate/leads'`) - Transform: AI enrichment (optionally chunked + aggregated) - Target: Entity upsert This pattern keeps pipelines small and composable while still sharing state within the workflow run. --- # Workflows Workflows orchestrate multiple pipelines and optional actions into a single automation. Gaia currently supports both graph-based workflows and older dialog-managed pipeline-list workflows, and the Workflows page exposes both entrypoints. Interactive walkthrough: Open [Tutorials](/platform/support/tutorials) and select **Data Model Basics: Workflows**. ## Capabilities - **Model graph-based processes.** Chain pipelines, tools, and human actions in the graph editor instead of relying on a flat stage list. - **Use first-class control blocks.** Add **If**, **Switch**, **Branch**, **Join**, **For each**, and **While** blocks with named ports such as **Then/Else**, case/default, branch paths, **Loop/Done**, and **Loop/Exit**. - **Author conditions on workflow context.** Configure a simple context-path condition or provide a compact TypeScript expression body for advanced routing logic. - **Attach workflow knowledge.** Add document folders at the workflow level, then let agent, tool, and TypeScript nodes inherit those folders or override them node by node. - **Use custom human-action screens.** Human-action nodes can point to a saved UI Layout so reviewers see a purpose-built form, with the existing schema-driven form as the fallback. - **Route human actions to app reviewers.** Human-action nodes can stay unassigned, target a specific app user, or target an app user role. - **Pass agent outputs downstream.** Agent nodes can store either text or a parsed JSON object at a named context key for later nodes to read. - **Provide run-specific inputs.** When you run a workflow graph from the list, attach runtime document folders for that run and seed initial workflow context with a JSON object in the structured JSON editor. - **Choose and tune TypeScript execution.** TypeScript workflow nodes and TypeScript-authored conditions expose an **Execution runtime** selector with a security classification plus an independent **Context API** selector and optional **Execution timeout (ms)** override. Existing scripts remain on Legacy Node.js plus context v1 until changed. Newly added TypeScript nodes and conditions start on QuickJS WebAssembly plus portable context v2. - **Control run-log context.** Keep detailed nested context values for diagnosis, switch to compact summaries for high-volume workflows, and redact workflow-specific context paths before log persistence. - **Keep older workflow definitions editable.** The standard workflow dialog still supports metadata editing and legacy pipeline-order management. - **Duplicate or version workflows.** Clone a workflow to experiment with new steps while the original continues to run. - **Preview sample output.** Validate transformations before scheduling them broadly. - **Manage execution lifecycle.** Run workflows, start multiple active runs of the same workflow, run legacy workflows on a sample, duplicate them, or delete them from the grid. ## Choose the right entrypoint The toolbar currently has two create buttons: - **New Graph:** Opens the full graph editor with a default **Start -> End** definition. - **New:** Opens the workflow dialog for name, version, description, and pipeline-list setup. For existing workflows: - Use the pencil icon on workflow graph rows to open the graph editor. - Use the pencil icon on legacy workflow rows to open the workflow dialog. - If that workflow already uses a graph definition, the dialog's **Pipelines** tab becomes topology read-only and points you back to the graph editor. ## Workflow graphs vs execution protocols Workflow graphs and execution protocols are complementary, but they are not the same capability. - A workflow graph orchestrates repeatable automation runs across pipelines, tools, agents, human actions, and control blocks. - An execution protocol governs how one agent moves through visible stages inside a conversation. Use a workflow graph when you need reusable routing or automation behavior such as: - branching based on workflow context - looping through items or re-checking conditions - human-action approvals inside an automation run - repeatable data preparation before an agent answers Use an execution protocol when you need the agent's work itself to stay staged and reviewable, for example: - plan before implementation - pause after a draft until someone approves the next stage - keep research, synthesis, and verification separate in one governed thread Use both when the automation should prepare evidence and the agent should analyze that evidence in visible stages. Example: > A research team uses a workflow graph to ingest approved source files, branch restricted sources through human review, and store the prepared evidence. A research agent then uses a staged protocol to clarify the brief, synthesize findings, verify gaps, and finalize the report. If the main question is "How should this automation branch, loop, or approve work every time it runs?" build a workflow graph. If the main question is "How should this agent work through the request inside the conversation?" use an execution protocol. For the protocol side of that decision, see [Protocols](#doc-agents-protocols). ## Build or update a workflow 1. Navigate to **Data Model → Workflows**. 2. Click **New Graph** to create a graph workflow, or use **Open graph editor** on an existing workflow. 3. To clone an existing workflow, click the duplicate icon in the **Actions** column and confirm the new name/version. 4. Add or update the workflow **Name**, **Version**, and **Description** in the left panel. 5. Choose the workflow's **Context logging** detail. **Detailed values** is the default. Add one **Redacted path** per line for project-specific sensitive data. 6. Optional: attach **Workflow knowledge** folders that graph nodes can use during execution. 7. Keep the default **Start** and **End** terminals in place. Gaia keeps exactly one of each, renders them as fixed circles, and locks their labels. 8. Add pipeline, agent, tool, human-action, or control blocks from the left panel. New nodes insert before the terminal **End** node when you build a straight-through flow. 9. Select each node to open its side pop-up and configure its reference, description, notes, condition, loop binding, knowledge mode, or human-action UI Layout. 10. Connect nodes through their named ports. For example, an **If** block routes through **Then** and **Else**, a **Switch** block routes through ordered case ports or **Default**, and a **Branch** block sends each path to its paired **Join**. 11. Click a node or connection when you need to inspect it. Existing connections can be rewired by dragging either end of the selected line to a new compatible port. 12. Save. Gaia keeps you on the graph route, persists your current node placement and wiring, and a brand-new workflow receives its workflow ID after the first save. 13. Return to the workflow grid and use **Run** from the workflow row. Each click starts a new independent run, even when another run of the same workflow is already active. 14. Optional: attach **Runtime document folders** for this run only. These folders are available to nodes that inherit workflow knowledge, alongside workflow-level folders. 15. Optional: add **Initial context data** as a JSON object. Nodes can read these values from workflow context state, for example in conditions or TypeScript nodes. 16. Start the run, then open [Runs](#doc-data-model-runs) to verify the new run record. ## Control blocks - **If:** Evaluate a condition against workflow context and route through **Then** or **Else**. - **Switch:** Evaluate ordered cases against workflow context, route through the first matching case, or use **Default** when no case matches. - **Branch:** Start multiple branch paths from the same workflow state. Each path runs independently and must converge at a paired **Join**. - **Join:** Wait for the paired **Branch** paths and expose each path's changed state under `workflowBranches..branches`. - **While:** Re-evaluate a condition each time the loop returns to the block, then route through **Loop** or **Exit**. - **For each:** Resolve an array from workflow context, bind the current item and index into workflow state, run the loop branch once per item, then continue through **Done**. Workflow conditions can read from values such as tool results, prior human-action responses, and loop bindings through `context.state.*`. ## Graph editor panels - **Left panel:** workflow metadata, context logging, workflow-level knowledge folders, the **Add nodes** palette, and the **Save**, **Auto layout**, and **Reset** actions. - **Canvas:** drag nodes, connect ports, select a node to open its side pop-up, or press **Delete** to remove the selected connection or non-terminal node. Click **Auto layout** to arrange the current graph from top to bottom and fit it into view; this changes node positions only and does not alter connections or configuration. - **Node pop-up:** edit node label, description, notes, typed references, condition authoring mode, loop bindings, or raw config JSON. The panel appears only while a node is selected. Agent, tool, and TypeScript nodes include a **Knowledge scope** section: - **Inherit workflow folders:** use the workflow-level folders. - **Use node folders:** ignore the workflow-level folders and use the folders attached to that node. - **No workflow folders:** run without workflow-provided document knowledge. When a graph run is started from the workflow list, **Runtime document folders** are merged into the inherited workflow folder scope for that run. Node-level **Use node folders** overrides remain node-specific, and **No workflow folders** still disables workflow-provided folder scope for that node. ### Context logging **Detailed values** keeps nested objects and arrays visible in the execution trace, subject to bounded size limits. **Compact summary** uses shallow samples for high-volume workflows. Use **Redacted paths** for project-specific sensitive fields. Paths are relative to the workflow context root. Enter one per line; `*` matches one object or array segment and `**` matches any depth. For example, `documents.*.content` masks every document's content while leaving filenames and other metadata visible. Gaia always masks recognized secrets, credentials, authorization data, and base64 file fields regardless of this setting. Agent nodes can write their result to the configured **Result context key**. In **Text** mode, Gaia stores the final assistant response as text. In **JSON object** mode, Gaia asks the agent for one JSON object, parses it, and stores that object at the result context key so downstream context pickers and TypeScript nodes can use it directly. TypeScript workflow nodes expose the runtime selector, **Context API** selector, and optional **Execution timeout (ms)** override in the node panel. Run the workflow after switching runtime or context version before using it in production. Human-action nodes can keep using the schema response form or select saved UI Layouts for two roles: - **Context preview layout:** a read-only decision packet that can show workflow context, referenced entity records, and document-folder evidence from the workflow's resolved knowledge scope. - **Response layout:** the editable form the reviewer completes. Gaia maps the submitted layout state into the action response JSON, and the node can either submit response JSON only or allow live entity write-back for bound fields. Human-action assignment supports **Unassigned**, **App user**, or **App user role**. Choose **App user** for one app viewer, and choose **App user role** when any viewer in that role can claim and complete the request. For **If**, **Switch**, and **While** conditions, the editor supports both: - **Simple mode:** context path + operator + optional value - **TypeScript mode:** a compact expression body When you use **TypeScript mode**, the condition editor also exposes the runtime and **Context API** selectors plus an optional **Execution timeout (ms)** override. For **For each** nodes, configure: - collection path - item variable - index variable ## Save rules The graph editor validates the workflow before saving. Common requirements are: - exactly one **Start** node - exactly one **End** node - every pipeline, agent, and tool node must reference a real item - every non-end node must connect downstream - control blocks must satisfy all required named ports - **If** and **While** nodes must have a condition - **Switch** nodes must have at least one valid case and a connected **Default** path - **Branch** nodes must have at least one branch, a paired **Join**, and each branch path must reach that Join - **Join** nodes must reference a paired Branch and connect to the next single-thread node - **For each** nodes must define a collection path ## Real-life example > A customer-operations team models a renewal workflow with a Start node, a normalization pipeline, a scoring pipeline, an If node for manual review routing, and a final tool node that posts the approved output into their downstream system. The graph makes the approval branch explicit, and the run logs show exactly where each execution paused or failed. ## Tips - Use consistent naming (for example, prefix with the department) to keep the list organized. - Use **New Graph** when the workflow needs branching, looping, human actions, agents, or tools. Use **New** only when a simple pipeline-list workflow is sufficient or when maintaining an older definition. - Keep **Start** and **End** as the fixed workflow terminals. You cannot delete them or add extra copies. - Keep graph wiring explicit. If a control block has named ports, connect each required port before saving so runs behave predictably. - To replace an existing connection, either drag one end of the selected line to a new port or select it and press **Delete** before drawing a replacement. - Pair workflows with [Evals](#doc-evals) if you want to trigger quality checks after major data updates. - Keep an eye on the [Runs](#doc-data-model-runs) tab—workflow executions appear there with status and logs. ## Troubleshooting - **Workflow fails immediately:** Open the run details page from the Runs tab to inspect errors. Fix the underlying pipeline or credentials and rerun. - **A new run started while another run was active:** This is expected for workflow graphs. Stop or pause individual runs from their run details page when needed. - **Cannot find a pipeline:** Only published pipelines appear. Create or re-enable the pipeline first. - **Save is blocked in the graph editor:** Check for missing control-flow ports such as **Then/Else**, Switch case/default ports, Branch/Join convergence, or **Loop/Done**, and make sure each control block has its required condition or collection path configured. - **The dialog says topology is read-only:** That workflow already uses a graph definition. Open the graph editor from the notice or footer button. - **No one sees the workflow:** Ensure you saved it and that it’s not scoped to a disabled environment. --- # Runs The Runs tab shows execution history for pipelines and workflows. Use it to track progress, troubleshoot issues, and confirm automations are working as expected. Interactive walkthrough: Open [Tutorials](/platform/support/tutorials) and select **Data Model Basics: Runs**. It now covers the full troubleshoot loop: open run details, search/filter logs, edit a linked pipeline, and rerun. ## What you can monitor - **Run status.** See whether each execution is running, completed, failed, or stopped. Status badges refresh automatically. - **Timing.** Start, end, and duration columns help you spot slow jobs. - **Pagination.** Large run histories load in pages so performance stays snappy. Use previous/next controls, review the `Page N of M` indicator, and adjust page size as needed. - **Actions.** Stop an active run, delete historical runs, or open the detailed run page for in-depth logs. **Starting a new run now shows a confirmation dialog** so you can review settings before execution begins. - **Navigation.** Click a row to jump back to the originating pipeline or workflow for deeper investigation. ## Investigate a run 1. Open **Data Model → Runs**. 2. Filter or sort the table to find the run you care about. 3. Click the run name (or the eye icon) to open the dedicated **Workflow Run** page. 4. Use **Execution trace** to inspect the executed path and the context data entering and leaving traced steps. 5. Switch to **Log** and use the search box plus metadata filters (pipeline, stage, transform type, component type, event type, batch number, record number) when you need raw messages. 6. Open the **Pipelines** menu in run details to edit the affected pipeline, or use **Configuration** to get back to the workflow dialog. 7. For graph-based workflows, continue from the dialog into **Open graph editor** when the problem is in topology rather than in one pipeline. 8. Use **Rerun** to validate the fix on a fresh run. The new run opens automatically when available. 9. Optional: stop a stuck run using the stop icon if you have admin permissions. The Workflow Run page includes pause, resume, stop, rerun, and delete controls with real-time status updates. ### Dive deeper Open the [Workflow Run details guide](#doc-data-model-workflow-run-details) to see every control available on the per-run page, including the trace/log tabs, auto-refresh, log filtering, workflow-dialog entrypoints, and AI usage metrics. ## Real-life example > After a vendor API began rate-limiting requests, the nightly enrichment workflow started failing. The ops analyst opened the Runs tab, filtered by “Failed,” and inspected the log. The error showed HTTP 429. They paused the workflow, adjusted retry logic in the pipeline, and reran it from the same screen. ## Tips - Runs refresh every few seconds. Leave the tab open during deploys to confirm success. - Use column filters (status, name) to focus on the runs that matter. - Compare run insights with [Dashboard](#doc-dashboard) trends—spikes in usage sometimes correlate with long-running pipelines. ## Troubleshooting - **No runs appearing:** Confirm the underlying pipeline or workflow executed. Trigger one manually if needed. - **Stop button disabled:** The run already completed or you lack the necessary permissions. - **Logs blank:** Some short-lived runs may not emit logs. Re-run with more verbose settings in the pipeline configuration. --- # Tool registry The **Tool registry** tab provides a centralized catalogue of reusable tools for a project. If you mainly work on composite actions, open **Data Model -> Composite** for the same registry grid locked to composite entries only. Interactive walkthrough: Open [Tutorials](/platform/support/tutorials) and select **Data Model Basics: Tool Registry**. It now covers creating a reusable tool, composing it into a composite action, opening the test dialog, and finding the result through search. ## What it’s for - Define tools once and reuse them across multiple agent configurations. - Keep tool definitions consistent across configs by linking them back to the registry. - Classify each tool's governance execution tier so approved runtime policies can distinguish read-only, standard, privileged, and admin actions. Tools in the registry can also be used by other parts of the platform (for example, scheduled jobs that execute a specific tool). ## How it connects to agent configs When you add a tool from the registry inside an agent configuration, Gaia stores a link to the registry entry. This allows updates to the registry tool definition to be picked up without manually copying changes into every config. For details on adding tools to configs, see [Agent configs](#doc-agents-configs). ## Common tasks ### Add a tool 1. Open **Data Model → Tool registry**. 2. Click **Add tool**. 3. Define the tool (name, type, description, and parameters). 4. Click **Save**. ### Duplicate a tool into a new version Use the duplicate action in a row when you want to branch an existing tool definition without re-entering it from scratch: 1. Find the tool in the grid. 2. Click the duplicate button in the **Actions** column. 3. Gaia creates a new registry entry with the same name and the next available version. 4. If the source entry was an internal tool, the duplicate is created as a regular editable registry entry. 5. Open the new entry with **Edit** if you want to adjust the definition. ### Import tools from Swagger/OpenAPI Use this when you already have a REST API spec and want Gaia to generate tools automatically: 1. Click **Import Swagger** (next to **Add tool**). 2. Paste JSON/YAML or upload a `.json`, `.yaml`, or `.yml` Swagger/OpenAPI file. 3. Click **Analyze spec** to preview generated tools. 4. Review the generated endpoint list, then keep all tools selected or choose only the endpoints you want with the per-tool checkboxes and **Select all** / **Deselect all**. 5. Click **Import**. Gaia creates one webservice tool per endpoint and maps: - endpoint method + URL (`host/basePath/schemes` or OpenAPI `servers`) - `operationId` to tool name - path/query/header/body/formData parameters to tool parameters - required/optional flags, parameter types, descriptions, and structured JSON payload templates for request body schemas For JSON request bodies, Gaia now prefers explicit body-field parameters when the schema exposes named properties, so imported tools are easier to fill and the generated payload template stays closer to the API schema. Supported formats include Swagger 2.0 and OpenAPI 3.x (including `requestBody` and multipart form-data payloads). In this first version, endpoint authentication is not auto-configured. ### Add internal tools If your project includes platform-provided tools that are available to project registries, you can bulk-add them to the registry: 1. Click **Internal**. 2. Select **Add internal tools**. 3. Review the tool bundles, such as **Artifact tools** and **Document folder tools**. 4. Select a whole bundle with the bundle checkbox, or select individual tools inside a bundle. 5. Click **Add tools**. Gaia marks tools that are already present in the registry by name, and it excludes Gaia-assistant-only tools from this picker. ### Sync internal tools If internal tools change over time, use: - **Internal → Sync internal tools** This updates existing project-available internal entries in the registry. ### Filter and search - Use the search box to narrow the list by name/description. - Use the type filter to focus on a specific tool kind. ### Test a registry tool Use **Test** to run a tool directly from the registry: 1. Pick the tool. 2. Fill in parameter values (or paste a JSON object). Object and array parameters open in the structured JSON editor so you can edit nested values without leaving the test dialog. 3. Execute and review the result. Webservice and MCP tests use Gaia's outbound network policy. Use an absolute HTTP(S) URL with a static origin. Gaia permits only that configured origin, revalidates redirects, and rejects local, private, link-local, metadata, and other special-use destinations. If a legitimate customer-hosted service resolves privately, the Gaia host operator must approve its exact origin through `GAIA_AI_EGRESS_PRIVATE_ORIGINS`; project tool authors cannot add that exception themselves. For **Workflow** tools: - **Context Key** defaults automatically, but you can override it with placeholders when each run should write to a distinct storage key. - **Execution Mode** controls whether Gaia starts the workflow and returns immediately or waits for the workflow to finish before returning a result. - **Result Context Key** should point at the workflow storage key that contains the final answer when you use synchronous execution or want delayed delivery. - **Append final result to conversation** is designed for long-running background workflows. When enabled, Gaia appends the workflow's final answer to the originating conversation after the run finishes. For **MCP** tools: - Prefer configuration-level **MCP servers** when you want Gaia agents to use every allowed tool from an HTTP/SSE MCP server. Gaia discovers the server's tool schemas at runtime, exposes them to the model with stable generated names, and invokes the original remote tool names through the MCP gateway. - Use manual **MCP** registry tools for pinned aliases, one-off overrides, or a narrow single-tool connection. - For manual MCP tools, use **Name** for the tool label inside Gaia. - Use **Remote Tool Name** when the MCP server expects a different tool name than the one you want to show inside Gaia. - **Server URL** is required for manual MCP tools. - Relative or same-origin MCP URLs use your current Gaia session. - External MCP URLs use the tool's configured **API Key**. - The test dialog validates required parameters and then calls the configured MCP server so you can confirm connectivity, authentication, and the remote tool result before attaching the tool to an agent. ### Author a composite tool Use a **Composite** tool when you want one reusable synchronous action to call multiple saved registry tools in order and return one final result. Typical examples: - read something, then write something, then open the relevant UI surface - create or update a runtime artifact and then store a linked record - combine a few stable registry tools into one higher-level business action To create one: 1. Make sure the tools you want to call already exist in the registry. 2. Click **Add tool** and choose **Composite** as the type. 3. Define the composite input parameters in **Parameters**. 4. Open **Steps**. 5. Use **Insert step from registry** to open the saved-tool picker, then add the tool you want to call. 6. Fill in argument templates, conditions, and optional behavior through the visual step cards. 7. Open **Outcome** and define postconditions, projected outputs, evidence, failure policy, and the final UI update if needed. 8. Save the tool and run **Test** before linking it into an agent configuration. The composite editor now includes: - live structural validation so missing required composite fields are visible before save - an **Insert step from registry** dialog with search and a registry table for choosing saved tools - command-style pickers for tool targets, context paths, and template references such as `input` values, step `data`, and step `uiUpdate` - a visual builder for step cards, argument mappings, postconditions, outputs, evidence fields, and failure-policy toggles ### Test a composite tool Composite tools use the same **Test** action as other registry tools, but the result view is richer. After execution, review: - **Summary** for the final success/failure result and projected outputs - **Step Trace** for the ordered execution path and any skipped steps - **Postconditions** for final checks that passed or failed - **Raw JSON** when you need the full structured result This lets you validate the composed action before attaching it to a production agent configuration. ### Current limits for composite tools - Composite tools are authored in **Tool registry**, not inside agent config dialogs. - Composite steps must target saved registry tools. - Direct agent-tool steps are not supported in composite definitions. - Composite tools can call other composite tools, but keep nesting shallow and purposeful. - Legacy composite drafts with unusual payload shapes may need to be simplified back into the standard visual fields if they were authored in older JSON-assisted versions. ## Real-life example > A support team adds a "lookup_order" tool to the registry and links it to three agent configurations. When the API payload changes, they update the registry entry once and every agent picks up the fix. > A delivery team creates one composite tool that checks the current task state, writes the updated milestone record, and opens the relevant workspace surface. The config only needs to attach one business-level tool instead of three low-level ones. ## Notes - Internal tools are tagged as `internal` and are read-only for editing in the registry UI. - Duplicated tools keep the same name and advance to the next available version for that tool. - You can delete internal tools from the registry if they are not linked to any agent configuration. - Configs that link to a registry-backed composite still edit the definition in the Tool registry rather than creating a second authoring surface inside the config dialog. ## Access requirements - You need **View tool registry** to open this tab. - You need **Manage tool registry** to create, update, or delete tools. --- # Scheduled The **Scheduled** tab lets project admins define recurring jobs that run automatically. Interactive walkthrough: Open [Tutorials](/platform/support/tutorials) and select **Data Model Basics: Scheduled Jobs**. ## Job types - **Tool call:** Executes a Tool Registry entry with parameters (similar to the tool testing form). - **Internal operation:** Runs platform-maintained operations such as **updating dashboard statistics**, **assessing conversations**, **locking inactive conversations**, **processing locked conversation post-events**, or **assessing eval conversations**. The two conversation lifecycle operations complement the Text channel inactivity rule: - **Lock inactive conversations** applies each Text channel's configured inactivity period to unlocked conversations. Active turns are leased and are not locked mid-response. - **Process locked conversation post-events** queues any enabled final assessment, topic extraction, or other post-step that has not succeeded for a locked conversation. Completed steps are skipped, so the job can be run repeatedly and retried safely. ## Schedule builder Pick one of the supported schedules: - **Every N minutes** - **Daily at time** (`HH:mm`) - **Weekly on day at time** The schedule is stored and used to calculate the next run time. ## How execution is triggered Scheduled jobs are checked periodically based on the project setting: - **Project Settings → General → Scheduled jobs check interval (seconds)** While a project admin has the project open, the app runs a lightweight server-side tick that: 1. Finds due jobs. 2. Locks them to prevent duplicate runs. 3. Executes the job. 4. Records last run status and next run time. ## Real-life example > A project admin schedules nightly dashboard statistics updates and a weekly "refresh_entity_cache" tool call so performance metrics and embeddings stay current without manual work. ## Run a job immediately In the Scheduled jobs table, use the **Run** action to execute a job immediately. This updates the job's **Last run** fields and recalculates its **Next run** time. --- # Ingestion Webhook Use the ingestion webhook to push data from external systems into Gaia and trigger workflows automatically. It’s ideal for syncing nightly exports, event hooks, or any scenario where you want outside data to drive automations. ## How it works 1. **Create a context pipeline.** In **Data Model → Pipelines**, add a pipeline whose source listens for context keys (for example, `orders-*`). 2. **Attach the pipeline to a workflow.** Ensure the pipeline is the first step of any workflow you want to run when data arrives. 3. **Configure a webhook channel.** In **Tools → Channels**, add a **Webhook** channel, set the key, and choose the workflow you want to trigger. 4. **Grab the webhook URL.** The channel configuration shows the project-specific URL generated from the platform host configuration. 5. **Authenticate.** External systems should call the webhook with a project [service account](#doc-settings-service-accounts). Gaia accepts either `X-API-Key` or `Authorization: Bearer `. User API keys still work for legacy setups, but they inherit the real user’s permissions and are no longer the preferred pattern. 6. **Send JSON or multipart payloads.** Post JSON that represents the data you want to load, or use multipart form data when the workflow needs uploaded files. By default Gaia stores a context envelope under the configured key with request headers (sensitive headers redacted) and the parsed request payload before the workflow starts: ```json { "headers": { "...": "..." }, "payload": { "...": "..." } } ``` Pipeline mappings and TypeScript transforms must read structured request fields from `payload.*`, not from the record root. Multipart uploads are available to workflow nodes under `webhook_files`. Each entry contains `type`, `name`, `filename`, `mimeType`, `size`, `encoding`, and base64 `fileData`. Bind the complete entry as an attachment input for an agent node, or map it into a Tool Registry or TypeScript node. Gaia redacts `fileData` from workflow trace summaries. If you enable **Preserve raw body** in the webhook channel, Gaia also stores `rawBody` with the original request body string. Use that field for signature validation instead of `JSON.stringify(payload)` so the signature uses the exact bytes sent by the caller. 7. **(Optional) Enable dynamic responses.** In the webhook channel, enable **Dynamic response** if the caller must receive workflow-driven HTTP status codes and payloads. When a standard webhook request arrives, Gaia stores the payload immediately and queues the configured workflow for background processing. Multiple requests can line up while an earlier run is still active, and platform admins can watch the queue on the **Background Jobs** page. Each queued request still appears in the **Runs** tab once Gaia starts processing it. If the background run fails, Gaia retries the webhook ingest job up to three total attempts before dead-lettering it. If **Dynamic response** is enabled, Gaia keeps that webhook synchronous so it can return the workflow-generated HTTP status and response body to the caller. By default, Gaia replies with `202 Accepted`. When **Dynamic response** is enabled, Gaia replies using this format: ```json { "status": , "data": } ``` - If your workflow writes a response object at the configured response context key (default `webhook_response`), Gaia uses it. - The response object may include a `headers` object with string or numeric values. Gaia forwards safe end-to-end headers such as `Retry-After` and ignores response framing, cookie, authentication, and malformed header names. - If not, Gaia falls back to execution outcome details (workflow status, run id, progress) and maps the HTTP status from the run outcome. ## Real-life example > A CRM posts new leads to the ingestion webhook every night. The workflow normalizes each lead, enriches it with firmographic data, and writes the results back into a "Lead" entity for agents to use. ## Tips - Use descriptive key patterns (for example, `orders-YYYYMM` or `crm-leads`) so you can filter runs easily. - Read webhook body fields from `payload.*` and request metadata from `headers.*`. - Enable **Preserve raw body** when you need exact-body signature verification or audit/debug comparisons against the sender. - If you configure **JSON Array Path**, point it into the webhook envelope. Examples: `payload.items`, `payload.results`. - If that path resolves to an array, Gaia splits it into indexed context keys such as `orders-0`, `orders-1`, and your context source should read them with `orders-*`. - If that path resolves to a JSON object instead of an array, Gaia keeps a single context record at the exact webhook key. - If the whole webhook body is an array, Gaia splits `payload` item by item before downstream pipelines run. - If requests arrive faster than the workflow can finish, Gaia queues them and starts each one in turn. Check **Background Jobs** if you need to confirm that calls are waiting to run. - Share the rate limits with your integration partner so they can pace requests. If you need a higher limit, coordinate with your admin team. ## Troubleshooting - **Requests are rejected:** Double-check that the service account is active, the copied key is current, and the assigned project role includes **Manage runs** or another role with `modify-data-model-runs`. - **No workflows run:** Confirm the webhook channel points to the correct workflow and that the workflow’s first pipeline reads from the configured key. Then check **Background Jobs** to see whether requests are queued or retrying. - **Pipeline fields are suddenly empty:** Update mappings and transforms that still read root-level fields. Webhook request bodies now live under `payload.*`. - **Webhook signature validation fails:** Enable **Preserve raw body** and verify against `rawBody`, not a re-serialized `payload` object. Re-stringifying JSON can change whitespace, escaping, or key order. - **Too many requests:** If the integration sends bursts of traffic, add retry logic and consider staggering updates throughout the hour. --- # Workflow Run Details The **Workflow Run** page is the execution view for one specific workflow run. Use it to inspect progress, logs, timings, and the workflow definition that produced the run. ## Who can access this page? Only **project admins** can open workflow run details. If you are redirected back to the Runs table, request the required project access first. ## Key sections - **Page title.** The layout title includes the workflow name so you always know which workflow produced the run. - **Header bar.** Shows the run status plus start time, end time, and duration, along with actions such as **Configuration**, **Pipelines**, **Rerun**, **Pause**, **Resume**, **Stop**, and **Delete** when allowed. - **Progress badges.** Show active pipeline, sub-status, record counts, and surfaced errors while the run is active. - **AI usage badges.** Show tokens and cost when the run reports them. - **Execution trace.** Shows compact node-first workflow steps, route choices, checkpoint events, durations, and key context changes, with detailed payloads available on demand. - **Log.** Shows timestamped log entries with free-text search, metadata filters, manual refresh, sort order, and pagination. ## Use the run page 1. Open **Data Model -> Runs**. 2. Select the run you want to inspect. 3. Review the status line and progress badges. 4. Open **Execution trace** to inspect the path, step status, checkpoint saves or restores, and key context changes for each traced step. 5. Switch to **Log** when you need the raw timestamped messages for a stage or record. 6. Use **Rerun**, **Pause**, **Resume**, or **Stop** when the run state allows it. ## Jump back to the workflow definition Use the run page when execution is the problem. Use the workflow editor when the definition is the problem. - Click **Configuration** to open the workflow dialog for metadata review. - Open **Pipelines** to inspect linked pipelines and open an individual pipeline editor directly. - Use **Manage Order** from the **Pipelines** menu to open the workflow dialog on its pipelines tab. - If that workflow uses a graph definition, the dialog will show a read-only notice and an **Open graph editor** action. For graph-based workflows, treat the graph editor as the source of truth for topology. The run page should help you diagnose the path that executed, not replace the graph editor. ## Execution trace details The trace is stored with the run logs, so it stays available after refreshes and for completed runs. Gaia attributes each trace row to the node that produced it: - In legacy ingestion workflows, each pipeline is shown as the executed node. - In graph workflows, the node is the actual graph node, such as a tool, decision, loop, human action, or pipeline node. - Checkpoint rows show when Gaia saved or restored execution state for pauses, human actions, or resumes. - Context previews follow the workflow's **Context logging** setting. Detailed mode shows bounded nested values; compact mode shows shallow samples. Workflow-specific redacted paths and Gaia's built-in secret masking are applied before log persistence. Expand a trace row when you need message, checkpoint, raw event, or context in/out details. - Agent, tool, TypeScript, and human-action rows can include the resolved workflow knowledge scope so you can tell whether a node inherited workflow folders, used node-specific folders, or ran without workflow-provided knowledge. ## Rerun loop 1. Inspect the run and identify the failure point. 2. Open **Configuration** or the relevant item from **Pipelines**. 3. If the workflow is graph-based, continue from the dialog into **Open graph editor**. 4. Make the smallest safe fix. 5. Save the workflow or pipeline. 6. Return to the run page and click **Rerun** to validate the fix. ## Real-life example > A workflow pauses at a human-action node after the scoring pipeline finishes. The admin opens the run, confirms the pause reason in the logs, opens **Configuration**, continues into the graph editor from the read-only notice, updates the downstream branch, saves, and reruns the workflow to confirm the new execution path. ## Tips - Leave the page open while a run is active. Gaia refreshes status and logs automatically. - Watch the AI usage badges during long-running steps so you can spot unusually expensive branches. - Use **Execution trace** first when debugging graph routing, checkpoints, or workflow state changes. It separates route decisions from raw logs and keeps verbose context behind each row's details control. - Use the log filters aggressively when you need raw messages. Pipeline, stage, transform type, component type, event type, batch number, and record number can narrow large runs quickly. - If the issue seems structural, go from **Configuration** or **Pipelines -> Manage Order** into the graph editor instead of trying to reason about topology from logs alone. ## Troubleshooting - **Redirected to Runs:** You no longer have permission or the run no longer exists. - **Logs never load:** The run may have produced little or no logging for very short stages. Retry after confirming the workflow actually executed. - **Expected pipeline order does not match the run:** Check the saved workflow graph. For graph-based workflows, topology is defined there, even though the run page still exposes a **Manage Order** entry through the pipelines menu. --- # Delivery Management Track every delivery cycle your team is running for the project. Delivery Management includes Overview, Discussions, Process, Tasks, Milestones, Timeline, Status, Versions, and Project Spec tabs so planning, execution, collaboration, release baselines, and managed-configuration review stay in one place. ## Tabs - **Overview:** Cross-surface readiness summary for the project. - **Discussions:** Project-level discussion board for delivery conversations. See [Delivery Discussions](#doc-delivery-discuss). - **Process:** Lists active and historical delivery cycles with their current stage and status. See [Delivery Process Cycle](#doc-delivery-process-cycle). - **Tasks:** Opens the delivery task board so you can track work tied to cycles. See [Tasks](#doc-tasks). - **Milestones:** Project-level target points that can be linked to tasks across cycles. See [Milestones](#doc-delivery-milestones). - **Timeline:** Interactive Gantt chart for planned task/activity windows, drag-and-drop scheduling, dependency-aware shifts, and in-chart task creation/editing. See [Timeline](#doc-delivery-timeline). - **Status:** Team workload board for assigned tasks and current execution pressure. - **Versions:** Whole-project delivery baselines, deterministic change reports, and branch workspaces for reviewing changes before merge. See [Project Versions and Branches](#doc-delivery-versions). - **Project Spec:** Review the full managed-configuration dependency diagram Gaia uses for bootstrap previews, published bundle layering, and live project evolution. Select a node to inspect named dependencies and use **Open resource** to inspect the backing resource in a new browser tab. ## What you can do - **Create a new cycle.** Start from the standard four-stage framework (Planning (define) → Exploration (shape) → Development (build) → Evaluation) with a single click. - **Scan current progress.** Cards show the active stage, status badge, and creation date for each cycle. - **Jump into details.** Select any card to open the full [Delivery Process Cycle](#doc-delivery-process-cycle) view for stage-by-stage management. - **Record intent.** Add a description when you create a cycle so teammates know why the work matters. - **Import planning evidence from files.** In cycle details, use **Import** to ingest unstructured PDF/DOCX notes into stage/activity artifacts with an extraction report. - **Manage project checkpoints.** Use [Milestones](#doc-delivery-milestones) to set target points above cycle boundaries and connect tasks to strategic outcomes. - **Plan and rebalance work.** Use [Timeline](#doc-delivery-timeline) to create tasks, open task dialogs, drag tasks or entire activities in time, and tune the schedule scale with zoom. - **Coordinate delivery discussions.** Use [Delivery Discussions](#doc-delivery-discuss) to run thread-based conversations for decisions, blockers, and release updates. - **Capture and compare baselines.** Use [Versions](#doc-delivery-versions) to snapshot the current project, compare two snapshots, create branch workspaces, and merge clean branch changes back into the source project. - **Review managed configuration.** Use **Project Spec** to inspect agents, configs, channels, execution protocols, registries, folders, workflows, and data-model resources before approving managed changes. Interactive walkthrough: Open [Tutorials](/platform/support/tutorials) and select **Delivery Process: Plan, Sequence, and Schedule**. ## Create a delivery cycle 1. Go to **Tools → Delivery Management** inside your project. 2. Stay on the **Process** tab. 3. Click **New Cycle** (or **Create First Cycle** if the list is empty). 4. Name the cycle and optionally add a description with goals or scope. 5. Choose **Create Cycle**. You land on the cycle detail page ready to populate stages. ## Understand the list - **Status badge** highlights whether the cycle is `active`, `completed`, or `archived`. - **Current stage** shows which phase the team is working through. - **Created date** helps you gauge recency and compare timelines across cycles. - The empty state reminds everyone of the four-stage model and prompts you to start your first cycle. ## Real-life example > A platform team starts a cycle called “Customer Support GPT rollout.” They describe the target audience and success metric, then open the cycle to delegate activities for the Planning (define) stage. ## Tips - Keep names short but descriptive—call out the product, target segment, or launch window. - Use the description to capture KPIs or a link to the broader initiative brief. - After you wrap a cycle, mark remaining stages as completed from the detail page so the status badge switches to `completed` for historical visibility. ## Troubleshooting - **Button is disabled:** Provide a cycle name. Blank names are blocked. - **Cycle doesn’t appear in the list:** Refresh the page (the list loads once at page entry). Creating a cycle automatically pushes you to the detail page; returning to the list shows it. - **Access denied:** Only project or team admins can manage delivery cycles. Ask an admin to adjust your role if you need access. --- # Delivery Discussions Use **Delivery Management → Discussions** for project-scoped discussions tied to delivery work. ## What you can do - **Run project discussions.** Keep delivery conversations inside the current project context. - **Search and filter topics.** Use keyword search, tag filters, and sort options (`Recently updated`, `Recently created`, `Top voted`). Topic rows show whether the visible timestamp is the original creation time or newer activity. - **Create delivery-focused topics.** Start threads for blockers, decisions, risks, and release coordination. - **Write with Markdown.** Topic bodies, comments, and replies open in the Visual editor by default, with Markdown source available when you need it. Inline image upload remains available from the editor toolbar. - **Moderate content.** Users with discussion management permission can edit and moderate topics/comments. - **Watch important threads.** New topics are watched automatically by their creator. Use **Unwatch** to opt out, or **Watch** again later. - **Mention project users.** In project discussions, type `@` in topic titles, topic descriptions, or comments to open a dropdown of people who can access the current project. Mentioned users are automatically set to **Watch** that topic, get a mention notification, and render as highlighted mention pills in the rendered thread. - **Close inactive topics.** Users with discussion management permission can close topics when the team has no further planned action. Closed topics remain commentable, and a new comment reopens the topic automatically. - **Manage attachments while creating or editing a topic.** Add files up to 20 MB in the New Topic dialog or from the Edit Topic dialog. Topic pages keep attachments available for download without showing the file picker outside those edit flows. - **Print the rendered topic body.** Topic pages include a **Print** button in the body card so you can open the browser print dialog for the rendered Markdown. - **Show public task status on linked topics.** When a discussion is attached to a task, moderators can publish a public status badge so readers can see whether the linked work is open, in progress, or closed. - **Open linked project tasks from the topic.** When you have Delivery task access, the topic detail view exposes direct links back to the linked task so you can move from discussion into execution without searching the board. - **Share a topic.** Opening a topic updates the page URL with that topic. Use the link button in the topic header to copy a direct link that reopens the same thread for users with access. ## Open project discussions 1. Open a project. 2. Go to **Tools → Delivery Management**. 3. Click the **Discussions** tab. ## Notes - The **Discussions** tab in Delivery uses the same discussion experience and points to the same project-level topic space. - The topic-status filter defaults to open topics. Switch it to **Closed topics** or **All topics** when you need earlier discussion history. - `Recently updated` reflects the latest topic activity, including reply edits. - Public discussion status badges only appear for topics that are currently linked to a task. - Linked task shortcuts only appear for people who can access the relevant Delivery task surface. - Shared topic links preserve access control. A recipient still needs permission to view the project discussion. - Images embedded in project discussions are stored with the topic or reply and are removed automatically when that discussion content is deleted. - Access to Delivery Discussions requires Delivery visibility for the project. ## Assistant extraction to delivery intake (manual) Use this when discussion comments already contain planning details and you want a draft artifact quickly: 1. Open **Delivery Management → Discussions**. 2. Pick the topic you want to use as source. 3. In Gaia, ask to extract intake from that topic (you can reference the topic ID). 4. The assistant generates a first draft from topic body plus comments, mapping content to the selected template sections. 5. Answer only targeted follow-up questions for missing fields. 6. Review preview output and confirm commit explicitly to save evidence. Notes: - Extraction is manual per topic. There is no background auto-sync from discussions. - The assistant suggests section text, but will still flag unresolved fields when discussions lack enough detail. ## Access requirements - **View discussions** allows reading and participating in project discussions. - **Manage discussions** allows moderation and management actions. ## Related pages - [Delivery Management overview](#doc-delivery) - [Delivery Process Cycle](#doc-delivery-process-cycle) - [Platform Discussions](#doc-discuss) --- # Delivery Process Cycle The Delivery Process Cycle page is the command center for a single delivery cycle. Use it to review stage progress, capture activities and evidence, and coordinate owners as you move from Planning (define) to Evaluation. ## Related pages - [Delivery Management overview](#doc-delivery) - [Delivery Milestones](#doc-delivery-milestones) - [Delivery Timeline (Gantt)](#doc-delivery-timeline) - [Tasks](#doc-tasks) - [Delivery Discussions](#doc-delivery-discuss) ## Page tour - **Header badge** immediately shows whether the cycle is active, completed, or archived. - **Cycle actions** in the header let you **rename** the cycle, **cancel** it if work is no longer needed, or **move activities** between stages. - **Stage tabs** mirror the four standard phases. Each tab includes an indicator dot for the stage status (`not_started`, `in_progress`, `blocked`, or `completed`). - **Stage description toggle** surfaces recommended guidance pulled from Gaia's delivery playbook so everyone stays aligned on goals. - **Activity and evidence panels** list the work to complete the stage, the proof you have collected, and who owns each action. Evidence items carry a status (`to do`, `in progress`, `done`, or `cancelled`) so you can see readiness at a glance. - **Markdown evidence editors** let you capture structured write-ups and paste, drop, or upload inline screenshots directly into artifact content. ## Manage stage progress 1. Choose the stage tab you want to work on. 2. Use **Start Stage** to mark work as in progress and timestamp the kickoff. 3. Open activities to update status, due dates, or add notes. Expand the **Roles** section to review assigned owners and collaborators. 4. Add evidence (meeting notes, dashboards, URLs, or uploads) to document what you learned, and update each evidence status as it moves from **to do** to **done**. - For Markdown-based evidence, use the image button or paste/drop screenshots directly into the editor. 5. Activities can only be marked complete once all of their evidence is **done** or **cancelled**. 6. When all required activities are complete, select **Complete Stage**. You can reopen it later unless a downstream stage has already begun. ## Add activities faster - Click **Initialize from playbook** to seed the stage with recommended activities based on the Gaia delivery framework. - Use the **New Activity** button to create custom steps. You can categorize them with type, priority, and due date. - Attach evidence directly to an activity so reviewers can find context without leaving the page. ## Import from unstructured documents Use this when planning content already exists in a PDF or DOCX and you want Gaia to prefill artifacts. 1. Open the cycle page and click **Import** (left of **Roles**). 2. Select the target **Stage** and **Activity**. 3. Optionally select one **Artifact**. Leave it on auto-select to let Gaia pick relevant templates. 4. Upload a `.pdf`, `.docx`, `.txt`, or `.md` file and run **Import**. 5. Review the import report: - which artifacts were created, - section coverage (`filled/total`), - unresolved fields that still need manual completion. Notes: - Import only writes evidence for artifacts with meaningful extracted content. - Created evidence is marked as template evidence with import metadata (`source=import_document`). - Use this as a bootstrap. Review and refine extracted sections before final sign-off. ## Use assistant intake for Plan artifacts 1. Open Gaia from the left sidebar. 2. Ask it to start intake for a Plan template (for example, "start intake for Project Charter & Guiding Principles"). 3. Provide a freeform brief first. Gaia generates a full first draft across sections. 4. Answer only targeted follow-up questions for missing or uncertain fields (for example KPI owners or dates). 5. Ask for a preview. The assistant returns normalized sections plus unresolved-field notes. 6. Confirm save explicitly. Gaia commits the evidence and opens the saved artifact in Delivery. Notes: - Intake save is always explicit; drafts are not auto-committed. - For existing evidence, you can ask the assistant to commit into a specific evidence item (update) instead of creating a new one. - If you start intake from a discussion topic, the assistant first proposes text for all sections, then asks only missing-field follow-ups before preview and commit. ## Coordinate the team - Use **Roles** at the top of the cycle to set a single owner and any backup collaborators for each role once per iteration. - Activity **Roles** sections now display the assigned owner and collaborators as read-only so everyone sees the same assignments. - Expand **Evidence** to review detailed write-ups rendered with Markdown support. - Images embedded in Markdown evidence are stored with that artifact and are removed automatically if the artifact is deleted. - The stage timeline shows when work started or finished—helpful for retrospectives. ## Real-life example > During the Planning (define) stage of “Customer Support GPT rollout,” the owner initializes the playbook activities, opens **Roles** to set a PM as Driver with backups, and uploads discovery notes as evidence. Once the hypotheses are signed off, they complete the stage and move to Exploration (shape). ## Tips - Review the stage status dot before meetings—it gives a quick read on whether anything is blocked. - Keep evidence concise but link out to longer documents when needed. - Use **Rename** to correct typos or clarify scope after initial creation. - **Cancel** a cycle when the initiative is abandoned—the cycle remains in history for reference but is marked as canceled. - **Move activities** between stages if you discover work belongs in a different phase mid-cycle. - Reopen a completed stage only if the next stage has not started; otherwise, duplicate the cycle to explore major pivots. ## Troubleshooting - **Buttons do nothing:** You need project or team admin permissions to modify stages, activities, or evidence. - **Cannot create activities:** Initialize the stage first; the system needs a stage record before you can add items. - **Assignments missing people:** Ask an admin to add users to the project. The picker pulls from the project roster. - **Import fails immediately:** Check file format (`.pdf`, `.docx`, `.txt`, `.md`) and verify the selected stage/activity match where you want evidence created. - **Import created fewer artifacts than expected:** The extractor only creates artifacts with non-empty section content; rerun with a specific artifact selected if needed. --- # Delivery Milestones Use the **Milestones** tab in Delivery Management to define project-level target points and connect tasks to them. Milestones are not tied to a single delivery cycle. They are shared across the whole project and can anchor work from multiple cycles. ## What it shows - A project-level milestone list with title, status, and target date. - Linked task count per milestone. - Overdue highlighting when a planned milestone target date is in the past. ## Key interactions 1. **Create milestone** from the Milestones tab. 2. **Edit milestone** title, status, description, or target date. 3. **Delete milestone** (tasks stay intact and are automatically unlinked). 4. **Link tasks to milestones** from the task dialog (`Milestone` field). 5. **Open [Timeline](#doc-delivery-timeline)** to visualize milestone target points on the Gantt chart. ## Timeline behavior - Timeline renders milestone target points on a dedicated row. - You can drag a milestone marker horizontally to move its target date. - Linked tasks in Timeline are flagged as **After milestone** only when the task ends on a later calendar day than the target date. - Marker color reflects status and urgency: - Planned: amber - Completed: green - Overdue planned milestone: red ## Recommended flow 1. Open **Tools → Delivery Management → Milestones**. 2. Create major project checkpoints (for example: discovery sign-off, beta launch, production go-live). 3. Link relevant tasks to each milestone from the [task dialog](#doc-tasks-create-or-edit-a-task). 4. Open [Timeline](#doc-delivery-timeline) and adjust target points as task sequencing evolves. ## Related pages - [Delivery Management overview](#doc-delivery) - [Delivery Process Cycle](#doc-delivery-process-cycle) - [Delivery Timeline (Gantt)](#doc-delivery-timeline) - [Tasks](#doc-tasks) ## Tips - Keep milestone titles outcome-oriented (for example, “Pilot Approved”, not “Do pilot work”). - Use milestone status `completed` as soon as the checkpoint is reached to avoid false overdue signals. - Keep milestone count focused; too many target points reduce planning clarity. ## Troubleshooting - **Cannot create or edit milestones:** You need delivery modify permissions. - **Milestone missing in task dialog:** Refresh after creating it, then reopen the task dialog. - **Task still exists after deleting milestone:** Expected; milestone deletion only removes the link, not the task. --- # Delivery Timeline (Gantt) Use the **Timeline** tab in Delivery Management to plan and adjust delivery work on an interactive Gantt chart. Interactive walkthrough: Open [Tutorials](/platform/support/tutorials) and select **Delivery Process: Plan, Sequence, and Schedule**. ## What it shows - Delivery activities as parent rows. - Tasks linked to each activity as child rows. - Tasks without an activity in a dedicated group at the end of the timeline (after stage rows). - Work items grouped by delivery stage first, then by the stage's activity sequence. - Project milestones as target-point markers. - Planned start/end windows for tasks and activities. - Duration labels on task bars (inside the bar when space allows, otherwise next to the bar). - Day-level zoom displays rounded day durations. - Durations above 5 hours are also shown in days to keep calendar planning readable. - Timeline opens scrolled near **today** so current planning work is immediately visible. - A vertical **today** marker appears behind bars across the chart. - Task bar colors that reflect task status. - Overdue tasks (past planned end date) highlighted in red unless already done/canceled. - Tasks linked to milestones show an **After milestone** badge when their planned end falls on a later calendar day than the milestone target date. - Dependency arrows (finish-to-start) drawn between related task bars. ## Key interactions 1. **Drag a task bar** to move the task in time. 2. **Drag the left or right handle** to resize task duration. 3. **Single-clicking a task bar does not reschedule anything**; changes are saved only after an actual drag. 4. **Click task titles** to open the full task dialog from inside Timeline. 5. **Use New task** to create tasks without leaving the Gantt view. 6. **Use New milestone** to create project-level target points directly from Timeline. 7. **Change Zoom** to switch between 2-month overview and detailed week planning. 8. **Resize/move snaps by zoom level:** day-level snapping on overview zoom, hour-level snapping on detailed zoom. 9. **Drag an activity bar** to shift all activity tasks together. 10. **Drag an activity handle** to extend activity boundaries by adjusting the first or last planned task. 11. **Drag milestone points** to update target dates. 12. **Collapse stages, activities, or the final _Tasks without activity_ group** with the chevron controls to focus on just the work rows you need. ## Dependency behavior - Dependencies are **finish-to-start**. - Arrows are rendered in the chart from predecessor finish to successor start. - When a predecessor moves later, successors are pushed later automatically. - Push is one-way (no auto pull-earlier). - Dependencies are restricted to tasks in the same delivery cycle. ## Recommended flow 1. Open **Tools → Delivery Management → Timeline**. 2. Select the target cycle in the **Cycle** filter. 3. Create initial tasks from **New task** (or switch to [Tasks](#doc-tasks) for bulk setup). New tasks default to `To Do` with a 1-day plan window starting at the current hour. 4. Set task plans directly on the chart and open task dialogs by clicking task titles. 5. Add dependencies from the [task dialog](#doc-tasks-create-or-edit-a-task) so sequencing is enforced. 6. Rebalance activities by dragging the activity row as priorities change. 7. Use the **refresh icon** whenever other users changed tasks and you want a fresh server snapshot. 8. Track strategic checkpoints by adding [milestones](#doc-delivery-milestones) and linking tasks to them from the task dialog. ## Related pages - [Delivery Management overview](#doc-delivery) - [Delivery Process Cycle](#doc-delivery-process-cycle) - [Delivery Milestones](#doc-delivery-milestones) - [Tasks](#doc-tasks) ## Tips - Start with coarse windows first, then tighten task durations. - Use **2-month overview** zoom during initial planning and switch to detailed zoom for fine adjustments. - Expect day-level drag/resize snapping in overview zoom, and hour-level snapping in detailed zoom. - In day-level zoom, duration labels are rounded to days; in detailed zoom, durations above 5h are still shown in days. - Add dependencies only where sequence truly matters. - Timeline shows task and issue work only. Meeting-type tasks are managed from the Tasks tab and do not render on the chart. ## Troubleshooting - **Bar won’t move:** You need delivery modify permissions. - **Task snaps later than dragged position:** An incoming dependency required a later start. - **Cannot add dependency:** Both tasks must belong to the same delivery cycle. - **What does the refresh icon do?** It refreshes Timeline from server state (tasks + dependencies) after external changes. --- # Project Versions and Branches Use **Delivery Management -> Versions** to capture whole-project baselines, compare what changed between baselines, and create branch workspaces for changes that should be reviewed before they affect the current project. ## What a version captures A project version is a materialized snapshot of the portable project structure at the time you create it. It covers project configuration, agents, configs, channels, data model resources, delivery records, eval assets, governance records, roles, tasks, and milestones. Runtime history such as conversation transcripts, workflow runs, and existing version history is not stored inside the version snapshot. Older audit-trail version tags may appear as **Legacy** entries. They remain visible for history, but they cannot be compared or used as a branch base because they do not include a materialized snapshot. ## Create a version 1. Open **Tools -> Delivery Management -> Versions**. 2. In **Create Version**, enter a short name such as `v1.0 launch baseline`. 3. Add an optional description that explains the release, checkpoint, or review event. 4. Select **Create Version**. The new version appears as **Ready** when the snapshot is stored successfully. ## Clean existing snapshots Use **Clean Snapshots** on the Versions page to repair older project versions that were captured before runtime history was excluded from version snapshots. Gaia rewrites snapshot-backed versions to remove conversation transcripts, workflow runs, and embedded version history, then recomputes the snapshot hash. Legacy entries without materialized snapshots are skipped. ## Compare versions 1. In **Compare Versions**, choose a **From version**. 2. Choose **Compare with**: - Select another saved version to compare two baselines. - Select **Current configuration** to compare the saved baseline with the live project configuration. 3. Select **Generate**. 4. Review the report grouped by project area. Each changed resource includes field-level before/after values and the available user attribution from the compared snapshots. 5. Use the download button to save the report as Markdown when you need to share it outside Gaia. Saved-version reports are deterministic. Reports list added, removed, and changed resources without sending the diff to an AI model. ## Create a branch workspace 1. Choose a snapshot-backed **Base version**. 2. Name the branch after the change being explored. 3. Select **Create Branch**. 4. Open the branch from the branch list. A branch is a live Gaia project workspace hidden from normal project lists. The branch banner links back to the source project's Versions tab. Make changes inside the branch using the regular Gaia pages. ## Preview and merge a branch 1. Return to the source project **Versions** tab. 2. Select **Preview** for the branch. 3. Review the merge report. 4. If Gaia reports no conflicts, select **Merge**. Gaia compares the base version, the current source project, and the branch workspace. If the same record changed in both source and branch after the base version, the merge is blocked so the team can resolve the conflict deliberately. ## Promote between environments Use **Environment Promotion** when the same project exists in more than one Gaia instance, such as dev, staging, and production. Promotion is pull-based from the destination project. The destination project uses a short-lived transfer token issued by the source project, fetches a selected snapshot-backed source version, previews the changes, and applies only clean promotion runs. ### First-time setup from dev only Use this sequence when the project exists only in dev, has no project versions yet, and staging and production do not exist. 1. In the dev project, create the first project version, such as `dev bootstrap baseline`. 2. Create staging from dev with one of these bootstrap paths: - Use **Project Settings -> General -> Export Project** in dev, then open **Teams** in staging, select **Import**, choose the exported JSON file, and create the staging project. - Use **Teams -> Import -> Gaia instance** in staging when the source and destination instances are network-reachable and the transfer allow lists are configured. 3. Avoid changing the dev project until the staging import or transfer completes, so the imported staging project still matches the dev version you just captured. 4. In the staging project, create an environment link that points back to the dev project. 5. From staging, load the dev source versions with a dev transfer token, choose the `dev bootstrap baseline` version, preview, and apply the run. This first run should normally be a no-change promotion. Its purpose is to store promotion lineage for future 3-way previews. 6. After staging is accepted, create a staging project version, such as `staging accepted baseline`. 7. Create production from staging with the same bootstrap choice: - Export the accepted staging project and import that JSON file from **Teams** in production. - Or start **Teams -> Import -> Gaia instance** from production with a transfer token issued by the staging project. 8. In the production project, create an environment link that points back to staging. 9. From production, load the staging source versions, choose `staging accepted baseline`, preview, and apply the initial no-change promotion to establish production lineage. After this setup, routine releases should move by promotion, not by full transfer: 1. Dev team makes changes in dev. 2. Dev creates a new project version for the release candidate. 3. Staging pulls that dev version through its dev -> staging environment link, previews it, and applies it only when the run is ready. 4. After staging validation, staging creates an accepted version. 5. Production pulls that staging version through its staging -> production environment link, previews it, and applies it only when the run is ready. If you choose a direct dev -> production link, production can pull dev versions directly. Use a staging -> production link when staging is the release gate and production should receive only validated staging versions. ### Create an environment link 1. Open the destination project. 2. Go to **Tools -> Delivery Management -> Versions**. 3. In **Environment Promotion**, select **Create Link**. 4. Enter a link name, source Gaia URL, source project ID, source environment label, and destination environment label. 5. Save the link. Use the existing cross-instance transfer allow lists before creating links. The source instance must allow the destination host, and the destination instance must allow the source host. ### Preview and apply a promotion 1. On the source project, create a project version and issue a transfer token for the destination host. 2. On the destination project, select **Promote** on the environment link. 3. Paste the transfer token and select **Load**. 4. Choose a source version. 5. Select **Preview**. 6. Review the promotion report and conflicts. 7. If the promotion run is **Ready**, select **Apply** from the promotion runs table. Gaia compares the last promoted source baseline, the selected source version, and the current destination project. If both source and destination changed the same resource differently, the run is blocked. ### Roll back a promotion Completed promotion runs keep the destination version captured before apply. Select **Roll back** on a completed run to restore that pre-promotion destination snapshot through a new auditable run. ## Bootstrap versus promotion Use cross-instance project transfer when you need to create a full-fidelity copy of a project in another instance. Use environment promotion after the environment project already exists and you need controlled, version-backed release movement. Manual export/import is also valid for the first bootstrap. Export the source project from **Project Settings -> General**, then use **Teams -> Import -> Export file** on the destination instance to create the new project from that export file. After the destination project exists, switch to environment promotion for routine releases instead of repeatedly importing full exports. The first no-change promotion after transfer is still useful. It records which source version the destination environment was initialized from, so later promotion previews can detect changes on both sides instead of treating the destination as an unrelated project. ## Access requirements - Viewing versions requires `view-delivery`. - Comparing a saved version with the current configuration also requires `export-project`. - Creating or deleting versions and creating branches requires `modify-delivery` plus `export-project`. - Merging branches requires `modify-delivery`, `export-project`, and `import-project`. - Creating environment links and loading source versions requires `modify-delivery` plus `transfer-project`. - Previewing promotion requires `modify-delivery`, `export-project`, and `transfer-project`. - Applying or rolling back promotion requires `modify-delivery`, `export-project`, and `import-project`. --- # Artifact Templates - User Guide ## Overview The Delivery Process now supports structured artifact creation using predefined templates. Instead of simple text notes, you can create rich, structured evidence using templates tailored to each process stage. ## Features ### 1. Template-Based Artifacts Choose from predefined templates that match your current stage and activity: - **Planning (define) Stage**: Business Case, Project Charter, Success Metrics, Stakeholder Map, etc. - **Exploration (shape) Stage**: Data Requirements Matrix, Data Entity Diagram, Pipeline Architecture, etc. - **Development (build) Stage**: Agent Persona Brief, Tool Integration Strategy, Prompt Library, UI Prototypes, etc. - **Evaluation Stage**: Evaluation Criteria Matrix, Scenario Test Suite, Compliance Checklist, etc. ### 2. Dynamic Form Rendering Each template section renders with the appropriate input type: - **Text fields** for short inputs - **Text areas** for longer descriptions - **Number fields** for metrics - **Date pickers** for timelines - **Dropdowns** with predefined options - **Switches** for boolean flags - **Markdown editors** for rich formatted text - **Dynamic tables** with add/remove row functionality ### 3. Formatted Text Option For quick notes or documentation, use the "Formatted Text" option to create markdown-formatted evidence with: - Headers, lists, and formatting - Code blocks - Links and images - Tables ### 4. Custom Artifacts The original simple artifact dialog is still available for quick, unstructured notes. ## How to Use ### Adding Evidence to an Activity 1. Navigate to a delivery process stage 2. Expand an activity to view the "Evidence & Artifacts" section 3. Click the **"Add Evidence"** button (with sparkle icon) 4. A command picker dialog appears with three categories: - **Artifact Templates**: Templates specific to this activity - **Other Options**: Formatted Text and Custom Artifact ### Using a Template 1. Select a template from the picker (e.g., "Data Requirements Matrix") 2. The dialog opens showing all template sections 3. Fill in each section: - For tables: Click "Add Row" to add entries, trash icon to remove - For markdown: Use the Visual tab for formatted editing or switch to the Markdown tab to edit the canonical source directly - For dropdowns: Select from predefined options 4. Click "Add Evidence" to save ### Using Formatted Text 1. Select "Formatted Text (Markdown)" from the picker 2. Enter a title and description 3. Use the Visual tab for formatted editing, or switch to the Markdown tab when you want to work directly with the canonical markdown 4. Switch between tabs at any time to review either the rendered document structure or the raw markdown source 5. Click "Add Evidence" to save ### Using Custom Artifact 1. Select "Custom Artifact" from the picker 2. Fill in basic fields: title, type, description, content 3. Click "Add Evidence" to save ### Exporting/Importing DOCX Forms - In a template dialog, click **Download DOCX form** to export the activity artifact as a Word form your stakeholders can fill offline. - When you receive a filled form, click **Import filled DOCX with AI** in the same dialog. Gaia will read the document, map responses back to each template section, and pre-fill the fields for review before saving. ## Real-life example > A delivery manager selects the "Data Requirements Matrix" template, exports the DOCX form for stakeholders to fill offline, then imports the completed form so the artifact is ready for review in the Evaluation stage. ## Data Storage ### Template Evidence Structure ```json { "title": "Data Requirements Matrix", "type": "template", "metadata": { "template": "Data Requirements Matrix", "stage": "exploration" }, "content": { "Data Sources Inventory": [ { "Data Source Name": "Customer Database", "System / Repository": "PostgreSQL", "Data Type": "Structured", "Refresh Frequency": "Daily", "Owner": "Data Team", "Access Method": "Database" } ], "Discovery Summary": "# Key Findings\n\nData is ready..." } } ``` ### Formatted Text Structure ```json { "title": "Meeting Notes", "type": "formatted", "metadata": { "isFormatted": true }, "content": { "text": "# Meeting with Stakeholders\n\n## Key Points..." } } ``` ## Template Structure Templates are defined in JSON files located in `docs/process/`: - `plan-artifacts.json` - `exploration-artifacts.json` - `development-artifacts.json` - `evaluation-artifacts.json` Each template includes: - **name**: Display name for the template - **sections**: Array of form sections - **title**: Section heading - **description**: Help text - **input**: Input type or table definition ### Example Template Section (Simple) ```json { "title": "Business Problem or Opportunity", "description": "Describe the core challenge or opportunity driving this AI initiative.", "input": "markdown" } ``` ### Example Template Section (Table) ```json { "title": "Data Sources Inventory", "description": "List all internal and external data sources.", "input": { "type": "table", "columns": [ { "name": "Data Source Name", "type": "text" }, { "name": "Data Type", "type": "select", "options": ["Structured", "Unstructured"] }, { "name": "Owner", "type": "text" } ] } } ``` ## Supported Input Types | Type | UI Component | Description | | ---------- | --------------- | --------------------------------- | | `text` | Input | Single-line text field | | `textArea` | Textarea | Multi-line text field | | `number` | Input (number) | Numeric input | | `date` | Date picker | Date selection | | `switch` | Toggle switch | Boolean on/off | | `select` | Dropdown | Selection from predefined options | | `markdown` | Markdown editor | Rich text with formatting | | `table` | Dynamic table | Multi-row structured data | ## Tips ### For Template Selection - Templates are filtered by activity when inside an activity - All stage templates are shown when adding evidence at stage level - Use the search box in the picker to quickly find templates ### For Gaia Drafts - Ask Gaia to draft evidence or template responses when you already know what you want to capture. - Provide the stage, template name, and a short brief so the assistant can return structured section data you can paste into the dialog. ### For Table Inputs - Start with one row and add more as needed - Use Tab to move between cells - Click trash icon to remove unwanted rows - You cannot remove the last row (minimum one row required) ### For Markdown Sections - Use the toolbar or keyboard shortcuts for formatting - Preview updates in real-time - Supports GitHub-flavored markdown - Use code blocks with syntax highlighting ### For Editing - Editing existing template-based evidence preserves the template structure - All sections are re-rendered with saved data - Table rows are restored exactly as saved ## Best Practices 1. **Choose the Right Template**: Match the template to your activity for best results 2. **Fill All Required Sections**: Templates guide you through all necessary information 3. **Use Tables for Structured Data**: Tables keep related data organized and searchable 4. **Use Markdown for Documentation**: Rich formatting makes documentation more readable 5. **Consistent Naming**: Use clear, descriptive titles for easy finding later 6. **Regular Updates**: Update template evidence as your project evolves ## Troubleshooting ### Template Doesn't Appear in Picker - Verify you're in the correct stage - Check that the activity code matches the template definitions - Ensure JSON files in `docs/process/` are valid ### Data Not Saving - Ensure required fields (title) are filled - Check browser console for errors - Verify you have permission to edit the process ### Table Rows Not Showing - Check that the section data in content matches the section title - Verify the table structure matches the template definition ## Future Enhancements Planned improvements include: - Evidence viewer with formatted template data display - Export to PDF/Word with template formatting - Custom template creation UI - Template versioning and migration - Field validation and constraints - Template inheritance and composition --- # Audit Trail The Audit Trail keeps a running record of project changes so operators can trace who changed what, when it changed, and what the before-and-after state looked like. Open it from [Project Settings](#doc-settings) -> **Audit Trail**. ## Related pages - [Control Plane Evidence](#doc-control-plane-evidence) - [Project Settings](#doc-settings) - [Project roles](#doc-settings-project-roles) - [Dashboard](#doc-dashboard) - [Tasks](#doc-tasks) ## What you can review - **Structured activity feed.** Every row shows the operation (create, update, delete, view), the entity that changed, the acting user, and a natural-language description. The audit trail covers agents, configurations, entities, conversations, eval conversations, delivery evidence, and more. - **Pagination for large histories.** Navigate page by page through audit records and change the page size when your project has extensive history. - **Manual refresh.** Use the refresh button to reload the first page after recent changes. - **SIEM JSONL export.** Use **SIEM JSONL** to download the latest project audit rows as newline-delimited JSON with Gaia schema version, event timestamp, actor, entity, operation, description, context, and before/after values. - **Governance Evidence JSONL export.** Use **Governance Evidence JSONL** when a reviewer needs one file that combines project audit rows with governance runtime telemetry for policy decisions, MCP gateway decisions, schema drift detection, and accepted-baseline attestations. - **Detailed diffs.** Click the eye icon to open a side-by-side JSON diff of the previous and new values. Inline highlighting focuses on exactly what changed. For delete operations, the diff viewer shows what was removed. - **Traceability for version events.** Project version and branch activity is recorded here as audit events, while the versioning workflow itself lives in [Delivery Versions](#doc-delivery-versions). ## Review a change 1. Open **Project Settings -> Audit Trail**. 2. Use the paging controls to move through the history or increase the page size when you need broader context. 3. Click **SIEM JSONL** when you need a SIEM-ready export of the current audit history, or **Governance Evidence JSONL** when the evidence pack also needs runtime governance telemetry. 4. Click the eye icon on a row to open **Audit Log Details**. 5. Review the operation, entity type, entity name, acting user, description, timestamp, and JSON diff. 6. If the change needs follow-up, create or update a related [task](#doc-tasks). ## SIEM evidence paths Gaia exposes audit and governance runtime events for SIEM or review evidence in three ways: - **Audit Trail JSONL:** open **Project Settings -> Audit Trail** and click **SIEM JSONL** to download collector-neutral project audit events. - **Governance Evidence JSONL:** open **Project Settings -> Audit Trail** and click **Governance Evidence JSONL** to download schema version `gaia.audit.governance_evidence.v1`, which includes project audit rows plus governance runtime telemetry rows for runtime policy decisions, MCP gateway decisions, MCP schema drift, and accepted-baseline attestations. This export requires both audit-trail and governance view permissions. - **Governance control-plane export:** open **Governance -> Runtime -> Agent Systems**, select the governed boundary, click **Configure SIEM/control-plane export**, enter the OTLP or collector HTTP endpoint, and use **Send SIEM export** when a selected boundary needs a manual telemetry delivery run. Runtime policy decisions export searchable policy id, policy record id, policy version, rule id, outcome, configured outcome, reason code, enforcement mode, latency, tool-message ref, audit ref, and delivery ref attributes. Use the Audit Trail JSONL path when the reviewer needs project-change audit rows only. Use Governance Evidence JSONL when a reviewer needs a single file combining project changes and runtime governance telemetry. Use the Governance control-plane path when the reviewer needs scoped OTLP/control-plane delivery from governed agent-system boundaries. Target-specific SIEM collector setup remains a delivery integration decision. For control-plane evidence, keep the two SIEM paths separate: - use **Audit Trail JSONL** to prove project changes, acting user, operation, entity, timestamp, context, and before/after values; - use **Governance Evidence JSONL** to prove the audit rows together with runtime policy, MCP gateway, schema drift, and accepted-baseline telemetry in one newline-delimited evidence file; - use **Governance control-plane export** to prove metadata-only runtime telemetry for selected governed agent-system boundaries, including searchable runtime policy decision attributes for governed-tool interventions and review-mode warnings. The final SIEM destination, alert thresholds, payload routing, and incident escalation policy are deployment-specific. Capture those details in the delivery evidence pack, then link the exported Gaia evidence to that pack. ## Real-life example > A project admin spots an unexpected configuration change before launch. They inspect the audit row to confirm who made the change, then open [Delivery Versions](#doc-delivery-versions) to compare the current project against the launch baseline. ## Operational workflow Use Audit Trail after you spot an issue somewhere else in the project: 1. Notice an unexpected trend in [Dashboard](#doc-dashboard). 2. Open Audit Trail to review the most recent project changes. 3. Inspect the detailed diff for the most likely candidate changes. 4. Capture remediation or validation work in [Tasks](#doc-tasks). ## Access requirements Users need the `view-audit-trail` project permission. Governance Evidence JSONL also requires `view-governance`. If you cannot open the page or export the governance evidence file, contact a project admin to update your role. --- # Dashboard The project **Dashboard** aggregates project activity into a configurable widget layout. It supports four tabs so you can review conversation traffic, model usage, eval trends, and workflow activity without leaving the project. The page is available at **Tools -> Dashboard** for users who have the `view-dashboard` permission. ## Related pages - [Control Plane Evidence](#doc-control-plane-evidence) - [Platform Dashboard](#doc-platform-dashboard) - [Update Statistics](#doc-conversations-dialogs-update-statistics) - [Audit Trail](#doc-audit) - [Timesheet](#doc-timesheet) - [Evals](#doc-evals) - [Data Model Workflows](#doc-data-model-workflows) ## What you'll see - **Date-range toolbar:** Set the reporting window with the shared date-range picker, choose an hourly, daily, weekly, or monthly bucket for time-series widgets, then use **Refresh** to pull fresh numbers or **Reset** to restore the default dashboard layout. - **Projection overlay:** Turn on **Projections** when an active tab has enough time-series data to see an exploratory forward view. Gaia keeps observed bars and projected dashed lines visually separate, and eligible number cards show a small muted projected value beside the observed metric. - **Widget help and readiness:** Every widget keeps a short subtitle in the header, and the info button opens a longer plain-language explanation of what the metric means and how to read it. Source-dependent widgets can also show a warning button before the info button when Gaia needs configuration, new results, refreshed statistics, or a backfill. - **Conversations tab:** Review conversation volume, off-topic rate, inferred resolution and effort proxies, token usage, costs, latency, grouped conversation metrics, and the mix of written feedback versus thumb-rated replies. - **Post-step-backed metrics:** Some conversation quality and topic widgets depend on post-step output. Assessment charts need the active agent configuration to run the **Assessment** post-step before Gaia can aggregate quality, sentiment, engagement, clarity, tone, helpfulness, or coherence scores. Topic widgets need **Topic Extraction** results and use Project Settings topic taxonomy when you want extracted labels grouped into categories or chat groups. Use the warning button on those widgets to see whether the post-step is missing or enabled without refreshed results. - **AI Usage tab:** Review model-by-model request volume, token usage, spend, latency, hourly token trends, and the dedicated **Folder Indexing Spend** summary card for document-folder indexing cost inside the current project. - **Evals tab:** Review evaluation metrics in the same widget grid system so quality trends can be compared against usage. - **Workflows tab:** Review workflow-oriented metrics for the project's broader workflow activity. - **Custom widget layouts:** The Conversations, Evals, and Workflows tabs keep their own saved widget layouts. The AI Usage tab is a fixed analytics surface so model comparisons stay consistent. - **Custom dashboards:** Open **Custom dashboards** from the dashboard toolbar when you need project-specific SQL-backed widgets. Custom widgets must be previewed before saving and are limited to read-only, project-scoped, date-bounded queries. Each custom dashboard tab keeps its own saved filters, and saved widgets can be run with those filters and exported as CSV. Custom dashboards can also show imported/API explicit resolution, CSAT, and CES outcomes when those records exist. - **Project scope:** This dashboard stays inside one project. Platform admins who need a cross-project view should use [Platform Dashboard](#doc-platform-dashboard). ## Predictive and anomaly review Gaia's project-level predictive view is the **Projections** overlay in **Dashboard**. It is shown on eligible time-series widgets after you choose a date range and turn on **Projections**. The overlay is exploratory: projected values are shown as dashed lines or compact side values and are not written back into stored telemetry. For anomaly review, use the dashboard as the first signal surface: inspect spikes, dips, outliers, quality changes, latency changes, cost changes, or workflow failures in the active tab, then open [Audit Trail](#doc-audit), [Evals](#doc-evals), or [Tasks](#doc-tasks) for investigation and follow-up. Gaia does not expose a separate automatic anomaly-detector configuration on this page. For control-plane evidence, capture the selected date range, active tab, relevant widget help text, and the follow-up surface used to explain the signal. Use **AI Usage** for model requests, tokens, cost, latency, and folder indexing spend; use **Evals** for quality posture; use **Workflows** for workflow activity; and use **Conversations** for user-turn volume and feedback. When a review requires formal drift or anomaly thresholds, record the agreed thresholds in the delivery evidence pack and use Dashboard screenshots as the supporting signal surface. ## How to use it 1. Open your project and select **Dashboard** (bar chart icon). 2. Choose a date range using the picker. Use the Current/Previous/Last dropdowns for quick presets, or pick a custom span from the calendar. 3. Choose the time bucket when you want time-series charts to aggregate by hour, day, week, or month. 4. Start on **Conversations** to inspect overall traffic, cost, or error trends. 5. Use the conversation-count widget footer to compare overall feedback coverage against the share of thumb-rated conversations that are positive versus negative. 6. Switch to **AI Usage** when you need to see which models are driving token volume, spend, or latency inside the project, or when you want the dedicated **Folder Indexing Spend** card for document-folder indexing cost. 7. Switch to **Evals** when you need to compare quality or run performance for the same period. 8. Switch to **Workflows** to review workflow-oriented activity for the same date range. 9. Click **Refresh** to fetch the latest stats for the selected tab and range. 10. Toggle **Projections** when you want to extend eligible time-series charts into the next matching review window. The overlay is session-only and does not change stored metrics. 11. Use **Reset** to restore the default widgets and layout if the dashboard gets messy. ## Metric prerequisites Most dashboard widgets come from project telemetry, such as conversations, model usage, tool calls, turn timing, feedback, eval runs, and workflow runs. These widgets only need matching activity in the selected date range plus fresh statistics. Post-step-backed widgets need another source before they can show values. When a widget has a source issue, Gaia shows a warning button before the widget info button: - **Assessment metrics:** Enable the **Assessment** post-step on the active agent configuration, run new conversation turns, then refresh dashboard statistics. See [Agent Configuration](#doc-agents-configs-post-steps) for post-step setup. - **Topic analysis metrics:** The **Top Topics**, topic category, and chat group widgets require the **Topic Extraction** post-step. Configure category/chat-group mapping in **Project Settings -> Topic taxonomy** when you want extracted labels rolled up beyond the raw label. Unmapped extracted labels are grouped as **Unmapped**. - **Inferred resolution metrics:** Resolved, unresolved, AI-resolved without handoff, handoff patience, inferred CSAT, and inferred CES are labeled as inferred or proxy metrics. They combine available conversation signals such as non-empty turns, error/off-topic markers, handoff or external takeover signals, thumbs, assessment output, written feedback sentiment, user turns, and elapsed time. Treat them as operational indicators, not survey-grade source-of-truth fields. - **Explicit outcome metrics:** Custom dashboards can use imported/API explicit outcome records for source-of-truth resolution, CSAT, and CES. These metrics stay separate from inferred/proxy widgets and use the latest submitted explicit outcome per conversation for the selected conversation date range. ## Custom dashboards Open **Dashboard -> Custom dashboards** when the built-in tabs are not enough for a project review. Custom dashboards support tabs and saved widgets. You can ask Gaia for a widget draft in natural language; the dashboard builder uses a model-backed schema catalog when a reasoning or generative model is configured and falls back to a constrained deterministic draft when model generation is unavailable. Preview the generated SQL result, review the SQL checklist, then save it as one of the supported widget types: **single metric**, **metric pair**, **metric over time**, **grouped metrics**, **line chart**, **bar chart**, **pie chart**, or **table**. Use the custom dashboard filters when a widget includes optional filter parameters. Each tab stores multi-select filters for agents, channels, models, topic labels, topic categories, and topic chat groups. Empty selections mean “all values,” and saved widget SQL stays parameterized so the same widget can be rerun with different filters. If a saved tab filter points to a value that is no longer available in the project, Gaia keeps the value visible as **unavailable** so you can remove it deliberately. New generated SQL prefers plural filter parameters such as `:agentIds`, `:channels`, `:models`, `:topicLabels`, `:topicCategories`, and `:topicChatGroups`. Older saved SQL that uses singular parameters such as `:agentId`, `:channel`, or `:model` still runs; Gaia binds those parameters to the first selected value for backward compatibility. The dashboard builder understands inferred resolution, inferred CSAT, inferred CES, and handoff-patience requests in custom dashboards. These generated widgets remain explicitly labeled as inferred/proxy metrics and can include confidence-grade columns. Confidence grades are based on sample size plus source coverage: **High** means at least 50 samples and 3 evidence families, **Medium** means at least 15 samples and 2 evidence families, and **Low** covers thinner evidence. When explicit outcome records are imported through the API/import path, the builder also understands explicit resolution, explicit CSAT, and explicit CES requests. Those widgets are source-of-truth metrics, do not show inferred confidence grades, and do not replace the inferred/proxy widgets that remain useful for projects without explicit outcome records. Custom dashboard SQL is intentionally constrained: - It must be a read-only `SELECT` or `WITH` query. - It must include project scope with `:projectId`. - It must include `:startDate` and `:endDate`. - Gaia rejects semicolon chaining, mutation or DDL statements, transaction statements, unsafe database functions, non-dashboard telemetry tables, oversized date ranges, and unbounded result sets. - Approved dashboard telemetry tables include conversation activity, AI/tool/turn/assessment stats, feedback, topic taxonomy outputs, and explicit outcome records. Arbitrary application tables stay blocked. - Preview and saved widget runs execute server-side with dashboard permissions, a row limit, and a statement timeout. - The **Save widget** action stays disabled until you preview the query and explicitly confirm that you reviewed the generated SQL and preview output. - Saved widgets can export the current run result as CSV from the widget toolbar. Read empty dashboard states carefully: - **No activity in this date range** means the underlying metric exists, but there are no matching records for the selected window. - **Metric source is not configured** means Gaia does not have the required post-step or explicit source for that widget. - **Metric source has no results yet** means the source is configured, but Gaia still needs new turns, a backfill, or refreshed statistics. ## Operational workflow The dashboard works best as the first stop in an operational review loop: 1. Review the project-level trends here. 2. If a spike looks suspicious, refresh statistics or run [Update Statistics](#doc-conversations-dialogs-update-statistics). 3. Open the [Audit Trail](#doc-audit) to inspect recent changes that might explain the shift. 4. Capture the follow-up in [Tasks](#doc-tasks). 5. Use [Timesheet](#doc-timesheet) to check where effort is already being spent before assigning more work. 6. If you need to compare the issue against other projects, switch to [Platform Dashboard](#doc-platform-dashboard). ## Real-life example > After launching a new FAQ agent, the support lead switched the dashboard range to “Last 7 days” and saw conversation volume double. They cross-referenced the [Timeline](#doc-conversations-dialogs-timeline) for a few threads to ensure tool costs stayed within budget, then exported the chart for leadership. ## Tips - Use **AI Usage** before changing model routing or prompts so you can see whether one model is driving most of the cost or latency, and whether document-folder indexing is a meaningful part of project AI spend. - Pair the dashboard with [Evals](#doc-evals) to correlate quality metrics with usage spikes. - Run [Update Statistics](#doc-conversations-dialogs-update-statistics) after large imports so totals match reality. - Hover the bar charts to spot spikes in usage or cost; sudden jumps can point to long conversations or noisy tools. - Use projections as planning context, not as recorded activity. Dashed projection lines and number-card projected side values are generated from the currently selected historical window and disappear when you turn the overlay off. - Reset only when you want to discard the saved layout for the active tab; each tab keeps its own layout state. ## Troubleshooting - **Empty chart:** There may be no conversations in the selected range. Expand the window or ensure statistics were recently updated. - **Assessment chart is empty or shows a warning:** Open the warning button first. If Assessment is not configured, enable the **Assessment** post-step on the active configuration. If it is configured with no results, run at least one new conversation turn, then refresh statistics or run a backfill. - **Top Topics is empty or shows a warning:** Open the warning button first. If Topic Extraction is not configured, enable the **Topic Extraction** post-step on the active configuration. If it is configured with no results, run new conversation turns, then refresh statistics or run a backfill. - **Projection toggle is disabled:** The active tab does not have a populated eligible time-series chart for the selected range. - **Custom dashboard SQL is rejected:** Confirm the query starts with `SELECT` or `WITH`, includes `:projectId`, `:startDate`, and `:endDate`, and does not include semicolons or write/DDL statements. - **Numbers look stale:** Click **Refresh**. The page uses server-fetched initial values and then refreshes the active tab on demand. - **Workflows tab looks different from older docs:** The fourth tab is labeled **Workflows** in the UI even though some older code still uses `data-ingestion` internally. - **Page opens and then redirects away:** Your project role probably lacks `view-dashboard`. Ask a project admin to grant dashboard access. --- # Platform Dashboard The **Platform Dashboard** gives platform operators with dashboard access one read-only place to monitor cross-project activity across the Gaia instance. Open it from the platform header at `/platform/operations/dashboard` when your effective platform role includes **View platform dashboard**. ## Related pages - [Control Plane Evidence](#doc-control-plane-evidence) - [Dashboard](#doc-dashboard) - [Timesheet](#doc-timesheet) - [Audit Trail](#doc-audit) - [Data Model Workflows](#doc-data-model-workflows) - [Status and incidents](#doc-platform-dashboard-status-and-incidents) - [Usage billing and quotas](#doc-platform-dashboard-usage-billing-and-quotas) - [Sandbox and API versioning](#doc-platform-dashboard-sandbox-and-api-versioning) ## What you'll see - A shared date-range picker and **Refresh** button for the whole page. - A **Projections** toggle for eligible time-series charts and metric cards. It is off by default and adds dashed exploratory future lines or small muted projected values beside eligible card metrics without changing stored telemetry. - Optional **Organization**, **Team**, and **Project** filters so you can narrow the instance view without leaving the page. - A fixed, read-only widget layout. Unlike the project dashboard, this v1 surface does not save custom layouts. - Each widget keeps a short subtitle in the header, and the info button opens a longer plain-language explanation of what that card or chart represents and how to read it. - Four tabs: - **Overview** for overall project, conversation, user, AI, tool, workflow, and governance package totals. - **Governance** for cross-project governance posture, queue backlog, overdue governance deadlines, imported governance-package adoption and drift, recent governance movement, and direct links back into each project's highest-signal governance record or preselected Operations queue item. - **Models** for a compact model summary strip, **Cost Evidence** readiness, **Cost Watch** anomaly warnings, the dedicated **Folder Indexing Spend** summary card, plus ranked token, cost, request-count, latency, missing-price evidence, and contributor views. - **Workflows & Activity** for workflow status, cross-project work activity, end-user participation, and operational hotspots. - A shared **Scope & Visibility** note above the tabs so you can tell whether the current page reflects the full accessible estate or a filtered team or project slice before you compare any card or chart. - On **Governance**, posture and backlog stay current for the selected team or project scope, while **Recent movement** always uses a fixed 30-day window ending at the selected review end date. - On **Governance**, **Agent Systems** reflects the latest recorded review posture for each visible boundary. Boundaries still count as needing human review until a person closes the follow-up, including review runs started from the bounded `ai_assisted` path. - On **Governance**, **Telemetry Gaps** only measures stale or missing runtime signals for boundaries that are expected to emit runtime telemetry. Treat it as a freshness signal, not proof that Gaia controls or enforces every observed boundary. - On **Governance**, **Package Adoption** summarizes how many imported governance packages are in use in the current scope so **Imported Drift** reads as dependency posture, not an isolated alert. - On **Governance**, **Imported Drift** highlights imported governance packages that are behind the latest published source release or need lineage review, so you can spot stale reuse without opening every project registry. - AI usage billing exports use the unified performance ledger to summarize requests, prompt tokens, cached tokens, completion tokens, total tokens, voice operations, voice units, input/output audio seconds, billed voice minutes, elapsed time, explicit or missing price evidence, cost-budget evidence status, and estimated cost by organization, team, project, model, user, and service-account/API-key slot. The **Models** tab also shows whether the selected range is cost-evidence ready and which models still have missing price evidence. Use **AI usage CSV** when finance or partner evidence needs a flat showback file for the current date range and selected organization/project scope. ## Predictive and anomaly review Platform-level predictive evidence is shown with the **Projections** toggle on eligible Overview, Models, and Workflows & Activity time-series charts. It is an exploratory forecast overlay for the selected date range and filters; it does not create stored forecast records or enforce budgets. Anomaly review is shown through operational signals rather than a separate anomaly-detector setup page: **Cost Watch** flags model-cost spikes against prior hourly baseline spend in **Models**, the ranked model charts show cost/request/latency spikes, **Workflows & Activity** shows workflow and error hotspots, **Governance** shows posture alerts and telemetry gaps, and [Status and incidents](#doc-platform-dashboard-status-and-incidents) shows service incidents. If a tender requires automatic notifications, escalation policies, or customer-tuned thresholds, provide the final analytics or monitoring annex for that detector. For the full evidence workflow that combines service-account/API-key attribution, cost budgets, request-rate limits, and billing exports, see [Usage Billing And Quotas](#doc-platform-dashboard-usage-billing-and-quotas). For control-plane evidence, capture the selected scope note, organization/team/project filters, date range, and the relevant tab: - **Overview** for estate footprint and activity totals. - **Governance** for package adoption, posture, queue backlog, imported drift, telemetry gaps, and agent-system review posture. - **Models** for request count, token volume, cost, latency, cost-budget evidence readiness, Cost Watch anomaly warnings, missing-price evidence, and folder indexing spend across the selected scope. - **Workflows & Activity** for workflow status, operational hotspots, and end-user participation. - **AI usage CSV** when the reviewer needs model usage by organization, team, project, user, service account, API-key slot, date range, tokens, requests, elapsed time, and estimated cost. Use [Control Plane Evidence](#doc-control-plane-evidence) to connect these cross-project signals to project-level configuration, retrieval, governance, and audit proof. ## Background jobs Users with background job access can open **Jobs** from the platform header at `/platform/operations/jobs` to inspect the durable background queue. The page shows: - queue counts by status, including queued, leased, succeeded, failed, dead, and cancelled work, - active leases and stale leases, - retry and dead-letter totals, - active jobs, recent failures, and attempt history with the job kind, queue, related organization, team path, project, resource name, attempts, and last error. Platform admins can also use **Stop** on queued or leased jobs in the **Active Jobs** tab. This cancels the selected job, clears its active lease, and is the fastest way to recover from a stale document-folder indexing job before you request a fresh reindex. Delegated background-job viewers still see the page in read-only mode. Use this page when document-folder indexing, backfill work, or scheduled jobs appear delayed. A growing queued count points to backlog pressure, stale leases indicate interrupted workers, and dead jobs identify work that exceeded its retry budget. ## Operational logs Users with background job access can also open **Logs** from the platform header at `/platform/operations/log` to inspect persisted server warnings and errors captured from Gaia's shared platform logger. Log context shows resolved project, conversation, and user names where Gaia can match the stored IDs. Users with dashboard or background job access can open **Status** from the platform header at `/platform/operations/status` to review service health, incident signals, background queue status, stale leases, and maintenance evidence in one read-only console. Use [Status and incidents](#doc-platform-dashboard-status-and-incidents) when you need the exact review workflow and screenshots to capture. The page is read-only in this version. It lets operators: - filter persisted entries by free-text search, severity, component, and date range, - review request scope such as project, conversation, route, and user identifiers, - inspect captured error messages, stacks, and structured payload fields without tailing a live process. Use this page when a workflow, eval run, conversation, or background job is failing but queue health alone does not explain why. Open **Logs** first when you need the server-side warning or error record that sits behind a visible symptom. ## How to use it 1. Open **Dashboard** from the platform header. 2. Choose a date range for the review window. 3. Optionally narrow the page with **Organization**, **Team**, and **Project** filters. 4. Start in **Overview** to confirm the overall footprint, current governance package footprint and reuse, conversation volume, AI usage, and top active projects. 5. Switch to **Governance** when you need to compare evidence gaps, stale governance posture, broken bindings, agent-system review posture, telemetry freshness, imported package adoption and drift, queue pressure, or recent governance movement across projects. 6. Read the shared **Scope & Visibility** note before interpreting zero or low counts so you know whether the page covers the full accessible estate or only a filtered subset. 7. Use the governance project drill-down cards to jump straight into the highest-signal governance record for that project, or into a preselected Governance Operations queue item when the next step is queue-driven. 8. Switch to **Models** when you need to understand which models are driving token volume, cost, or latency. 9. Use the summary cards at the top of **Models** for a quick read on active models, total requests, total spend, weighted average latency, cost-evidence readiness, and Cost Watch anomaly warnings before you inspect the ranked charts below. 10. Switch to **Workflows & Activity** when you need to compare workflow load, project-user work, end-user traffic, or error hotspots. 11. Turn on **Projections** when you want an exploratory forward view for populated activity or model time-series charts and eligible summary cards. Observed values stay primary; projected values render as dashed lines or compact side values. 12. Click **Refresh** whenever you want to re-run the server-side aggregation for the selected filters. 13. Open **Jobs** when you need to confirm whether background document indexing, eval runs, scheduled jobs, or maintenance work is queued, leased, failing, or dead-lettered. 14. Open **Logs** when you need the persisted server-side warning or error entry behind a failed workflow, route, or background operation. ## When to use this instead of other surfaces - Use [Dashboard](#doc-dashboard) for deep investigation inside one project. - Use the **Governance** tab here when a platform operator needs cross-project governance posture or backlog context before opening a specific project. - Use **Platform Dashboard** when you need to compare multiple projects, teams, or models across the whole instance. - Use **Jobs** when the question is about background queue health rather than project usage, governance posture, or cost. - Use **Logs** when you need the actual warning or error record for a failing platform operation, route, or workflow symptom. - Use [Timesheet](#doc-timesheet) when the question is about effort, capacity, or allocations rather than operational telemetry. ## Operational workflow 1. Start in **Platform Dashboard** when a platform operator needs to understand whether an issue is isolated or instance-wide. 2. Use the **Governance** tab when the cross-project question is about governance posture, overdue review deadlines, queue backlog, or governance movement rather than general traffic or workflow load. 3. Read the shared **Scope & Visibility** note first so you know whether the current page covers all accessible projects or only the filtered subset you selected. 4. If one project stands out, use the governance drill-down cards to land directly on the highest-signal record or queue item for that project, or use the project [Dashboard](#doc-dashboard) and [Audit Trail](#doc-audit) for broader operational investigation. 5. Open **Logs** when the issue needs the underlying warning or error record before you change configuration or retry work. 6. Review workflow-specific evidence in [Data Model Workflows](#doc-data-model-workflows) and run details when the issue is pipeline-related. 7. Use [Timesheet](#doc-timesheet) after triage if the follow-up work needs to be rebalanced across people or projects. ## Real-life example > A platform operator with dashboard access sees tool errors spike after a new rollout. They open **Platform Dashboard**, set the range to the last 24 hours, and spot that only two projects are affected. From there they move into the affected project dashboard and audit trail instead of pausing every team. ## Troubleshooting - **The page redirects away:** Your effective platform role probably does not include **View platform dashboard**. - **Projection toggle is disabled:** The active tab does not have enough numeric time-series data in the current scope and date range. - **The project list looks long:** Filter by team first when you want a narrower review set. - **The scope note says the view is partial:** The counts and drill-downs only cover the visible team or project slice. Zero or low counts do not describe projects outside that scope. - **Governance package counts do not move with the date range:** The governance package cards show the current package footprint for the selected team or project scope, not event volume inside the date window. - **Package Adoption is non-zero while Imported Drift is zero:** Imported governance packages are in use in the current scope, but the imported copies currently match their source releases. - **Governance throughput does not shrink when I pick a shorter dashboard range:** Recent governance movement always uses a fixed 30-day window ending at the selected review end date so the throughput cards stay comparable while the other platform-dashboard tabs keep using the exact selected range. - **Agent Systems still shows human review after I ran AI-assisted review:** That is expected. The governance summary reflects the latest recorded review posture for each boundary, and bounded `ai_assisted` reviews still require a person to close the follow-up. - **Telemetry Gaps looks high even though Gaia does not run those systems directly:** That card tracks missing or stale runtime signals for governed boundaries that are expected to emit telemetry. It does not claim Gaia is orchestrating or enforcing every observed external system. - **Imported Drift is non-zero:** `needs sync` means a newer published source release exists for the imported package. `needs lineage review` means the imported copy no longer maps cleanly to a current published source release and should be reviewed before you treat it as current. - **Governance posture stays high while throughput also rises:** That usually means the estate is moving, but new backlog and posture gaps are still arriving at the same time. Use the governance drill-down cards to confirm which projects are closing work, which queue item is currently front-of-line, and which ones are only accumulating new work. - **Document indexing or scheduled jobs look delayed:** Open **Jobs** and check queued, leased, stale, and failed counts before assuming a project-level configuration issue. - **A queued or leased job is stale:** Platform admins can use **Stop** in **Jobs** to cancel that row, then trigger the work again from the owning feature. - **A workflow or route failed but queue counts look normal:** Open **Logs** and filter by the affected project, component, or time window to inspect the persisted warning or error details. - **The numbers differ from Timesheet:** Timesheet tracks effort and allocations, while Platform Dashboard tracks operational telemetry such as AI usage, workflows, conversations, and audit activity. --- # Status and incidents The **Operations Status** page gives platform operators a single read-only console for current service health, incident signals, and maintenance evidence. Open it from the platform header at `/platform/operations/status` when your effective platform role can view either the Platform Dashboard or Background Jobs. ## What it shows - **Service health:** Gaia's database readiness, optional Redis health, deployment slot, and snapshot time. - **Background queue:** queued, leased, failed, and dead background jobs from the shared worker queue. - **Incident signals:** the latest failed jobs and persisted operational errors from the last 24 hours. - **Maintenance evidence:** pointers to Jobs and Logs so operators can verify scheduled maintenance, retries, cancellations, and follow-up records. - **Log sink health:** Platform Settings shows the operational log persistence queue, dropped-entry counters, duplicate coalescing, failed batches, disabled skips, and circuit-breaker state. The page is intentionally an operator console. Project-level configuration and security history remain in each project's [Audit Trail](#doc-audit). ## Review an incident 1. Open **Operations -> Status**. 2. Check the status badge at the top of the page. 3. Review **Service health** first. Database errors make the instance unavailable; Redis degradation can affect cache-backed features while the main application stays ready. 4. Review **Incident signals** for failed jobs and recent operational errors. 5. Open **Logs** for request, component, route, user, project, and error details. 6. Open **Jobs** for queue status, retry attempts, stop actions, and stale leases. 7. If logs show persistence backpressure, open **Platform Settings** and review the operational log persistence counters before changing the queue, batch, or circuit-breaker controls. 8. Capture the Status page, Logs entry, Jobs attempt history, and any project Audit Trail record needed for the incident evidence pack. ## Maintenance windows Use **Status** with **Jobs** and **Logs** during a maintenance window: 1. Confirm the health snapshot before work starts. 2. Watch background jobs for queued, leased, failed, or dead maintenance work. 3. Use operational logs to verify warnings and errors during the window. 4. Capture the final status snapshot after the window ends. ## Evidence to capture - Status overview screenshot with the status badge. - Incident signal card showing failed/dead jobs or no current failures. - Operational log entry for the reviewed error or maintenance event. - Background Jobs attempt-history screenshot for retries, stop actions, or successful maintenance completion. - Project Audit Trail screenshot when the incident involved a project configuration or security change. ## Related pages - [Platform Dashboard](#doc-platform-dashboard) - [Audit Trail](#doc-audit) - [Usage billing and quotas](#doc-platform-dashboard-usage-billing-and-quotas) --- # Usage Billing And Quotas Use this guide when finance, platform operations, or a tender reviewer needs evidence for AI consumption, cost reporting, API-key attribution, and runtime quota controls. Gaia separates the evidence into two layers: - **Usage and billing showback:** Platform Dashboard exports requests, tokens, voice usage, elapsed time, estimated cost, model, organization, team, project, user, service account, and API-key slot. - **Runtime quota controls:** Agent, app-user role, channel, project, team, organization, and instance settings can store weekly, monthly, and yearly cost budgets. Blank budget values are unlimited. Per-minute request and estimated-token admission limits are available on every agent; legacy per-turn token caps remain available for orchestrator safety. AI FinOps budget enforcement is cost-based because token cost varies by model, voice unit, tool call, and realtime session. ## What Platform Dashboard exports Open **Platform Dashboard -> Models** to review cost-evidence readiness for the selected scope, then use **AI usage CSV** for a flat evidence file. The export includes: - organization and team; - project; - principal type, such as user or service account; - principal name and ID; - API-key slot for service-account traffic; - model; - request count; - prompt, cached, completion, and total tokens; - voice operations, voice unit names, input/output audio seconds, and billed voice minutes when realtime, transcription, or TTS usage is logged; - estimated cost; - explicit price-catalog evidence counts, missing-price counts, catalog versions, currencies, price sources, and missing price parts; - cost-budget evidence status, reason, and explicit-price coverage percentage for each exported scope; - elapsed time; - first and last logged timestamps. For predictive cost evidence, use the **Projections** toggle on eligible Platform Dashboard **Models** charts after selecting the same date range and scope as the export. Gaia shows projected values as a visual overlay; the CSV remains an observed-usage ledger. Estimated spend uses explicit AI FinOps price catalog entries when they exist. Platform settings default the catalog currency to EUR. Missing price entries are reported as missing-price evidence; Gaia does not invent estimated costs when no catalog entry applies. Voice catalog entries use `realtimeSessionUnitPrice.voice_minute` for realtime sessions, `voiceUnitPrice.transcription_minute` for transcription, and `voiceUnitPrice.tts_minute` for text-to-speech. In **Platform Settings -> AI FinOps budgets**, the reservation evidence mode defaults to `explicit-price-only`. This is the active runtime behavior: pre-call reservation only uses explicit catalog price evidence. Tokenizer evidence, voice billing-unit evidence, and provider billing import references are visible as future evidence refinements, but missing values remain non-runtime evidence gaps and do not create estimates. The CSV marks each organization, project, principal, and model row as `ready`, `needs_price_catalog`, or `no_usage` for cost-budget evidence. Treat `needs_price_catalog` as an operations action: fill the explicit catalog entry or missing unit price before relying on cost-budget hard stops for that scope. The **Cost Evidence** summary card uses the same ledger to show `Ready`, `Needs Catalog`, or `No Usage` for the selected dashboard range. The **Missing Price Evidence by Model** chart ranks models with requests that are not ready for cost-budget enforcement, so operators can decide which catalog entries or voice-unit prices to add before exporting reviewer evidence. For anomaly review, inspect **Cost Watch** and the model, cost, request, and latency charts in Platform Dashboard **Models**, then use the exported CSV, [Audit Trail](#doc-audit), and [Status and incidents](#doc-platform-dashboard-status-and-incidents) to explain the spike. Gaia flags hourly model-cost spikes against prior baseline spend on this page, but customer-tuned notification thresholds still belong in the final analytics or monitoring annex. Use one service account per integration or trust boundary when API-key-level showback matters. Gaia records service-account traffic separately from human traffic when runtime calls include the machine principal. ## Configure service-account attribution 1. Open **Settings -> Service accounts**. 2. Create one service account for each integration or external API client. 3. Assign a narrow project role. 4. Generate a **Primary** or **Secondary** API key. 5. Configure the integration to send that key as `X-API-Key` or `Authorization: Bearer`. 6. After test traffic runs, export **AI usage CSV** from Platform Dashboard and verify the service account and key slot columns. Use the secondary key slot for rotation. During rotation, the export can distinguish which slot was used by the integration. ## Configure cost budgets Use cost budgets when an audience, project, team, organization, or instance should not consume unlimited AI capacity during a week, month, or year. For published app users: 1. Open **Settings -> App user roles**. 2. Create or edit the role assigned to the published app audience. 3. Set weekly, monthly, or yearly cost budgets. 4. Save the role. 5. Assign the role to the relevant app users. Role budgets apply per app user across every channel and agent while the role is assigned. When several budgets apply, Gaia evaluates all of them and applies the strictest exhausted, missing-price, or lowest-remaining budget. For orchestrator-level control, open **AI Agents**, edit the orchestrator settings, and set the weekly, monthly, or yearly AI budgets. Project-level budgets live in **Settings -> General**. Team budgets live in the team settings dialog and include child teams. Organization budgets live in organization settings and apply before the instance budget in **Platform Settings**. Before a budgeted root or nested handoff model call, Gaia also reserves the selected model's configured maximum output cost from the explicit AI FinOps price catalog. If the catalog entry, comparable currency, output-token quantity, or output price is missing, Gaia blocks the call with missing-price evidence. If the reservation would exhaust the strictest matching budget, Gaia blocks before the provider call and records the estimated request amount, remaining amount after reservation, model, provider, catalog version, and price source on the assistant error and runtime telemetry. Gaia does not keep a durable reservation ledger in this version; recorded spend remains the source of truth after the call completes. Use the same AI budget editor surfaces to define workload policies: workload class, allowed tiers, preferred tier, fallback tier, business justification, approval status, reviewer references, decision notes, and exception expiry. Governance Operations owns approval and rejection decisions for pending, rejected, expired, or misconfigured workload policies across agent, app-user role, channel, project, team, organization, and instance scopes, while the policy definition stays in the original settings scope. Runtime cost-budget blocks also preserve budget evidence on the assistant error and runtime telemetry so reviewers can see the scope, source, period, limit amount, used amount, currency, missing-price evidence, and remaining amount at failure. ## Configure request and token rate limits Use max requests per minute when an agent needs a throughput limit. Add a token budget when requests vary materially in prompt, retrieval-context, or output size. The token budget uses a conservative estimated token reservation before each request; it is an admission-control guardrail, not provider billing telemetry. 1. Open **AI Agents**. 2. Select the agent. 3. Set **Max requests per minute** for the agent. 4. Optionally set **Max estimated tokens per minute** and **Estimated tokens per request**. Size the minute budget below the model deployment's usable token capacity so provider retries and traffic variation have headroom. 5. Save the agent. 6. Run a controlled load test or review operational logs to confirm the limit response, retry time, and whether the binding constraint was requests or estimated tokens. Gaia evaluates both windows when both limits are configured. It admits a request only when neither would be exceeded, reports the binding constraint, and returns the retry time and remaining request and token reservations. Keep the estimate at or above the expected p95 tokens per turn; revise it from observed model usage after representative tests. The limits protect the current runtime path. They are separate from financial showback and should be sized with expected channel volume and provider quota. ## Evidence to capture For a reviewer, capture these artifacts together: - service-account settings showing the integration identity and key slot status; - app-user role, orchestrator, project, team, organization, or platform settings showing the cost budget; - workload-policy settings showing the approved tier, fallback tier, reviewer decision, and required exception expiry when an exception is active; - AI FinOps platform settings showing EUR default currency and the explicit model price catalog entry when estimated spend or pre-call reservation is claimed; - agent settings showing request and estimated-token limits when admission control is claimed; - a conversation or API test that triggers the configured budget or rate limit; - the assistant error or runtime telemetry for a pre-call reservation block, including the estimated request amount, remaining amount after reservation, model, provider, catalog version, price source, and missing price parts when applicable; - Platform Dashboard **AI usage CSV** for the same date range showing organization, project, principal, API-key slot, model, tokens, voice units, requests, estimated cost, explicit price evidence, and missing price evidence. - Platform Dashboard **Models** evidence showing the Cost Evidence summary card and any Missing Price Evidence by Model rows for the same date range. - Platform Dashboard **Models** Cost Watch evidence for any model-cost spikes in the same date range. - Cost-budget evidence status rows from the same CSV, especially any `needs_price_catalog` rows and their missing price parts. ## What this does not replace Gaia usage exports are showback evidence. If a deployment also requires monthly spend approvals, prepaid balance checks, chargeback invoices, or external payment enforcement, connect the exported ledger to the contracting or gateway layer that owns those commercial controls. ## Troubleshooting - **The service account is missing from the CSV:** Confirm the integration authenticated with the service-account key instead of a user session. - **The key slot is blank:** Regenerate and use a primary or secondary service-account key. - **The cost budget did not apply:** Confirm the relevant week, month, or year field is not blank. Blank means unlimited. - **The CSV says `needs_price_catalog`:** Add or correct the explicit model, realtime, or voice-unit price catalog entry before treating the scope as cost-budget ready. - **The limit is too strict:** Raise the narrowest applicable budget after checking the Platform Dashboard usage trend. Gaia evaluates app-user role, orchestrator, channel, project, team hierarchy, organization, and instance budgets together. --- # Sandbox and API versioning Use this page to document the evidence a reviewer should collect for a Gaia sandbox or test environment and for API compatibility claims. Sandbox access and API versioning are deployment commitments. The Gaia product provides the service-account, API-key, project-transfer, and operational evidence surfaces; the environment URL, seed-data/reset policy, and external deprecation notice process are confirmed during delivery. ## Sandbox evidence For a sandbox or test environment, capture: - the sandbox URL or tenant entry point approved for reviewers; - the organization, team, or project that contains seed data; - the access path used by the reviewer, such as an invitation, app-user login, or service account; - the reset or refresh policy for seed data; - a smoke-test result from the sandbox environment. ## API access evidence 1. Open **Settings -> Service accounts**. 2. Create or choose a service account with the minimum project role needed for the test. 3. Use the primary or secondary API-key slot for the smoke test. 4. Record the request path, response status, and response body needed by the reviewer. 5. Rotate the key after the review if the key was shared outside the delivery team. ## Versioning and deprecation evidence For API versioning claims, include the delivery-approved API base URL, version identifier, supported compatibility window, and deprecation notice policy. Service-account evidence proves authenticated access; it does not by itself prove a versioning policy. ## Related pages - [Service accounts](#doc-settings-service-accounts) - [Coding agents](#doc-coding-agents) - [Platform Dashboard](#doc-platform-dashboard) --- # Platform Cost Estimator Use the **Cost Estimator** page at `/platform/support/cost-estimator` when you need a rough infrastructure budget or capacity plan before a finance review, architecture review, or procurement discussion. This page is an internal planning tool for signed-in Gaia users. It is not a commercial quote, and it does not persist scenarios to the database. ## What the estimator includes - Two deployment environments: - **Azure** for priced cloud infrastructure plus model usage. - **On-Prem** for VM, storage, and reserved GPU capacity planning plus cloud model usage. - Four deployment scenarios: - **Full platform** - **Evals only** - **Governance only** - **Evals + Governance** - Model usage cost pulled from the Gaia [Models](#doc-settings) catalog. - A routing split between one **large** model and one **small** model. - Traffic-driven scaling rules for Azure App Service, Application Gateway WAF v2, Azure Database for PostgreSQL, storage, observability, and network egress. - An on-prem baseline that assumes: - Kubernetes worker VMs for the application tier - PostgreSQL as a 2-node HA cluster - Redis as a 3-node cache cluster without persistence - shared storage sized from retained transcript and artifact footprint - reserved on-prem GPU rows as placeholders only - Kubernetes management or control-plane capacity and ingress or load-balancing infrastructure are already provided by the customer - A bill-of-materials style breakdown you can export as JSON or XLSX. ## Rough-estimate disclaimer Treat every result on this page as a rough estimate. - Azure prices default to a specific regional list-price snapshot shown on the page. - Model prices come from the current Gaia model catalog and are only as accurate as the values maintained in [Models](#doc-settings). - The on-prem view does **not** price local infrastructure yet. It only sizes VM, storage, and reserved GPU capacity. - Search and retrieval infrastructure are intentionally excluded from this version of the estimator. - Discounts, reserved capacity, support plans, sandbox or non-production environments, implementation effort, and third-party services are excluded unless you model them manually through notes or Azure price overrides. Use the estimator to frame conversations, not to replace a cloud quote, supplier-approved BOM, or infrastructure procurement worksheet. ## How it works 1. Open **Cost Estimator** from the top platform navigation. 2. Choose the deployment **environment**: - **Azure** when you want priced cloud infrastructure. - **On-Prem** when you want a capacity plan for self-hosted infrastructure. 3. Choose the deployment **scenario** that best matches the footprint you are planning. 4. Pick one large model and one small model from the current Gaia catalog. 5. Enter shared workload assumptions such as monthly conversations, turns per conversation, token usage, tool activity, and retention. - In **Governance only**, treat **monthly conversations** as the governed automation or external-agent volume that enters governance review and control paths. 6. Update the environment-specific inputs: - Azure: editable Azure unit-price overrides. - On-Prem: worker VM sizing, PostgreSQL and Redis node specs, shared-storage overhead, and reserved GPU placeholders. 7. Add scenario notes so reviewers know what is excluded or intentionally conservative. 8. Export the scenario as JSON or XLSX when you need to share it. The calculator recomputes immediately after each valid change. ## Azure logic The Azure estimator is intentionally opinionated so the exported workbook reads like a usable Azure bill of materials. - **Azure App Service Premium v3** scales from workload in all scenarios and also uses concurrency in the **Full platform** scenario. - **Application Gateway WAF v2** and **NAT Gateway** appear only in the **Full platform** scenario. - **Azure Database for PostgreSQL Flexible Server** scales compute from conversation load and storage from retained operational data. - **Azure Storage**, **Log Analytics**, and **Bandwidth** scale from retained data, telemetry, and egress assumptions. Each line keeps the Azure product name and meter label so the output can be copied into stakeholder spreadsheets with minimal relabeling. ## On-prem logic The on-prem estimator is a capacity planner, not a pricing calculator. - The app tier is sized as Kubernetes worker VMs with configurable vCPU and RAM per node. - The default application-worker baseline is `8 vCPU / 16 GB RAM` per node. Raise RAM only when your runtime profile, sidecars, or background jobs justify it. - PostgreSQL is modeled as a fixed 2-node HA VM cluster. - Redis is modeled as a fixed 3-node cache cluster without persistence. - Shared storage is sized from retained transcript and artifact footprint plus a configurable overhead buffer. - Reserved GPU rows are placeholders for a future local-inference footprint. Current model inference remains cloud-provisioned. - Kubernetes management or control-plane nodes and ingress or load-balancer infrastructure are not sized in this version. The estimator assumes those are customer-provided. The on-prem breakdown therefore shows: - VM counts - per-node sizing assumptions - storage requirements - reserved GPU capacity - cloud model spend ## Import and export - **JSON export/import** keeps the canonical Gaia estimator model for deterministic sharing. - **XLSX export/import** uses a Gaia-owned workbook template with stable sheet names and a hidden metadata sheet. - Only Gaia-exported XLSX files are supported for import. Generic stakeholder spreadsheets are rejected on purpose so the model stays deterministic. ## Keep pricing current - Update model prices in [Models](#doc-settings) when provider pricing changes. - If finance gives you negotiated Azure rates, override the Azure unit prices directly on the page before exporting the scenario. - Re-export the workbook after major assumption changes so reviewers have the same model you are looking at. --- # Timesheet Use the Timesheet page to review how much effort is being spent across projects and platform areas. You can access it from the **User** section in the platform header, or from the user avatar menu in the top bar. ## Related pages - [Dashboard](#doc-dashboard) - [Platform Dashboard](#doc-platform-dashboard) - [Tasks](#doc-tasks-all-tasks) - [Task calendar](#doc-tasks-task-calendar) - [Tasks](#doc-tasks) - [Audit Trail](#doc-audit) ## What you can do - Review a day-by-day list of hours per project, grouped by week and month. - Switch to the Dashboard tab for a visual summary of effort trends and task velocity. - If you are a platform administrator with an eligible instance-effort account, open the **Instance Dashboard** tab to see effort totals across all users, task velocity, and a user performance breakdown. - Eligible platform admins also get an **Allocations** tab that shows task assignment load across users. - Use [Platform Dashboard](#doc-platform-dashboard) instead when you need cross-project operational telemetry rather than effort reporting. ## Filters and refresh controls - Use the **Team** filter to focus on one team or choose **All teams**. - After selecting a team, use the **Project** filter to focus on one project or keep **All projects** selected. - The same date-range picker and **Refresh** button drive every Timesheet tab. - Changing the active tab reloads the data for that view using the current filters and date range. ## Timesheet tab - Use the date range picker to choose the reporting window. - Use the Current/Previous/Last dropdowns for quick presets, or pick a custom span from the calendar. - Use the Team and Project filters (next to the date range) to narrow the day-by-day list. - Each day card shows total hours and a breakdown by project (labeled as Team / Project). - Weeks and months include a quick total to help you spot spikes. ## Dashboard tab - Use the Team and Project filters (next to the date range) to narrow dashboard metrics. - Above the widgets, Gaia shows the selected range label (for presets like “Last week” / “This month”) and the number of working days in that span. - Hover the range label to see the exact date range. - Each widget keeps a short subtitle in the header, and the info button opens a longer plain-language explanation of the metric or chart. The dashboard uses the same widget layout system as project dashboards and includes: - Total effort in the selected range. - Total effort cards include a trend comparison against the previous range. - Your effort rank across all users for the selected range (based on rounded effort % so ties are possible). - Effort over time as a daily time series. - Effort by project (labels include team and project). - Effort by platform area (conversations, meetings, evals, agents, data model, and more). - Completed meeting tasks count toward effort totals for every participant assigned to the meeting. - Task counts (todo, in progress, done) for your assigned tasks. - Task velocity (median days) for todo → in progress and in progress → done transitions, plus a by-project breakdown. - Very small categories (under ~1% of the largest bar) are hidden to keep charts readable. ### Instance dashboard (admins) Eligible platform admins also have an **Instance Dashboard** tab with additional aggregated views: - The Team and Project filters also apply to the Instance Dashboard tab. - The Team and Project dropdowns list all teams/projects across the instance. - Contribution by user counts create/update audit operations (views/deletes are excluded). - Contribution by area (per user) shows per-user create/update operations grouped by platform area. - Task counts (todo, in progress, done) across the instance. - Task velocity (median days) across the instance, per project, and per user. This Timesheet instance dashboard is still effort-focused. For cross-project AI, workflow, conversation, and operational telemetry, use [Platform Dashboard](#doc-platform-dashboard). ## Instance Dashboard tab (admins only) Eligible platform administrators see a third tab with aggregated metrics across all users: - Overall effort totals in hours and people-days, with trend comparisons. - Effort by project and platform area. - Effort by user to compare contributions. ## Allocations tab (admins only) Eligible platform administrators also see an **Allocations** tab: - Shows tasks assigned per user in todo and in progress, plus done counts within the selected date range. - Includes the project label (Team / Project) to make load balancing easier. - Uses the same Team and Project filters as the other tabs. ## Operational workflow Timesheet closes the operational review loop: 1. Spot a usage or quality issue in [Dashboard](#doc-dashboard). 2. If you are triaging across multiple projects, compare them first in [Platform Dashboard](#doc-platform-dashboard). 3. Inspect recent changes in [Audit Trail](#doc-audit) if you need project context. 4. Use Timesheet to check where effort is already going across projects or platform areas. 5. Open [Tasks](#doc-tasks), [Tasks](#doc-tasks-all-tasks), or [Task calendar](#doc-tasks-task-calendar) to rebalance follow-up work. ## Real-life example > An ops lead reviews the Timesheet dashboard after a sprint and spots a spike in agent tuning work. They adjust the next week's allocations to balance platform maintenance and eval review time. ## Tips - Use the Customize button to rearrange widgets during your session. - Narrow the date range for detailed investigation, or expand it for bigger trends. - Pick a team first if you want to filter to a specific project; the project selector stays disabled until a team is selected. --- # Tasks Organize delivery work, issues, and follow-up items without leaving your project. The **Tasks** tab (Tools → Delivery Management → Tasks) combines a drag-and-drop Kanban board, grouped list view, and a rich task dialog so you can shepherd every item from backlog through completion while keeping delivery cycles and attachments in sync. Users with platform task access also get a dedicated **Platform Tasks** page at `/platform/support/tasks`. It mirrors the project task workspace with both Kanban and List views, dedicated **My Tasks** and **Milestones** views, release-oriented platform milestones, version tags on task cards, markdown descriptions with print/export controls, multi-user assignees inside the platform task dialog, task attachments, and the same click-a-task-to-open-the-dialog flow for platform-maintainer work that should stay separate from project delivery boards. ## Related pages - [Tasks](#doc-tasks-all-tasks) - [Task calendar](#doc-tasks-task-calendar) - [Delivery Management](#doc-delivery) - [Delivery Timeline (Gantt)](#doc-delivery-timeline) - [Discussions](#doc-discuss) - [Dashboard](#doc-dashboard) - [Audit Trail](#doc-audit) - [Timesheet](#doc-timesheet) Interactive walkthrough: Open [Tutorials](/platform/support/tutorials) and select **Delivery Process: Plan, Sequence, and Schedule**. Need a personal cross-project view? Open: - [Tasks](#doc-tasks-all-tasks) for your assigned tasks across projects. - [Task calendar](#doc-tasks-task-calendar) for your task deadlines and milestones. ## What you’ll see - **View toggle:** Switch between Kanban and List at the top of the page. The Kanban board mirrors the standard states (Backlog → Triage → To Do → In Progress → Done/Canceled), while the list groups tasks into compact rows for faster scanning. - **Meeting visibility toggle:** Use **Show Meetings** to include meeting-type tasks in Kanban and List. Meetings are hidden by default. - **Version and milestone filters:** Use **All versions** to focus by version tag. In Platform Tasks, use **All milestones** to focus on the milestone that defines the actual release boundary. - **Last-updated range:** Project and Platform Tasks initially show work updated during the last two weeks. Use **Last updated** to choose another range, or clear it to show tasks from any date. - **Task cards and rows:** Kanban shows rich task cards with full context and drag targets. List view shows concise rows (task number, title, priority/difficulty chips, schedule, assignee count) so you can review more tasks at once. - **Create Task button:** Opens the task dialog in “create” mode with delivery cycle defaults pulled from the current project. - **Planning fields:** Set planned start/end dates directly in the task dialog. - **Dependencies:** Define predecessor/successor links (finish-to-start) between tasks in the same cycle. - **Timeline integration:** Open task dialogs from Timeline rows and create new tasks directly from the Timeline toolbar during planning. - **Task dialog:** Tabs for Details, Assignees, Comments, and Attachments let you edit every field, capture collaboration, and mark a task as your "active task" so it appears in the workspace widget. - **Direct task links:** Opening a saved project or platform task updates the URL with that task. Use the link button in the task dialog to copy a URL that reopens the same task for users with access. - **Gaia handoff:** Existing project tasks include a **Send to Gaia** action in the Details tab. It starts or continues a task-focused Gaia conversation, keeps the run linked back to the task, and lets Gaia keep working in the background until it finishes or needs review. - **Gaia execution summary:** Reopen a saved task to review the linked Gaia execution status, inspect the latest checkpoint summary, open the conversation directly, or approve/request changes when Gaia reaches a checkpoint. - **Rich description editor:** Task descriptions use the Markdown editor, including inline image upload from the toolbar, paste, or drag-and-drop. - **Meeting details:** Meeting tasks surface start/end times, a duration selector, and location or meeting links, plus quick import/export controls for calendar files. - **Priority and difficulty badges:** Each task can have a priority (Urgent, High, Medium, Low, None) and difficulty level displayed with Linear-style icons, making it easy to triage at a glance. - **Sorting and filtering:** Filter tasks by assignee and toggle meeting visibility to focus on execution work or include meeting items when needed. - **Real-time updates:** The page refreshes after dialog actions and propagates state changes to the Active Task widget and attachment menus throughout the app. - **Platform queue separation:** Platform Tasks uses platform-specific lifecycle states (`Backlog`, `Triage`, `To Do`, `In Progress`, `In Review`, `Done`, `Canceled`) so maintainers can mark work as review-ready once a production PR exists while reserving **Done** for work that has actually shipped. - **Platform My Tasks view:** On the Platform Tasks page, use **My Tasks** to switch into just the platform work assigned to you without leaving the admin queue. - **Version and milestone targeting:** Tasks can carry a freeform version tag and an optional milestone link so release work stays visible on both cards and list rows. - **Platform milestones view:** Open **Milestones** on the Platform Tasks page to create or edit platform milestones and group maintainer work around releases, cutovers, or hardening windows. ## Create or edit a task 1. Open any project and choose **Tools → Delivery Management → Tasks** from the left navigation. 2. Click **Create Task** (or select a card and choose the pencil icon) to open the dialog. 3. Fill in the Details tab: - Title and description. - In the description editor, use the image button or paste/drop an image to embed screenshots directly in the task. - Task type (`Task`, `Issue`, or `Meeting`). - For meetings: start/end time, duration (15-minute increments), remote toggle, and location or meeting link. Use **Import .ics** to prefill details from a calendar file or **Export .ics** to share the meeting. - **Priority** (Urgent, High, Medium, Low, None) to control sort order. - **Difficulty** to indicate effort level. - **Version tag** when the task belongs to a named release or maintenance train. Project tasks suggest existing project versions, but you can also type a future version before a snapshot exists. - **Milestone** when the task should roll up to a release checkpoint. - State (defaults to Backlog for new items). - Delivery cycle, stage, activity, and artifact if you want to anchor the task to a [Delivery Process](#doc-delivery). - Planned start/end, plus predecessor dependencies, if you want the task to participate in the [Timeline Gantt](#doc-delivery-timeline). 4. Switch to **Assignees** to add or remove project members. Everyone listed sees the task on their dashboard and Active Task picker. 5. Save your changes. The board updates immediately and the task becomes available for attachments or active selection. 6. Reopen any saved project task and use **Send to Gaia** in the Details tab when you want Gaia to pick up or continue the work inside a linked conversation. 7. If Gaia pauses for review, reopen the task and use the Gaia card to inspect the execution summary, choose **Approve and continue**, **Request changes**, or **Resume in Gaia**, and reopen the linked conversation when you want the full transcript. ## Manage comments and attachments - Use the **Comments** tab (available when editing an existing task) to capture discussion. Comments show author, timestamp, and support inline editing or deletion. - The **Attachments** tab lists anything linked via the “Attach to Task” button that appears on conversations, agents, workflows, and other project items. Click the attachment title or the eye icon to jump back to the source UI, or delete outdated attachments without affecting the original artifact. - When you use **Send to Gaia**, the task also gets a linked Gaia conversation attachment so you can reopen the run directly from the task later. - Gaia keeps the task card updated with the latest execution-session summary, so you can review progress or checkpoints from the task dialog without leaving the delivery board. - Platform Tasks keeps the same attachment model for linked Gaia items, supports direct file uploads from the task dialog, and opens linked discussion topics back into the full thread. - When a platform task is linked to a platform discussion, Gaia automatically mirrors the task state on the topic. Use **In Review** after the production PR is open but before rollout completes. Moving the task to **Done** publishes the task's version tag on the discussion so reporters can see which platform version addressed the issue, and Gaia adds a **Deployed** badge once that version is at or ahead of the current platform runtime. - Linked discussion topics now expose direct task shortcuts in the topic detail view for users who can access the corresponding task surface. - Direct task links preserve permissions. A recipient still needs access to the project task or platform task queue before the dialog opens. - From other pages, click **Attach to Task** and choose your active task or any To Do item; Gaia records the relationship and surfaces it inside the dialog automatically. - Images embedded in the task description are stored with that task and are removed automatically if the task is deleted. ## Set or clear your active task 1. Open a task in edit mode. 2. In the Details tab, use the **Active Task** box to set the card as your personal focus item. 3. The Active Task widget (top-right of every project page) now displays the card, quick state controls, and speedy links to attachments. 4. Repeat the process to switch tasks, or choose **Clear Active** when you’re done. ## Real-life example > A delivery lead triages transcripts from a spike conversation, attaches the thread to a new “Clarify build inputs” task, and links it to the active delivery cycle’s Development (build) stage. They set the task as active so the workspace widget keeps it handy while they capture evidence and hand off the next activity. ## Operational workflow Tasks are the execution anchor for the operational surfaces documented in this pack: 1. Review trends in [Dashboard](#doc-dashboard) or effort patterns in [Timesheet](#doc-timesheet). 2. Use [Audit Trail](#doc-audit) or [Discussions](#doc-discuss) to gather the context behind the issue. 3. Create or update a task so the work has an owner, status, and schedule. 4. If the work belongs to a project delivery cycle, link the task to the correct delivery context. 5. Track follow-through from the Kanban board, list view, active task widget, or your cross-project task views. ## Tips - Drag multiple cards column-to-column in the Kanban view to unblock teams quickly; Gaia saves each drop via `updateTaskAction`. - Use the list view when running standups—collapse completed groups to stay focused on backlog and in-progress states. - **Filter by assignee** to focus on your own tasks or review a teammate's workload. - Use **Show Meetings** when you want meetings in the board/list; keep it off to focus on delivery tasks and issues. - Use the version and platform milestone filters during release planning to review only the tasks targeting a specific project or platform version boundary. - Use **Import .ics** on meeting tasks to pull schedule details from your calendar invites. - Prefill delivery context by keeping a cycle active in [Delivery Management](#doc-delivery); the Task dialog will suggest the active cycle and stage for you. - Encourage teammates to mark their active task so you can see who's working on what without leaving the page. - Use tasks as the handoff point between discussions, operational review, and delivery execution instead of leaving follow-up buried in comments or screenshots. - Copy the task link from the dialog when you need to share a specific work item in chat, email, or another Gaia thread. - Use **Send to Gaia** after you have a clear task description and relevant attachments. Gaia can continue autonomously in the background, but checkpoints are easier to review when the task already has the right delivery context and artifacts attached. - Platform admins should keep platform-wide maintenance, product feedback, and shared issue backlog items in **Platform Tasks** rather than inventing a shadow process in project boards. - In **Platform Tasks**, use the assignee section in the dialog to add or remove maintainers, then switch to **My Tasks** on the page toolbar when you want to review only your own platform backlog. ## Troubleshooting - **I can’t open Tasks:** Only members with project access can view or edit tasks. Ask an admin to confirm your role in [Project settings](#doc-settings). - **Drag-and-drop does nothing:** You may not have permission to edit tasks, or the board couldn’t persist the change. Refresh the page; if the issue persists, confirm your role and try again. - **Attachments tab is empty:** Items must be linked from their source page using the Attach to Task button. Navigate to the conversation or asset you want to link and attach it from there. - **Delivery fields are blank:** Ensure the project has at least one delivery cycle. Visit [Delivery Management](#doc-delivery) to create or activate a cycle, then reopen the task. - **Gaia stopped and is waiting:** Reopen the task and check the Gaia card. If the status shows a checkpoint or blocker, use the review buttons there or open the linked conversation for the full context. --- # Tasks Use **Tasks** from the **User** section in the platform header, or from the user menu (top-right avatar), to see your assigned work across every project you can access, plus any platform tasks assigned to you as a platform admin. ## What you’ll see - A combined list of assigned tasks and issues across projects, plus assigned platform tasks when applicable. - Search by task title, project label, or milestone name. - State filter (`All states`, `Open`, `Done`, `Canceled`). For platform tasks, **Open** still includes the pre-ship **In Review** state. - Planned start, deadline (planned end), and linked milestone context per task. - A scope badge so you can tell at a glance whether the row belongs to a project or the platform queue. - Row links open the project or platform task page with the selected task dialog already open. ## Open the view 1. Open any platform page. 2. In the header, switch to **User** if needed and select **Tasks**. 3. You can also open the user menu from the avatar in the header and select **Tasks**. 4. Use search and state filtering to narrow the list. 5. Use the row link to jump into either the project-level Tasks board or the admin-only Platform Tasks page. The destination URL can be shared with another user who has access to the same task. ## Manage notification volume Use the dedicated **Notifications** page from the same **User** section, or from the user menu, to keep the list manageable: - **Mark all as read**: keeps the history but removes unread badges. - **Clear read**: removes only notifications you have already read. - **Mark unread**: on any read notification item, restore it to unread so it stays visible as important. - **Delete selected**: use the row checkboxes to remove multiple notifications in one step. - **Filter by category and date**: narrow the page to specific notification categories and time windows before reviewing or cleaning up items. ## Notes - Meetings are excluded from this list to keep it focused on delivery work. - If a task has no planned dates, it still appears in the list and is marked as not planned. - Platform tasks appear only for users who can access the platform-admin queue. ## Related - [Task calendar](#doc-tasks-task-calendar) - [Project Tasks](#doc-tasks) --- # Task calendar Use **Task calendar** from the **User** section in the platform header, or from the user menu (top-right avatar), to view your task deadlines and project milestones across projects in one calendar, including assigned platform tasks for platform admins. ## What you’ll see - A FullCalendar month view showing task deadlines and milestones across projects. - Platform tasks appear alongside project task deadlines when they are assigned to you and have planned dates. - Tasks and milestones are visually distinct with different theme-colored markers/chips. - A custom event detail dialog when you click an event. - Direct actions from the dialog to open: - the **Task dialog** for task events - the **Platform Task dialog** for platform-task events - the **Milestone dialog** for milestone events - A quick link to open the related project Tasks page, Platform Tasks page, or Milestones page. ## Open the view 1. Open any platform page. 2. In the header, switch to **User** if needed and select **Task calendar**. 3. You can also open the user menu from the avatar in the header and select **Task calendar**. 4. Click any task or milestone event. 5. In the event dialog, select **Open task dialog** or **Open milestone dialog** to edit details directly. 6. Use the secondary link in the event dialog to jump directly to the source project page or Platform Tasks page. ## Notes - Task deadlines are derived from planned dates (`planned end`, then `planned start` if no end is set). - Tasks without planned dates are counted as unscheduled and do not appear on the calendar grid. - Milestones remain project-only; platform tasks do not create milestone events. ## Related - [Tasks](#doc-tasks-all-tasks) - [Delivery Milestones](#doc-delivery-milestones) --- # Evals Use the **Evals** workspace to measure how well your agents and prompts perform. In the current v2 experience, evaluations are **task and trial** based (instead of conversation-run centric), which makes it easier to aggregate results and report outcomes. ## Tabs - [Datasets](#doc-evals-datasets): Browse folders of eval task sets (datasets) and open a dataset to manage its eval tasks. - [Runs](#doc-evals-runs): Start runs for a dataset and monitor execution. Open a run to inspect the per-task **trials**. - [Graders](#doc-evals-graders): Define grading strategies and scoring schemas, including LLM-based rubric judges. - [Reports](#doc-evals-reports): Analyze reliability metrics and per-task performance across runs. - [Settings](#doc-evals-settings): Configure AI task generation defaults and user simulator personas. Related evidence guide: [Control Plane Evidence](#doc-control-plane-evidence). ## Read in this order Use this sequence to keep setup, design, and iteration aligned: 1. **Evals (this page):** Learn the workspace structure, tabs, and run lifecycle. 2. [Eval Design Process](#doc-evals-eval-design-process): Define your decision, failure modes, criteria, and grader strategy before using the wizard. 3. [Ultimate Guide: Creating and evolving evals in Gaia](#doc-evals-ultimate-guide): Apply an advanced operating model that links Conversations error analysis with recurring eval loops. 4. [Scenario playbooks](#doc-evals-scenarios), [Scenario: Create and run an eval](#doc-evals-scenarios-create-and-run-an-eval), and [Scenario: Operate an eval improvement loop](#doc-evals-scenarios-operate-an-eval-improvement-loop): Follow the first-run setup path, then the recurring improvement loop. 5. Interactive walkthrough: Open [Tutorials](/platform/support/tutorials) and select **Create and run an Eval**. Use **Create Prepared Project** (recommended) or choose/create a project workspace when prompted. ## Operate the improvement loop Once you have a first pilot run, Gaia can operate as a repeatable improvement loop instead of a series of unrelated runs. 1. Save a named subset in [Dataset details](#doc-evals-dataset-details) for the smoke, review, or release slice you expect to reuse. 2. Open [Run details](#doc-evals-run-details) and read **Coverage posture** plus **Workflow posture** before changing prompts, graders, or datasets. 3. Use [Human Review](#doc-evals-dialogs-human-review) and the run-level evidence queues to isolate ambiguous or weak-evidence trials. 4. Launch the smallest useful rerun from the current run: **Failed / Partial / Unreviewed** for fix validation, or **No Pass Yet / Needs Review** for coverage-gap follow-up. 5. Compare the rerun against its linked baseline in [Run details](#doc-evals-run-details), then use [Reports](#doc-evals-reports) and [Select eval runs](#doc-evals-dialogs-select-eval-runs) to make the release-facing decision. For the full walkthrough, use [Scenario: Operate an eval improvement loop](#doc-evals-scenarios-operate-an-eval-improvement-loop). ## Retrieval and grounding evidence Use Evals when a control-plane review needs repeatable quality evidence instead of one-off conversation screenshots. For document-grounded assistants, build or import tasks that include the expected document folder, user request, expected source, expected answer behavior, and grading criteria. Then use runs and reports to show: - whether the agent searched the required folder before answering; - whether citations or retrieved evidence support the answer; - whether deterministic, transcript, or rubric graders passed; - whether weak-evidence trials went through human review; - whether a rerun improved or regressed against the selected baseline. Use [Document Folders](#doc-conversations-document-folders) for the retrieval configuration proof, then use Evals for the repeatable pass/fail or score evidence. For offline retrieval-quality comparisons, keep the same fixture across Gaia variants and external-backend captures. Each case should record the query, expected source or retrieval-unit targets, expected citation spans, ranked candidates, ACL posture, latency, freshness, and cost. Provider comparisons should also record the backend id, capability path, capture time, and baseline deltas so reviewers can compare PostgreSQL compact, Azure AI Search, and future adapters without using provider-native scores. The standard metrics are `Recall@k`, `Precision@k`, `MRR`, `nDCG`, citation-span accuracy, ACL false-positive rate, p95 latency, maximum indexing freshness lag, and cost per query. ## Governance requirement evidence When an Agent System is selected in Governance, the standards evidence export can produce ASSERT-style eval scenario drafts from approved Governance Policies and active MCP gateway rules. Treat those drafts as requirement-to-eval starting points: they still need a reviewed eval dataset, run, or human-review result before a release or proposal pack should claim regression evidence. ## Detail views - [Dataset details](#doc-evals-dataset-details) - [Run details](#doc-evals-run-details) - [Trial details](#doc-evals-trial-details) ## New Features Gaia's evaluation system now includes enhanced capabilities for building and analyzing evaluations: ### Eval Design Wizard Create evaluations through a guided 6-step wizard accessible from **Datasets** → **New Evaluation**: 1. **Select Agent** — Choose the target agent and configuration to evaluate. 2. **Evaluation Type** — Pick from task success, tool use, conversational, security, or custom types. 3. **Dataset Source** — Upload data, use existing tasks, or leverage AI-powered generation: - **Import from conversations** — Pull conversations marked "for evaluation" - **AI prompt generation** — Describe what you want to test and let AI generate tasks - **Excel import** — Upload spreadsheets with request/response pairs 4. **Scoring Rubric** — Define dimensions and criteria for evaluation. 5. **LLM Judge** — Optionally configure AI-powered grading. 6. **Review & Create** — Confirm settings and launch. See [Eval Design Wizard](#doc-evals-dialogs-eval-design-wizard) for details, including the AI task generation wizard. ### Eval Settings Set defaults for AI task generation, import prompt templates, and the list of personas used by multi-turn user simulations. See [Evals settings](#doc-evals-settings) to manage generation prompts, import templates, models, and the persona library. ### LLM Judge Integration Configure LLM-based rubric grading directly in the UI: - Define scoring dimensions with names, descriptions, and weights - Provide good/bad examples for each dimension - Choose model, temperature, and output format - Enable caching for reproducible scores See [LLM Judge Configuration](#doc-evals-dialogs-llm-judge) for details. ### Unified Result Viewer The new **Results Dashboard** provides comprehensive visibility into evaluation outcomes: - **Overview metrics** — Pass/fail rates, average scores, human agreement percentages - **Score distribution** — Histograms and heatmaps of grader results - **Trend analysis** — Track performance across multiple runs - **Per-instance drilldown** — View input, trace, labels, and scores for any trial - **Export** — Download results as CSV ### Enhanced Human Review The human review workflow now supports advanced scoring and collaboration: - **Batch review interface** — Review multiple trials at once with keyboard shortcuts - **Custom dimensions** — Define labeler instructions per dimension - **Multi-label support** — Classification, scalar ratings, and freeform feedback - **Inter-rater statistics** — Fleiss Kappa and majority vote aggregation - **Review queue** — Filter by pending, reviewed, or needs-attention status See [Human Review](#doc-evals-dialogs-human-review) for details. ### Agent Behavior Trace Viewer Visualize agent decision steps with a timeline view: - **Observe → Think → Act → Outcome** flow visualization - **Tool call details** — Arguments, results, duration, and error messages - **Agent handoffs** — Track when control passes between agents - **Reasoning steps** — View the agent's thinking process - **Anomaly highlighting** — Spot failures and unexpected behavior See [Agent Behavior Trace](#doc-evals-dialogs-agent-behavior-trace) for details. ### Conversation to Eval Promotion Convert any conversation into an evaluation task: - **Mark for evaluation** — Flag conversations from the Conversations grid - **Promote to Eval** — One-click conversion with AI-assisted task parameter filling - **Auto-detection** — Agent, context, and task intent are pre-filled - **Batch selection** — Promote multiple conversations at once See [Promote to Eval](#doc-evals-dialogs-promote-to-eval) for details. ## Core evaluation patterns (reference) Use these patterns as your baseline when defining new eval tasks and graders: - **Single-turn outcome checks:** Validate structured outputs with deterministic checks (fields, values, thresholds). - **Multi-turn clarification:** Use a user simulator when the agent must ask a follow-up question before acting. - **Transcript patterns:** Require or forbid phrases/patterns in the conversation transcript to enforce policy language. - **Rubric scoring:** Use rubric dimensions for nuanced quality scoring (clarity, correctness, tone, etc.). - **Multi-grader aggregation:** Combine graders with **all/any/majority/weighted** strategies for robust verdicts. These patterns replace the old “Examples” tab and are now maintained here. ## Datasets The Datasets page is the home for **task sets**. Use the folder tree to organize collections (for example, `security/`, `regression/`, `launch/`). - **New folder** opens a dialog to create a folder path. - **New dataset** creates a task set with name, folder, description, and tags. - **Edit dataset** updates the metadata for an existing task set. - **Import datasets** opens the import dialog for JSON/CSV task sets (with an option to create a new dataset on import). - Use the **play** action on a dataset or folder to start a run. - Drag datasets onto folders to reorganize them (drop on the root area to clear the folder path). ## Dataset details (task set) Opening a dataset shows the task table for that set. - **New task** opens the task editor with tabs for Task Info, Tools, User Simulator, and Success Criteria. - **Generate security tasks** seeds the dataset with curated security prompts. - **Import tasks** brings in CSV/JSON tasks. - **Run** starts a run for the dataset; use the play icon on a row to run a single task. - Task row actions: **Run**, **Edit**, **Duplicate**, **Delete**. ## Runs The Runs page lists all runs and their status. - A coverage rollup summarizes task-level pass, grade, review, no-pass-yet, needs-review, and evidence-risk posture for the runs currently in view. - **Start run** opens the run dialog (choose dataset scope and grading settings). - **Re-run** creates a fresh run with the same dataset and settings. - **View** opens run details; **Delete** removes the run and its trials. ## Run details Run details show the live status of a run plus a trial table. - Status badge, dataset scope, and agent/config info appear in the header. - Summary cards show counts for pending/running/completed/failed/stopped/paused trials. - Use **Stop** to halt execution and **Refresh** to update the view. - Open any trial to see its full details. ## Trial details Trial details provide a deep dive into a single task execution. - **Conversation** shows the transcript in read-only mode. - **Grading Results** shows verdicts and explanations per grader. - **Outcome** shows structured output for deterministic checks. - **Human Review** lets you record a manual decision and rationale. - **View Task** opens the task definition in read-only mode. ## Graders Graders define how runs are scored. Create reusable graders and apply them when starting runs. - **Deterministic (Outcome):** Check structured outputs for exact matches and thresholds. - **Transcript pattern:** Require or forbid phrases in the transcript. - **LLM rubric:** Score dimensions via a rubric prompt (pick a model, temperature, and which inputs to include). - **Multi-grader:** Combine existing graders with all/any/majority/weighted strategies (optionally with weights). Use **New grader** to create one, then edit/duplicate/delete from the table. ## Reports Use the Reports page to generate reliability summaries across one or more runs. - Select one or more eval runs from the **Select runs** dialog to aggregate results and compare trends. - Click **Compute metrics** to generate pass@k, pass^k, and per-task success rates. - If you have manage permissions, use **Save metrics** to store the report on each run for quick access. - Use the comparison charts to spot regressions across runs. - Metrics use grader results when available; otherwise they fall back to trial status. ## Run an eval 1. Navigate to **Evals → Datasets** and (optionally) create a folder to organize task sets. 2. Create an eval task set (dataset) and assign it to the right folder. 3. Use the folder tree to locate a dataset and open it to manage eval tasks. 4. Add eval tasks to the dataset (each eval task defines input, success criteria, and any reference material). - Use the tabbed task dialog for both creating and editing tasks (Task Info, Tools, User Simulator, Success Criteria). - Use **Task Info → Document folders** when a task should inherit document-folder search and retrieval during the eval run. - Use **Import** to paste CSV/JSON tasks. - Use **Generate security tasks** inside the task set to seed security scenarios. ### User Simulator (multi-turn evals) Use the **User Simulator** tab when you want multi-turn evaluations that simulate a real user. - **Deterministic** simulators use pattern matching rules to reply to agent messages. - **LLM-based** simulators use a model to select the best rule semantically. See [Create or edit an eval task](#doc-evals-dialogs-eval-task-editor) for detailed configuration and examples. 5. (Optional) Create one or more graders in **Evals → Graders**. - Choose a grader type (deterministic, transcript pattern, or LLM rubric) from the dropdown. - Fill in the type-specific form (checks, patterns, or rubric dimensions). For LLM rubric, the rubric prompt is optional and the scoring dimensions are appended automatically. - Use **Multi-grader** to combine existing graders with all/any/majority/weighted logic. - Ensure the pass threshold and required fields are filled before saving. 6. Start a run from either location: - **Evals → Datasets:** Click the play icon on a dataset to run it, or on a folder to run all datasets in that folder. - **Evals → Runs:** Click **Start run** and choose whether to run a folder, a task set, or a single task. 7. In the start run dialog, choose the configuration, trials per task (k), optional graders, and any execution limits before launching. 8. Click the eye icon on a run to open **Run Details**, which lists all trials (one row per task instance). 9. Runs start automatically when created. Open **Run Details** to monitor progress, stop the run, and click **View** on a trial to open **Trial Details** (task, transcript, outcome, grader results). 10. To re-run the same dataset/configuration, use the **Re-run** action in the **Evals → Runs** table. This creates a fresh run with the same settings. 11. Grading runs automatically once all trials finish. Open **Trial Details → Grading Results** to inspect the verdicts and explanations. - Each grader row shows its **type** and a short configuration summary (e.g., checks, patterns, rubric dimensions). - Expand a grader to see structured breakdowns (checks, issues/successes, dimension scores, or sub-grader results). ## Real-life example > Before shipping a new customer-support prompt, the team built a small dataset of tricky tasks (cancellations, refunds, compliance edge cases), defined a grader rubric, and started a run. They opened the run details page to quickly spot failing trials and iterate on the agent configuration. ## Tips - Start with a small dataset (5–10 tasks) to validate your setup, then expand. - Keep tasks cohesive inside a dataset so results are easy to interpret. - Use **New folder** and dataset paths (e.g. `security/`, `regression/`) to organize larger collections. ## Guides and dialogs - [Eval Design Process](#doc-evals-eval-design-process) - [Ultimate guide: Creating and evolving evals in Gaia](#doc-evals-ultimate-guide) - [Scenario: Operate an eval improvement loop](#doc-evals-scenarios-operate-an-eval-improvement-loop) - [Eval Design Wizard](#doc-evals-dialogs-eval-design-wizard) - [Create or edit a dataset](#doc-evals-dialogs-dataset-editor) - [Create or edit an eval task](#doc-evals-dialogs-eval-task-editor) - [Create or edit a grader](#doc-evals-dialogs-grader-editor) - [Select eval runs](#doc-evals-dialogs-select-eval-runs) - [LLM Judge Configuration](#doc-evals-dialogs-llm-judge) - [Agent Behavior Trace](#doc-evals-dialogs-agent-behavior-trace) - [Promote Conversation to Eval](#doc-evals-dialogs-promote-to-eval) - [Manage eval folders](#doc-evals-dialogs-rename-folder) - [Start an eval run](#doc-evals-dialogs-start-run) - [Import tasks](#doc-evals-dialogs-import-candidates) - [Generate security tasks](#doc-evals-dialogs-generate-security-evals) - [Human review an eval turn](#doc-evals-dialogs-human-review) - [View trial details](#doc-evals-dialogs-turn-details) ## Troubleshooting - **Run stuck in pending:** Confirm you have `modify-evals` permission and refresh the run details page. - **Dataset shows no tasks:** Confirm tasks were added to the task set. - **Grader results missing:** Confirm at least one grader exists, the run has completed, and you have `modify-evals` access. Refresh the trial details view after completion. - **LLM Judge not scoring:** Check that a model is configured and the grader is enabled for the run. - **Trace viewer empty:** Ensure the trial has completed and the conversation messages contain tool calls or reasoning steps. - **Cannot promote conversation:** Verify you have `modify-evals` permission and the conversation has at least one user message. --- # Eval Design Process This guide is about **what to evaluate**, not just where to click in the UI. Use it before you open the Eval Design Wizard so your dataset, success criteria, and graders are intentional. ## Recommended reading order 1. Start with [Evals](#doc-evals) for the workspace overview. 2. Use this page to design your first decision-driven eval. 3. Continue with the [Ultimate Guide: Creating and Evolving Evals in Gaia](#doc-evals-ultimate-guide) to operationalize ongoing review and improvement loops. ## When to use this Use this process whenever you: - Launch a new assistant and need a release gate. - Compare prompts or models. - Add tool use and need to verify decisions and calls. - Investigate regressions in quality, policy, or task completion. ## The 6-step process 1. Define the decision your eval should drive. 2. List the highest-risk failure modes. 3. Write success criteria (must-pass vs quality targets). 4. Choose graders per criterion. 5. Build a pilot dataset that reflects real usage. 6. Calibrate on a small run, then scale. ## 1) Define the decision first Start with one concrete decision: - `Ship / no-ship` for a release - `Model A vs B` for a given workflow - `Prompt v1 vs v2` for quality or safety - `Regression check` after a change If the decision is unclear, the eval will be noisy and hard to trust. ### Decision template - **Decision:** What will this eval decide? - **Scope:** Which user journeys are in/out? - **Target metric:** What result counts as success? - **Deadline:** When do you need confidence? ## 2) List failure modes before tasks Write the failures you cannot afford. Keep this short and specific. Examples: - Wrong policy decision (false approval/denial) - Hallucinated facts or citations - Incorrect tool call arguments - Missing clarification question before action - Correct answer but unsafe/confusing phrasing Prioritize by business impact. Your first dataset should cover the top risks first. ## 3) Define success criteria Split criteria into levels: - **Must-pass:** hard gates (policy, safety, compliance, critical correctness) - **Quality:** target thresholds (accuracy, helpfulness, completeness) - **Nice-to-have:** tone/style improvements ### Criteria format (recommended) - **Criterion:** what is judged - **Pass rule:** binary rule or threshold - **Priority:** must-pass or quality - **Evidence:** where to inspect (output, transcript, tool trace) ## 4) Select grader strategy per criterion Use the simplest reliable grader for each criterion. | Criterion type | Best grader | Why | | ------------------------------------ | ---------------------------- | -------------------------------------- | | Exact value/field/range | Deterministic outcome check | Stable and cheap | | Required/forbidden wording | Transcript pattern grader | Clear policy checks | | Nuanced quality (clarity, relevance) | LLM rubric grader | Handles subjective judgments | | Ambiguous or high-stakes judgments | Human review (or hybrid) | Final guardrail for edge cases | | Tool behavior correctness | Hybrid: tool checks + rubric | Verifies both mechanics and usefulness | Do not rely on one “mega-grader” for everything. ## 5) Build a pilot dataset Start with 10–20 tasks before scaling. Include: - Typical requests (baseline behavior) - High-risk edge cases (from failure modes) - Tool-required tasks (if tools are part of scope) - Negative cases (assistant should refuse, ask clarification, or avoid tool use) For tool-use evals, ensure the project is already configured with the relevant tools and the selected agent configuration has access to them. ## 6) Calibrate, then scale Run a pilot and inspect disagreements: - Criteria unclear? tighten wording. - Graders disagree with humans? refine rubric/examples. - Too many false failures? split criteria into smaller checks. Repeat until pilot outcomes are stable. Then scale dataset size and run frequency. ## Quality checklist - Decision is explicit and time-bound. - Top failure modes are represented in tasks. - Must-pass criteria are separate from quality criteria. - Each criterion has a mapped grader. - Pilot results were reviewed before broader rollout. ## Common anti-patterns - Starting from UI forms before defining the decision. - Mixing policy gates with subjective style in one score. - Creating only “happy path” tasks. - Evaluating tool use without tool-enabled tasks and traces. - Treating first run results as final without calibration. ## Real-life example > A support team wanted to release an assistant that can check order status via tools. Their decision was “ship if policy safety is 100% pass and task completion is at least 85% on pilot cases.” They built a 15-task pilot focused on refund and escalation edge cases, tuned rubric language after human-review disagreements, then scaled to 120 recurring tasks. ## Next steps - Apply this process in a concrete walkthrough: [Scenario: Create and run an eval](#doc-evals-scenarios-create-and-run-an-eval). - Use the UI flow to implement your design: [Eval Design Wizard](#doc-evals-dialogs-eval-design-wizard) and [Start an eval run](#doc-evals-dialogs-start-run). - After your first pilot is stable, adopt the advanced operating model in the [Ultimate Guide: Creating and Evolving Evals in Gaia](#doc-evals-ultimate-guide). --- # Ultimate Guide: Creating and Evolving Evals in Gaia This page is the advanced companion to the step-by-step eval setup pages. Use it when your goal is not just "run an eval once," but build a repeatable quality system that keeps learning as your product, prompts, tools, and user behavior evolve. Recommended sequence: 1. [Evals](#doc-evals) for the workspace map and run lifecycle. 2. [Eval Design Process](#doc-evals-eval-design-process) to define your first decision, criteria, and graders. 3. This guide to scale into a continuous operating model. The central idea is simple: - **Conversations** is where reality appears. - **Evals** is where reality becomes repeatable tests. If you only do one side, quality drifts. If you run both together, quality compounds. ## Concepts first: the mental model Before mechanics, align on key terms: - **Trace:** The full story of one user request, including messages, tool calls, retrieval context, intermediate steps, and final output. - **Error analysis:** Systematically reviewing traces to discover real failure patterns. - **Failure taxonomy:** A small, evolving set of named failure families (for example `wrong-tool`, `missing-constraint`, `unsafe-tone`). - **Eval task:** A reusable scenario in Evals that checks expected behavior. - **Grader:** The scoring logic (deterministic checks, transcript patterns, rubric judge, or human review). - **Calibration:** Aligning automated grader outputs with human judgment so results are trustworthy. In practice, this is a control loop: 1. Observe production behavior. 2. Explain failures with a taxonomy. 3. Encode those failures as tasks and graders. 4. Validate with humans. 5. Re-run continuously as the system changes. ## What this guide adds - How to use **Conversations review** for error analysis, not only feedback collection. - How to transform findings into robust eval assets in [Evals](#doc-evals). - How to work the run-to-rerun operator loop with saved subsets, coverage posture, evidence queues, and linked baseline comparison. - How to run separate loops for **CI regression** and **production monitoring**. - How to evaluate **multi-turn**, **agentic**, **handoff-heavy**, and **RAG** workflows. ## The operating model in Gaia Use this loop continuously: 1. Capture and triage traces in [Conversations](#doc-conversations). 2. Run structured error analysis on sampled traces. 3. Convert failure patterns into tasks and graders in [Evals](#doc-evals). 4. Calibrate with [Human Review](#doc-evals-dialogs-human-review). 5. Ship, monitor production, and feed new failures back into datasets. > Real-life example > A support team starts with user feedback tags in Conversations, then discovers a recurring "agent skips eligibility check" pattern. They promote representative traces into Evals, add deterministic and rubric graders, and run the dataset on every prompt release. Two weeks later, production monitoring finds a new edge case, and they add it to CI so it never regresses again. ## Stage 1: Capture and triage traces in Conversations Start in [Conversations](#doc-conversations), because this is where real behavior appears first. The objective here is not to "score quality" yet. It is to create a clean intake flow for evidence. Use these controls as your intake system: - **Review state** (`For review`, `In review`, `In progress`, `Addressed`) for triage flow. - **Decision** (`pass/fail`) for quick quality signal while reviewing. - **For evaluation** toggle to mark traces for promotion into Evals. - **Tags** for failure families (for example: `missing-context`, `bad-tool-args`, `tone-mismatch`). - [Give feedback](#doc-conversations-dialogs-feedback) for reviewer notes tied to exact turns. - [Timeline](#doc-conversations-dialogs-timeline) and **Inside Info** for step timing, tool usage, tokens, and errors. - **Messages** JSON transcript to inspect raw tool calls and handoffs. Practical setup: - Reserve a small, stable tag taxonomy for failure modes. - Keep review states process-oriented (`For review` means "needs analysis", not "bad output"). - Prefer concrete tags over abstract labels (`wrong-currency` beats `quality-issue`). ## Stage 2: Run error analysis, not generic scoring This is the highest-leverage step. Do not start from prefab "quality" metrics. Start from actual failures in your own traces. Recommended flow: 1. Sample traces from multiple buckets: random, negative feedback, outliers, and key user segments. 2. Open-code each trace with short notes about the first meaningful upstream failure. 3. Group notes into a failure taxonomy (axial coding). 4. Count frequency and impact of each failure family. 5. Select top failure families for evaluator creation. Gaia mapping: - Use conversation filters (review state, tags, favorites, creator, date) to build sample sets quickly. - Keep reviewer notes in [feedback threads](#doc-conversations-dialogs-feedback) so they stay attached to evidence. - Use [Promote Conversation to Eval](#doc-evals-dialogs-promote-to-eval) once a trace is confirmed as representative. Why this works: - It keeps evaluation tied to real business risk. - It prevents over-investment in abstract metrics. - It gives clear priorities for what to automate next. ## Stage 3: Convert findings into eval assets Move from observations to executable checks in [Evals](#doc-evals). This is where "we saw a problem" becomes "we can detect this every release." Build datasets with three task sources: - Real traces promoted from Conversations. - Handwritten edge cases from the taxonomy. - Synthetic cases generated from explicit dimensions (only after failure hypotheses are clear). Pick grader types by failure type: - Deterministic checks for structured outcomes and hard constraints. - Transcript pattern checks for explicit required or forbidden language. - LLM rubric graders for nuanced judgments. - [Human Review](#doc-evals-dialogs-human-review) for ambiguous or high-stakes decisions. Avoid two traps: - Building one large "mega-grader" that mixes unrelated criteria. - Relying on generic off-the-shelf quality metrics as your primary gate. ## Stage 4: Calibrate before scaling A grader is useful only if you trust it. Calibration is how you earn that trust. Run a pilot first (small task set), then expand. Calibration checklist: 1. Run a small set with representative failure modes. 2. Compare grader output against human reviewers. 3. Tighten criteria and examples where disagreement is high. 4. Re-run until agreement is acceptable for your use case. 5. Scale task volume and run frequency only after alignment. Use these pages during calibration: - [Run details](#doc-evals-run-details) - [Trial details](#doc-evals-trial-details) - [Human Review](#doc-evals-dialogs-human-review) - [Agent Behavior Trace](#doc-evals-dialogs-agent-behavior-trace) Tip: - Track disagreements by failure family. This tells you whether the problem is rubric wording, missing examples, or fundamentally ambiguous criteria. ## Stage 4.5: Work the run-to-rerun operator loop in Gaia Once the first pilot exists, do not treat every new run as a fresh experiment. Gaia now supports a tighter operator loop for narrow fixes, coverage follow-up, and release decisions. 1. Save reusable subsets in [Dataset details](#doc-evals-dataset-details) for the slices you expect to rerun often, such as smoke, review, or release. 2. Open [Run details](#doc-evals-run-details) and read **Coverage posture** plus **Workflow posture** before you start drilling into individual trials. 3. Use the run-level evidence queues plus [Human Review](#doc-evals-dialogs-human-review) to isolate ambiguous, weak-evidence, or reviewer-disagreement cases. 4. Launch the smallest useful rerun from the current run: **Failed / Partial / Unreviewed** when validating a fix, or **No Pass Yet / Needs Review** when closing gaps. 5. Let the linked baseline comparison on [Run details](#doc-evals-run-details) judge whether the rerun actually improved the shared task scope. 6. Use [Reports](#doc-evals-reports) and [Select eval runs](#doc-evals-dialogs-select-eval-runs) to aggregate only the comparable runs when you need a release-facing summary. 7. Promote any newly discovered failure mode back into the dataset instead of keeping it as an ad hoc rerun-only check. Use [Scenario: Operate an eval improvement loop](#doc-evals-scenarios-operate-an-eval-improvement-loop) for the step-by-step version of this flow. ## Stage 5: Split CI evals from production evals These are complementary systems with different purposes: - **CI evals** keep releases safe. - **Production evals** detect drift and discover new failures. CI evals: - Curated, smaller datasets. - Fast, deterministic checks preferred. - Regression prevention after prompt, tool, or configuration changes. Production evals: - Sampled live traces. - More reference-free checks and human review. - Monitoring for drift, new failure modes, and changing user behavior. Feedback loop: - When production reveals a new failure mode, add representative tasks to CI datasets. ## Stage 6: Advanced workflow patterns ### Multi-turn and agentic workflows Use a two-phase strategy: 1. End-to-end success (did user goal complete?). 2. Step-level diagnostics (tool choice, argument quality, recovery behavior, context retention, efficiency). In Gaia: - Start with trial outcome and transcript. - Open [Agent Behavior Trace](#doc-evals-dialogs-agent-behavior-trace) for step-by-step failure localization. - Use [turn details](#doc-evals-dialogs-turn-details) plus transcript JSON to identify first upstream breakpoints. ### Human handoffs Include handoff quality in evaluation scope: - Was handoff necessary? - Was context transferred adequately? - Was resolution achieved after handoff? Treat poor handoff boundaries as first-class failure modes in your taxonomy. ### RAG systems Separate retrieval from generation: - Retrieval: track IR metrics such as `Recall@k`, `Precision@k`, `MRR`, and `nDCG`. - Generation: evaluate faithfulness, relevance, and answer quality using calibrated graders. For structured RAG framing, use question-context-answer relationships as an organizing lens, then extend with domain-specific failure checks discovered via error analysis. ## Stage 7: What to automate vs what not to automate Automation should accelerate judgment, not replace product understanding. Good automation targets: - First-pass grouping of open-coding notes. - Mapping notes to existing failure taxonomy labels. - Suggesting prompt or tool fixes after human-reviewed patterns are clear. - Bulk analysis over annotated traces. Keep human-owned: - Initial open coding of raw traces. - Final taxonomy decisions. - Ground-truth labels used to calibrate LLM judges. - High-stakes arbitration when graders and humans disagree. ## Stage 8: Suggested cadence Baseline operating cadence: - Weekly: sample and review a small batch of production traces. - Bi-weekly or monthly: full error-analysis cycle on a larger sample. - On major changes: run focused CI regression and targeted human review. - After incidents: immediate focused analysis and dataset updates. This cadence is a starting point. Increase frequency when usage grows quickly, new features launch, or quality is unstable. ## Common anti-patterns - Treating feedback comments as the full eval system. - Measuring only dashboard metrics without reading traces. - Building evaluators before understanding real failure modes. - Mixing policy gates and style preferences into one pass/fail check. - Ignoring grader-human disagreement. ## A practical first-30-days plan If your eval system is still immature, use this rollout: 1. Week 1: establish triage tags and review flow in Conversations. 2. Week 2: run first error-analysis pass and define taxonomy. 3. Week 3: create first dataset and graders in Evals. 4. Week 4: calibrate with human review, save reusable subsets, and schedule recurring runs. By the end of month one, the goal is not perfect scores. The goal is a working feedback loop you can trust. ## Source-backed further reading - Hamel Husain, [LLM Evals: Everything You Need to Know](https://hamel.dev/blog/posts/evals-faq/) - Hamel Husain, [Your AI Product Needs Evals](https://hamel.dev/blog/posts/evals/) - Hamel Husain, [Using LLM-as-a-Judge For Evaluation: A Complete Guide](https://hamel.dev/blog/posts/llm-judge/) - Hamel Husain, [A Field Guide to Rapidly Improving AI Products](https://hamel.dev/blog/posts/field-guide/) - Hamel Husain and Shreya Shankar, [How to Process Documents at Scale with LLMs (annotated notes + timestamps)](https://hamel.dev/notes/llm/data-processing/shreya-data-processing.html) - Hamel Husain, [Stop Saying RAG Is Dead](https://hamel.dev/notes/llm/rag/not_dead.html) - Nandan Thakur (annotated by Hamel), [Modern IR Evals For RAG](https://hamel.dev/notes/llm/rag/p2-evals.html) - Jason Liu, [There Are Only 6 RAG Evals](https://jxnl.co/writing/2025/05/19/there-are-only-6-rag-evals/) - Shreya Shankar et al., [Who Validates the Validators?](https://arxiv.org/abs/2404.12272) ## Next steps - If your team is still setting up first-pass evals, start with the [Eval Design Process](#doc-evals-eval-design-process). - Use this page to define and run your long-term operating model. - For first execution in Gaia, run [Scenario: Create and run an eval](#doc-evals-scenarios-create-and-run-an-eval). - For the recurring operator workflow after the first pilot, run [Scenario: Operate an eval improvement loop](#doc-evals-scenarios-operate-an-eval-improvement-loop). --- # Eval Scenarios These scenario playbooks show how to apply the [Eval Design Process](#doc-evals-eval-design-process) to real product goals. Use them when you need practical examples of: - what to test - how to define success - which graders to use - how to run a pilot before scaling - how to turn a first pilot into a repeatable improvement loop ## Available scenarios - [Create and run an eval (tool-enabled support assistant)](#doc-evals-scenarios-create-and-run-an-eval) - [Operate an eval improvement loop (saved subsets, evidence queues, targeted reruns)](#doc-evals-scenarios-operate-an-eval-improvement-loop) --- # Scenario: Create and run an eval This playbook is for teams evaluating a **tool-enabled support assistant**. The focus is not just UI clicks. It is how to design useful eval content before implementing it in Gaia. ## Scenario goal You have a support agent that should: - answer policy questions correctly - call tools when needed - avoid unsafe or non-compliant responses You need confidence to decide if the current agent/config is ready to ship. ## Prerequisites Before creating eval tasks: - The agent and active configuration already exist. - Required tools are configured and available to that configuration. - You can run a normal conversation that triggers at least one expected tool call. If tools are not ready, do that first in [AI Agents](#doc-agents) and [Agent Configuration](#doc-agents-configs). ## Step 1: Define the decision Write one explicit decision statement: - **Decision:** Ship this support assistant to production for order-status and refund workflows. - **Ship gate:** Must-pass safety/policy at 100%, task completion at >= 85% in pilot. - **Out of scope:** Non-support chit-chat and unsupported languages. ## Step 2: Identify failure modes Prioritize the failures that would hurt users or business most. | Priority | Failure mode | Why it matters | | -------- | ------------------------------------- | --------------------------- | | High | Wrong policy decision | Compliance and trust risk | | High | Incorrect tool arguments | Wrong account/order actions | | High | Hallucinated policy text | Misleading support guidance | | Medium | No clarification when context missing | Avoidable bad outcomes | | Medium | Correct but confusing response | Poor UX and escalations | ## Step 3: Define success criteria Separate hard gates from quality goals. | Type | Criterion | Pass rule | Evidence | | --------- | --------------------- | --------------------------------------------------- | ---------------------------------- | | Must-pass | Policy safety | No disallowed advice or policy violations | Transcript | | Must-pass | Tool-call correctness | Tool name and key arguments match expected behavior | Tool trace / timeline | | Quality | Task completion | User intent resolved in allowed workflow | Transcript + outcome | | Quality | Communication quality | Clear next step, concise wording, no ambiguity | LLM rubric + optional human review | ## Step 4: Map criteria to graders Use multiple graders instead of one monolithic grader. | Criterion | Grader type | Notes | | --------------------- | ----------------------------------------- | ------------------------------------------- | | Policy safety | Transcript pattern + deterministic checks | Catch forbidden content reliably | | Tool-call correctness | Deterministic checks on tool events | Verify tool selection and arguments | | Task completion | LLM rubric grader | Judge if user intent was actually satisfied | | Communication quality | LLM rubric + human spot-check | Use pilot calibration for rubric wording | ## Step 5: Build a pilot dataset (10-20 tasks) Use realistic prompts from support traffic patterns. Include: - straightforward order-status requests - refund edge cases - ambiguous requests requiring clarification - requests that should not trigger tools - policy-sensitive requests requiring safe refusal or escalation ### Example pilot tasks | Task | Expected behavior | Tool expected | | -------------------------------- | ---------------------------------- | ------------------------- | | “Where is order #12345?” | Fetch status and summarize clearly | Yes | | “Refund my order from last year” | Check policy window before promise | Maybe | | “Change shipping address now” | Ask for missing verification data | Yes (after clarification) | | “Give me admin override steps” | Refuse and offer safe alternative | No | ## Step 6: Run pilot, save reusable slices, then calibrate Run one pilot first, review trial details, then adjust: - save the exact pilot filter as a named subset once the dataset table reflects the smoke slice you want to reuse - read **Coverage posture** and **Workflow posture** in [Run details](#doc-evals-run-details) before deciding what to fix next - use the evidence queues and [Human Review](#doc-evals-dialogs-human-review) for ambiguous or high-stakes cases - launch **Rerun Failed / Partial / Unreviewed** when validating a fix, or **Rerun No Pass Yet / Needs Review** when closing coverage gaps - compare the rerun against its linked baseline and use [Reports](#doc-evals-reports) for the release-facing summary - tighten vague criteria text - refine rubric examples where graders disagree with humans - split broad criteria into smaller checks when needed When stable, expand dataset and schedule recurring runs. For the repeatable post-pilot loop, continue with [Scenario: Operate an eval improvement loop](#doc-evals-scenarios-operate-an-eval-improvement-loop). ## How this maps to Gaia UI Interactive walkthrough: Open [Tutorials](/platform/support/tutorials) and select **Create and run an Eval**. When you start it, choose **Create Prepared Project** (recommended) or select/create your project workspace. 1. Create dataset and tasks in [Datasets](#doc-evals-datasets). 2. Add task-level criteria in [Create or edit an eval task](#doc-evals-dialogs-eval-task-editor). 3. Open [Dataset details](#doc-evals-dataset-details) and save the filters you want to reuse as named subsets. 4. Define reusable graders in [Graders](#doc-evals-graders) and [Create or edit a grader](#doc-evals-dialogs-grader-editor). 5. Launch pilot from [Start an eval run](#doc-evals-dialogs-start-run). 6. Inspect failures in [Run details](#doc-evals-run-details), [Trial details](#doc-evals-trial-details), [Human Review](#doc-evals-dialogs-human-review), and [Agent Behavior Trace](#doc-evals-dialogs-agent-behavior-trace). 7. Launch the smallest useful rerun from [Run details](#doc-evals-run-details), then compare it against the linked baseline. 8. Use [Reports](#doc-evals-reports) and [Select eval runs](#doc-evals-dialogs-select-eval-runs) when you need the release-facing summary. After a run starts, Gaia continues executing it in the background. You can leave the run details page or close the browser and return later to review progress and results. ## Ready-to-use worksheet Copy this and fill it before opening the wizard: ```md Decision: Scope in: Scope out: Ship gate: Top failure modes: 1. 2. 3. Must-pass criteria: 1. 2. Quality criteria: 1. 2. Grader mapping: - Criterion -> grader type Pilot dataset size: Calibration plan: ``` ## Real-life example > A customer support team preparing a seasonal launch used a 15-task pilot to stress refund and delivery exceptions. They saved a smoke subset for the riskiest workflows, discovered tool-argument mistakes in edge cases, used **Rerun Failed** to validate the fix, then checked the linked baseline comparison and reports before enabling the channel for all users. --- # Scenario: Operate an eval improvement loop This playbook starts after your first pilot run exists. Use it when the question is no longer “How do I create an eval?” but “How do I improve this eval intentionally without losing scope, evidence, or comparison discipline?” Interactive walkthrough: start with [Tutorials](/platform/support/tutorials) and select **Create and run an Eval** for the first execution path. Then use this page for the recurring loop that follows the pilot. ## Scenario goal You already have a dataset, grader set, and at least one completed run. You now need to: - preserve the exact task slices you rely on - identify whether the next problem is pass coverage, review coverage, or weak evidence - rerun only the tasks that still matter - compare the new run against its baseline without inventing a new measurement frame - decide in reports whether quality is improving enough to ship or advance ## Prerequisites Before starting this loop: - the dataset and graders already exist - at least one run has completed - you can open [Dataset details](#doc-evals-dataset-details), [Run details](#doc-evals-run-details), [Human Review](#doc-evals-dialogs-human-review), and [Reports](#doc-evals-reports) - you know which change you are validating: prompt, tool contract, policy rule, grader, or dataset update If you are still creating the first dataset or first run, use [Scenario: Create and run an eval](#doc-evals-scenarios-create-and-run-an-eval) first. ## Step 1: Save the slices you intend to reuse Open [Dataset details](#doc-evals-dataset-details) and treat the filtered task table as the source of your reusable run scopes. Good starting subsets are: - a **smoke** subset for the smallest high-risk slice you run after every change - a **review follow-up** subset for tasks that usually need human inspection - a **release** subset for the broader ship or hold decision Use **Save subset** after applying the filters. The point is not just convenience. It is to keep the rerun scope stable enough that future comparisons remain honest. ## Step 2: Launch the smallest meaningful run Use [Start an eval run](#doc-evals-dialogs-start-run) from the saved subset when you want a narrow candidate run, or from the full dataset when the decision really needs the broader release surface. Good defaults: - use the smoke subset when validating a narrow fix - use the release subset when you need a go or no-go argument - keep the same configuration and grader set unless the measurement change is itself part of the experiment If the scope changes, write that down before comparing the result with anything older. ## Step 3: Read coverage and workflow posture before drilling into trials Open [Run details](#doc-evals-run-details) and start with the summary cards plus **Coverage posture** and **Workflow posture**. Use that card to decide what kind of problem you actually have: - **No pass yet** means the task still has no passing trial in the current run - **Needs review** means the task is blocked by missing, unresolved, or disagreeing review state - **Evidence risk** means the task outcome may be weak because citations are missing evidence or source context - **Recovery fail** means the workflow reached a failure or blocked state without restoring the expected checkpoint or follow-on action - **Invariant fail** means the workflow completed the wrong state transition even if the run still produced a final answer This prevents a common mistake: jumping straight into individual trial rows without knowing whether the real issue is correctness, review backlog, or evidence quality. ## Step 4: Use the evidence queues to isolate the next review slice Stay on [Run details](#doc-evals-run-details) and use the queue buttons above the trials table. Choose the slice that matches the current problem: - **Evidence Risk** when you want every trial with weak or missing grounded evidence - **No Evidence** when Gaia resolved nothing and the answer may be unsupported - **Mixed Evidence** when citations exist but the resolved evidence is incomplete - **Reviewer Disagreement** when human review and the automated final verdict diverge Then open the relevant trials and use [Human Review](#doc-evals-dialogs-human-review) for the ambiguous or high-stakes cases. ## Step 5: Pick the right rerun action Do not default to whole-dataset reruns. Use the rerun action that matches the kind of change you made: - **Rerun Failed** when you addressed a concrete defect and want to recheck only the failed slice - **Rerun Partial** when partial completion was the main issue - **Rerun Unreviewed** when the blocker was missing review coverage - **Rerun No Pass Yet** when the objective is to close pass coverage gaps quickly - **Rerun Needs Review** when the objective is to clean up reviewer follow-up or verdict disagreement - **Run Again** when the whole run is still the right comparison surface Gaia keeps these reruns linked back to the source run so you can judge improvement without opening two unrelated pages side by side. ## Step 6: Use baseline comparison to judge whether the rerun helped After the rerun reaches a terminal state, stay on [Run details](#doc-evals-run-details) and read the **Baseline comparison** card. Look for: - verdict improvements versus regressions - score movement - review backlog changes - whether evidence-risk pressure shrank or grew - whether the shared task scope gained or lost passing coverage This comparison matters most when you used a saved subset or a targeted rerun action. It keeps a narrow rerun from being misread as either a full-dataset win or a full-dataset regression. ## Step 7: Make the release-facing decision in reports Open [Reports](#doc-evals-reports) and then [Select eval runs](#doc-evals-dialogs-select-eval-runs). Use the run-selection coverage cues to choose only the runs that belong in the same decision frame. Then: 1. compute metrics for the selected runs 2. compare the baseline and candidate runs together 3. keep the decision explicit: ship, hold, or continue learning Use **Reports** for the release-facing summary and keep the richer diagnosis in **Run details** and **Human Review**. ## Step 8: Promote what you learned back into the dataset If the rerun exposed a new failure class, do not leave it as a one-off observation. Update the dataset so the next cycle becomes easier: - add or revise the task - tighten the grader or rubric wording - save a better subset if the old slice was too broad - record whether the change belongs to smoke, review follow-up, or release scope That is how the loop compounds instead of repeating the same manual investigation. ## Real-life example > A support team changed a refund-policy prompt after a failed pilot. They opened **Run details**, saw that the main issue had shifted from pass rate to **Evidence Risk**, reviewed only the weak-evidence trials, launched **Rerun Needs Review**, and then used the linked baseline comparison plus **Reports** to confirm the change improved the shared task scope without widening the release slice. ## Related pages - [Scenario: Create and run an eval](#doc-evals-scenarios-create-and-run-an-eval) - [Dataset details](#doc-evals-dataset-details) - [Run details](#doc-evals-run-details) - [Human Review](#doc-evals-dialogs-human-review) - [Reports](#doc-evals-reports) - [Select eval runs](#doc-evals-dialogs-select-eval-runs) --- # Eval Datasets Use the **Datasets** tab to organize eval task sets with folders and tags. This page is the starting point for building datasets and launching runs. ## What you’ll see - Search bar and refresh button. - A folder tree for datasets (expand/collapse and drag-and-drop). - Dataset rows showing tags and last updated dates. - Toolbar actions: - **New folder** - **New dataset** - **Create with AI** - **Import datasets** - **Import package** ## Create a dataset 1. Click **New dataset**. 2. Select a folder (or type a custom path). 3. Add a name, description, and tags. 4. Click **Create**. See [Create or edit a dataset](#doc-evals-dialogs-dataset-editor) for field details. ## Create with AI (Eval Design Wizard) Use **Create with AI** to generate tasks from prompts, conversations, or Excel and optionally start a run. Use **Start from template** inside the wizard to restore a project-shared Eval design template. You can modify every restored choice before generating new tasks. Templates do not contain generated tasks or uploaded file contents. See [Eval Design Wizard](#doc-evals-dialogs-eval-design-wizard) for the AI task generation flow. ## Import datasets Import tasks from CSV/JSON into existing or new datasets. See [Import tasks](#doc-evals-dialogs-import-candidates). ## Move a dataset between Gaia environments Use the **Export portable package** action on a dataset row to download a versioned JSON package. The package contains the dataset metadata and tasks, but not project IDs, row IDs, credentials, or other environment-specific references. The export reports any fields that it omits. On another Gaia project, click **Import package** and select that file. Gaia validates the package, shows its folder, task count, warnings, and name conflicts, and asks for confirmation before creating a new dataset. Import is transactional: Gaia creates the dataset and all of its tasks together, or does not persist any of them if validation or storage fails. ## Run a dataset or folder - Use the **play** icon on a dataset to open the run dialog prefilled with that dataset. - Use the **play** icon on a folder to run every dataset under that path. See [Start an eval run](#doc-evals-dialogs-start-run). ## Organize folders - Click **New folder** to add structure for datasets. - Drag datasets onto folders to move them. - Drop a dataset onto the root area to clear its folder path. - Use the pencil action on a folder to rename or move the full folder subtree. Dataset identities and links remain stable. Gaia rejects collisions and attempts to move a folder inside itself. - Use the trash action on a folder to delete every dataset and task in that folder and its nested folders. The confirmation dialog shows the number of affected datasets, tasks, and subfolders. Historical run results remain available with their deleted task links cleared. Stop affected active trials before deleting the folder. See [Manage eval folders](#doc-evals-dialogs-rename-folder). ## Dataset actions Each dataset row includes quick actions: - **Run** — Start a run from the dataset. - **Open** — Navigate to the dataset tasks. - **Edit** — Update name, path, description, and tags. - **Duplicate** — Clone dataset metadata. - **Export portable package** — Download environment-neutral dataset metadata and tasks. - **Delete** — Remove the dataset (tasks become unassigned). ## Tips - Use consistent folder prefixes such as `security/`, `regression/`, or `release/`. - Add tags for quick filtering across datasets. --- # Dataset details Opening a dataset shows its task list and management actions. ## What you’ll see - Dataset name/path with tags. - Task table showing **Title**, **Type**, **Difficulty**, **Tags**, and **Updated**. - Toolbar actions for task creation, import, and runs. - A filter row with **Search**, **Type**, **Difficulty**, and multi-select **Tags** filters. ## Toolbar actions - **New eval task** — Opens the task editor for a single task. - **Import** — Bulk import tasks into this dataset. - **Security** — Generate curated security tasks. - **Run** — Start a run for this dataset. When search or filters are active, Gaia pre-fills the current filtered task subset instead of the whole dataset. - **Save subset** — Save the current search and filter combination as a reusable named subset for later runs. - **Search** and **Refresh** — Search loaded tasks and reload the list. ## Filter tasks - Use **Type** and **Difficulty** to narrow the table to specific task categories. - Use **Tags** to select one or more tags. Gaia keeps tasks that contain every selected tag. - Use **Run filtered** after narrowing the list to launch a run against every matching task, not just the tasks visible on the current page. - Use **Clear filters** to reset the local filter state without leaving the dataset. ## Save and reuse subsets - Use **Save subset** after applying a search or filter combination you expect to rerun. - Saved subsets keep the current search text plus the selected type, difficulty, and tag filters. - Click a saved subset name to reapply it to the dataset table. - Use the subset run action to open **Start Eval Run** with that subset locked as the task scope. - Delete a saved subset when it is no longer useful. This removes only the saved filter definition, not the dataset tasks. ## Task row actions - **Run** — Start a run for a single task. - **Edit** — Update task details and criteria. - **Duplicate** — Clone a task into the dataset. - **Delete** — Remove a task. ## Related dialogs - [Create or edit an eval task](#doc-evals-dialogs-eval-task-editor) - [Import tasks](#doc-evals-dialogs-import-candidates) - [Generate security tasks](#doc-evals-dialogs-generate-security-evals) - [Start an eval run](#doc-evals-dialogs-start-run) --- # Eval Runs The **Runs** tab lists all evaluation runs and lets you start new runs or revisit results. ## What you’ll see - Search bar to filter runs by name. - A coverage rollup card that summarizes pass, grade, review, no-pass-yet, needs-review, and evidence-risk posture for the currently visible runs. - A workflow posture card for the currently visible runs when those runs include workflow-backed trials with invariant or recovery grading. - Toolbar actions: - **New Evaluation** (Eval Design Wizard) - **Start run** - **Refresh** - A run table with **Run name**, **Status**, **Dataset**, **Trials/task**, and **Updated**. When workflow-backed runs are in view, the workflow posture card and table column summarize: - invariant pass, partial, and fail posture - recovery pass, partial, and fail posture - how many workflow-backed trials are represented in the current slice ## Start a run Click **Start run** to open the run configuration dialog. See [Start an eval run](#doc-evals-dialogs-start-run). ## Create a new evaluation Click **New Evaluation** to open the Eval Design Wizard and generate tasks with AI or imports. See [Eval Design Wizard](#doc-evals-dialogs-eval-design-wizard). ## Run actions Each row includes quick actions: - **View** — Open run details. - **Re-run** — Create a new run with the same dataset and settings. - **Delete** — Remove the run and its trials. ## Run details actions When you open a run, the toolbar includes: - **Export** — Download either a full run JSON bundle or a human-reviews CSV. - **Run Again** — Recreate the run with the same settings. - **Stop** — Stop an in-flight run. ## Tips - Use **Re-run** after updating an agent configuration to compare results quickly. - Search, filter, or paginate first when you want the coverage rollup to reflect a narrower slice of runs. - Use the workflow posture rollup to decide whether a run failure is primarily an invariant break or a recovery problem before drilling into individual trial rows. - Keep run names descriptive so they’re easy to track in reports. --- # Run details The run details page tracks status, shows summary metrics, and lists all trials in the run. ## Header overview - **Status badge** for the run state (pending, running, completed, failed, stopped, paused). - **Dataset scope** (dataset, folder, or task list). - **Agent/config version** used for the run. - **Started/Finished** timestamps when available. ## Run actions - **Export** downloads the full JSON bundle, a human-review CSV, or an evidence-led ledger CSV for the run. - **Run Again** recreates the run with the same settings and links the new run back to the current run as its baseline. - **Rerun Failed** uses the same failed execution status shown by **Failed (Execution)** in the summary. A completed trial with a failing grade is not an execution failure; use **Rerun No Pass Yet** for that improvement loop. - **Rerun Partial / Unreviewed** opens the start-run dialog with a locked task subset based on the current trial outcomes and review state. - **Rerun No Pass Yet / Needs Review** generates the next useful task subset from current run state and opens the same locked start-run dialog. - **Resume** — Queue or resume execution when an in-flight run still has pending trials. - **Stop** — Halt an in-flight run (pending/running trials are marked stopped). - **Refresh** — Reload run status and trials. - **Delete** — Remove the run and its trials. ## Summary cards Cards show counts for **Total**, **Pending**, **Running**, **Completed**, **Failed**, **Stopped**, **Paused**, and **Stopping** trials. When the run includes workflow-backed trials, Gaia also shows a **Workflow posture** card that summarizes run-level: - invariant pass, partial, and fail posture - recovery pass, partial, and fail posture - how many workflow-backed trials currently contribute workflow grading signals If the run was launched from **Run Again** or one of the rerun subset actions, the page also shows a **Baseline comparison** card after the rerun reaches a terminal state. When the run has task-backed trials, the lower section switches between full-width **Trials** and **Coverage posture** tabs so you can stay on the trial table while still reviewing task-level coverage. The **Coverage posture** tab summarizes task-level: - passing coverage - graded coverage - reviewed coverage - no-pass-yet pressure - needs-review pressure - evidence-risk pressure Coverage is counted once per task from the current run state and the shared rerun/evidence semantics, not by raw trial totals alone. The comparison surface shows: - matched-trial counts against the linked baseline - verdict improvements and regressions - pass-rate and average-score deltas - review changes such as unresolved to reviewed - shared-task coverage rollups for pass, review, evidence-risk, and gap pressure - a changed-trials list with baseline versus rerun values for verdict, score, and review Use **Open Baseline** to inspect the source run. Gaia keeps the rerun context in the URL and shows **Back to comparison** on the baseline so you can return directly to the completed comparison. The run details surface remains vertically scrollable while the comparison is visible, and the trials workspace keeps a usable minimum height instead of being pushed out of reach. The same card now includes a **Coverage rollup** section that compares the shared task scope between the baseline and current run. It highlights: - how many tasks gained or lost passing coverage - how many tasks still need review follow-up - whether evidence-risk pressure shrank or grew - which task gaps were resolved or introduced between runs ## Trials tab Use the **Trials** tab and its **evidence queue** buttons above the table to focus the current run on a smaller review slice: - **All Trials** shows the full run. - **Evidence Risk** combines trials with **None** or **Mixed** evidence posture. - **No Evidence** isolates trials where Gaia resolved no grounded evidence. - **Mixed Evidence** isolates trials where one or more citations are missing excerpt or source context. - **Reviewer Disagreement** isolates trials where the saved human review disagrees with the automated final verdict. Each trial row includes: - Task title and type. - Trial index (#). - Status, final grading outcome, workflow posture, evidence posture, human review decision, and last updated time. - **View** action to open trial details. ## Notes - Runs execute through Gaia's background job queue, so you can leave the page and return later. The details page auto-refreshes lightweight run status while work is in progress and reloads full trial/grading detail when the run reaches a terminal state. - If a browser or server request ends while a run still has pending trials, **Resume** safely queues the remaining work without duplicating active execution. - The evidence queue badge shows how many trials are currently visible versus the total run size. - Coverage posture highlights task-level gaps such as **No pass yet**, **Not reviewed**, **Needs review**, and **Evidence risk** so you can spot thin coverage without inspecting every trial row. - Workflow posture highlights whether the current issue is an invariant break or a failed recovery path before you open individual trial details. - Subset reruns preserve the original agent, config, grader, and limit settings; only the task scope changes. - **Rerun No Pass Yet** targets tasks that still have no passing trial in the current run. - **Rerun Needs Review** targets tasks that are missing a completed review, are still marked needs-review, or now disagree with the automated verdict. - Saved dataset subsets and rerun subsets open the start-run dialog with a locked task scope label so you can confirm exactly which task slice will execute. - Runs launched from run details keep a link to the source run so the rerun can show baseline deltas without manually opening two runs side by side. - Coverage rollups compare only the shared task scope between the linked baseline and current run so subset reruns do not read like full-dataset regressions. - Full JSON exports include normalized grounded evidence references, evidence provenance metadata, and the shared evidence posture for each trial so downstream analysis can reuse the same interpretation as the Gaia UI. - Keep **Include review data** enabled in the export dialog when the JSON should include grader results, trial human reviews, and precise response-level feedback for error analysis. - Evidence ledger CSV exports flatten the run into one evidence-focused audit table: one row per grounded-evidence item plus a no-evidence row for trials where Gaia resolved nothing. - Human reviews CSV exports include a compact response-level feedback count and summary alongside trial-level review decisions and rationales. - Use **Stop** before **Delete** if you need to halt execution safely. - Trial outcomes come from a synthetic **Final verdict** that combines grader results and task success criteria according to the run’s final verdict policy. --- # Trial details The trial details page provides a complete view of a single evaluation attempt. ## Header overview - Status badge and run info. - **Previous** and **Next** move through the current run in the same order shown on the run details page. - The trial position field accepts any value from `1` to the run total. Press `Enter` to jump directly to that position. - **View Task** button opens the task definition in read-only mode. - **Refresh** to reload trial data. ## Summary cards - **Trial #** - **Task** (title) - **Type** - **Verdict** (from the first grader, when available) ## Tabs ### Conversation Read-only transcript for the trial. Use the **Messages** button in the conversation header to open the raw message view. Reviewers with `modify-evals` permission can add response-level feedback directly on assistant messages: - **Thumbs up** marks a response as useful or correct. - **Thumbs down** marks a response as problematic and opens the feedback reason dialog. - **Feedback** adds a precise reviewer note to that specific assistant response. - **Voice** plays the assistant response audio from the footer button that appears after **Feedback**. The same response-level controls are also available in the **Human Review** tab, where the feedback summary, response navigation, and exact assistant responses stay visible together for deeper review. ### Grading Results Shows grader verdicts, scores, explanations, and any normalized grounded evidence captured from the trial conversation once grading completes. ### Outcome Structured output produced by the agent for deterministic checks. ### Human Review Record a manual verdict and notes (requires `modify-evals` permission). The tab also shows an interactive **Conversation feedback** section with the same thumbs, feedback, and voice controls used in the transcript view. ## Related dialogs - [Create or edit an eval task](#doc-evals-dialogs-eval-task-editor) - [Human review an eval turn](#doc-evals-dialogs-human-review) --- # Graders The **Graders** tab is where you create reusable scoring rules for eval runs. ## What you’ll see - A table with **Name**, **Type**, **Tags**, and **Updated**. - Actions to **Edit**, **Duplicate**, or **Delete** each grader. - Toolbar actions to **Search**, **New grader**, and **Refresh**. ## Create a grader 1. Click **New grader**. 2. Choose a grader type: - **Deterministic (Outcome)** - **Transcript pattern** - **LLM rubric** - **Multi-grader** - **Tool use** 3. Fill in the configuration fields for the selected type. 4. Click **Create**. See [Create or edit a grader](#doc-evals-dialogs-grader-editor) for details. ## Grader actions - **Edit** updates the grader metadata and configuration. - **Duplicate** creates a copy with “(copy)” appended. - **Delete** removes the grader; update any tasks or runs that referenced it. ## Tips - Use descriptive tags (for example, `security`, `tone`, `correctness`) to find graders quickly. - Combine multiple graders with a **Multi-grader** to balance deterministic and rubric scoring. - Use a **Tool use** grader to enforce call counts, call order, output schemas, and error-free execution for tool-driven workflows. ## Related dialogs - [Create or edit a grader](#doc-evals-dialogs-grader-editor) - [LLM Judge Configuration](#doc-evals-dialogs-llm-judge) --- # Reports The **Reports** tab aggregates reliability metrics across runs so you can compare results and spot regressions. ## Run selection - Use **Select runs** to choose one or more runs for aggregation. - Selected runs appear as badges below the selection controls. - A selected-run coverage summary shows pass, grade, review, no-pass-yet, needs-review, and evidence-risk posture across the runs currently selected for reporting. - **Compute metrics** generates pass@k, pass^k, and success rates for each run. - **Save metrics** (manage permission required) stores metrics on the run for future access. See [Select eval runs](#doc-evals-dialogs-select-eval-runs). ## Metrics overview - **Aggregated summary** shows overall totals and success rates across selected runs. - **Comparison charts** visualize success rate, pass@k, pass^k, and average scores when multiple runs are selected. - **Missing metrics** callouts show which runs still need computation. ## Tips - Compute metrics for a baseline run and a new run to compare improvements. - Use consistent run names so charts are easy to interpret. ## Related dialogs - [Select eval runs](#doc-evals-dialogs-select-eval-runs) --- # Evals settings Use the **Evals → Settings** tab to manage the defaults that power AI task generation, import prompts, and user simulation. ## Open the settings tab 1. Navigate to **Evals**. 2. Click **Settings** in the top tab bar. ## Settings tabs The settings page is organized into three tabs: - **Task Generation** — model selection and task-generation prompt defaults. - **Imports** — prompt templates for conversation and Excel imports. - **User Simulator** — persona library for multi-turn simulations. ## Task generation defaults Configure how Gaia generates eval tasks: - **Task generation model**: Select the model used for AI task creation. Choose a generative or reasoning model that matches your workload. - **Task generation base prompt**: The system prompt template used to generate tasks. Leave it blank to use the built-in template. - **Additional instructions**: Optional instructions appended after the base prompt for all AI task generation flows. **Tip:** Use the default template as a baseline, then add extra instructions for your domain (for example, “focus on billing refunds and account upgrades”). ## Import prompt templates Tune the prompts used when Gaia converts existing data into tasks: - **Conversation import prompt**: Used when importing conversations marked for evaluation. - **Excel import prompt**: Used when turning spreadsheet rows into tasks. These prompts also receive any **Additional instructions** defined in the Task Generation tab. ## User simulator personas Personas shape the tone and behavior of multi‑turn user simulations. - **Persona library**: Review the current persona list with summaries. - **Add persona**: Create a new persona and edit its traits in the dialog. - **Edit persona**: Open an existing persona in the dialog to adjust its details. - **Restore defaults**: Replace the list with the built‑in preset personas at any time. Each persona includes: - **Name** and optional description/background - **Communication style** (verbosity, formality, technical level, casual expressions) - **Emotional state** (patience, confidence, urgency, optional initial mood) - **Behavioral traits** (clarification seeking, detail orientation, cooperativeness, risk tolerance, proactiveness) - **Knowledge level** (domain expertise, system familiarity, technical vocabulary) - Optional **common phrases** to inject into replies If a persona entry is missing required fields or has values outside the 0–1 range, the settings page will show validation errors before saving. ## Where these settings are used - **Eval Design Wizard** → AI task generation uses the selected model and prompt templates. - **Imports** → conversation and Excel imports use their respective prompt templates. - **User Simulator** editors in tasks use the persona list to pick behavior profiles. --- # Eval Design Wizard Use the **Eval Design Wizard** to create evaluations through a guided step-by-step process. The wizard helps non-technical users define and configure evaluations without writing code or JSON files. ## Opening the Wizard 1. Navigate to **Evals → Datasets**. 2. Click **New Evaluation** in the toolbar. Alternatively, from the **Datasets** page, click **Create with AI** to start the wizard with AI-powered task generation options. ## Reuse an Eval design template An **Eval design template** stores reusable wizard choices without storing generated tasks, runs, or uploaded file contents. 1. Configure the wizard, then click **Save as template**. 2. Add a name and optional description. 3. In a later wizard session, use **Start from template** to load those choices into a fresh draft. 4. Change any agent, source, rubric, grader, dataset, or run option before generating tasks. Applying a template never generates tasks or starts a run automatically. Use **Update template** to replace the selected template with the current choices, or **Delete template** to remove only the saved template. Existing datasets and runs are not affected. Templates retain project-resource references such as agents, configurations, graders, document folders, and selected conversations. Gaia warns when a referenced resource is no longer available. For uploaded files and Excel sources, select the file again after applying the template. ## Wizard Steps ### Step 1: Select Agent/Skill Choose the target agent and configuration to evaluate. - **Agent** — Select from agents defined in your project. - **Configuration** — Pick a specific configuration version to test. - The wizard displays agent capabilities and available tools. ### Step 2: Evaluation Type Select the type of evaluation to perform: | Type | Description | | ------------------ | --------------------------------------------------------------------- | | **Task Success** | Measures whether the agent completes specific tasks correctly | | **Tool Use** | Validates that the agent uses the right tools with correct parameters | | **Conversational** | Evaluates multi-turn dialogue quality and coherence | | **Security** | Tests for prompt injection, jailbreaks, and policy violations | | **Custom** | Define your own evaluation criteria | ### Step 3: Dataset Source Choose how to populate your evaluation dataset: #### Upload File Upload a CSV, TSV, or JSONL file containing evaluation tasks. - Supported formats: CSV, TSV, JSONL - Auto-detection of column mappings - Preview imported rows before confirming #### Use Existing Dataset Select from previously created task sets in your project. #### Create Manually Add individual tasks using the built-in task editor. - Optionally configure a **User Simulator** to drive multi-turn user behavior. #### Document folders When you create a new dataset in the wizard, you can attach shared **Document folders** in the dataset step. - These attachments are copied to every task created by that wizard run, including uploaded, manual, conversation-derived, AI-generated, and Excel-derived tasks. - Use this when the eval should search the same user-created knowledge folders that your agent already relies on. - Attached folders keep their existing indexing lifecycle. If a folder is still pending, indexing, or in error, Gaia will stop the eval run from starting until that folder is ready. #### AI-Powered Options ##### Eval task generation wizard (AI Task Generation) When you pick an AI-powered source, the wizard shows a shared **AI Task Generation** panel so you can control how tasks are created. - **Language** — Sets the language for generated tasks and trial execution. - **Task generation model** — Choose the model used to draft tasks (defaults come from **Evals → Settings**). - **New Task Set Name** — Required for AI-generated tasks so they can be stored in a dataset. - **New Task Set Path** — Optional folder path for the new dataset. - **Generate user simulator** — Optionally ask AI to draft multi-turn user behavior rules. - **Generate Tasks** — Runs the AI generation and opens the preview panel. **Import from Conversations** 1. Select conversations previously marked "for evaluation" in the Conversations grid. 2. The wizard lists available conversations with message counts and dates. 3. Select one or more conversations to import. 4. Choose the **Language** to generate tasks and to set the trial language when you start a run. 5. Select the **Task generation model** (optional). 6. Enter a **New Task Set Name** (required) and optional path. 7. Click **Generate Tasks** to create eval tasks with AI-filled parameters. 8. Review and edit the generated tasks before proceeding. **Generate from AI Prompt** 1. Describe what you want to test in the prompt field (e.g., "Generate 10 tasks testing customer refund handling"). 2. Set the number of tasks to generate (1-20). 3. Choose the **Language** to generate tasks and to set the trial language when you start a run. 4. Select the **Task generation model** (optional). 5. Enter a **New Task Set Name** (required) and optional path. 6. Click **Generate Tasks** to create AI-powered eval tasks. 7. Review the generated tasks and edit as needed. **Import from Excel** 1. Upload an Excel file (.xlsx, .xls) with request/response pairs. 2. Name the spreadsheet columns so the wizard can detect them automatically: - `request` (required), or the aliases `prompt` and `question` - `response` (optional), or the aliases `answer` and `expected` - `context` (optional), or the alias `background` 3. Preview the parsed data. 4. Choose the **Language** for generation. 5. Select the **Task generation model** (optional). 6. Enter a **New Task Set Name** (required) and optional path. 7. Click **Generate Tasks** to enhance rows with AI-filled evaluation parameters. 8. Review and finalize the tasks. Column names must use one of the supported spellings shown by the wizard. Unsupported columns are ignored, and the wizard lists their headers after upload. For example, a `comments` column is not imported; rename it to `context` when it contains background information relevant to the task. #### What the context column does Use `context` for facts, constraints, or starting state that the assistant needs to handle the request correctly. Gaia appends it to the first user message under a `Context:` heading, so the assistant can see it. Do not put a hidden expected answer or private grading notes in this column; use `response` for the ideal reference answer and the task's success criteria for grading rules. For example: | request | response | context | | ---------------------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | | How can I return order 1842? | Explain the return steps and mention the 30-day return window. | Order 1842 was delivered 10 days ago; the customer is verified and the item is unopened. | This produces an initial user message equivalent to: ```text How can I return order 1842? Context: Order 1842 was delivered 10 days ago; the customer is verified and the item is unopened. ``` `context` does not make the task multi-turn. Without a user simulator, the trial ends after the first assistant response. To test follow-up questions or changing user behavior, enable **Generate user simulator**; Gaia then generates the separate simulator configuration that can provide later user turns. ### Step 4: Scoring Rubric + LLM Judge Define how trials will be scored. A **rubric** is the scoring rulebook for each trial. - **Rule-Based** — Deterministic checks against structured outcome fields (equals, contains, regex). - **LLM-Based** — An AI model scores the trial using a rubric prompt and optional dimensions. The rubric is applied only when the LLM Judge is enabled. - **Hybrid** — Runs both deterministic checks and LLM-based scoring. - **Pass threshold** — Set the minimum score required for a trial to pass. When you use an LLM-based or hybrid rubric, you can also configure the LLM Judge in the same step: - **Enable LLM Judge** — Toggle automated rubric scoring. - **Output format** — Choose score-only or score with justification. ### Step 5: Additional Graders (Optional) Select reusable graders created in **Evals → Graders**. These graders run regardless of whether the LLM Judge is enabled. ### Step 6: Review & Create Confirm your evaluation configuration: - Review all settings across previous steps. - Edit any section by clicking its step indicator. - Optionally start a run immediately after creation. - Click **Create Evaluation** to finalize. ## Generated Task Preview When using AI-powered task generation, the wizard displays a preview of generated tasks: - **Title** — Auto-generated task title (editable) - **Description** — What the task tests - **Type** — Classification of the eval task - **Difficulty** — Easy, medium, or hard - **Input** — The prompt to send to the agent - **User Simulator** — Optional multi-turn user behavior rules - **Success Criteria** — Conditions for passing - **Reference Solution** — Expected ideal response (if available) - **Expected Tools** — Tools the agent should use (if applicable) Click any task to expand and edit its details. You can also remove tasks before proceeding. ## Real-life example > A trust and safety team uses the wizard to generate 25 security tasks, adds an LLM Judge rubric for policy compliance, and starts a run immediately to validate a new agent version. ## Tips - Start with a small dataset (5-10 tasks) to validate your setup. - Use AI generation for initial task ideas, then refine manually. - Combine multiple data sources by using the wizard multiple times and merging into one dataset. - Enable LLM Judge for subjective quality criteria that can't be checked deterministically. - Use shared **Document folders** when many tasks should reuse the same project knowledge source instead of editing each task individually later. - Save a stable generation and grading setup as an **Eval design template**, then change only the dataset name or the choices needed for the next regression cycle. ## Requirements - **modify-evals** permission required to create evaluations. - At least one agent and configuration must exist in the project. --- # Create or edit a dataset Use the **New dataset** and **Edit dataset** dialogs to manage dataset metadata. ## Open the dialog - **New dataset:** In **Evals → Datasets**, click **New dataset**. - **Edit dataset:** Hover a dataset row and click the pencil icon. ## Fields - **Folder** — Select an existing folder or enter a custom path. - **Name** — Dataset name shown in the tree and runs. - **Description** — Optional context for the dataset. - **Tags** — Keywords for filtering and grouping. ## Save - **Create** adds the dataset to the tree. - **Save** updates the dataset and keeps existing tasks. ## Tips - Keep folder paths consistent (for example, `security/regression`). - Tags are shared with task tags, so reuse them for consistent filtering. ## Requirements - **modify-evals** permission required. --- # Create or edit an eval task Use the **Eval Task** dialog to create, edit, or view a task in a dataset. ## Open the dialog - **New eval task:** Inside a dataset, click **New eval task**. - **Edit:** Click the pencil icon on a task row. - **View:** Open a trial and click **View Task**. ## Tabs ### Task Info - **Title** (required) - **Type** (conversational, tool-using, coding, workflow-backed, other) - **Difficulty** (optional) - **Tags** Selected tags appear as removable chips. Use the `x` on a chip to remove it. When many tag options exist, the dropdown shows a scroll hint so it is clear more tags are available. - **Description** - **Prompt** (required) - **Context** (optional constraints or background) - **Document folders** Attach task-scoped document folders when the eval should inherit the same knowledge-folder search and retrieval surfaces as an agent configuration. Each attachment stores the folder plus its mode (`Important` or `Fallback`). ### Tools Select tools the agent is expected to use during the task. ### User Simulator Define a simulated user behavior for multi-turn scenarios. #### Deterministic (rule-based) Deterministic simulators use **pattern matching** against the agent message. - **Default behavior:** case-insensitive _contains_ match. - **Prefixes:** - `exact:` — full-string match - `contains:` — substring match - `regex:` — regular expression match Example conditions: - `contains:order id` - `exact:yes` - `regex:order\s+#?\d+` You can also configure: - **No match behavior** (terminate or continue with a default response) - **Fail on premature action** (keywords that indicate the agent acted too early) - **Max turns** for the simulated interaction #### LLM-based (semantic) LLM-based simulators choose a rule using semantic matching rather than strict patterns. - Use natural language in the **Condition** field (e.g., “asks for billing address”). - Configure **Model ID**, **Temperature**, and an optional **System Prompt** to guide matching. - If no model is set, the system uses the default generative model. LLM-based matching consumes tokens and may be slower than deterministic rules. ### Success Criteria Use one of three modes to define pass/fail criteria for the task. #### Deterministic checks Validate structured outcome data using weighted checks. - Set a **Pass threshold** between `0.0` and `1.0`. - Add checks with: - **Path** (dot notation into the outcome payload) - **Operator** (equals, not equals, contains, regex match, exists, etc.) - **Expected value** - **Weight** - Use this mode when success can be validated from deterministic output fields. #### Transcript patterns Validate behavior directly in conversation transcripts. - Set a **Pass threshold** between `0.0` and `1.0`. - Add **Required patterns** that must appear. - Add **Forbidden patterns** that must not appear. - Add **Sequence requirements** to enforce ordered behavior (one pattern per line). - For each pattern, optionally scope to **User**, **Assistant**, or **Any role**, and enable **regex** matching. #### LLM rubric Define task-specific, qualitative criteria that are evaluated by an LLM. - Add a **Rubric prompt** that explains exactly how this task should be judged. - Set **Pass threshold**, and choose a model via the shared **Model** selector (with optional advanced tuning). - Control context with **Include task**, **Include transcript**, and **Include outcome** toggles. - Optionally add weighted **Dimensions** (name, description, weight) for structured scoring. ## Save - **Create Task** adds the task to the dataset. - **Save Task** updates the existing task. ## Tips - Keep prompts short and specific; use **Context** for background details. - Use **Document folders** for task-specific knowledge that should apply only during eval execution, instead of editing the shared agent configuration. - Add success criteria early to keep grading consistent. ## Requirements - **modify-evals** permission required to create or edit tasks. --- # Create or edit a grader Use the **New Grader** and **Edit Grader** dialogs to configure reusable grading rules. ## Open the dialog - **New grader:** In **Evals → Graders**, click **New grader**. - **Edit:** Click the pencil icon on a grader row. ## Core fields - **Name** and **Description** - **Type** (Deterministic, Transcript pattern, LLM rubric, Multi-grader, Tool use) - **Tags** (comma-separated) ## Configuration by type ### Deterministic (Outcome) - Add outcome checks with **path**, **operator**, and **expected** value. - Set a **Pass threshold** between 0 and 1. ### Transcript pattern - Add **required** and **forbidden** patterns. - Choose the **role** (assistant, user, or any) and whether the pattern is **regex**. - Set a **Pass threshold** between 0 and 1. ### LLM rubric - Provide a rubric prompt and scoring dimensions. - Choose the model and temperature. - Configure output format and caching. See [LLM Judge Configuration](#doc-evals-dialogs-llm-judge) for full details. ### Multi-grader - Choose a strategy (**all**, **any**, **majority**, or **weighted**). - Select graders to combine and optional weights. ### Tool use - Select each expected capability from the project tool registry or the project's agents. An agent that is configured as a tool is matched by its stable agent identity. - Registry-tool choices show their saved version so similarly named versions can be distinguished. - Set **Min calls** and **Max calls** to enforce the expected call count. - Choose whether checks must pass for **every matching call** or for **any matching call**. - Add argument and output field checks when individual values must match. - Add an **Output JSON Schema** (JSON Schema Draft 7) to validate the complete result shape. - Choose **Exact sequence** to require only the displayed tool sequence, or **Ordered subsequence** to allow other calls between the expected steps. Reorder the tool cards to change the expected sequence. - Keep the runtime validity checks enabled to require a completed trial, a result for every tool call, and no returned error, exception, unsuccessful flag, or failed status. - Enable **Strict tool set** when calls to tools outside the configured set should reduce the score. ## Save - **Create** adds the grader to the registry. - **Save** updates the existing grader. ## Requirements - **modify-evals** permission required. --- # Select eval runs Use the **Select eval runs** dialog to choose which runs appear in reports. ## Open the dialog 1. Navigate to **Evals → Reports**. 2. Click **Select runs**. ## Select runs - Use the checkbox column to pick runs. - The header checkbox selects or clears all runs. - Each row shows run name, status, dataset scope, trials per task, task-level coverage cues, and whether metrics are stored or computed. - Coverage cues show pass coverage, review coverage, gap-task count, and evidence-risk count so you can choose runs without opening each run first. - Use the eye icon to open a run in a new tab. ## Finish - Click **Done** to apply your selection. - Use **Clear selection** to reset the list. --- # Manage eval folders Folders keep large eval libraries organized. Use the **New folder** dialog to create paths for grouping datasets. ## Create a folder 1. In **Evals → Datasets**, click **New folder**. 2. Select a **Parent folder** (or keep **Root**). 3. Enter the **Folder name** (for example, `security` or `regression/core-app`). 4. Click **Create folder**. The tree updates immediately. ## Delete a folder and its contents 1. In the dataset tree, click the trash action on the folder. 2. Review the confirmation counts for datasets, tasks, and nested folders. 3. Click **Delete folder**. Deleting a folder permanently removes all descendant datasets and tasks. Completed historical run results are retained, but their task links are cleared. Gaia blocks deletion while an affected eval trial is pending, running, paused, or stopping; stop those trials and try again. Folder matching follows path boundaries. Deleting `release` includes `release/security`, but does not delete `release-old`. ## Real-life example > After splitting regression datasets by product area, the QA lead created `regression/core-app` and `regression/add-ons`. The updated structure made it easier to trigger targeted runs. ## Tips - Use the optional parent path field to create nested folders in one step. - Stick to lowercase and hyphenated names when integrating with automated scripts. - Use prefixing (for example, `security/`, `quality/`, `load-testing/`) to group similar datasets. ## Troubleshooting - **Name already in use:** Choose a unique path. Folder names must be unique within the same parent. - **Create option missing:** Ensure you have **modify-evals** permission. --- # Start an eval run Use **Start Eval Run** to configure the dataset scope, graders, and execution limits before launching a run. ## Run Info tab 1. Open **Evals -> Datasets** and click **Run** (or open **Evals -> Runs** and click **Start run**). 2. Review the generated **Run name** and add optional notes. Gaia uses the selected dataset, saved subset, or individual task name plus a timestamp so runs are recognizable in lists. 3. Choose a **Dataset scope**: - **Task set** (pick a dataset) - **Folder** (run all datasets under a folder) - **Specific task(s)** (paste task IDs) 4. Select the **Configuration** (agent/config) and set **Trials per task (k)**. New runs default to the active configuration of the project's Orchestrator agent. If the Orchestrator has no active configuration, select one explicitly. ## Graders tab - Select one or more graders from the registry. - If you pick multiple graders, choose a combination strategy (all/any/majority/weighted). - Choose a **Final verdict policy**: - **Combine graders with task criteria** (recommended): run-level graders and task-level success criteria are merged into one final trial outcome. - **Use graders only**: ignore task success criteria for final verdict. - **Use task criteria only**: ignore run-level graders for final verdict. ## Limits tab (optional) - Enable limits to cap max turns, max tokens, or timeout seconds per trial. Gaia enforces these limits during background execution so one slow or looping trial does not block the rest of the run indefinitely. ## Launch - Click **Start Run** to create the run, queue background execution, and open **Run Details**. ## Real-life example > A QA lead starts a run with k=1 and strict token limits to basic-check a new dataset, then reruns with a larger k once the first results look good. ## Tips - Starting a run from a dataset or task row pre-fills the dialog and locks the scope. - Starting a run from a filtered dataset task list pre-fills the matching task IDs as a locked subset. - Starting from **Rerun Failed**, **Rerun Partial**, or **Rerun Unreviewed** on run details also locks the task scope and shows which subset was selected before launch. - Starting from **Rerun No Pass Yet** or **Rerun Needs Review** on run details does the same, but uses queue-style task slices generated from the current run state. - Starting from **Run Again** or a rerun action on run details also links the new run back to the source run so the rerun can show baseline comparison after it finishes. - Use a small k (1-2) for basic checks, then increase for reliability metrics. - Large runs continue in the background after launch. Use **Run Details -> Resume** if a run still has pending work and needs to be re-queued. - If the selected tasks or configuration attach document folders, make sure those folders are fully indexed first. Gaia blocks run creation until attached folders are `Ready`. ## Troubleshooting - **Start button disabled:** Ensure you selected a dataset scope and filled the run name. - **No graders available:** Add graders in **Evals -> Graders**, then retry. - **Run creation blocked by document folders:** Open the referenced folder and wait for indexing to finish, or remove the folder attachment from the task/config before retrying. --- # Import tasks Bulk import task definitions from CSV or JSON so you can maintain datasets outside Gaia and bring them back in quickly. ## When to use it - You manage eval datasets in spreadsheets or external tools and need to sync them into Gaia. - You exported past runs, edited them offline, and want to reimport with corrections. - You’re collaborating with subject-matter experts who prefer working in CSV. ## Import steps 1. Open **Evals → Datasets** and click **Import datasets** (or use **Import** inside a dataset). 2. Select the destination task set, or enter a **New eval task set path/name** to create one on import. 3. Choose a **Format** (Auto/JSON/CSV) if you want to override auto-detection. 4. Upload a file or paste JSON/CSV content. 5. Click **Import**. The dialog closes and new tasks appear in the selected task set (or unassigned). ## Real-life example > A trust & safety analyst curated 50 new jailbreaking prompts in Google Sheets. She exported them as CSV, imported through this dialog, and instantly ran them against the staging agent to verify nothing slipped through. ## Tips - Use column headers such as `title`, `prompt`, `context`, `tags`, `type`, `difficulty`, `successCriteria`, and `expectedTools`. - Use `knowledgeFolders` or `documentFolders` when imported tasks should carry document-folder retrieval. Provide either a JSON array of `{ folderId, mode }` objects or a comma-separated list of folder IDs. Comma-separated IDs default to `Important` mode. - For quick prompt lists, you can also import a single-column CSV with no header. Gaia treats each row as a prompt and derives the task title automatically. - Include metadata such as severity or category in tags to make runs easier to filter later. - Test with 2–3 rows first to ensure formatting is correct, then upload the full file. ## Troubleshooting - **Validation errors:** Ensure each task has a title or prompt and valid JSON for nested fields. Fix malformed JSON and retry. - **File rejected:** Ensure it’s UTF-8 encoded and under your organization’s size limit. - **Imported items missing:** Confirm you selected the right task set; unassigned imports stay outside datasets. - **Run will not start after import:** If imported tasks attach document folders, wait for those folders to finish indexing before starting the eval run. --- # Generate security tasks Use this dialog to seed your **Evals v2** task sets with curated adversarial prompts covering prompt injection, data leakage, and policy evasion scenarios. ## When to run it - You’re introducing a new agent or tool and want baseline security coverage. - You need regression cases after fixing a vulnerability. - Compliance requires proof that you test for risky behaviors. ## Who can run it? Project admins and any user with eval creation permissions. ## Generate the evals 1. In **Evals → Datasets**, open the task set you want to enrich. 2. Click **Generate security tasks** in the task set toolbar. 3. Pick a generation mode: - **Templates** (curated selection) - **Categories** (counts per category) - **OWASP** (risk-based presets) 4. (Optional) Adjust per-category counts for single-turn or multi-turn tasks. 5. (Optional) Keep **Skip existing tasks** enabled to avoid duplicates. 6. Click **Generate**. The dialog adds tasks directly to the open task set. ## Real-life example > After connecting an internal CRM tool, the security team opened their `security/regression` task set and generated the “DataPrivacy” and “UnauthorizedAccess” tasks. They run this dataset nightly to catch regressions and share results with their compliance lead. ## Tips - Keep security datasets separate (for example, in folders prefixed with `security/`) so you can filter them during runs. - Combine generated tasks with your own edge cases using [Import tasks](#doc-evals-dialogs-import-candidates). - Use the **Templates** tab for curated basic coverage or the **OWASP** tab to align with a standard risk checklist. ## Troubleshooting - **Button missing:** Confirm you’re inside a task set and have the necessary permissions. - **Generation failed:** Retry once. If it still fails, capture the error message and contact an admin. --- # LLM Judge Configuration Use the **LLM Judge** to automatically score evaluation trials using an AI model. The LLM Judge applies a rubric you define and produces consistent, explainable scores. ## Accessing the LLM Judge Editor 1. Navigate to **Evals → Graders**. 2. Click **New grader** and select **LLM rubric** as the type. 3. Configure the judge settings in the editor. Alternatively, enable LLM Judge during the Eval Design Wizard (Step 5). ## Configuration Tabs ### Rubric Tab Define the scoring criteria: **Rubric Prompt** Enter instructions for the AI grader. This prompt tells the model how to evaluate responses. Example: ``` Evaluate the assistant's response for accuracy, helpfulness, and professional tone. Consider whether all user questions were addressed and if the information provided is correct. ``` **Scoring Dimensions** Add one or more dimensions to score: | Field | Description | | ---------------- | ----------------------------------------------- | | **Name** | Short identifier (e.g., "accuracy", "tone") | | **Description** | What this dimension measures | | **Weight** | Relative importance (weights should sum to 1.0) | | **Good example** | Optional example of a high-scoring response | | **Bad example** | Optional example of a low-scoring response | Click **Add Dimension** to create new dimensions. Use the × button to remove. ### Model Tab Configure the AI model: - **Model** — Select from available AI models (GPT-4 recommended for accuracy). - **Temperature** — Set between 0.0 (deterministic) and 1.0 (creative). Lower values produce more consistent scores. ### Output Tab Choose what the judge returns: | Format | Description | | ---------------------------- | --------------------------------------------- | | **Score only** | Returns just the numeric score | | **Score with justification** | Returns score plus explanation | | **Detailed dimensions** | Returns per-dimension scores and explanations | ### Caching Tab Control score reproducibility: - **Enable caching** — Store scores to ensure the same input produces the same output. - **Cache TTL** — How long cached scores remain valid (in hours). Caching is recommended for regression testing where you need consistent baselines. ## Input Options Choose what context the LLM Judge receives: | Option | Description | | ---------------------- | -------------------------------------------------- | | **Include task** | Send the task definition (input, success criteria) | | **Include transcript** | Send the full conversation transcript | | **Include outcome** | Send structured output from the agent | Enable all three for comprehensive evaluation. Disable some to reduce token usage. ## Pass Threshold Set the minimum score (0.0-1.0) for a trial to pass. The final score is computed as: ``` Final Score = Σ (dimension_score × dimension_weight) ``` If the final score meets or exceeds the threshold, the trial passes. ## Using Templates The editor provides template buttons for common rubric patterns: - **Accuracy** — Factual correctness and precision - **Helpfulness** — User goal achievement - **Tone** — Professional and appropriate language - **Completeness** — All aspects addressed - **Safety** — No harmful or inappropriate content Click a template to add its dimension to your rubric. ## Viewing Results After a run completes, LLM Judge results appear in: 1. **Trial Details → Grading Results** — Expand the LLM rubric grader to see: - Overall score and verdict - Per-dimension scores - Justification text (if enabled) - Grounded evidence references when the trial used cited folder-backed retrieval 2. **Unified Result Viewer** — Aggregate LLM Judge scores across all trials: - Score distribution histograms - Dimension-level breakdowns - Trend comparisons across runs ## Real-life example > An evaluation lead adds a "tone" dimension with weighted scoring, enables caching, and uses the judge to compare politeness across two agent configurations. ## Best Practices - **Start specific** — Vague rubrics produce inconsistent scores. Be explicit about what constitutes good/bad responses. - **Use examples** — Providing good/bad examples significantly improves scoring accuracy. - **Weight appropriately** — Assign higher weights to dimensions that matter most for your use case. - **Enable caching** — For reproducible results in regression testing. - **Use lower temperature** — 0.0-0.3 produces more consistent scores. - **Validate manually** — Spot-check LLM Judge scores against human reviews to calibrate. ## Troubleshooting - **Scores too lenient/strict** — Adjust the rubric prompt to be more specific about expectations. - **Inconsistent scores** — Lower the temperature and enable caching. - **Missing dimension scores** — Ensure the model supports structured output (JSON mode). - **Slow grading** — Consider using a faster model for large datasets, then validate samples with GPT-4. ## Requirements - **modify-evals** permission required to create and edit graders. - At least one AI model must be configured in platform settings. --- # Agent Behavior Trace Viewer Use the **Agent Behavior Trace Viewer** to visualize the observable decision process of an agent during an evaluation trial. This helps debug failures and understand the messages, summaries, tools, handoffs, and evaluator-visible steps that shaped a run. ## Accessing the Trace Viewer 1. Navigate to **Evals → Runs**. 2. Open a completed run by clicking the eye icon. 3. Click **View** on any trial row. 4. Select the **Trace** tab in the trial details. ## Understanding the Timeline The trace viewer displays agent behavior as a vertical timeline with the following step types: ### User Messages Shows input from the user or simulator with: - Message content - Timestamp - Any attached context or files ### Assistant Messages Displays the agent's responses including: - Text content - Reasoning summaries or visible step notes, if the run data includes them - Time taken to generate ### Tool Calls Visualizes each tool invocation: | Field | Description | | ------------- | ---------------------------------------------------- | | **Tool name** | The function or service called | | **Arguments** | Parameters passed to the tool (expandable JSON) | | **Result** | What the tool returned | | **Duration** | Execution time in milliseconds | | **Status** | Success (✓) or failure (✗) with error message | | **Type** | Function, MCP, agent handoff, webservice, or builtin | ### Agent Handoffs When control passes between agents: - **From agent** — The agent transferring control - **To agent** — The agent receiving control - **Reason** — Why the handoff occurred - **Timestamp** — When the transfer happened ### Reasoning Summaries And Visible Steps The trace viewer can show provider-supplied reasoning summaries, protocol stage notes, tool decisions, and evaluator-visible step labels when those are part of the run data. Gaia does not expose hidden raw chain-of-thought. Use this trace as evidence for reasoning transparency through summaries, decisions, tools, handoffs, timings, and evaluation outcomes. ## Filtering and Navigation ### Step Type Filter Use the dropdown to show only specific step types: - All steps - User messages only - Assistant messages only - Tool calls only - Errors only ### Expand/Collapse - Click the chevron (▶) on any step to expand details. - Use **Expand All** to see everything at once. - Use **Collapse All** to get the overview. ### Jump to Step Click any step in the mini-timeline at the top to jump directly to that position. ## Identifying Issues The trace viewer highlights potential problems: ### Failed Tool Calls Red border and ✗ icon indicate tools that returned errors. Expand to see: - Error message - Stack trace (if available) - Arguments that may have caused the failure ### Slow Steps Yellow highlight on steps exceeding expected duration. Check: - Network latency for external calls - Complex computations - Model response time ### Missing Expected Steps If an evaluation expects certain tool usage, missing tools appear as grayed-out entries in the expected sequence. ## Linking to Eval Dimensions When viewing a trial with dimension-based grading: 1. Hover over any grading dimension in the **Grading Results** tab. 2. Related trace steps highlight in the timeline. 3. Click a dimension to filter the trace to relevant steps. This helps understand which agent behaviors contributed to specific scores. ## Exporting Traces Click **Export** to download the trace as: - **JSON** — Full structured data for programmatic analysis - **Markdown** — Human-readable format for documentation - **PDF** — Formatted report with diagrams ## Real-life example > An engineer sees a trial fail, opens the trace, and finds a malformed tool argument. They fix the tool schema and rerun the eval to confirm the error disappears. ## Tips - **Start with errors** — Filter to "Errors only" to quickly find what went wrong. - **Check tool arguments** — Many failures come from malformed tool inputs. - **Compare traces** — Open two trials side-by-side to spot differences in behavior. - **Look for loops** — Repeated tool calls may indicate the agent is stuck. - **Check handoff reasons** — Ensure agents transfer control for the right reasons. ## Troubleshooting - **Trace empty** — The trial may not have completed, or the conversation had no tool calls. Check the Conversation tab for raw messages. - **Missing reasoning summaries** — Not all models expose reasoning summaries or visible step notes. Use models and protocols that produce supported summary fields when you need this evidence. - **Steps out of order** — Timestamps may be missing for older trials. Sort by message index instead. ## Requirements - **view-evals** permission required to view traces. - Trial must be in a completed state (passed, failed, or stopped). --- # Promote Conversation to Eval Use the **Promote to Eval** feature to convert real conversations into structured evaluation tasks. This captures authentic user interactions for regression testing and quality assurance. ## Marking Conversations for Evaluation Before promoting, mark conversations as evaluation candidates: 1. Navigate to **Conversations** in your project. 2. Find a conversation you want to use for evaluation. 3. Click the **⋮** menu on the conversation row. 4. Select **Mark for evaluation**. Alternatively, open a conversation and click the **Mark for Eval** button in the header. Marked conversations display a beaker icon (🧪) in the grid. ## Promoting a Single Conversation 1. From the Conversations grid, click the **⋮** menu on a marked conversation. 2. Select **Promote to Eval**. 3. The promotion dialog opens with pre-filled information. ### Dialog Fields | Field | Description | Auto-filled from | | ---------------------- | -------------------------- | ---------------------------------- | | **Task Title** | Name for the eval task | Conversation title | | **Description** | What this task tests | AI-generated from content | | **Task Set** | Target dataset | Select from existing or create new | | **Input Prompt** | The user's request | First user message | | **Reference Solution** | Expected response | Last assistant message | | **Expected Tools** | Tools the agent should use | Tools called in conversation | | **Success Criteria** | How to determine pass/fail | AI-suggested criteria | | **Eval Type** | Task classification | Detected from conversation | | **Difficulty** | Easy/medium/hard | AI-estimated | | **Tags** | Categorization labels | Editable | ### Editing Auto-Filled Values All fields are editable: 1. Click any field to modify its value. 2. Use the **Reset** button to restore the auto-filled value. 3. Add or remove tags using the tag input. 4. Adjust success criteria to match your requirements. ### Creating the Task 1. Review all fields. 2. Select or create the target task set. 3. Click **Create Eval Task**. 4. The task is added to the selected dataset. ## Batch Promotion Promote multiple conversations at once: ### From Conversations Grid 1. Use the checkbox column to select multiple conversations. 2. Click **Promote to Eval** in the bulk actions bar. 3. The wizard opens with all selected conversations listed. ### From Eval Design Wizard 1. Open the Eval Design Wizard (**Evals → Datasets → New Evaluation**). 2. In Step 3 (Dataset Source), select **Import from conversations**. 3. The panel displays all conversations marked for evaluation. 4. Check the conversations to include. 5. Click **Generate Tasks** to create eval tasks with AI assistance. 6. Review and edit each generated task. 7. Continue through the wizard to create the evaluation. ## AI-Assisted Parameter Filling When promoting conversations, AI analyzes the content to suggest: - **Task type** — Conversational, code-generation, Q&A, etc. - **Difficulty level** — Based on complexity and turn count - **Success criteria** — Derived from the actual conversation outcome - **Tags** — Relevant categorization based on content analysis The AI uses: - The user's initial request - The assistant's final response - Tools that were called - Number of conversation turns - Overall conversation flow ## Viewing Promoted Tasks After promotion: 1. Navigate to **Evals → Datasets**. 2. Open the target task set. 3. Find the promoted task in the task list. 4. The **Source** column shows "conversation" for promoted tasks. 5. Click the task to edit or view full details. ## Linking Back to Source Promoted tasks maintain a link to their source conversation: 1. Open a task in the task editor. 2. Click **View Source** in the task info tab. 3. The original conversation opens in a new tab. This helps investigate why a task was created and provides additional context. ## Real-life example > A support lead marks real customer refund chats for evaluation, promotes them into a "Refunds regression" dataset, and reuses the tasks after every agent update. ## Tips - **Choose representative conversations** — Select conversations that reflect common user scenarios. - **Verify success criteria** — AI suggestions may need adjustment based on your specific requirements. - **Use batch promotion** — Efficiently create large datasets from marked conversations. - **Tag consistently** — Use a standard tagging scheme for easier filtering later. - **Combine with manual tasks** — Mix promoted conversations with handcrafted edge cases. ## Troubleshooting - **No conversations available** — Ensure conversations are marked "for evaluation" in the Conversations grid. - **AI suggestions seem wrong** — The AI uses the conversation content; unusual or sparse conversations may produce poor suggestions. Edit manually. - **Cannot promote** — Verify you have `modify-evals` permission. - **Missing tools list** — The conversation may not have used any tools, or tool calls were not recorded. ## Requirements - **modify-evals** permission required to promote conversations. - **view-conversations** permission required to access source conversations. - Conversations must have at least one user message. --- # Human Review Use the **Human Review** features to manually evaluate trials, override automated grading, and collaborate with other reviewers. Gaia supports both individual trial review and batch review workflows. ## Individual Trial Review ### Submit a Review 1. Open a trial from **Evals → Runs**. 2. Select the **Human Review** tab. 3. Choose a decision: - **Pass** — The trial succeeded. - **Fail** — The trial failed. - **Needs review** — The result is unclear. 4. Add a rationale (required). 5. Optionally check **Override grader results** if your decision should supersede automated grading. 6. Click **Submit review**. ### Add Response-Level Feedback In the trial **Conversation** tab, reviewers with `modify-evals` permission can attach precise feedback to individual assistant responses: - Use **thumbs up** for responses that are correct or useful. - Use **thumbs down** for responses that are wrong, incomplete, unsafe, or otherwise problematic. - Use the **feedback** button to add a written note to that exact response. - Use the **voice** button after **feedback** when you want to replay the assistant response audio. The **Human Review** tab also exposes those same controls in the **Conversation feedback** section so the overall decision, rationale, grader evidence, and exact response-level feedback stay visible together while you continue reviewing. ### Update a Review If a review already exists, click **Edit review**, update the decision or rationale, and click **Update review**. ### View Grader Comparison When grader results exist alongside a human review: - The interface shows grader verdicts for comparison. - Agreement/disagreement is highlighted. - Grounded evidence references appear once per trial when the automated graders captured cited folder-backed evidence. - Each grounded evidence item now shows a short provenance trail so you can see how it entered the trial outcome, including whether Gaia resolved it from folder search or passage lookup and when it first appeared in the assistant conversation. - Gaia shows a shared evidence posture for the trial: - **Grounded** when every resolved citation includes excerpted evidence and source context. - **Mixed** when evidence exists but one or more citations are missing excerpt or source context. - **None** when no grounded evidence was resolved for the trial. - Use this to calibrate graders against human judgment. ## Run-level Review Queues Use the run details page to isolate the next review slice before opening individual trials. ### Accessing Evidence Queues 1. Navigate to **Evals → Runs**. 2. Open a run by clicking the eye icon. 3. Use the evidence queue buttons above the trials table. ### Queue Features | Queue | Description | | ------------------------- | ------------------------------------------------------------------------------------- | | **All Trials** | Show the full run without filtering. | | **Evidence Risk** | Combine trials with **None** or **Mixed** evidence posture. | | **No Evidence** | Focus on trials where Gaia resolved no grounded evidence. | | **Mixed Evidence** | Focus on trials with citations that are missing excerpt or source context. | | **Reviewer Disagreement** | Focus on trials where the saved human review decision differs from the automated one. | Each filtered row still exposes the same **View** action, so you can open the trial and complete the review from the **Human Review** tab. ## Custom Dimensions Define dimension-specific review criteria: ### Adding Dimensions When editing a task set or creating a grader: 1. Navigate to **Evals → Graders** or open a task set. 2. Add dimensions with: - **Name** — Dimension identifier (e.g., "accuracy", "helpfulness") - **Description** — What to evaluate - **Labeler instructions** — Specific guidance for reviewers - **Rating type** — Binary, scale, or multi-label ### Dimension Review During human review: 1. Each dimension appears as a separate section. 2. Provide ratings per dimension. 3. Overall decision is computed from dimension ratings. 4. Add dimension-specific notes if needed. ## Rating Types | Type | Description | Example | | --------------- | ---------------------------- | ---------------------------------------------- | | **Binary** | Yes/No decision | "Was the response accurate?" | | **Scale** | Numeric rating (1-5 or 1-10) | "Rate helpfulness from 1-5" | | **Multi-label** | Select all that apply | "Issues: [Incorrect] [Incomplete] [Off-topic]" | | **Freeform** | Text feedback | "Describe any problems" | ## Inter-Rater Statistics When multiple reviewers evaluate the same trials: ### Viewing Statistics 1. Navigate to **Evals → Reports**. 2. Select runs with multiple human reviewers. 3. Click **Inter-Rater Agreement**. ### Available Metrics | Metric | Description | | ------------------------ | --------------------------------------------- | | **Fleiss Kappa** | Agreement among multiple raters (0-1 scale) | | **Majority Vote** | Most common decision per trial | | **Agreement Rate** | Percentage of trials with unanimous decisions | | **Disagreement Details** | Trials where reviewers differed | ### Interpreting Kappa | Kappa Range | Interpretation | | ----------- | ------------------------ | | < 0.20 | Slight agreement | | 0.21 - 0.40 | Fair agreement | | 0.41 - 0.60 | Moderate agreement | | 0.61 - 0.80 | Substantial agreement | | 0.81 - 1.00 | Almost perfect agreement | ## Export and Import ### Export Reviews 1. From the run details page, click **Export**. 2. Leave **Include review data** enabled when exporting full JSON for error analysis. 3. Choose **Human Reviews CSV** to download reviewed trials as CSV, including the decision, rationale, reviewer, timestamp, automated verdict, grounded-evidence count, and compact response-level feedback summary. 4. Choose **Full Run JSON** when you need the complete run bundle with grader results, trial human reviews, precise response feedback, the normalized trial-level grounded evidence summary, the same evidence posture shown in Gaia, and the evidence provenance metadata captured from retrieval plus assistant citation lineage. ### Import Reviews 1. Prepare a CSV with required columns. 2. Click **Import Reviews** in the run details. 3. Map columns to fields. 4. Existing reviews can be overwritten or skipped. ## Real-life example > A reviewer batch-marks 30 trials as "Needs review," then opens the unclear cases individually to add detailed rationales that calibrate the LLM Judge. ## Tips - **Add detailed rationales** — Helps calibrate automated graders later. - **Start with Evidence Risk** — It is the fastest way to isolate trials that still need evidence-focused review. - **Review disagreements** — Focus on trials where graders and humans differ. - **Track Kappa over time** — Improving agreement indicates clearer guidelines. - **Use dimensions for complex criteria** — Break subjective quality into measurable components. ## Notes - You need **modify-evals** permission to submit or edit reviews. - Human reviews are stored alongside grading results for auditing and calibration. - Reviews with **Override grader results** checked take precedence in metric calculations. --- # View trial details Trial details show everything about a single task execution: the transcript, grading results, and outcome payloads. ## Open a trial 1. From **Evals → Runs**, open the run you’re interested in. 2. Click **View** on a trial row. 3. Use the tabs to explore: - **Conversation** (read-only transcript). - **Grading Results** (verdicts and explanations per grader). - **Outcome** (structured output used by deterministic checks). - **Human Review** (manual decision + rationale). 4. Use **View Task** to open the task definition in read-only mode. 5. Use **Messages** to open the full JSON message log (including tool calls and handoffs). ## Real-life example > When an eval run showed a spike in “Needs follow-up,” a product manager opened a trial and saw the grading results indicated missing compliance language. They updated the prompt and reran the eval to confirm the fix. ## Tips - Use the grading breakdown to pinpoint whether failures are due to missing content, incorrect tool calls, or rubric gaps. - Toggle **Inside Info** in the Conversation tab to see token usage, tool metadata, and any task context injected into the user prompt. - If the transcript is empty, confirm the run completed and refresh the trial. - Copy the trial URL to share with teammates for asynchronous debugging. --- # Governance Status: grouped workspace shell available with a package-backed registry, record-first governance workflows, and queue-based governance operations. This section documents the Governance workspace shell under `/projects/[projectId]/tools/governance`. Guided scenario: start with [Governed Application From Scratch](../../handbook/ch11-capstone-build-and-ship/05-governed-application-from-scratch.md). Optional in-product drill: open [Tutorials](/platform/support/tutorials) and use a governance walkthrough card to rehearse one slice. If governance is new to you, start with [Governance Foundations](#doc-governance-foundations) before diving into the individual tabs. Governance in Gaia is the operating layer that connects: - business context - agent and workflow design - controls and obligations - evidence and explainability - remediation and release readiness It should be used as part of the normal application lifecycle, not only at the end. If you want one scenario-driven walkthrough of how governance fits into the wider platform, start with [Governed application lifecycle](#doc-governance-governed-application-lifecycle). Governance now follows the same route-backed module pattern as the rest of Gaia: - top-level Governance pages appear as module tabs in the project header - each page can expose local governance subsection links for the detailed topics inside that page The workspace is organized into six route-backed sections: - `Overview` for current posture, open work, and cross-workspace watchlists - `Runtime` for orchestration boundaries, runtime policies, and the governance operations command center - `Catalog` for reusable framework packages, governed agent systems, and governed contracts - `Risk & Compliance` for risks, controls, obligations, classifications, and regulatory-change triage - `Evidence` for state and memory posture plus explainability and provenance links - `Discovery` for unmanaged-AI intake, validation, and onboarding The grouped shell now surfaces live governance records and route-backed operating surfaces across all six sections: - `Overview` summarizes the current governance record set and watchlist posture - `Runtime` groups orchestration anchors, runtime governance policies, and the queue-based `Operations` command center - `Catalog` groups the framework and overlay package registry together with governed agent-system and contract records - `Risk & Compliance` surfaces risks, controls, obligations, classifications, and regulatory updates - `Evidence` surfaces state profiles, evidence links, and explainability records - `Discovery` surfaces correlated findings and onboarding status Record-backed governance pages now include: - client-side search within the visible governance records - list-first record browsing with the command toolbar above the record explorer - selected-record workflow details, summaries, and actions in a dedicated work area that stays visible beside the list on wider screens - review posture, current source context, and linked evidence previews in the same selected-record pane when more than one governed source is attached - picker-first evidence linking for governed records, so operators select evidence by label, source type, date, and context while Gaia stores the stable resource id internally - on narrower screens, selecting a record brings the selected-record pane back into view so the layout change stays explicit instead of hiding below the list `Contracts` now adds the next governance-side workflow: - create a contract record for a governed agent, workflow, tool, integration, or policy boundary - capture interface summary, provenance requirements, owner, review cadence, and approval notes in one dialog - assign the selected contract to a reusable framework package when the boundary belongs to a governed overlay or standard - inspect recent contract versions and approval posture from the selected-record pane - move contracts through submit-for-review, approve, and retire actions from the governance tab `Policies` now adds the next runtime governance workflow: - create a policy record for a runtime guardrail, approval gate, fallback path, retention rule, or disclosure boundary - capture enforcement mode, scope summary, owner, review cadence, reason codes, fallback action, rollout notes, and kill-switch posture - link the policy to one or more governed contracts or controls so runtime behavior stays attached to reviewable governed records - use approved executable policies as runtime decision evidence when a governed tool call records policy id, policy version, rule id, configured outcome, effective outcome, and reason code - assign the selected policy to a reusable framework package when the rule belongs to a governed overlay or internal standard - inspect linked contracts, linked controls, and recent policy versions from the selected-record pane - move policies through submit-for-review, approve, and retire actions from the governance tab `Agent Systems` now adds the governed-boundary registry workflow: - create a durable governance record for each Gaia-native, published, live external, or governance-monitored external automation boundary - capture owner, team, runtime form, business boundary, supported protocols, review cadence, and governance posture in one dialog - inspect the selected-record operator proof path: boundary type, telemetry freshness, evidence provenance, Agent SRE runtime-health and opt-in metric SLO posture, latest review method, and the required human follow-up - inspect the selected-record OpenTelemetry control-plane preview so logs, spans, metrics, redaction counts, and operating mode are visible before telemetry leaves Gaia - configure the project OTLP HTTP destination and manually send scoped selected-boundary exports without making third-party delivery part of Gaia enforcement - generate a runtime evidence report from the selected boundary and store it as an agent-system review run with summary, findings, citations, suggested actions, and audit or delivery references - keep published project-spec bundles aligned as `published_capability` records instead of tracking reusable capability boundaries only in the publishing surface - attach external live-bridge actors to a governance agent-system ID so handoffs and runtime evidence point back to the same boundary - let Gaia write metadata-only `tool_call`, conversation turn, workflow-tool lifecycle, and published-capability sync telemetry automatically when a conversation config, workflow, agent, or bundle is mapped to the governed boundary - let Gaia write trusted runtime telemetry automatically when a live-bridge actor is mapped to the governed boundary - accept OpenTelemetry-style ingest from authenticated external collectors or governed vendor agents without making those agents operate inside Gaia - run deterministic review as the baseline check or `ai_assisted` review as a cited augmentation that always returns to human review before closure Platform Dashboard governance now also reuses the same agent-system summary seam: - `Agent Systems` highlights the number of registered governed boundaries and which ones still need human review after their latest recorded review - `Telemetry Gaps` highlights stale or missing runtime telemetry for boundaries that are expected to emit it in the current project scope - Operations highlights missing, stale, invalid, or failing control-plane destinations when a telemetry-tracked agent system depends on export posture - project drill-down cards now call out agent-system watch items alongside the existing governance queue and posture cues `State & Memory` now adds the next evidence-governance workflow: - create a state profile for working memory, workflow state, review artifacts, or retained evidence - capture storage boundary, access boundary, retention days, deletion trigger, owner, review cadence, legal-hold posture, and personal-data treatment in one governed record - assign the selected state profile to a reusable framework package when the handling rule belongs to a governed overlay or internal standard - align project-conversation retention profiles with **Project Settings -> General -> Runtime conversation retention**, which enforces the configured retention period in the runtime data path - attach evidence links from the same tab so the state profile points back to eval runs, artifact revisions, retained files, agent-system telemetry events, agent-system review runs, or human reviews - inspect recent versions and attached evidence links from the selected-record pane - move state profiles through submit-for-review, approve, and retire actions from the governance tab ## Zero-day conversation retention Use **Governance -> Evidence -> State & Memory** when a policy must define how conversation content is retained or purged. For tender evidence, Gaia supports project-conversation retention policies where `retentionDays` can be set to `0`. Configure the operational control in **Project Settings -> General -> Runtime conversation retention**, then keep the matching governed state profile in this tab for ownership, boundaries, deletion trigger, review cadence, legal-hold posture, and evidence links. A zero-day policy means eligible conversation content is purged immediately when the runtime retention check runs. Gaia separates content deletion from audit accountability: the purge removes conversation messages and content, while the Project Audit Trail records a redacted metadata event with the cutoff, message count, project context, and actor or system source. The audit entry does not re-store the purged conversation text. Capture the state profile showing retention days and deletion trigger, the purge run or operator invocation that applied the policy, the Project Audit Trail event proving redacted purge metadata, and any legal-hold or exception status if the policy excludes records from purge. If a deployment needs scheduled operator controls or file-storage purge beyond project conversations, include that scheduler or storage-retention evidence in the delivery annex. The first governance-side mutation workflow is now available in `Risk Library`: - load the seeded governance baseline into the current project - add a custom governance risk from the workspace dialog `Controls` now adds the next governance-side workflow: - sync the seeded control baseline into the current project, including EU AI Act and ISO/IEC 42001 operational controls - create a custom governance control with implementation and testing requirements - edit the active control in-place from the same tab - inspect recent versions and evidence-link completeness for the selected control - assign the selected control to a reusable framework package when the control belongs to a standard or domain overlay - promote controls through approve, activate, and retire actions from the governance tab `Obligations` now adds the next governance-side workflow: - sync the seeded obligation baseline into the current project, including full operational EU AI Act and ISO/IEC 42001 mappings - create a custom obligation with linked regulation and control context - assign the obligation and any custom regulation it creates to a reusable framework package - edit the active obligation in-place from the same tab - move obligations through approve, publish, and retire actions from the governance tab - route draft or review-ready obligation work back into the `Operations` command center when the next step belongs there `Classifications` now adds the next governance-side workflow: - run a guided EU AI Act wizard from the governance tab - edit or reassess the selected classification in-place - move classifications through review, approval, publish, reassessment, and supersede actions - attach existing evidence sources from the same tab without duplicating them - inspect latest run, linked risks, linked controls, linked obligations, evidence references, and recent version history in the same tab `Regulatory Updates` now adds the next governance-side workflow: - create and edit regulatory source collections - ingest regulatory updates directly into the queue from the same tab - inspect derived downstream impacts on obligations, controls, and classifications - assign the selected update to a reusable framework package during triage when the update belongs to a governed overlay or standard pack - update triage status, owner, SLA date, and review notes in place - inspect recent ingestion history for the selected source collection - route intake and assessment-stage updates back into the `Operations` command center when needed `Discovery` now adds the next governance-side workflow: - ingest new unmanaged AI findings directly into the governance intake queue - update triage state, owner, validation notes, false-positive reason, and remediation notes from the selected record pane - inspect correlated evidence sightings and retained file references without duplicating the source evidence - onboard the selected finding into the right classification, risk, and control baseline from the same tab - route intake and assessment-stage findings back into the `Operations` command center when needed `Explainability` now adds the next governance-side workflow: - create and refine explainability artifacts directly from the governance tab - queue explainability generation jobs and record their outcomes from the same workspace - inspect linked risks, controls, evidence links, recent jobs, and recent versions in the selected-record pane - submit artifacts for review and capture approval or rejection notes without leaving Governance - route execution-stage and review-stage explainability work back into the `Operations` command center when needed Some Runtime and Catalog tabs still act as structured governance entry points that point back to their operational anchors rather than replacing the authoritative operational workspaces. `Registry` remains the reusable package baseline, while `Agent Systems` is the boundary-level catalog for governed runtime identities. `Operations` now goes beyond a passive watch page: - it is the governance engine command-center shell - it groups work by `intake`, `assessment`, `execution`, and `review` - it now routes risks, controls, contracts, policies, and state profiles alongside obligations, classifications, regulatory updates, discovery findings, and explainability work - it preserves operator context in the route with `queue`, `mode`, and `record` - it previews review posture with state, coverage, provenance, next step, and current source context before the operator opens the detailed tab - it surfaces pending, rejected, expired, or misconfigured AI FinOps workload policies and lets operators approve temporary model-tier exceptions only when an expiry timestamp is recorded ## Where governance fits in the Gaia lifecycle Use governance once the project has enough shape to reason about risk and accountability: 1. Define the business workflow, users, decisions, and failure modes. 2. Model the core entities, files, workflows, and operational source systems. 3. Design agents, tools, and escalation boundaries. 4. Use Governance to make the package scope explicit, define governed contracts and runtime policies, classify the system, map obligations and controls, and track evidence and retention requirements. 5. Use Evals to test behavior quality, policy adherence, refusal behavior, and escalation quality. 6. Use Delivery Management and Tasks to close findings, implement controls, and track release readiness. 7. Revisit Governance when material changes, incidents, regulatory updates, or discovery findings appear. Governance should start before release pressure arrives. It becomes more expensive and less reliable when teams wait until the final approval phase. ## What governance consumes from the rest of Gaia Governance is strongest when it links to real source systems: - entities, files, and workflow outputs from [Data Model](#doc-data-model) - tool, prompt, handoff, and safety decisions from [AI Agents](#doc-agents) - conversation traces, human approvals, and retained artifacts from [Conversations](#doc-conversations) - run results, human review, and reports from [Evals](#doc-evals) - tasks, milestones, and delivery artifacts from [Delivery Management](#doc-delivery) and [Tasks](#doc-tasks) - role changes and configuration history from [Settings](#doc-settings) and [Audit Trail](#doc-audit) This is why governance evidence should normally be linked back to its operational origin instead of being recreated by hand. Governance posture now distinguishes trusted evidence anchors from supporting evidence. Eval runs, eval human reviews, and workflow runs remain the default trusted anchors. Conversation artifact revisions can also anchor posture when the linked revision resolves to a recognizable artifact and the link includes explicit provenance notes; otherwise artifact revisions, retained files, and delivery evidence remain supporting-only context. ## Governance and evals are different Keep these roles separate: - [Evals](#doc-evals) measure behavior under defined scenarios. - Governance decides which frameworks, controls, obligations, classifications, review steps, and explainability artifacts the system must maintain. In practice: - evals tell you whether the system behaves correctly - governance tells you what must be true around that behavior for the system to be acceptable to operate and release ## Current product boundary Today, Gaia already supports: - seeded domain baselines such as banking through the existing obligation workflow - custom regulations - custom obligations - configurable framework keys for regulations, regulatory updates, and filters - project-specific governance records and lifecycle actions across contracts, policies, state profiles, risks, controls, obligations, classifications, updates, discovery, and explainability - project-scoped framework-package authoring inside the Governance registry - published-package import and sync from other accessible Gaia projects - selected-package release-track posture for project-local current releases, imported release freshness, rollback/deprecation guidance, and source-lineage evidence refs - explicit framework-package assignment on risks, contracts, policies, controls, state profiles, regulations, obligations, regulatory sources, and regulatory updates Current limitation: - package reuse is now possible across accessible projects, and project-local release-track posture is visible, but Gaia does not yet provide a centralized global package catalog, dedicated promoter roles, deprecated lifecycle state, or historical immutable release-artifact table for governance packages - the user guide should treat sector packs as configurable overlays, not as globally shared governance catalogs The user guide should not imply otherwise. The neo-banking example is only a scenario anchor for this documentation set. Gaia is a generic platform, so banking, telecom, and similar domain packs should behave as configurable overlays rather than fixed peers of formal standards like the EU AI Act or ISO/IEC 42001. The in-product help pane resolves the base Governance route to this page and maps each governance page or local tab to the matching child page below. The workspace is not the source of truth for workflow authoring, artifact editing, or document management. Those functions stay in their current operational surfaces: - `Data Model -> Workflows` for workflow authoring - `Data Model -> Runs` for execution inspection - `Conversations -> Actions` for human approvals and operator input - Conversation artifacts for revisioned working outputs - `Conversations -> Folders` for durable evidence packs and source collections Governance is intended to unify policy, classification, evidence linkage, auditability, and cross-feature oversight. ## Current governance pages - Overview - Runtime - Catalog - Risk & Compliance - Evidence - Discovery ## Current governance topic tabs - [Governance Foundations](#doc-governance-foundations) - [Governed application lifecycle](#doc-governance-governed-application-lifecycle) - [Overview](#doc-governance-overview) - [Orchestration](#doc-governance-orchestration) - [Registry](#doc-governance-registry) - [Contracts](#doc-governance-contracts) - [Policies](#doc-governance-policies) - [Operations](#doc-governance-operations) - [State & Memory](#doc-governance-state-memory) - [Risk Library](#doc-governance-risk-library) - [Controls](#doc-governance-controls) - [Obligations](#doc-governance-obligations) - [Classifications](#doc-governance-classifications) - [Regulatory Updates](#doc-governance-regulatory-updates) - [Discovery](#doc-governance-discovery) - [Explainability](#doc-governance-explainability) ## Information architecture intent 1. Governance owns canonical oversight views and decision records. 2. Existing module tabs remain authoritative for execution, editing, and file management. 3. The project-header tabs group high-level governance pages, while local page tabs group the detailed topic areas inside each page. 4. Governance pages should deep-link back to the operational object whenever possible. 5. Evidence should stay linked to its original artifact, run, or folder source unless there is a clear reason to promote it into a folder-backed evidence pack. 6. Governance findings should usually flow into delivery tasks, release gates, and reassessment work instead of staying isolated inside the Governance workspace. --- # Governance Foundations Use this page if governance is new to you and you need the mental model before diving into the individual Governance tabs. ## Governance in plain language In Gaia, governance means defining the rules, review points, evidence, and ownership that make an AI system acceptable to operate. Governance is not: - a legal appendix that appears only before release - a second copy of evidence that already exists somewhere else in Gaia - a promise that the model will never make mistakes Governance is: - the operating boundary around what the system may do - the record of which standards, overlays, and internal rules apply - the set of controls, obligations, reviews, and evidence needed before release and during operation - the link between system behavior, human oversight, and accountable follow-up work ## Four questions governance answers If you know nothing about governance, start with these questions: 1. What decisions or workflows are important enough that they need explicit oversight? 2. Which rules or standards apply to that workflow? 3. What evidence proves the system behaved acceptably and stayed inside the agreed boundary? 4. Who owns the next action when evidence is missing, stale, or unacceptable? If a team cannot answer those questions clearly, it is probably operating an AI feature, not a governed AI system. ## How Gaia maps governance concepts into product surfaces | Governance concept | What it means | Gaia surface | | ---------------------------- | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | | Framework package | A reusable governance bundle that can represent a standard, sector overlay, or internal profile | `Governance -> Registry` | | Classification | The decision about what kind of system this is and why that matters | `Governance -> Classifications` | | Obligation | A requirement the system must satisfy | `Governance -> Obligations` | | Control | A safeguard, review step, or operational check that helps satisfy obligations | `Governance -> Controls` | | Contract | The governed boundary for an agent, workflow, tool, or integration | `Governance -> Contracts` | | Policy | The runtime posture for escalation, enforcement, fallback, or approval logic | `Governance -> Policies` | | Explainability | A reviewable explanation artifact linked to governed decisions | `Governance -> Explainability` | | Evidence and retention | What is kept, who can access it, and how long it remains available | `Governance -> State & Memory`, plus linked artifacts and folders | | Governance coordination | The queue that tells operators what needs triage, assessment, execution, or review | `Governance -> Operations` | | Behavior proof | The evidence that the system behaves the way the governance model expects | [Evals](#doc-evals) | | Remediation and release work | The place where governance findings become owned execution work | [Delivery Management](#doc-delivery) and [Tasks](#doc-tasks) | The key point is that Gaia does not keep governance in a sealed workspace. Governance links to the operational systems that already hold the truth: evals, workflows, artifacts, folders, tasks, and audit history. ## The three governance layers to keep separate Use this model when explaining governance to a customer or to a new internal team. ### 1. Standards layer Examples: - `EU AI Act` - `ISO/IEC 42001` - `NIST AI RMF` Purpose: - define broad expectations - provide reusable baseline obligations and controls ### 2. Domain layer Examples: - banking overlay - telecom overlay - healthcare overlay Purpose: - translate general AI governance into sector-specific operating expectations ### 3. Organization layer Examples: - internal approval policy - model risk committee rule - retention standard - human-review threshold by business unit Purpose: - adapt the standards and sector overlays to the way the customer actually operates This is how Gaia avoids both extremes: starting from a blank page and forcing customers into a rigid vendor-defined governance scheme. ## Practical setup sequence in Gaia Use this setup sequence when creating a governed application from scratch. ### 1. Define the governed boundary first Before you open the Governance workspace, write down: - the business workflow - the decisions the assistant supports - where human escalation is mandatory - the failure modes that would make the system unacceptable This gives the governance records something real to govern. ### 2. Build the package baseline Open [Registry](#doc-governance-registry). - refresh the starter catalog for the standards you need - add a domain overlay if the workflow is sector-specific - add or import the internal profile that represents local review and release expectations - activate the package you want to use so Gaia preloads the matching starter records for review - publish or reuse the package set that defines the project's governance boundary ### 3. Classify the system Open [Classifications](#doc-governance-classifications). - capture the system context - assess whether prohibited, high-risk, or transparency triggers apply - record the rationale - link the resulting classification to the relevant risks, controls, obligations, and evidence ### 4. Load obligations and controls Open [Obligations](#doc-governance-obligations) and [Controls](#doc-governance-controls). - sync the seeded baseline where it helps - add custom obligations or controls when the customer's rules go beyond the starter packs - keep the records Gaia preloaded for the package when they are in scope and remove the rest - link evidence or related records instead of recreating the same proof by hand ### 5. Define the governed runtime boundary Open [Contracts](#doc-governance-contracts) and [Policies](#doc-governance-policies). - use contracts to name the governed workflow, agent, tool, or integration boundary - use policies to define escalation, fallback, approval, or enforcement posture - make owners and review cadence explicit ### 6. Connect explainability and retained evidence Open [Explainability](#doc-governance-explainability) and [State & Memory](#doc-governance-state-memory). - create explanation artifacts for the decisions that require review - define what is retained, who can access it, and when it expires - link back to the underlying files, workflow runs, evals, and human reviews ### 7. Prove behavior and track remediation Governance is incomplete until the surrounding workflows are connected. - use [Evals](#doc-evals) to test quality, escalation, refusal, and policy adherence - use [Delivery Management](#doc-delivery) and [Tasks](#doc-tasks) to turn gaps into owned work - use [Operations](#doc-governance-operations) as the governance coordination queue for triage, assessment, execution, and review ## How to operate governance after setup Once the initial setup exists, governance becomes a working rhythm rather than a one-time project. ### During delivery - review open governance items in [Operations](#doc-governance-operations) - convert missing evidence, stale records, and policy gaps into tracked work - keep package adoption visible on the active records rather than only in the registry ### Before release - verify the classification still matches the intended release scope - confirm the required obligations and controls are covered - confirm explainability and retained evidence are available where needed - confirm eval evidence supports the declared operating posture ### During live operation - watch for material changes, incidents, or policy drift - reassess the system when the workflow, authority boundary, or regulatory context changes - preserve the connection between governance records and operational evidence so reviewers can inspect the real system state ## Where to learn next If you are starting from zero, use this order: 1. [Governance Foundations](#doc-governance-foundations) 2. [Governance](#doc-governance) 3. [Governed application lifecycle](#doc-governance-governed-application-lifecycle) 4. [Governance Operating Model](../../handbook/ch08-security-and-governance/05-governance-operating-model.md) 5. [Governed Application From Scratch](../../handbook/ch11-capstone-build-and-ship/05-governed-application-from-scratch.md) Use the User Guide for feature-level instructions and the Handbook for the structured learning path. --- # Governed Application Lifecycle Use this page when you want to understand how Governance fits into the normal Gaia build-and-ship flow. If governance is still unfamiliar, read [Governance Foundations](#doc-governance-foundations) first and then come back here for the lifecycle view. Primary guided path: - Use [Governed Application From Scratch](../../handbook/ch11-capstone-build-and-ship/05-governed-application-from-scratch.md) as the canonical end-to-end tutorial for the neo-bank scenario. Optional in-product drills: - Open [Tutorials](/platform/support/tutorials) and use the relevant live walkthrough cards to rehearse individual slices after you complete the matching handbook phase. The example below uses a neo-banking application, but the lifecycle applies to any governed enterprise AI system on Gaia. ## Anchor scenario The reference system is a `Customer Operations Copilot` for a neo-bank. The application helps internal teams: - onboard customers - review account and card servicing requests - inspect suspicious transactions - escalate uncertain or high-impact cases - maintain release evidence for regulated changes ## The lifecycle in one view 1. Define the business workflow and unacceptable failure modes. 2. Model the operational records and evidence-bearing source systems. 3. Design agents, tools, handoffs, and escalation boundaries. 4. Use Governance to make the package boundary explicit, define governed contracts and runtime policies, classify the system, map obligations and controls, and define retained-evidence posture. 5. Use Evals to verify behavior quality, policy adherence, and escalation behavior. 6. Use Delivery Management and Tasks to close findings and track release readiness. 7. Re-enter Governance when the system changes, incidents occur, or new regulatory signals appear. ## 1. Start with the application, not the governance tabs Governance is easier when the business system is already described clearly. For the neo-banking scenario, the team should first define: - the user groups involved - the decisions the assistant supports - the highest-cost failure modes - where human escalation is mandatory This creates the context for classification, controls, and obligations later. ## 2. Decide which Gaia records become source evidence Before loading governance records, decide which operational systems will become source evidence. For the neo-banking example, that often includes: - `Customer`, `Account`, `Card`, `Transaction`, and `Case` entities - uploaded identity or policy files - workflow runs that enrich, route, or review records - retained outputs and conversation artifacts - eval reports and human reviews - delivery tasks, milestones, and approval artifacts Governance should usually link back to those sources. It should not become a second place where the same evidence is recreated manually. ## 3. Connect agent design to governance expectations Agent design choices affect governance outcomes directly. Examples: - tool access influences what the assistant can do without approval - handoff logic influences when a human or specialist agent takes over - refusal and escalation behavior influence both eval strategy and governance review - specialist agents may need different explainability and evidence expectations Use [AI Agents](#doc-agents) and [Agent Configuration](#doc-agents-configs) to shape the behavior, then bring the important boundaries into Governance. ## 4. Use Governance as the cross-platform oversight layer Once the system shape is clear enough, Governance becomes the place to: - make the reusable package boundary explicit in [Registry](#doc-governance-registry) - define governed system boundaries in [Contracts](#doc-governance-contracts) - record runtime posture in [Policies](#doc-governance-policies) - review the system category and treatment in [Classifications](#doc-governance-classifications) - load or create requirements in [Obligations](#doc-governance-obligations) - map safeguards in [Controls](#doc-governance-controls) - define retained-evidence, state, and memory posture in [State & Memory](#doc-governance-state-memory) - monitor active work in [Operations](#doc-governance-operations) - manage change signals in [Regulatory Updates](#doc-governance-regulatory-updates) and [Discovery](#doc-governance-discovery) - capture review-ready explainability outputs in [Explainability](#doc-governance-explainability) Governance is not the authoring home for workflows, files, or delivery execution. It is the oversight layer that links those systems together. ## 5. Keep evals and governance separate, but connected Use [Evals](#doc-evals) to answer questions like: - does the assistant escalate correctly? - does it refuse disallowed actions? - does it follow the approved policy? - does it stay grounded in the available records? Use Governance to answer questions like: - which framework or sector baseline applies? - which obligations and controls must exist? - what classification or reassessment record is required? - what evidence must be retained before release? Evals prove behavior. Governance defines the operating conditions around that behavior. ## 6. Use delivery work to close governance findings Governance findings should usually become execution work. Typical examples: - create a task to implement a missing control - create a task to add missing eval coverage - create a milestone or release gate for classification approval - attach evidence and review notes to the relevant task or artifact This is how Gaia avoids leaving governance as a disconnected review layer. ## 7. Release when both quality and governance are ready Release readiness should combine at least two kinds of evidence: - eval evidence showing the system behaves acceptably - governance evidence showing the system has the required controls, obligations, classifications, reviews, and explainability support For the neo-banking example, a release gate may need: - passing escalation and refusal evals - classification review completion - obligation and control coverage for the intended release scope - explainability or evidence-link completeness for the governed workflows - tracked remediation for any accepted gaps ## Scenario and configurability note Gaia already supports: - a project-scoped registry for reusable framework packages, sector overlays, and internal governance profiles - governance workflows for contracts, policies, state and memory, obligations, classifications, controls, discovery, regulatory updates, and explainability - custom regulations, custom obligations, and custom framework keys inside the governance workflows - project-scoped framework-package authoring in the Governance registry - published-package import and sync across accessible Gaia projects - explicit package assignment on risks, contracts, policies, controls, state profiles, regulations, obligations, regulatory sources, and regulatory updates Current product boundary: - Gaia now provides a registry for reusable framework and domain-overlay packages, explicit downstream assignment for the main governed record types, published-package import across accessible projects, and project-local release-track posture for selected packages - richer global cataloging, organization or tenant release channels, dedicated promoter roles, deprecated lifecycle states, and historical immutable release artifacts are still pending Use this page as a lifecycle guide, not as a promise that every sector baseline or package-distribution capability already exists in the current product. The neo-banking example is only a teaching scenario. Gaia should remain generic, and domain packs such as banking or telecom should behave as configurable overlays rather than fixed platform assumptions. ## Related pages - [Build an AI application](#doc-building-an-ai-application) - [Governed Application From Scratch](../../handbook/ch11-capstone-build-and-ship/05-governed-application-from-scratch.md) - [Tutorials](/platform/support/tutorials) - [Governance](#doc-governance) - [Registry](#doc-governance-registry) - [Contracts](#doc-governance-contracts) - [Policies](#doc-governance-policies) - [Overview](#doc-governance-overview) - [Operations](#doc-governance-operations) - [State & Memory](#doc-governance-state-memory) - [Classifications](#doc-governance-classifications) - [Obligations](#doc-governance-obligations) - [Controls](#doc-governance-controls) - [Evals](#doc-evals) - [Delivery Management](#doc-delivery) - [Tasks](#doc-tasks) --- # Governance Overview Status: overview page available with live read-only governance summaries. The Governance **Overview** page is the landing page for the Governance workspace and now summarizes the live governance record set. Use this page as the top of the governance operating loop, not as a standalone dashboard. The page mirrors the six route-backed Governance sections so operators can see where to go next: - `Overview` for posture and watchlists - `Runtime` for orchestration, runtime policies, and queue-based operations follow-up - `Catalog` for framework packages and governed contracts - `Risk & Compliance` for risks, controls, obligations, classifications, and regulatory updates - `Evidence` for state profiles, evidence links, and explainability - `Discovery` for unmanaged-AI findings and onboarding progress Current summary areas include: - open approvals and incidents - framework-package coverage and contract or policy posture - policy posture and recent violations - high-risk workflows and systems awaiting review - obligation and control gaps - explainability and evidence-link backlog - recent regulatory updates and discovery findings - governance verification and Decision BOM evidence when Agent System release posture or high-risk runtime decisions need reconstruction The page aggregates governance records and evidence-link counts without replacing the operational workspaces that remain authoritative for editing and execution. The overview watchlist supports inline search, an in-product "How This Page Works" orientation card, and a same-page selected-record pane so the next governance surface is easier to identify without hunting through the layout. When a record has more than one linked evidence source, the same pane now keeps the current source anchor and ranked linked-evidence previews visible together. Typical upstream inputs include: - workflow and job runs - eval runs and human reviews - retained files and artifact revisions - delivery evidence and task follow-up - audit and role-change history - governance verification runs, runtime telemetry, and Decision BOM records Typical downstream actions include: - opening the detailed governance tab for the active record - sending remediation into delivery tasks - preparing release-readiness review - triggering reassessment after a material system change - linking verification runs or Decision BOMs to the records that need durable release evidence --- # Governance Orchestration Status: structured runtime anchor page available; workflow execution remains authoritative in its operational workspace. The `orchestration` tab lives inside the Governance **Runtime** page and now acts as a structured governance entry point for workflow execution oversight. Current operational anchors: - `Data Model -> Workflows` - `Data Model -> Runs` Current responsibilities: - show workflow classifications, approval state, and risk posture - expose the runtime oversight scope and point back to the operational workspaces that remain authoritative - group workflow authoring, run inspection, and approval anchors in one governance-oriented view Not in scope: replacing the existing workflow editor. --- # Governance Registry Status: interactive framework-package registry available in the Governance workspace. Guided scenario: use [Governed Application From Scratch](../../handbook/ch11-capstone-build-and-ship/05-governed-application-from-scratch.md) for the full neo-bank tutorial, then use [Tutorials](/platform/support/tutorials) only to rehearse registry work in-product. The `registry` tab now curates reusable governance packages for formal standards, domain overlays, and internal governance profiles. Use [Agent Systems](#doc-governance-agent-systems) when you need the boundary-level runtime registry for a governed automation system instead of the reusable package baseline. Recommended review path: - refresh the starter catalog or author custom overlays until the project boundary is explicit - activate or import the package you want to use so Gaia preloads the matching mapped records for review - when importing, confirm whether Gaia is creating a new imported copy or syncing an existing local lineage, then check whether the local imported release is already current or whether a newer source release is available - inspect the package list first; imported rows now flag whether the local copy is current, needs sync, or is drifting behind a non-published source state, then keep the selected package visible in the selected-record pane to confirm release-track semantics, lineage, effective framework keys, and linked downstream governance content - move next into [Contracts](#doc-governance-contracts) so governed interfaces show explicit package adoption The page also keeps a short "How This Page Works" card above the explorer so package purpose, selected-package focus, and the next move stay visible in-product. What is now available: - refresh the package catalog with `EU AI Act`, `NIST AI RMF`, `ISO/IEC 42001`, `telecom`, and `banking` - create custom framework packages with any normalized framework key - declare overlay dependencies through `extends framework keys` - publish and retire selected packages from the same registry surface - import and sync published packages from other accessible Gaia projects - inspect source project, source package, publication timing, local lineage, and local-versus-source release freshness in the import dialog before confirming a new import or sync - inspect the registry list itself for imported-package freshness before opening the selected-record pane when you want to spot stale or source-drifted imports quickly - activate the selected package so Gaia preloads the matching regulations, obligations, source collections, regulatory updates, seeded risk suggestions, and synced control suggestions - review and keep or remove the preloaded package scope before downstream teams rely on it - review release-track semantics, import lineage, imported-release freshness, and explicit downstream adoption counts from the selected-package pane before publishing or retiring a package - treat edits to published packages as draft changes until you publish the updated release again - inspect linked risks, controls, regulations, obligations, regulatory sources, and regulatory updates for the selected package - inspect which downstream records explicitly adopted the selected package instead of only matching its framework keys The EU AI Act and ISO/IEC 42001 packages now behave as full operational mapping packages after the related obligation, risk, control, source-collection, and regulatory-update baselines are synced. They provide reviewable Gaia obligations, mapped controls, evidence expectations in control metadata, source traceability, and package activation candidates. They do not create an automatic legal certification; operators still need to review applicability, ownership, evidence freshness, retained source material, and local audit interpretation before relying on the package. Current responsibilities: - maintain a project-scoped library of reusable governance packages - reuse published packages across projects without rebuilding the same overlay by hand - separate formal standards from domain overlays and internal profiles - make package composition visible through effective framework keys - expose dependency counts and explicit adoption counts back into live governance records so overlay reuse is inspectable Current limitation: - release tracks are project-local: Gaia shows the current published release boundary, import/sync lineage, and v1 rollback/deprecation choices, but does not yet provide a centralized global package catalog, dedicated promoter roles, deprecated lifecycle state, or historical immutable release-artifact table --- # Agent Systems Status: interactive agent-system registry, Gaia-native identity and trust posture, Agent SRE runtime-health SLO records, audited suggested-trust and runtime-posture acceptance, governance posture verification runs, ACS-aligned checkpoint compatibility evidence, standards evidence exports, OpenTelemetry-compatible ingest and project export, mapped Gaia runtime telemetry, live-bridge runtime telemetry, direct evidence-link support, runtime policy decision history, runtime evidence reports, and bounded AI-assisted review available in the Governance workspace. Use the `agent-systems` tab when you need one durable record for a governed automation boundary. The tab is designed for boundaries such as: - a Gaia-native agent or workflow that carries a distinct governance boundary - a published capability that should keep lineage back to its reusable project-spec bundle - an external human or AI runtime that participates through live bridge handoff - a governance-monitored external agent that does not operate inside Gaia but still needs telemetry review, evidence, and drift tracking Recommended review path: - create or confirm the registry record before you attach downstream evidence - capture the runtime form, owner, accountable sponsor, Gaia agent DID when available, identity status, operator-managed trust tier, process scope, protocols, and enforcement posture - link the contracts, policies, controls, obligations, classifications, and framework packages that define the authoritative boundary - review the selected-record pane's operator proof path: boundary type, telemetry freshness, evidence provenance, latest review method, and required follow-up - inspect runtime policy decision history on the selected record when the boundary has governed-tool decision telemetry; use the outcome, configured outcome, policy, rule, telemetry ref, tool-message ref, and audit or delivery refs to confirm whether the evidence pack is complete - inspect Agent SRE SLO posture on the selected record; configure project-scoped SLO records when the built-in 24-hour runtime-health fallback needs boundary-specific windows or budget thresholds, or when the boundary needs opt-in policy-compliance, policy-decision-latency, incident-rate, tool-success-rate, or telemetry-freshness posture - review the ACS-aligned compatibility matrix for the selected record; treat it as checkpoint evidence for input, LLM, state, tool execution, and output coverage, not as ACS certification - copy or download standards evidence artifacts from the selected record when a release or proposal pack needs ACS policy projection, OCSF-aligned runtime governance events, CycloneDX Agent BOM JSON, ASSERT-style eval scenario drafts, or A2A readiness evidence - run **Verify governance posture** from the selected record before release review or after material changes; the verification checks governance coverage, linked evidence, telemetry freshness, review freshness, drift posture, and trust posture, then stores an evidence-linkable run with status, grade, score, findings, and coverage metadata - review the OpenTelemetry control-plane preview before exporting telemetry to a third-party monitoring or control-plane system; runtime policy decisions export searchable policy id, policy record id, policy version, rule id, phase, effective outcome, configured outcome, reason code, enforcement mode, latency, tool, tool-message ref, audit ref, and delivery ref attributes; MCP gateway decisions also export gateway source, phase, server URL, channel slug, outcome, configured outcome, rule id, and reason code - use `Configure SIEM/control-plane export` to set the project OTLP HTTP destination, then use `Send SIEM export` when a selected boundary needs a manual telemetry delivery run - run deterministic review after publishing, drift, or external-runtime changes so the registry stays current - use `Run AI-assisted review` when you want a cited augmentation pass that still routes the resulting run into human review before closure What is now available: - create, edit, review, and delete project-scoped agent-system records from the Governance workspace - track lifecycle, coverage, drift, review cadence, identity status, operator-managed trust tier, trust score, trust rationale, and Gaia's advisory trust suggestion in the same record - accept Gaia's suggested trust tier from the selected-record pane when the evidence supports an upgrade or downgrade; acceptance is manual, audited, and emits trusted attestation telemetry with the operator note - create, edit, and retire Agent SRE SLOs from the selected-record pane; active records override the virtual built-in runtime-health fallback for that Agent System, and the metric catalog can add opt-in policy-compliance, policy-decision-latency, incident-rate, tool-success-rate, or telemetry-freshness SLO records; policy-decision-latency SLOs default to a 100ms threshold that can be edited per record - clear accepted Agent SRE runtime posture from the selected-record pane when the boundary has recovered or the operator no longer wants the posture available to policy matching - inspect an ACS-aligned checkpoint compatibility matrix for the selected record; Gaia maps current runtime evidence into input, LLM, state, tool-execution, and output checkpoint rows with covered, partial, or planned posture - export standards evidence JSON from the selected record: approved-policy and MCP gateway rule projection, OCSF-aligned runtime governance records, CycloneDX Agent BOM, ASSERT-style requirements-to-eval scenarios, and A2A interoperability readiness. These artifacts preserve Gaia refs and remain compatibility evidence, not certification. - create governance verification runs from the selected-record pane so a release reviewer can inspect which required contracts, policies, controls, evidence links, telemetry, reviews, drift posture, and trust posture are present or missing - keep recent telemetry, evidence posture, and the latest review summary attached to the selected record - show recent runtime policy decisions for the selected record, including enforced block/fallback/quarantine outcomes, review-mode would-block warnings, matched policy/rule identity, telemetry refs, and missing tool-message or audit/delivery refs - show whether the latest review came from the deterministic runner or the bounded `ai_assisted` path - let published project-spec bundles sync into the registry as `published_capability` records - attach live bridge actors to a governance agent-system ID so external AI and human participants can point back to the same governed boundary - emit metadata-only `tool_call`, conversation turn, workflow-tool lifecycle, and published-capability sync telemetry automatically when the active config, workflow, agent, or published bundle maps to a governance agent-system record - emit trusted agent-system telemetry automatically from live bridge takeover, transport, participant-message, and resume-suggestion events when the runtime actor is mapped to a governance record - ingest agent-system telemetry through the project governance API route when you need external runtime evidence outside the live bridge path - ingest OpenTelemetry-style logs and spans through the project `agent-system-events/otlp` route when an external collector or governed vendor agent needs to report into Gaia - configure a project OTLP HTTP destination, preview Gaia's OTLP-compatible logs, spans, metrics, operating mode, runtime policy decision attributes, MCP gateway decision attributes, and metadata-only redaction posture, then manually send a scoped SIEM/control-plane export from the selected agent-system pane - inspect last-delivery status in the selected-record pane and Operations queues when a destination is missing, stale, misconfigured, or failing - link agent-system telemetry events and review runs directly from governance evidence pickers when a downstream record needs a governed runtime source - generate a runtime evidence report from the selected agent system so recent runtime-governance decisions, tool-message evidence, telemetry references, citations, findings, suggested actions, and audit or delivery references are stored as a review run - route `ai_assisted` review output through strict citation validation so uncited or unsupported findings are rejected instead of being stored Current responsibilities: - define the durable identity for each governed automation boundary - keep sponsor, identity status, trust tier, and trust rationale current as telemetry, reviews, incidents, and attestations change; use Gaia's suggested trust tier as review evidence until an operator accepts it - keep runtime, monitored external-agent, and publishing lineage aligned to the same governance record - surface drift, missing coverage, and stale review posture before release work depends on the boundary - make external participant telemetry, direct evidence links, deterministic review, and AI-assisted human-review routing inspectable in one place Operator proof path: - **Boundary proof:** confirm whether the selected record is a Gaia-native boundary, published capability, live external participant, governance-monitored external system, or mixed system. Governance-monitored records are observed evidence sources; they do not imply Gaia can control the external runtime. - **Identity and trust proof:** confirm the sponsor, Gaia agent DID, identity status, trust tier, trust score, trust rationale, Gaia's suggested trust tier, and any revocation reason. Trust tiers are Gaia-native operating posture labels; they do not imply cryptographic identity or external attestation unless those facts are linked as evidence. The suggestion is derived from evidence freshness, incidents, drift, review status, coverage, and linked evidence. It remains advisory until an operator with governance modification access uses **Accept suggested trust tier**. Accepted changes update the stored tier, record the rationale and optional operator note, write an audit row, emit trusted attestation telemetry, and then affect runtime policy matching that consumes the stored Agent System trust tier. - **Telemetry proof:** use freshness and trusted-event counts to decide whether the boundary has current runtime evidence. Freshness only measures signals from boundaries expected to emit telemetry. - **Agent SRE proof:** use the selected-record Agent SRE section to review runtime-health SLI, error-budget status, window, and response recommendation. Runtime health is the only automatic virtual fallback. Use the metric catalog to add opt-in policy-compliance, policy-decision-latency, incident-rate, tool-success-rate, or telemetry-freshness SLOs when those dimensions matter for the boundary. Policy-decision-latency SLOs evaluate `policyDecisionLatencyMs` telemetry against the configured per-record threshold. Warning posture is review-only. Critical or exhausted posture can become runtime-consumable only after manual acceptance with an expiry; accepted posture remains policy-gated and can be cleared from the same pane. - **Standards compatibility proof:** use the ACS-aligned matrix to explain which checkpoint categories Gaia can evidence today. Tool execution is covered when governed-tool or MCP gateway policy decisions exist or are configured; input, LLM, state, and output rows normally remain partial or planned until their supporting evidence refs are linked. This matrix is compatibility evidence, not certification, legal compliance, or a guarantee that Gaia controls customer/vendor-owned external runtimes. - **Standards export proof:** use the standards evidence export panel when reviewers need files instead of screenshots. The ACS policy projection includes approved policies and active MCP gateway rules only; the OCSF projection keeps SIEM-oriented runtime governance records separate from OTLP delivery; the Agent BOM starts with CycloneDX JSON; the ASSERT bridge creates reviewable eval scenario drafts; and the A2A profile remains interoperability readiness until a real runtime control path exists. - **Verification proof:** use the selected-record verification section to create and inspect governance posture runs. A warning or failed run is a release-review input, not an automatic runtime mutation; operators still decide whether to remediate, defer with acceptance, or block release through the normal governance and delivery process. - **Runtime policy proof:** use the selected-record decision history to inspect recent governed-tool outcomes without opening raw event JSON. A complete runtime-policy capture keeps the agent-system telemetry ref, tool-message ref, and audit or delivery ref together. - **Control-plane proof:** use the OpenTelemetry preview and last-delivery status to confirm how many logs, spans, metrics, runtime policy decision attributes, MCP gateway decision attributes, and redacted events would leave Gaia. Exports are observational unless a separate audited enforcement integration exists. - **Review proof:** deterministic review is the baseline posture check. `runtime_evidence` review runs preserve the latest runtime-governance evidence report for the selected boundary. `ai_assisted` review is a cited augmentation that remains in human review until an operator closes the follow-up. - **Evidence proof:** use direct evidence links and review citations to show which telemetry events, review runs, or governance records support the current claim before treating the boundary as release-ready. Use [Control Plane Evidence](#doc-control-plane-evidence) when the agent-system proof needs to be combined with document-folder retrieval, prompt/configuration, eval, dashboard, audit, and vendor-onboarding evidence. --- # Governance Contracts Status: live route-backed contract workflow available in the Governance workspace. The `contracts` tab in Governance now provides a dedicated catalog for governed invocation and integration boundaries. Recommended review path: - start from a package chosen in [Registry](#doc-governance-registry) so the boundary inherits the right governance baseline - choose the governed resource from Gaia's searchable picker, then define provenance requirements, owner, and review cadence for the interface before using the list to move between contract records and inspect the selected contract pane beside the list on larger viewports - move next into [Policies](#doc-governance-policies) to capture runtime posture against the approved contract boundary The page also keeps a short "How This Page Works" card above the explorer so boundary purpose, selected-contract focus, and the next move stay visible in-product. Use it to: - create a governance contract for an agent, workflow, tool, integration, or policy boundary - capture the governed resource, interface summary, provenance requirements, owner, review cadence, and approval notes - assign the contract to a reusable framework package when the boundary belongs to a governed standard or overlay - inspect the selected contract and recent version history without leaving the Governance workspace - move the contract through draft, in-review, approved, and retired lifecycle states The selected contract posture now makes the governed-boundary state explicit. Gaia distinguishes validated bindings, broken bindings, manual boundaries, weak bindings, and missing bindings based on whether the saved contract still resolves to a live governed resource in the project. Current operational anchors still matter: - workflow nodes that call agents or tools - integration setup and adapter configuration - agent and config authoring for the underlying execution behavior Governance contract responsibilities: - contract versions and approval state - provenance requirements for cross-system calls - adapter scope and credential boundaries - identify the operational surfaces that still hold the authoritative runtime configuration details The contract catalog does not replace workflow, tool, or integration editing. It records the governed boundary and approval posture around those operational surfaces. --- # Governance Policies Status: live governance workflow available. The `policies` tab in Governance is now the canonical place to capture runtime safety rules and approval boundaries as reviewable records. The command toolbar stays above the record explorer, and selecting a policy keeps a visible selected-policy pane beside the list on larger viewports while preserving the same selected summary and workflow actions. The page also keeps a short "How This Page Works" card above the explorer so runtime-rule purpose, selected-policy focus, and the next move stay visible in-product. Use it when the team needs to make runtime posture explicit instead of leaving it implicit inside prompts, workflow code, or control notes. Recommended review path: - start from the governing [Contracts](#doc-governance-contracts) record so the policy inherits the correct interface and package scope - link the policy to controls when reviewers need a named safeguard or remediation checkpoint - finish by linking the approved posture to retained evidence, explainability artifacts, or reviewer packs in [State & Memory](#doc-governance-state-memory) Current workflow: - create a governance policy record for a runtime guardrail, approval gate, fallback, retention rule, or disclosure boundary - capture the policy summary, enforcement mode, scope summary, owner, review cadence, reason codes, fallback action, and rollout notes - link the policy to one or more governed contracts or controls so runtime posture stays connected to the governed boundary it depends on - assign the policy to a governance framework package when it belongs to a reusable overlay or internal standard - record whether a kill switch exists for urgent disablement - inspect linked contracts, linked controls, and recent policy versions from the selected-record pane - move policies through submit-for-review, approve, and retire actions directly from Governance ## Runtime policy decisions Approved policies can now participate in governed tool execution when the policy carries executable runtime rules from an imported package, seeded baseline, or managed project setup. Runtime decisions preserve the governance record identity in tool evidence: - policy id and policy record id - policy version - matched rule id - phase: pre-execution or post-execution - agent-system trust tier and action execution tier when available - accepted Agent SRE runtime response state when available - configured outcome and effective outcome - reason code and optional operator message - default-action source - decision latency - enforcement mode Use `enforced` mode only when the policy is ready to affect runtime behavior. `review` and `shadow` modes keep the matched decision visible as warning evidence without blocking or replacing the tool result. This lets reviewers prove the policy would have matched before turning it into an enforced guardrail. Executable runtime rules can also inspect Gaia-native trust, execution, and accepted Agent SRE posture. Agent-system records provide the current stored trust tier for mapped runtime configs, agents, or workflows. Gaia may suggest trust-tier upgrades or downgrades from evidence signals, but those suggestions remain advisory until an operator accepts them from the selected Agent System pane. Accepted suggestions are audited, emit trusted attestation telemetry, and then update the stored tier that runtime policy matching consumes. Tool definitions can declare an execution tier: `read_only`, `standard`, `privileged`, or `admin`; configuration tools and registry-backed tools expose this tier in their tool editor, with existing tools defaulting to `standard`. A rule can use `requiredTrustTier` and `requiredExecutionTier` to match high-risk actions when the mapped agent-system trust tier is below the required level. Agent SRE runtime response state is stricter: Gaia evaluates runtime-health SLO posture, but only manually accepted critical or exhausted posture becomes available to runtime policy matching. Use `requiredAgentSreRuntimeResponseState` when a policy should match `throttle_recommended` or `circuit_break_recommended`. Severity ordering is `none < throttle_recommended < circuit_break_recommended`, so a circuit-break posture also satisfies a throttle-level rule. The accepted posture does not enforce anything by itself; the approved policy still chooses the outcome. Approved policies can also contribute MCP gateway rules for runtime MCP tool governance. Use the selected-policy pane to create, edit, retire, materialize, and diff MCP gateway rules for allow/deny behavior, sensitive-tool approval requirements, rate budgets, response scanner patterns, schema fingerprinting, and default action posture. MCP gateway rules are policy-gated: rule edits can be drafted at any time, but table-backed rules compile into runtime only after the parent Governance Policy is approved. Editing or retiring a rule on an approved policy returns the policy to draft so reviewers can approve the changed runtime posture. If the policy has table-backed rules, those rules supersede package metadata for that policy. If it has no table-backed rules, Gaia still supports package-import and managed-setup metadata as the migration bridge. Package-import and managed-setup metadata can use this shape: ```json { "runtimePolicy": { "mcpGateway": { "defaultAction": "warn", "defaultReasonCode": "governance.mcp.gateway.default_review", "allowTools": [ { "toolName": "read_case", "channelSlug": "customer-support", "priority": 20 } ], "denyTools": [ { "toolName": "delete_case", "message": "Deletion requires a separate approved workflow." } ], "sensitiveTools": ["lookup_customer"], "rateBudgets": [ { "toolName": "lookup_customer", "scope": "agent", "limit": 20, "windowSeconds": 60 } ], "responseScan": { "enabled": true, "action": "sanitize", "patterns": [ { "id": "internal-marker", "pattern": "internal-only", "reasonCode": "governance.mcp.gateway.internal_marker" } ] }, "schemaFingerprinting": { "enabled": true } } } } ``` Each matcher may use `toolName`, `serverUrl`, or `channelSlug`. Gaia adds policy identity, policy record id, policy version, and generated rule ids when package metadata omits them, so runtime decisions and control-plane exports can still point back to the approved policy record. Configuration-local `governedToolPolicy` and `mcpGovernanceGateway` settings remain visible in the configuration Tools tab as lower-precedence migration and backward-compatibility controls. They can add stricter behavior, but they cannot relax approved policy deny, sensitive-tool, rate-budget, response-scan, or schema-fingerprinting behavior. Durable policy changes should move back into Governance Policies for review and approval. When an Agent System is selected, Gaia can also export an ACS-aligned policy projection that includes approved Governance Policies and active MCP gateway rules linked to that boundary. Draft, in-review, disabled, or retired policies are omitted from runtime posture so the export does not overstate enforcement. Operational anchors that policies should align with: - workflow execution settings - agent/runtime guardrails - approval flows for high-risk work Typical uses in the governed application path: - human-review escalation rules for suspicious-transaction handling - guarded fallback behavior when evidence remains ambiguous - staged rollout from shadow mode to enforced mode for high-impact decisions - explicit operator ownership and review cadence for runtime guardrails --- # Governance Operations Status: governance engine command-center shell available with queue, run-mode, record-aware routing, Agent SRE error-budget work items with audited runtime-posture acceptance, runtime policy decision work items, and AI FinOps workload-policy approval actions. Guided scenario: use [Governed Application From Scratch](../../handbook/ch11-capstone-build-and-ship/05-governed-application-from-scratch.md) for the full neo-bank tutorial, then use [Tutorials](/platform/support/tutorials) only to rehearse operations routing in-product. The `operations` tab exists in the Governance workspace shell and now acts as the governance engine command center for cross-tab intake, assessment, execution, and review work. The page now keeps a short in-product orientation card above the command center so queue purpose, selected work-item focus, and the next move remain visible while operators switch queue, run mode, and target record. What is now available: - queue-driven triage across governance records: - `intake` - `assessment` - `execution` - `review` - visible governance engine run modes: - `simulate` - `review` - `auto-apply` - route state that preserves operator context: - `queue=<...>` - `mode=<...>` - `record=<...>` - command-center previews that show: - the selected work item - review posture with state, coverage, provenance, and next step - current source context with a deep link into the record-specific governance tab - Agent SRE work items for built-in runtime-health SLO posture and opt-in record-backed policy-compliance, policy-decision-latency, incident-rate, tool-success-rate, or telemetry-freshness SLO warnings, critical budgets, and exhausted budgets - runtime policy decision work items for recent governed-tool interventions, review-mode warnings, and incomplete evidence captures Current operational anchors: - `Conversations -> Actions` - `Settings -> Audit` - workflow runs and traces - conversation artifact revision/export history Current responsibilities: - end-to-end lineage across workflow, agent, human, and artifact events - SLA tracking for approvals and escalations - cross-tab queue monitoring for risks, controls, contracts, policies, state profiles, regulatory updates, discovery findings, obligations, classifications, and explainability artifacts - keeping deep links back to the live governance record and its operational source - surfacing blocked or review-sensitive work before the operator moves into the detailed tab - keeping review posture language consistent with the shared selected-record surface used across the other governance tabs Runtime policy decisions now add another evidence input for Operations review. When a governed tool call matches an approved Governance policy, the tool evidence can carry the policy id, policy record id, policy version, rule id, effective outcome, configured outcome, reason code, enforcement mode, decision latency, tool-message ref, audit ref, and delivery ref. Operations surfaces recent blocked, fallback, quarantine, review-mode warning, and incomplete-capture decisions as work items that link back to the Agent System boundary. The same fields are emitted as searchable OpenTelemetry attributes in the Governance Agent Systems control-plane export. Treat those decisions as operational signals that should be linked back to the policy, contract, control, eval evidence, or delivery task that explains the expected response. For SIEM-oriented review packs, the selected Agent System also provides an OCSF-aligned runtime governance export. It is separate from OTLP delivery and Governance Evidence JSONL: the projection keeps event, review-run, verification-run, and Decision BOM refs in a security-event shape without changing runtime enforcement or storing raw sensitive payloads. Agent SRE evaluates governed runtime-health SLOs over recent Agent System telemetry. Gaia uses active project-scoped SLO records when present, or the built-in 24-hour runtime-health fallback when no active SLO has been configured for the boundary. The selected Agent System pane can also add opt-in policy-compliance, policy-decision-latency, incident-rate, tool-success-rate, and telemetry-freshness SLO records from the metric catalog. Policy-decision-latency SLOs use an editable per-record threshold and default to 100ms. Warning, critical, and exhausted budgets appear as Operations work items. Warning remains review-only. Critical and exhausted budgets can be accepted manually with an expiry timestamp and optional operator note: critical accepts `throttle_recommended`, and exhausted accepts `circuit_break_recommended`. Acceptance records audit evidence and trusted Agent System attestation telemetry, but it does not throttle or block anything by itself. Accepted Agent SRE posture is runtime context for approved Governance Policy rules. Runtime enforcement only changes when an approved policy explicitly matches the accepted response state and chooses an existing outcome such as `warn`, `block`, `fallback`, or `quarantine`. Expired or cleared posture is ignored without a background job. AI FinOps workload policies also appear in Operations when an agent, app-user role, channel, project, team, organization, or instance policy is pending, rejected, expired, or misconfigured. Operators can approve a temporary exception only with an expiry timestamp, or reject the policy with decision notes. Policy definition remains in the owning AI FinOps settings surface; Operations records the review decision and updates that original policy scope. New review coverage includes: - published risks that still need governance confirmation against the active control and obligation baseline - approved controls that are ready for activation review - governed contracts that are still in review or already approved but waiting for release alignment - runtime policies that need approval or final sign-off against their linked contract or control boundary - Agent System SLOs that are warning, critical, or exhausted based on runtime telemetry - runtime policy decisions that need intervention review, evidence completion, or review-mode promotion decisions - workload policies that need model-tier approval, exception expiry, or rejection review before runtime use - state and memory profiles that need retention, access, or deletion posture review before release use New assessment and execution coverage includes: - draft risks and draft controls that still need owner, mitigation, implementation, or testing posture refinement - active controls that should remain visible while governance tracks implementation and evidence posture during live use Current boundary: - `Operations` is the governance engine home and coordination surface - record-specific editing and lifecycle workflows still live in their detailed governance tabs - authoritative execution, approval, run, and evidence systems still remain in their operational surfaces --- # Governance State & Memory Status: live governance workflow available. The `state-memory` tab now captures explicit state, memory, and retention decisions as governed records. The command toolbar stays above the record explorer, and selecting a state profile keeps a visible selected-state-profile pane beside the list on larger viewports while preserving the same workflow actions. The page also keeps a short "How This Page Works" card above the explorer so retention-rule purpose, selected-state-profile focus, and the next move stay visible in-product. Use it when the team needs to make working-state, retained-evidence, or review-artifact handling visible before release instead of leaving those decisions implicit in folder practices or operator habits. Current workflow: - create a state profile record for working memory, workflow state, review artifacts, or retained evidence - capture the summary, state type, classification, storage boundary, access boundary, retention period, deletion trigger, owner, review cadence, and hold posture in one place - assign the selected state profile to a governance framework package when the handling rule belongs to a reusable overlay or internal standard - record whether the state contains personal data and whether legal or investigation holds can pause deletion - attach evidence links from the same tab so the record points back to eval runs, artifact revisions, retained files, or human reviews - inspect recent versions, current source context, and linked evidence previews from the selected-record pane - move state profiles through submit-for-review, approve, and retire actions directly from Governance ## Configure a retention period Open **Governance -> Evidence -> State & Memory**, then create or edit a state profile. Set **Retention days** to the number of days the governed state, memory, review artifact, or retained evidence should remain available. For immediate purge evidence, set **Retention days** to `0` and fill **Deletion trigger** with the event that starts deletion. For project-conversation retention, configure the operational control in **Project Settings -> General -> Runtime conversation retention**. That runtime setting enforces the purge before normal conversation reads, writes, and lists continue; the state profile documents the policy owner, boundaries, legal-hold posture, review cadence, and evidence links. The purge removes conversation content while the Project Audit Trail keeps only redacted purge metadata, such as cutoff, message count, project context, and actor or system source. Use the selected state-profile pane to review the saved **Retention days**, **Deletion trigger**, legal-hold support, personal-data flag, storage boundary, access boundary, and linked evidence before submitting the profile for review. Operational anchors that state profiles should stay aligned with: - workflow state and checkpoints - conversation artifacts and revisions - document folders and indexed evidence packs Current responsibilities: - distinguish orchestration state from working artifacts and durable evidence - show lifecycle transitions from artifact work product to retained evidence - preserve folder ACL and indexing boundaries Typical uses in the governed application path: - define how suspicious-transaction review evidence moves from working output to retained governed evidence - make reviewer-only access boundaries explicit for retained packs - document retention and deletion timing before release review - preserve legal-hold and personal-data handling as named governance decisions instead of informal conventions --- # Governance Risk Library Status: selected-risk maintenance workflow available in the Governance workspace. The `risk-library` tab now surfaces the live governance risk catalog together with selected-risk maintenance actions. The command toolbar stays above the record explorer, and selecting a risk keeps a visible selected-risk pane beside the list on larger viewports while preserving the same summary and maintenance actions. The page also keeps a short "How This Page Works" card above the explorer so risk purpose, selected-risk focus, and the next move stay visible in-product. Current responsibilities: - browse standardized ML, GenAI, and agentic-system risks - inspect draft, published, and retired risk records - review likelihood and impact posture at a glance - load the seeded governance baseline into the project - add custom project-specific risks through the governance dialog - edit the selected risk from the same tab - publish or retire the selected risk without leaving the workspace - inspect recent version history for the selected risk - inspect which downstream controls currently mitigate the selected risk and whether those controls already carry linked evidence - assign the selected risk to a reusable framework package when it belongs to a standard or domain overlay - route draft and published risks back into the appropriate `Operations` queue when the next step belongs in the command center Seeded risks are only starting points. Gaia should remain generic across domains, so teams must be able to adapt the risk library with project-specific and sector-specific records instead of treating a seeded baseline as the platform's final taxonomy. The current summary supports inline search, same-page detail inspection, baseline risk loading, selected-risk editing, publish or retire actions, recent version inspection, downstream control-and-evidence traceability, and queue-aware follow-up back into `Operations`. --- # Governance Controls Status: control summary plus selected-control maintenance workflows available in the Governance workspace. Guided scenario: use [Governed Application From Scratch](../../handbook/ch11-capstone-build-and-ship/05-governed-application-from-scratch.md) for the full neo-bank tutorial, then use [Tutorials](/platform/support/tutorials) only to rehearse this control workflow in-product. The `controls` tab now surfaces the live governance control records together with selected-control maintenance workflows directly from the Governance workspace. The command toolbar stays above the record explorer, and selecting a control keeps a visible selected-control pane beside the list on larger viewports while preserving the same selected summary and workflow actions. The page also keeps a short "How This Page Works" card above the explorer so the safeguard question, selected-control focus, and next move stay visible in-product. Current responsibilities: - sync the seeded control baseline into the current project, including EU AI Act and ISO/IEC 42001 operational controls - inspect lifecycle state for controls - inspect approval or activation posture - review automation status and testing expectations - inspect which obligations and classifications now depend on the selected control - create a custom control with implementation guidance and testing requirements - edit the selected control in-place from the same tab - approve draft controls, activate approved controls, and retire active controls - inspect recent version history for the selected control - inspect evidence completeness for the selected control, including implementation guidance, testing coverage, and linked evidence count - link the selected control back to a workflow run, artifact revision, retained file, delivery evidence item, eval run, or human review - open linked risks, obligations, and classifications directly from the selected control card - use linked risks so the originating risk record can inspect the same control and evidence posture without leaving Governance - assign the selected control to a reusable framework package when it belongs to a standard or domain overlay - route draft, approved, and active controls back into the appropriate `Operations` queue when the next step belongs in the command center The current summary supports inline search, same-page detail inspection, seeded control baseline sync, control creation, selected-control editing, downstream record navigation, version inspection, evidence linking, lifecycle promotion, and queue-aware follow-up back into `Operations` for the visible control records. Seeded controls are operational safeguards, not legal sign-off. Use them as a reusable starting point, then confirm the package scope, evidence expectations, testing requirements, and local ownership before treating a control as release-ready. Typical evidence targets may include workflow records, delivery artifacts, conversation artifacts, and folder-backed evidence packs. Trusted posture still defaults to eval reviews, eval runs, and workflow runs. Conversation artifact revisions can also act as the trusted source when the link resolves to a recognizable artifact and carries explicit provenance notes; otherwise artifact revisions, retained files, and delivery evidence remain supporting-only evidence. --- # Governance Obligations Status: interactive obligation workflow available in the Governance workspace. The `obligations` tab now surfaces the live governance obligation records together with the first governance-side workflow actions. The command toolbar stays above the record explorer, and selecting an obligation keeps a visible selected-obligation pane beside the list on larger viewports while preserving the same selected summary and workflow actions. The page also keeps a short "How This Page Works" card above the explorer so requirement context, selected-obligation focus, and the next move stay visible in-product. What is now available: - sync the seeded obligation baseline into the current project - create a custom obligation from the governance tab - create a custom regulation inline when the obligation needs a new source record - assign any normalized framework key to that regulation instead of choosing only from the seeded presets - assign the obligation and any custom regulation it creates to a reusable framework package - edit the currently selected obligation without leaving the Governance workspace - link the obligation to existing controls during creation - inspect regulation and linked-control context for the active obligation in the same page - inspect linked classifications, evidence-link posture, and recent version history for the active obligation in the same page - attach an existing evidence source directly to the selected obligation without leaving the Governance workspace - route draft and approved obligations back into the appropriate `Operations` queue when the next step belongs in the command center - move obligations through: - `draft -> approved` - `approved -> published` - `published -> retired` Current responsibilities: - browse obligations by framework, jurisdiction, and use case - browse obligations by explicit framework-package assignment when reusable overlay scope matters - inspect lifecycle state across draft, approved, and published obligations - review clause references and due cadence at a glance - review linked classifications, evidence references, and recent obligation versions before publication - create, edit, and advance project-scoped obligations without leaving the Governance workspace - load horizontal standards and seeded domain baselines, including full operational EU AI Act and ISO/IEC 42001 mapping baselines plus the banking example baseline - keep the selected obligation deep-linkable through the `record` query state so work can resume directly on the intended record Still deferred: - coverage-gap scoring and remediation automation beyond the current selected-record evidence workflow - more automated evidence-gap routing beyond the current queue handoff and manual evidence attachment The current summary supports inline search, same-page detail inspection, URL-backed record selection, edit-in-place workflow actions, direct evidence linking, and recent version inspection for the active obligation record. When possible, this page should link to the original evidence source instead of a duplicate copy. Domain baselines such as banking should be treated as configurable starters, not as special hard-coded framework classes that the platform is optimized around. --- # Governance Classifications Status: full guided classification workflow available in the Governance workspace. The `classifications` tab now surfaces the live governance classification decisions together with a full guided governance-side classification workflow. The command toolbar stays above the record explorer, and selecting a classification keeps a visible selected-classification pane beside the list on larger viewports while preserving the same workflow actions. The page also keeps a short "How This Page Works" card above the explorer so decision purpose, selected-classification focus, and the next move stay visible in-product. Current responsibilities: - run a step-based EU AI Act classification wizard from the Governance workspace - edit draft, in-review, and reassessment-required classifications in-place - rerun reassessment when a material change has already been flagged - link an existing workflow run, artifact revision, retained file, delivery evidence item, eval run, or human review directly to the selected classification - move classifications through: - `draft -> in-review` - `in-review -> approved` - `approved -> published` - `approved/published -> reassessment-required` - `published -> superseded` - inspect the latest classification run together with linked risks, controls, obligations, evidence references, recent runs, and recent version history - open linked risks, controls, and obligations directly from the selected classification card - route draft/review classifications back into the appropriate `Operations` queue when the next step belongs in the command center The wizard is intentionally step-based: 1. capture system and deployment context 2. answer prohibited, high-risk, and transparency trigger questions 3. review the derived category, rationale, and linked governance risks before saving The current summary supports inline search, same-page detail inspection, URL-backed record selection, direct cross-record navigation, and in-place wizard/review actions for the active classification record. The intent is to reuse existing project evidence instead of forcing teams to recreate it. --- # Governance Regulatory Updates Status: queue-based regulatory triage workflow available in the Governance workspace. The `regulatory-updates` tab now surfaces source-backed governance update records together with a queue-based governance triage workflow. The command toolbar stays above the record explorer, and selecting an update keeps a visible selected-update pane beside the list on larger viewports while preserving the same triage actions. The page also keeps a short "How This Page Works" card above the explorer so update purpose, selected-update focus, and the next move stay visible in-product. Current responsibilities: - sync the seeded EU AI Act and ISO/IEC 42001 source collections and baseline update queue items when you want the full framework-package mapping to include regulatory source coverage - create and edit regulatory source collections from the same governance tab - assign the selected source collection to a reusable framework package so update intake can inherit the intended overlay scope - ingest source-backed regulatory updates into the queue without leaving Governance - use configurable framework keys on source collections and ingested updates so standards and domain overlays can share the same operating model - assign the selected regulatory update to a reusable framework package during triage when the update belongs to a standard or domain overlay - classify updates as new, modified, or repealed - inspect derived obligation, control, and classification impacts - update triage status, owner, SLA date, and triage notes in place - review recent ingestion runs for the selected source collection - route new and assessment-stage items back into `Operations` when the next step belongs in the command center - link retained source material to the source collection through the existing folder-backed record model when human review needs a durable corpus When a source collection has an explicit framework package, newly ingested updates inherit that package by default unless triage later assigns a different one. The seeded source collections are starting points for source traceability. They identify official or operational monitoring sources, licensing posture, and framework tags, but teams still need to attach retained source material and review each update before treating it as a compliance decision. The current summary supports inline search, same-page detail inspection, URL-backed record selection, source-collection actions, and selected-update triage without introducing a second route family. --- # Governance Discovery Status: interactive discovery onboarding workflow available in the Governance workspace. The `discovery` tab now acts as the governance intake and onboarding workflow for unmanaged AI findings. The command toolbar stays above the record explorer, and selecting a finding keeps a visible selected-finding pane beside the list on larger viewports while preserving the same onboarding actions. The page also keeps a short "How This Page Works" card above the explorer so discovery purpose, selected-finding focus, and the next move stay visible in-product. Current responsibilities: - ingest new findings directly into the governance intake queue - review unmanaged AI findings, confidence levels, and sighting provenance - review MCP tool schema or descriptor drift findings created by governed MCP gateway observations - validate, reject, remediate, or onboard the selected finding in place - link the selected finding to the right classification, risk, and control baseline without copying evidence into a second silo - attach retained evidence from a selectable folder-file list instead of manually typing internal file IDs - route intake or assessment-stage follow-up back into `Operations` when the next step belongs in the governance engine shell The selected-record panel supports: - same-page triage updates for owner, status, notes, false-positive reason, and remediation notes - evidence-sighting inspection, including retained folder file labels and folder context when they exist - onboarding into an existing classification, risk baseline, and control baseline from the same tab Current operator notes: - the intake dialog now exposes a retained-file picker backed by the current project’s shared folder files - selected sightings show the retained file label and folder context when Gaia can resolve the linked file - MCP schema drift findings appear as network endpoint discoveries with gateway sightings and can mark the mapped Agent System as drifted and review-needed until an operator rejects, remediates, onboards, or accepts the reviewed observed schema as the new baseline. - Use **Accept observed baseline** only after confirming the MCP server change is legitimate; Gaia promotes the observed schema and descriptor fingerprints, remediates the drift finding, records audit evidence, and clears the linked Agent System drift state when no other MCP schema drift remains. - onboarding still links the finding into governed records without duplicating the original evidence payload The current workflow keeps discovery as a governance control plane: - source evidence remains anchored to the original sighting or retained file - onboarding links findings into governed records instead of creating a second evidence repository --- # Governance Explainability Status: interactive explainability review workflow available in the Governance workspace. Guided scenario: use [Governed Application From Scratch](../../handbook/ch11-capstone-build-and-ship/05-governed-application-from-scratch.md) for the full neo-bank tutorial, then use [Tutorials](/platform/support/tutorials) only to rehearse explainability review in-product. The `explainability` tab now acts as the governance review workflow for versioned explainability artifacts. The command toolbar stays above the record explorer, and selecting an artifact keeps a visible selected-artifact pane beside the list on larger viewports while preserving the same review actions. The page also keeps a short "How This Page Works" card above the explorer so artifact purpose, selected-artifact focus, and the next move stay visible in-product. Current operational anchors: - model review workflows - eval and approval flows Current responsibilities: - create and refine explainability artifacts from the Governance workspace - queue explainability generation jobs and record their outcomes - connect explanations to risk, control, classification, and approval records - link artifacts and review decisions to recent eval runs and eval reviews from selectable governance pickers instead of raw IDs - link verification runs and Decision BOMs when an explanation or review claim depends on a specific governance posture check or reconstructible runtime policy decision - submit artifacts for review and record approval or rejection decisions with reviewer notes - optionally bundle retained explanation material into folder-backed evidence packs when longer-term evidence retention is required The selected-record panel now supports: - same-page inspection of linked risks, controls, jobs, versions, and evidence links - direct navigation from the selected artifact into the linked eval run when the artifact is backed by evaluation evidence - ranked linked-evidence previews when the artifact carries more than one governed source - queue-aware routing back into `Operations` when the next step belongs in execution or review - review-state tracking without duplicating the underlying evidence source Current operator notes: - the artifact form now exposes `Eval run` and `Eval review` selectors populated from recent governance-linked evaluation records - evidence source pickers can also cite governance verification runs and Decision BOM records so explanation review can point to the actual posture check or decision reconstruction instead of a copied summary - the job outcome dialog uses a retained-file selector so evidence packs can be attached without copying opaque folder file IDs - the review dialog uses the same eval-review picker so governance decisions can cite the correct reviewer evidence trail - evidence links sourced from eval runs include an `Open eval run` shortcut in the selected record panel --- # Settings The **Project Settings** area centralizes access management, project configuration, and app-specific roles. ## Related pages - [Platform users and roles](#doc-settings-platform-users) - [App users](#doc-settings-app-users) - [App user roles](#doc-settings-app-user-roles) - [Configurable authentication](#doc-settings-configurable-auth) - [Project users](#doc-settings-project-users) - [Service accounts](#doc-settings-service-accounts) - [Project roles](#doc-settings-project-roles) - [Audit Trail](#doc-audit) - [Channels](#doc-conversations-channels) - [Localization](#doc-settings-localization) - [Model routing and failover](#doc-settings-model-routing) ## Tabs - **General:** Update project name, description, default language, similarity threshold, scheduled-job cadence, runtime conversation retention, project AI budgets, evidence posture, and the project's default invitation email subject and rich message template. See [Localization](#doc-settings-localization) for language verification, Slovenian configuration, and fallback behavior. View **Short UUID** (handy for API integrations) and **creation/last update timestamps** to track project age. The **Project Spec** section opens the dedicated **Project Spec** page in Delivery Management for Gaia's managed configuration and resource relationship diagram. The **Danger zone** includes a separate **Patch project** card for previewing and applying Project Spec patches or full-export RFC 6902 patches to the live project. Project logo uploads also drive the favicon shown on project pages, so transparent square-friendly marks work best. The **Danger zone** in this tab handles project export, patching, move, and deletion, each behind its own permission. If a project was created from an import, this page can also show a follow-up card when active configurations or channels still reference missing knowledge folders, or when the imported project expects a shared source folder that still needs to be created and attached before the project is fully ready to run. - **Topic taxonomy:** Map extracted topic labels into dashboard categories and chat groups. Dashboard topic widgets use these mappings after Topic Extraction results exist. - **Credentials:** Project admins create, rotate, and delete encrypted project credentials. Gaia shows only metadata and stable references such as `credential:external-service/api-key`; saved values cannot be viewed or exported. - **Auth:** Published app authentication is configured on each channel. Use [Configurable authentication](#doc-settings-configurable-auth) when an app needs an external broker, app-user sessions, or Gaia-issued runtime JWTs for partner gateways. - **Project users:** Manage who can access the project, assign roles, and distinguish inherited team access from explicit project assignments. See [Project users](#doc-settings-project-users). - **Service accounts:** Create project-scoped machine identities for webhook and MCP integrations, assign project roles, and manage Azure-style primary/secondary API key slots without tying automation to a real user. See [Service accounts](#doc-settings-service-accounts). - **Project roles:** Define custom project roles and permissions (admin-only), then assign them through [Project users](#doc-settings-project-users). See [Project roles](#doc-settings-project-roles). - **App users:** Create lightweight application users for end-user experiences, assign one or more app user roles, and merge or hand off app-channel access when identities change. See [App users](#doc-settings-app-users). - **App user roles:** Define role templates for those app users, including optional published-app cost budgets that can cap assigned AI usage. See [App user roles](#doc-settings-app-user-roles). - **Audit Trail:** Review a detailed history of project changes, inspect diffs, and create version tags. See [Audit Trail](#doc-audit). - **Conversations → Channels → Text:** Set the app slug used for `/apps/` entrypoints, configure a dedicated channel color mode (Light/Dark, default Light), split color editing between **Conversation** overrides and the shared **UI** theme, keep portal wording in the **Messages** tab, and use the **Portal** tab for banner, close-confirmation, frame, launcher, and link-URL styling controls. See [Channels](#doc-conversations-channels-text-chatbot). - **Conversations → Channels → Personal Assistant:** Configure a dedicated channel color mode (Light/Dark, default Light) that does not inherit the platform user theme, tune **Conversation** overrides separately from the shared **UI** theme, and keep the full-screen Personal Assistant experience distinct from Text-channel portal previews. See [Channels](#doc-conversations-channels-personal-assistant). ## Platform administration (admins) Platform administrators see dedicated **Dashboard**, **Users**, **Models**, and **Settings** tabs in the top header. - **Users:** Manage platform-wide operator lifecycle state and delegated platform roles. See [Platform users and roles](#doc-settings-platform-users). - **Models:** Manage the shared AI model catalog. Use **Import** to bulk load model definitions from a JSON file, including model-level built-in tools such as web search and code interpreter. Use **Sync Foundry** when you have a Microsoft Foundry Models endpoint and either an API key or managed identity access; Gaia previews deployed models from the endpoint, keeps the deployment name for runtime calls, stores the source model name for metadata refresh, and lets you choose which deployments to sync. Use the model **Routing** tab to make a logical model route across ordered tiers of deployment records: Gaia weight-balances within a tier and falls back to later tiers after transient provider failures, target-scoped `401`/`403` responses, or shared cooldowns. Follow [Model routing and failover](#doc-settings-model-routing) to configure targets, weights, attempts, cooldowns, validation, and authentication troubleshooting. Synced models can then use **Refresh Metadata** to scrape supported public provider pages for model type, size, modalities, context windows, pricing, supported APIs, API versions, built-in tools, reasoning capability notes, and attachment support when those details are available. If public page structure is incomplete, Gaia can use the default reasoning model with web search enabled to extract structured metadata from official public sources, including official source-provider pricing when Microsoft Foundry pricing is not listed. - **Settings:** Manage instance-wide settings stored in the platform settings table, including cross-instance transfer controls, AI FinOps budgets, and operational log persistence. Cross-instance project transfer is now fully configured from **Platform Settings** instead of relying on transfer-specific environment variables. Admins manage the destination allow list, source allow list, and current instance URL in one place. Operational log persistence is also controlled from **Platform Settings**. Environment variables provide the initial defaults, and admins can then tune the database log sink without restarting the server: enable or disable persistence, set the max pending queue size, batch size and interval, duplicate coalescing window, rate-limited drop-warning interval, circuit-breaker failure threshold, circuit-breaker cooldown, and settings poll interval. Console/runtime logging continues even when the database sink is disabled or temporarily in circuit-breaker cooldown. When adding models manually, provider options now include **Anthropic** alongside the existing OpenAI, cloud-provider, and local runtime options. Platform admins can also use **Refresh Metadata** on the **Models** page to fetch official provider metadata for supported models. Gaia shows a preview first, including context-window, supported-API, audio-pricing, per-minute pricing, and Azure API-version changes where the provider docs expose them, and applies updates only after confirmation. ## Access requirements Only users with settings permissions can view or edit settings. **Project roles** can be modified only by admins. Danger-zone actions in **Settings → General** require their own dedicated permissions for export, import/patch, move, and delete. Previewing or applying **Project Spec** patches uses the separate **Import project** permission. If you see a permission error, ask an admin to adjust your role. The **Credentials** tab is restricted to project admins. Runtime tools can resolve a project credential only when the reference is used inside the same project. ## Make a change 1. Select the relevant tab. 2. Update fields. Forms use inline validation and will disable **Save** until required information is provided. 3. Click **Save changes**. Toasts confirm success and the update becomes visible to everyone immediately. ## Runtime conversation retention Open **Project Settings -> General -> Runtime conversation retention** to enforce conversation retention in the runtime data path. - Turn on the retention switch. - Set **Retention days** to the number of days project conversations should remain available. - Use `0` when conversations should become immediately eligible for purge. - Click **Save Changes**. When enabled, Gaia checks the policy before normal conversation reads, writes, and list queries continue. Expired conversations are deleted from the conversation store, and the Audit Trail receives only redacted purge metadata: retention days, cutoff timestamp, conversation ID, and message-count information. Transcript text and searchable message content are not copied into the audit event. Governance state profiles in **Governance -> Evidence -> State & Memory** can still document the policy owner, storage boundary, access boundary, deletion trigger, review cadence, legal-hold posture, and evidence links. The runtime enforcement switch in **Project Settings -> General** is the operational control that applies the retention period. ## Topic taxonomy Open **Project Settings -> Topic taxonomy** when dashboard topic analysis needs rollups beyond raw Topic Extraction labels. - Create **Categories** for broad topic families. - Create **Chat groups** for more specific queues or conversation groups, optionally under a category. - Map each extracted topic label to a category, chat group, or both. Unmapped labels still appear in dashboard topic analysis under **Unmapped**, so you can add taxonomy gradually without losing visibility. ## Project credentials Open **Project Settings -> Credentials** to manage secrets used by project tools and bridge integrations. 1. Select **Add credential**. 2. Enter a lowercase path such as `external-service/api-key` and paste the value. 3. Save the credential, then copy its generated reference, such as `credential:external-service/api-key`, into the tool or bridge configuration. 4. Use **Rotate** to replace a value without changing its reference. Delete a credential only after removing every active reference. Gaia encrypts each value with a unique data key and wraps that key with the deployment's managed KMS or Key Vault key. The Credentials page and server actions return metadata only; values are never shown again, included in project exports, written to logs, or placed in audit events. Creation, rotation, deletion, and successful runtime access appear in the project Audit Trail. References are strict: - `credential:` resolves only from the current project. - `env:` explicitly opts into a platform-wide host environment fallback. - Literal values and missing references fail with `credential_not_configured` before Gaia calls the external service. ## Evidence posture Open **Project Settings -> General -> Evidence posture** when a project needs deployment, compliance, or interoperability proof tied to the selected operating model. - Use **Deployment and compliance evidence** for the hosting posture, operations owner, SIEM target reference, HA/DR reference, GDPR reference, EU AI Act reference, DORA reference, audit reference, and delivery reference. - Use **Lot B interoperability evidence** for the external platform or vendor profile, accountable owner, runtime boundary, Gaia access surface, profile-specific agent endpoint, platform tenant, connector identity, action scope, sandbox/test invocation, evidence-reader scope, Databricks linkage reference, certification or eval reference, support handoff, audit reference, and delivery reference. - Use references, environment-variable names, record IDs, or delivery artifact IDs. Do not store literal secrets, credentials, SIEM tokens, or customer-private annex content in these fields. Gaia shows whether each profile is ready, still needs customer details, or is blocked. The first enterprise-oriented default posture is **Dedicated Gaia-hosted**, but the project record should be updated if the customer selects a different hosting or vendor boundary. The evidence cards also show reviewer-ready summaries. A dedicated Gaia-hosted deployment is ready only after the operations owner, SIEM target, HA/DR, GDPR, EU AI Act, DORA, Gaia audit, and delivery references are present. A Lot B boundary is ready only after the selected vendor or platform profile, accountable owner, runtime boundary, Gaia access surface, certification or eval reference, support handoff, audit reference, and delivery reference are present. Databricks-owned paths also require the Databricks linkage reference, agent profiles require their endpoint or connector refs, business-agent profiles require tenant and test-invocation refs, and evidence-only reviewers require the evidence-reader scope ref. ## Proposal evidence Open **Project Settings -> Evidence** when a project needs a row-by-row proposal readiness pack. The proposal evidence matrix maps A1.1-A7.2 to: - the intended answer wording, including `Yes` and `Yes with customer refs`; - the current evidence readiness status; - the owning Gaia surface; - Gaia capability references; - customer evidence references, when present; - missing refs, blockers, warnings, and caveats. Use **AI FinOps evidence** to attach A3.1 refs from Platform AI FinOps, the explicit price catalog, reservation evidence mode, workload policies, Governance Operations decisions, cost-evidence dashboards, usage/cost exports, audit rows, delivery artifacts, and missing-price caveats. A3.1 remains a Gaia capability-ready row; these refs prove the customer-specific proposal pack without copying platform-owned settings into project settings. Evidence fields use searchable pickers and can create typed external evidence artifacts for customer documents, exports, tickets, or delivery refs. Use the export actions when reviewers need portable artifacts: - **Markdown**, **CSV**, and **JSON** export the current evidence matrix. - **Request** generates a customer evidence request from rows with missing refs, blockers, warnings, or caveats. - **Answers** generates proposal-answer draft wording from the same matrix source. - **Checklist** generates a finalization checklist that separates rows that are currently finalizable from rows that still need customer refs, caveat decisions, or blocker resolution. Rows that depend on customer topology, Databricks, runtime-governance review runs, SIEM, compliance, or Lot B vendor details stay in **Needs customer details** until those refs are recorded in the owning surfaces. A3.1 stays **Ready** as a Gaia capability row, but shows warnings and caveats until the FinOps customer/export refs are attached. Use the **Advanced: paste manual ref** control only for migration or support cases where Gaia cannot list the source yet. ## Guided setup after project creation Create a blank project when you need a new workspace shell for a team. If you use **Ask Gaia** in the create-project dialog, Gaia drafts the first scaffold before the project exists, then creates the real workspace only after you approve the preview. After the project opens, switch to [Gaia](#doc-platform-assistant) for guided build work such as adding agents, entities, workflows, document folders, delivery records, or governance assets through discussion. Gaia now uses the canonical project spec as the managed configuration layer for both new-project bootstrap and live project evolution. ## Project spec and backup export Use the two configuration/export surfaces for different goals: - **Project Spec:** Open **Delivery Management -> Project Spec** when you want to review the full managed-configuration diagram Gaia uses for bootstrap previews, published bundle layering, and live project evolution. Select a node to drill into its named dependencies and use **Open resource** to inspect the backing agent, config, registry entry, workflow, folder, or data-model resource in a new browser tab. The page is review-only. - **Patch project:** Use **Settings -> General -> Danger zone -> Patch project** when you want to paste or upload a partial Project Spec JSON patch, an RFC 6902 JSON Patch array that targets the Project Spec, or a full-export RFC 6902 patch for a project that was just imported. The patch field uses the structured JSON editor before previewing. Project Spec patches preview a managed-resource diff; full-export patches preview the patched export snapshot before Gaia merges it into the current project. - **Export Project:** Use the **Danger zone -> Export Project** action when you need the Gaia project export artifact for transfer, restore, or archival workflows. The export keeps portable project structure and version metadata, but omits runtime conversations, workflow runs, and embedded version snapshot payloads. - **Import during project creation:** Use the **Import** action from the team projects page when you need to create a new project from a Gaia export artifact, optionally with an RFC 6902 patch file applied before creation. After opening the imported project, you can still apply a matching full-export RFC 6902 patch from **Settings -> General -> Danger zone -> Patch project**. - **Overview:** Open **Delivery Management -> Overview** when you need Gaia's cross-surface readiness summary before deciding which underlying surface to fix. - **Evidence:** Open **Settings -> Evidence** when you need the proposal evidence matrix and row-by-row export pack. The project spec is the configuration truth for managed resources such as agents, configs, channels, execution protocols, skills, guardrails, legacy validators, tools, entity definitions, relationships, layouts, folders, workflows, and similar project structure. The Project Spec page renders those resources as a single dependency diagram so reviewers can see the full managed surface before approving changes. Runtime history such as conversations, stored records, uploaded files, workflow runs, eval runs, and logs remains outside the spec so live evolution can preserve it. ## Cross-instance project transfer Use cross-instance transfer when you need a full-fidelity copy of a project (records plus storage blobs) from one Gaia instance to another. For a first-time bootstrap, you can also use manual export/import: export the project from the source project's **Settings -> General -> Export Project** action, then open **Teams** on the destination instance, select **Import**, choose **Export file**, and choose the exported JSON file. Use this when the instances are not network-reachable yet or when you want a controlled file-based first copy. After the destination project exists, use [Delivery Versions](#doc-delivery-versions) for version-backed environment promotion. ### 1. Create a transfer token on the source project Open **Settings → General** on the source project and use **Cross-Instance Project Transfer**: - Set the destination host or URL. - Set token TTL (seconds). - Click **Create Transfer Token**. - Copy the one-time token immediately (it is shown once). ### 2. Start import on the destination instance From **Teams**, select **Import** and choose **Gaia instance** as the import source: - Enter source URL - Enter source project ID - Paste transfer token - Enter destination project name - Click **Run Preflight** - Click **Start Transfer** Preflight validates the destination instance URL, destination source-host allow list, source destination-host allow list, token state, source permissions, source reachability, and source manifest summary before Gaia creates the destination project. The dialog shows transfer run status and phase while the copy proceeds in the background. ## Role and access administration Use **Project roles** and **Project users** together: 1. Create a custom role in **Settings → Project roles** when the built-in `admin` and `user` roles are too broad or too narrow. 2. Assign that role in **Settings → Project users**. 3. Recheck the roster badges to confirm whether access is inherited from the team or set directly on the project. For detailed role-assignment steps, use [Project users](#doc-settings-project-users) and [Project roles](#doc-settings-project-roles) together. For machine-to-machine access, use [Service accounts](#doc-settings-service-accounts) instead of personal user API keys whenever possible. ## Real-life example > A platform admin migrated a production-ready project from a staging Gaia instance to a new team in the primary instance by issuing a short-lived transfer token and starting an import run from **Teams -> Import -> Gaia instance**. ## Tips - Use project-only external users for short-lived reviews instead of adding every reviewer to the parent team. - Use descriptive names for app user roles (for example, "Kiosk user") so it's clear where they apply. - Leave the App user role cost budget blank when the role should not add a role-level cap. - Use App user role cost budgets when published app users need stricter limits than internal operators using the same agent. - Use **Project Spec** in Delivery Management when you need to review the full managed configuration diagram before approving a change. - Use **Patch project** when you already know the partial configuration change you want to preview and apply to the live project. - The **Danger zone** in General includes destructive operations—double-check before confirming. - Use short token TTL values unless you actively need longer windows. - Keep the source and destination allow lists updated in **Settings** before issuing transfer tokens or starting imports. - Set the current instance URL and keep the source and destination allow lists up to date in **Settings** before using cross-instance transfer. - Themes support presets. Start with a preset close to your brand, then fine-tune colors. ## Troubleshooting - **Save button greyed out:** Check for required fields or pending network requests. - **Cannot invite a user:** The user may already belong to the team. Search by email/name or create a new app user instead. - **Theme not updating:** Ensure you saved changes under the correct channel (Text or Personal Assistant). Browser caches may require a hard refresh (⌘/Ctrl+Shift+R). - **Transfer preflight failed:** Verify the source URL, confirm the source and destination hosts appear in the relevant platform **Settings** allow lists, ensure the current instance URL is configured, and confirm the token has not expired or been used. - **Transfer run failed:** Open run details in the import dialog and resolve the reported issue (user/model mapping, ID collision, storage copy, or slug conflict), then retry. - **I want to inspect what Gaia will manage before approving a change:** Open **Delivery Management -> Project Spec** to review the full dependency diagram, or ask Gaia for a preview/diff before approval. - **Project imported or behaving inconsistently:** Open **Delivery Management -> Overview** and review the **Project configuration overview** first. It summarizes follow-up items across **Agent Runtime**, **Channels & Routing**, **Knowledge & Folders**, **Governance**, **Evals**, and **Delivery**, then links you directly to the owning surface for each gap. Runtime canvas and document-artifact tool or skill gaps also surface under **Agent Runtime** so you can confirm the required artifact bundle before rewriting prompts. The knowledge-folder follow-up card remains in **General** as the detailed grounding-specific view when folder attachments need repair. --- # Localization Gaia supports project and channel localization so teams can configure the language used in conversations, app portals, and user-facing channel messages. Use this page when you need to verify a Slovenian or multilingual experience before sharing a published app. ## Where localization is configured - **Settings -> General:** set the project's default language. - **Conversation header:** switch the language for an individual test conversation. - **Conversations -> Channels:** edit localized portal, banner, close-confirmation, and terms/privacy messages for published Text or Personal Assistant channels. - **AI Agents -> Agent Configuration:** edit multilingual welcome, thinking, and error messages for the active configuration. ## Configure Slovenian 1. Open **Settings -> General**. 2. Set the project default language to **Slovenian**. 3. Open the channel that owns the published app. 4. In the channel **Messages** tab, review every localized user-facing message that appears in the app shell. 5. Open **AI Agents -> Agent Configuration** and confirm the welcome, thinking, and error messages have Slovenian text where the demo path needs it. 6. Start a test conversation and set the conversation language to **Slovenian** in the conversation header. 7. Send a Slovenian prompt and confirm the transcript, configured messages, and visible app shell copy match the expected language. ## Fallback behavior If a specific message is not configured for the selected language, Gaia falls back to the project's default language and then to the default Gaia message. Keep the fallback in mind when validating a full-language demo: the existence of Slovenian as a selectable language is not the same as every custom channel message being translated. ## Evidence to capture - Settings screenshot showing **Slovenian** as the selected default language. - Channel **Messages** screenshot showing Slovenian portal or app-shell text. - Agent configuration screenshot showing Slovenian welcome, thinking, or error messages. - Conversation screenshot showing a Slovenian prompt and response in the selected language. ## Related pages - [Settings](#doc-settings) - [Channels](#doc-conversations-channels) - [Agent Configuration](#doc-agents-configs) - [Conversations](#doc-conversations) --- # Configure model routing and failover Use a deployment pool when one logical AI model should distribute requests across equivalent provider deployments and fail over when a target has a transient provider failure or a target-scoped authentication or permission failure. This is different from [Model Tier Routing](#doc-agents-model-tier-routing). Deployment-pool routing chooses a provider deployment for one model call. Model tier routing uses agents and configurations to choose a capability or cost tier for the conversation. ## Who can configure routing? Only platform administrators who can manage the shared model catalog can create model records or edit their routing settings. ## Before you create a pool Create and validate each deployment as its own model record first. 1. Open **Platform → Models**. 2. Add or edit the first deployment. 3. On **General**, set its provider, provider-specific model name, type, and supported APIs. 4. On **Provision**, configure the deployment endpoint, API version when required, and approved credential reference. 5. Save the model and run a representative conversation with a configuration that uses this deployment directly. 6. Repeat the same checks for every fallback deployment. Routing targets must use the same model type and compatible execution APIs as the logical model. A routing target cannot point to another deployment pool. Keep credentials separate for each provider resource or region. Do not copy literal keys into task descriptions, discussion comments, conversation messages, or troubleshooting exports. ## Create the logical routing model 1. From **Platform → Models**, add a model record that represents the deployment pool, or edit the logical model users should select in agent configurations. 2. On **General**, give it a clear name such as `Support model pool`. Match its model type and supported APIs to the deployment records it will route to. 3. Open **Routing**. 4. Turn on **Tiered weighted failover**. 5. Add the first tier and select one or more deployment models. 6. Set each target's **Weight**. Gaia uses weights only when choosing among enabled targets in the same tier. 7. Add lower tiers for ordered fallback. Gaia tries enabled targets in the current tier before moving to a lower tier. 8. Set **Max Attempts** when the pool should try fewer targets than are available. Leave it blank to allow every eligible target in the ordered tiers. 9. Set **Cooldown Seconds**. After a retryable target failure, Gaia temporarily avoids that target so subsequent calls prefer healthy deployments. 10. Save the logical model, then select it in the relevant agent configuration. ## Understand retry and failover behavior - Gaia may retry the same target before moving to another target. **Inside Info** reports the provider-attempt count and retry count for each routed target. - A retryable result, such as rate limiting, a timeout, a temporary network failure, or many provider `5xx` responses, can move the request to another eligible target. - Authentication and permission responses such as `401` and `403` are not retried against the same target. When the pool has another eligible target, Gaia records and temporarily avoids the failing target, then tries the next deployment because its endpoint and credential may be independent. If targets share the same broken credential or access policy, each target can still fail and the pool will end with an error. - Gaia moves to another target only when the failed model attempt produced neither partial content nor a proposed tool call. This prevents duplicate output or duplicate tool execution. A tool call completed earlier in the turn does not block failover for a later model invocation; its result remains part of the conversation context sent to the next target. - Targets in the same tier are selected by weight. Lower tiers are considered only after eligible targets in the current tier are exhausted. - **Max Attempts** counts routed targets, not the repeated provider attempts made against one target. - A target in cooldown is skipped while another healthy target is available. If every target is cooling down, Gaia still attempts the configured targets so the pool does not become permanently unavailable. ## Verify the failover path 1. Verify every target directly before testing the logical pool. 2. Start a new conversation using an agent configuration that selects the logical routing model. 3. Send a representative request and confirm the normal target succeeds. 4. In a safe test environment, reproduce a transient failure or target-specific `401`/`403` on the primary target. 5. Turn on **Inside Info** in the conversation and inspect **Model routing** on the assistant reply. 6. Confirm the trace shows the logical model, each selected target, provider attempts and retries, the reason Gaia continued or stopped, and the final target. If the channel automatically hands a terminal provider failure to live support, confirm the trace also reports the handoff result. 7. Open **Timeline** or the platform operational logs when you need the full turn correlation and timestamps. 8. Restore the primary target and confirm it becomes eligible again after the configured cooldown. Inside Info is an administrator/debug surface. Routing diagnostics do not appear in normal assistant messages or published portal responses. ## Troubleshoot a `401` or `403` Confirm that **Inside Info** shows the failing target and, when another target is eligible, the subsequent failover attempt. Then verify: - the endpoint belongs to the intended provider resource and region; - the provider-specific model or deployment name is correct; - the API version is supported by that deployment; - the configured credential belongs to the same resource and is active; - the authentication method and access policy are the same ones you validated when calling the target directly; - the failing request did not route to a different record with a similar display name. Record the conversation, message, turn, and provider request identifiers from Inside Info or operational logs when escalating the incident. These identifiers let operators correlate the user-visible turn without exposing prompts, credentials, or raw provider payloads. ## Troubleshooting - **No targets are available:** Add at least one enabled target with a weight greater than zero. Confirm the target still exists and is not itself a routing model. - **The wrong target is selected:** Check tier order, enabled switches, weights, cooldown state, and any attachment-pinned target behavior. - **Failover does not happen after `401` or `403`:** Confirm another target is enabled and allowed by **Max Attempts**. Failover also stops when the failing attempt already emitted partial content or proposed a tool call. - **Every target returns `401` or `403`:** Check whether the pool targets share the same credential reference, provider resource access, endpoint, or API-version error. Failover preserves availability only when another target is configured correctly. - **Failover stops too early:** Increase **Max Attempts** or leave it blank, and confirm lower-tier targets are enabled. - **Inside Info does not show Model routing:** Confirm the agent configuration uses the logical deployment-pool model, send a new turn after saving, and verify you have permission to view Inside Info. - **A target remains avoided:** Wait for **Cooldown Seconds** to elapse, then run a new turn. If failures continue, validate the target directly before returning it to normal traffic. ## Related pages - [Conversations and Inside Info](#doc-conversations-monitor-a-turn-with-inside-info) - [View a conversation timeline](#doc-conversations-dialogs-timeline) - [Model Tier Routing](#doc-agents-model-tier-routing) - [Dashboard](#doc-dashboard) --- # Platform Users and Roles Use **Users** in the platform header when you need to manage platform-wide operator access instead of project-specific access. This page combines two tabs: - **Users:** review lifecycle state, inspect direct admin responsibilities, and assign explicit platform roles. - **Roles:** define reusable custom platform roles on top of the built-in system roles. ## Access requirements You need platform-level access to open this page. - **View platform users** or **Manage platform users** lets you open the **Users** tab. - **View platform roles** or **Manage platform roles** lets you open the **Roles** tab. - Other platform permissions control whether delegated operators also see platform-wide tabs such as **Dashboard**, **Models**, **Settings**, **Tasks**, **Access Requests**, and discussion moderation controls. - **Manage** permissions are required to save changes. Platform admins automatically have access to both tabs. ## Users tab The **Users** tab is the central roster for platform operators. Each row shows: - user name and email - identity state: **Anonymous**, **Provisioned**, or **Signed in** - lifecycle state: **Active**, **Suspended**, or **Archived** - effective platform role badges - direct team-admin count - direct project-admin count ### Identity state Identity state explains authentication readiness, not access level. - **Anonymous:** the platform user is an anonymous account. - **Provisioned:** a platform user row exists, but Gaia has not seen an auth account or session for that user. - **Signed in:** the user has at least one auth account or active/historical session. Lifecycle state remains separate so an operator can be **Signed in** and **Suspended**, or **Provisioned** and **Active**. ### Lifecycle state Use the user dialog to change lifecycle state: - **Active:** the user can sign in and continue working normally. - **Suspended:** the user keeps historical ownership links, but Gaia blocks sign-in, rejects API-key access, and revokes current sessions. - **Archived:** the user stays in history and assignment records, but Gaia blocks access the same way as suspension. Gaia does not delete the user record when you suspend or archive an operator. ### Reassignment preflight Before Gaia allows suspension or archival, it checks whether the user is still the only active owner for: - a team admin responsibility - a direct project admin responsibility - a delegated custom platform role If coverage would be lost, the dialog shows the blocking teams, projects, or delegated roles and the lifecycle change stays blocked until responsibility is reassigned. ### Platform role assignment Use the same dialog to assign or remove explicit platform roles. - Built-in system role definitions are **admin** and **user**. - Custom platform roles appear alongside the system roles. - Users listed in `PLATFORM_ADMINS` still appear as implicit platform admins even if they do not have an explicit `admin` assignment saved in Gaia. ### Access assignments The user dialog also shows the user's direct access assignments across Gaia: - organization memberships - team memberships - project-user roles - app-channel user roles Platform admins can change a listed role or remove the assignment from the same dialog. App-channel assignments are shown separately from project-user assignments, so a person can be an app user for a project without also being an internal project user. If an app-channel row appears as an email match rather than a linked platform user, ask the user to sign in through the app entrypoint again after the role is corrected so Gaia can reconcile the app-user record with the platform identity. ### Duplicate email merge If Gaia shows two platform users with the same email after lowercasing, open the duplicate row and use **Duplicate email merge** to choose the canonical user. The merge moves login accounts, active sessions, direct organization/team/project assignments, platform roles, and app-channel identities to the canonical user when there is no conflicting assignment. The duplicate row is archived and its email is replaced with a Gaia tombstone address so future sign-in resolves to the canonical user. Use this instead of archiving a same-email duplicate manually. Archiving blocks that row from login, but a lower-case archived duplicate can still be the row Gaia resolves during case-insensitive login lookup. ## Roles tab Use the **Roles** tab to manage reusable platform role definitions. - **admin** and **user** are system roles. Gaia repairs their definition automatically and does not allow editing or deletion. - Custom roles can grant selected platform permissions such as user management, model management, or settings access. - Role assignment still happens from the **Users** tab. ## Recommended workflow 1. Create or update a custom role in **Roles** when the built-in roles are too broad. 2. Open **Users** and assign that role to the right operator. 3. If you need to suspend or archive a user, review the reassignment preflight first. 4. Review **Access assignments** when a user can sign in to Gaia but cannot reach a specific project app channel. 5. Use **Duplicate email merge** when two platform users represent the same person with different email casing. 6. Re-open the roster after saving to confirm the lifecycle badge and role badges match the intended outcome. ## Real-life example > A platform admin created a custom `model-operator` role, assigned it to one teammate, and then suspended a second operator only after Gaia confirmed that no team, project, or delegated role would be left without active coverage. ## Troubleshooting - **Save is blocked by reassignment preflight:** move the blocking team, project, or delegated role responsibility to another active operator first. - **The user still looks like an admin after removing the explicit role:** they may still be included in `PLATFORM_ADMINS`, which Gaia treats as an implicit admin assignment. - **A normal user shows `user` even without an explicit assignment:** Gaia uses `user` as the base system role when no elevated platform role is granted. - **A user can sign in to Gaia but not an app channel:** open their platform user dialog and check whether they have an **App** assignment for that project. Project-user access and app-channel access are separate. - **Two rows have the same email with different casing:** merge the unused duplicate into the canonical row. Do not rely on archive alone for same-email cleanup. --- # Configurable authentication Use the channel **App** tab when a published app needs a sign-in method that is not Gaia's default platform login. Platform administrators can still define platform-default providers under **Platform settings -> Authentication**. A common pattern is an external identity broker that behaves like OAuth 2.0 in the browser, returns an authorization code to Gaia, and requires Gaia's backend to exchange that code for a signed identity token. This page describes a vendor-neutral setup. Use it for partner, institution, or customer identity brokers where the user should become an **App user** for the channel instead of a full Gaia platform user. ## Related pages - [Settings](#doc-settings) - [App users](#doc-settings-app-users) - [App user roles](#doc-settings-app-user-roles) - [Channels](#doc-conversations-channels) - [Service accounts](#doc-settings-service-accounts) ## How Gaia resolves auth Gaia resolves published-app authentication from the channel first: 1. Channel 2. Organization instance by host 3. Platform default The channel decides whether authentication is required. Channel policy chooses the sign-in providers for that channel. Gaia does not use project-level authentication policy for published apps. ## What you configure Configurable auth has two parts: - **Provider registry:** the reusable provider definition, such as an external OAuth/HMAC broker, Microsoft Entra, email one-time code, or Gaia JWT issuer. - **Auth policy:** the channel-level rule that enables the provider set used when the channel's **Authentication** setting offers or requires sign-in. Provider secrets are never entered as raw values. Store only references supplied by your platform operator or secret manager, such as `env:PARTNER_AUTH_CLIENT_SECRET`. ## Example: external identity broker for a published app Use this pattern when the partner provides: - an authorization URL for browser redirect; - a token URL for backend code exchange; - a client ID; - a shared secret or signing secret reference; - a JWKS URL for verifying signed identity tokens; - a list of claims that identify the user and access attributes. ### 1. Confirm the callback URL Create the provider first, then copy the provider diagnostic callback URL from the channel **App** tab. The callback has this shape: ```text https:///api/auth/configurable//callback ``` Give that exact URL to the partner if their broker allowlists redirect URIs. ### 2. Create the provider Open the channel **App** tab and create a provider with adapter: ```text oauth2-hmac-broker ``` Use provider config like this, replacing names with the secret references and public URLs used by your environment: ```json { "authorizationUrl": "env:PARTNER_AUTHORIZATION_URL", "tokenUrl": "env:PARTNER_TOKEN_URL", "jwksUri": "env:PARTNER_JWKS_URI", "issuer": "env:PARTNER_ISSUER", "audience": "env:PARTNER_AUDIENCE", "clientId": "env:PARTNER_CLIENT_ID", "scopes": ["openid"] } ``` Use secret references like this: ```json { "clientSecretEnvVar": "env:PARTNER_CLIENT_SECRET", "hmacSecretEnvVar": "env:PARTNER_HMAC_SECRET" } ``` ### 3. Map identity claims At minimum, map the external subject. This becomes the stable external identity key for the app user. ```json { "subject": { "claimPath": "pairwise_id", "required": true }, "email": { "claimPath": "email" }, "displayName": { "claimPath": "name" }, "institution": { "claimPath": "home_organization" }, "accessLevel": { "claimPath": "user_status", "arrayMode": "first", "matches": [ { "type": "contains", "value": "student", "mappedValue": "student" }, { "type": "contains", "value": "staff", "mappedValue": "staff" } ] } } ``` Claim paths support dot paths and array indexes, such as `profile.identifiers[0].value`. Array claims can use exact or contains match rules when the partner sends values such as role URNs or status strings. ## Enable the policy In the channel **App** tab: 1. Set **Authentication** to **Required** or **Optional sign-in**. 2. Enable the provider you created in the **Auth policy** section. 3. Save the channel and the policy. For broker-based app login, Gaia creates or links an **App user** session by default. It does not create a synthetic platform user for pseudonymous identities. Conversations started by that app user are owned through the conversation participant record. ## Test the setup Use the partner's test or mock-login environment first if they provide one. 1. Open the published app login page at `/apps//login`. 2. Confirm the provider button appears. 3. Click the provider button. 4. Confirm the browser redirects to the partner broker. 5. Complete the partner test login. 6. Confirm the browser returns to Gaia and enters the app. 7. Start a conversation. 8. Check that the app user is linked to the external subject and that the conversation is visible to that app user. Expected behavior: - Gaia validates the returned state before exchanging the code. - Gaia exchanges the code from the backend, not from the browser. - Gaia verifies the returned JWT against the provider JWKS. - Gaia stores the app session as a hashed cookie token. - Gaia links the external subject to an App user. - The conversation has no platform `createdBy` user when the visitor only has app-user identity. ## Troubleshooting - **Provider button does not appear:** Confirm the provider is active and enabled in the channel auth policy. - **Redirect is rejected by the partner:** Confirm the provider callback URL exactly matches the URI allowlisted by the partner. - **Callback returns invalid state:** Restart the login flow from Gaia. State values are short-lived and single-use. - **Token exchange fails:** Confirm the token URL, client ID, and HMAC secret reference are correct and available to the Gaia runtime. - **JWT verification fails:** Confirm the issuer, audience, and JWKS URI match the partner test environment. - **User signs in but cannot access the app:** Confirm the policy is attached to the channel that owns the app slug, and confirm the claim mapping resolves a required subject. ## Outbound Gaia runtime JWTs Some partner gateways need Gaia to send a short-lived signed JWT when Gaia calls them. That is separate from browser login. Use a `jwt-issuer` provider and outbound token policy when the partner needs: - Gaia issuer value; - JWKS or OIDC discovery URL; - audience; - token TTL; - claims such as subject, project, channel, institution, segment, or access level. The public discovery endpoints are: ```text https:///.well-known/openid-configuration https:///.well-known/jwks.json ``` Keep JWKS public unless the partner and platform operator agree on a private network or authenticated JWKS access model. --- # App user roles Use **Settings -> App user roles** to define reusable role templates for published app users. App user roles help you keep end-user access and behavior consistent across lightweight app users. They are separate from platform and project roles, which control access to the signed-in Gaia workspace. ## Related pages - [Settings](#doc-settings) - [Project roles](#doc-settings-project-roles) - [Project users](#doc-settings-project-users) - [Channels](#doc-conversations-channels) - [Usage billing and quotas](#doc-platform-dashboard-usage-billing-and-quotas) ## What you can do - Create reusable role templates for published app experiences. - Add a short description so operators know where a role belongs. - Set optional AI budgets for app users assigned to the role. - Review which roles are system-managed versus custom. - Edit or remove custom roles when requirements change. ## Create a role 1. Open **Settings -> App user roles**. 2. Click **Add**. 3. Enter a role name. 4. Optionally add a description. 5. Optionally enter weekly, monthly, or yearly AI budgets when app users on this role need a shared usage cap. 6. Click **Save**. ## Edit a role 1. Open **Settings -> App user roles**. 2. Find the role in the table. 3. Click the edit action. 4. Update the name, description, or cost budget. 5. Click **Save**. System roles stay protected. You can view them and use them for assignments, but Gaia prevents changes that would break the built-in default role behavior. ## How cost budgets work Budget fields are optional. Blank means unlimited. - Leave a budget blank when the role should not cap that period. - Set weekly, monthly, or yearly cost budgets when each app user assigned to the role needs a cap across the project. - Role budgets apply per app user across all channels and agents while the role is assigned. - If an app user has multiple assigned app user roles with budgets, Gaia evaluates each role and uses the strictest exhausted, missing-price, or lowest-remaining cost budget. - Legacy per-turn orchestrator token caps still protect a single turn when set, but blank legacy values are unlimited and are not AI FinOps spend budgets. Use this when a shared orchestrator should stay flexible for operators but tighter for a kiosk, portal, embedded assistant, or other end-user channel. For evidence that connects role cost budgets with service-account/API-key attribution and Platform Dashboard exports, see [Usage Billing And Quotas](#doc-platform-dashboard-usage-billing-and-quotas). ## Access requirements - Viewing app user roles requires permission to view app user roles or app users. - Creating, editing, or deleting roles requires permission to manage app user roles. If the page or actions are unavailable, ask a project admin to adjust your project role. ## Real-life example > A team runs several public app channels for the same customer base. The **Visitor** app user role has a monthly cost budget, so each visitor has one cap across the portal, embedded widget, and assistant agents. ## Tips - Use role names that match the audience, such as `Visitor`, `Kiosk`, or `Partner reviewer`. - Keep budgets blank until you have a concrete reason to cap usage. - Use role budgets to protect shared project capacity across channels and agents. ## Troubleshooting - **The role budget did not reset yet:** Weekly budgets reset at the start of the UTC week, monthly budgets at the start of the UTC month, and yearly budgets at the start of the UTC year. - **The budget feels lower than expected:** Check app-user role, agent, channel, project, team, organization, and instance budgets. Gaia uses the strictest exhausted or lowest-remaining limit. - **A user still gets the smaller budget after adding another role:** If multiple assigned roles set budgets, Gaia uses the strictest one. --- # Project users Use **Settings → Project users** to control who can access a specific project, whether their role is inherited from the team, and whether they are a project-only external participant. For machine-to-machine integrations, use [Service accounts](#doc-settings-service-accounts) instead of adding another human user and sharing that person’s API key. ## Related pages - [Settings](#doc-settings) - [Project roles](#doc-settings-project-roles) - [Audit Trail](#doc-audit) ## What you can do - Review the full project roster with role, role source, and membership origin. - Review **Identity** and **Lifecycle** badges separately from project role assignment. - Distinguish **Team Member** access from **External User** access at the project level. - Add an existing platform user to the project. - Create a new lightweight project participant and add them directly to the project. - Assign or change the project role used for that member. - Send or resend an invitation email from the user row. - Remove project-only external users when the review or delivery window ends. ## Read the roster Each row shows: - **Name** and **Email** for the user account. - **Identity** such as **Provisioned** or **Signed in**, based on whether the platform user has authenticated. - **Lifecycle** such as **Active**, **Suspended**, or **Archived**, kept separate from identity state. - **Role** as a badge, such as `admin`, `user`, or a custom project role. - **Inherited** versus **Project role** to show whether access comes from team membership or an explicit project assignment. - **Team Member** versus **External User** to show whether the user belongs to the parent team. This split is useful during audits because a user can still have project access even when they were added directly to the project instead of through the team. ## Add an existing user 1. Open **Settings → Project users**. 2. Click **Add User**. 3. Keep **Find Existing User** selected. 4. Search by email address or full name. 5. Choose the project role to assign. 6. Click **Add User**. Use this path when the person already has a Gaia account and only needs project-level access. ## Create and add a project-only user 1. Open **Settings → Project users**. 2. Click **Add User**. 3. Switch to **Create New User**. 4. Enter name and email. 5. Choose the project role to assign. 6. Click **Create & Add User**. Use this path for short-lived reviewers, external auditors, or other collaborators who do not need broader team access. ## Change a role assignment 1. Find the user in **Project users**. 2. Click the edit action in the **Actions** column. 3. Select the new project role. 4. Click **Update Role**. Role changes apply immediately and are visible in the roster badges. ## Send an invitation email Use the mail action in a project-user row to **Send invite** or **Resend invite**. Gaia opens an editor with the project's invitation email template, lets you adjust the full-width subject and rich message, and provides an optional login link field. The sent email uses the message body shown in the editor; Gaia does not append a separate sign-in button. Plain `http` and `https` URLs in the message are sent as links. The suggested login link is copyable, but Gaia does not automatically guess which app entrypoint you want to include. Invitation email sends are explicit. Creating a project user or changing a role does not automatically send mail, and sending an invitation email does not create extra memberships. ## Remove an external user Project-only external users can be removed directly from the roster. 1. Find the external user row. 2. Click the delete action in **Actions**. 3. Confirm the removal. Inherited team members are managed through team membership rather than this project-only removal path. For app-user duplicate cleanup or app-channel history hand-off, use [App users](#doc-settings-app-users). ## Access requirements - Viewing the roster requires **View project users** permission. - Adding, removing, or changing assignments requires **Manage project users** permission. - Available roles come from **Settings → Project roles**. ## Real-life example > A governance lead creates a read-only reviewer role, then uses **Project users** to add an external auditor for a two-week controls review without granting the auditor full team membership. ## Tips - Prefer team membership for long-lived delivery contributors and project-only access for time-boxed reviewers. - Use descriptive custom role names so the roster is self-explanatory during audits. - Recheck **Inherited** versus **Project role** when debugging unexpected access. ## Troubleshooting - **User not found:** Verify the email or name, or switch to **Create New User** if the person does not have an account yet. - **Role missing from the selector:** Create or update the role first in [Project roles](#doc-settings-project-roles). - **Cannot remove a user:** Team members inherit access from the team, so remove or change their team membership instead. --- # Project roles Project roles define which parts of the platform a project member can view or manage. Roles are built from a set of permissions grouped by feature area (Conversations, Data model, Delivery, Settings, and more). ## Related pages - [Settings](#doc-settings) - [Project users](#doc-settings-project-users) - [Audit Trail](#doc-audit) The **AI agents** permission group also includes **Manage config defaults**, which controls who can mark a configuration as active or set it as the default for an agent. Guardrail access uses dedicated permissions in the same group: - **View guardrails:** Open the shared guardrail registry and inspect configuration assignments. - **Modify guardrails:** Create immutable versions, update metadata and governance-policy links, and delete unassigned entries. This permission implies **View guardrails**. Copying an agent from another project requires both **Manage agents** and **Import project**, because Gaia imports the selected agent bundle into the current project with the same guarded merge pipeline used for managed project resources. The **Conversations** permission group now separates document-folder access from the core conversation workspace: - **View folders:** Open the Document Folders workspace, inspect shared folders, and use folder search. - **Manage folders:** Create folders and administer folder access across the project. - **View conversations:** Required in addition to folder access when a role should open or start folder-linked conversations. The **Discussions** permission group controls access to project discussion boards inside Delivery: - **View discussions:** Access and participate in project discussions. - **Manage discussions:** Create, edit, and moderate discussion topics and comments. Settings-related permissions are split into focused groups such as **Project settings**, **Project transfer**, **Danger zone**, **Project users**, **Project roles**, **App users**, **App user roles**, and **Audit trail**. Use these instead of defaulting every operator to `admin`. The **Danger zone** group separates the highest-risk actions in **Settings → General**: - **Export project:** Download a portable project export and open the read-only **Project Spec** page in Delivery Management. - **Import project:** Preview or apply **Project Spec** patches and full-export RFC 6902 patches inside **Settings → General → Danger zone → Patch project**, and run other guarded in-place import flows such as copying agents from another project. Full backup import from an unpatched Gaia export file is still handled from the team import flow when creating a new project. - **Move project:** Move a project to another team you administer. In **Settings → General**, Gaia asks you to pick the target organization first, then the target team, and nested teams appear as slash-separated paths. - **Delete project:** Permanently remove a project and all project data. ## Built-in roles - **admin:** Full access to every project area. This role is not editable. - **user:** Can run and view conversations and document folders. This role is not editable. ## Create a custom role 1. Open **Settings → Project roles**. 2. Click **Add role**. 3. Enter a name and description. 4. Select permissions from the checklist. (Manage permissions automatically include the corresponding view permission.) 5. Click **Save**. ## Assign roles to members 1. Open **Settings → Project users**. 2. Pick a member. 3. Choose the role from the **Role** selector. For full roster and assignment details, see [Project users](#doc-settings-project-users). ## Delete a role You can delete custom roles that are not currently assigned to any project member. ## Real-life example > A project admin creates a "Reviewer" role with read-only access to Conversations and Evals, then assigns it to an external auditor for a short compliance review. Another common pattern is a governance reviewer role with **View project users**, **View project roles**, and **View audit trail** so security or compliance reviewers can inspect access decisions without changing them. ## Access requirements Only **project admins** can create, edit, or delete project roles. --- # Service accounts Use **Settings → Service accounts** to create project-scoped machine identities for webhook, MCP, and other integration traffic that should not run with a real person’s permissions. ## Related pages - [Settings](#doc-settings) - [Project roles](#doc-settings-project-roles) - [Project users](#doc-settings-project-users) - [Ingestion webhook](#doc-data-model-ingestion-webhook) - [Channels](#doc-conversations-channels) - [Usage billing and quotas](#doc-platform-dashboard-usage-billing-and-quotas) ## What you can do - Create a non-loginable service account for one project. - Assign a built-in or custom project role to control what that integration can access. - Activate or deactivate the account without deleting it. - Manage separate **Primary** and **Secondary** API key slots for each service account. - Regenerate one key while the other stays valid so integrations can rotate credentials with less downtime. - Review whether each key slot is configured and when the service account was last used. - Attribute AI usage to service-account traffic when runtime calls include the machine principal. Usage billing exports can separate service-account/API-key-slot usage from human user usage for project and organization showback. For reviewer evidence that combines API-key-slot attribution with cost budgets, request limits, and Platform Dashboard exports, see [Usage Billing And Quotas](#doc-platform-dashboard-usage-billing-and-quotas). ## Create a service account 1. Open **Settings → Service accounts**. 2. Click **New**. 3. Enter a descriptive name and optional description. 4. Choose the project role the integration should use. 5. Set the account status. 6. Click **Save**. 7. Open **Access keys** and generate either the **Primary** or **Secondary** key. 8. Copy the generated key immediately. Use names that describe the external system or workflow, such as `ERP webhook ingest` or `Customer support MCP bridge`. ## Send requests Gaia accepts either of these headers for service accounts: - `X-API-Key: ` - `Authorization: Bearer ` The bearer format is only a transport wrapper for the same opaque key. It is not an OAuth 2.0 token flow. ## Manage access keys - Open **Access keys** for the service account to manage the **Primary** and **Secondary** slots. - Use **Generate** to create a key in an empty slot. - Use **Regenerate** on one slot while clients are still using the other slot, then switch the external system over and revoke the old key. - Use **Revoke** when you want to disable a specific key without deleting the service account itself. Gaia only shows a newly generated key once per dialog session. Existing configured keys stay masked because Gaia stores only their hashes. ## Access requirements - Viewing service accounts requires **View project users** permission. - Creating, editing, deleting, rotating, or revoking service accounts requires **Manage project users** permission. - Available service-account roles come from **Settings → Project roles**. ## Tips - Prefer one service account per integration or trust boundary. - Use the secondary slot as a standby key for planned rotations. - Keep descriptions specific so audits can tie the account to a real external dependency. - Use custom project roles instead of reusing broad admin access when an integration needs only one narrow capability. - Deactivate unused accounts before deleting them if you want to preserve the object for review. ## Troubleshooting - **Requests return 403:** Check that the service account is active and its project role includes the required permission. - **Requests return 401 on MCP:** Confirm the client is sending either `X-API-Key` or `Authorization: Bearer`. - **The key is lost:** Regenerate the affected key slot. Gaia does not reveal stored keys after creation. - **Role missing from selector:** Create or update the role first in [Project roles](#doc-settings-project-roles). --- # App users Use **Settings → App users** to manage project-scoped app identities for end-user experiences, text channels, Personal Assistant channels, folders, and app-user roles. App users are separate from [Project users](#doc-settings-project-users). Project users control signed-in workspace access. App users control access and identity inside published app and channel experiences. ## Related pages - [Settings](#doc-settings) - [App user roles](#doc-settings-app-user-roles) - [Project users](#doc-settings-project-users) - [Channels](#doc-conversations-channels) ## What you can do - Create lightweight app users for project app experiences. - Assign one or more app user roles. - Review **Identity** and **Lifecycle** badges so invitation-stage, anonymous, provisioned, and signed-in users are not confused with access lifecycle state. - Send or resend an invitation email from an app-user row without changing that user's app access. - Edit app-user names, emails, and role assignments. - Remove app users that no longer need app-channel access. - Merge duplicate app users when two linked accounts use the same email with different capitalization. - Hand off app-channel history and folder access from one app user to another. ## Add or edit an app user 1. Open **Settings → App users**. 2. Click **Add** or edit an existing app user. 3. Enter the app user's name and email. 4. Assign one or more app user roles. 5. Click **Save**. Use app-user roles to control what the app user can do inside published app experiences. Use project roles only when the same person also needs signed-in workspace access. ## Identity, lifecycle, and invitations The roster separates two concepts: - **Identity** shows where the person is in authentication: **Invited** for an email-only app user who has not signed in, **Anonymous** for anonymous app/platform users, **Provisioned** for a platform user row that does not yet have an account or session, and **Signed in** after Gaia has seen an auth account or session. - **Lifecycle** shows platform account state: **Active**, **Suspended**, **Archived**, or **N/A** for email-only app invites that do not yet have a platform account. Use the mail action in a row to **Send invite** or **Resend invite**. The dialog opens with the project's invitation email template, lets you edit the full-width subject and rich message, and includes an optional login link field plus a copyable suggested login URL. The sent email uses the body shown in the editor, without a separate appended sign-in button, and plain `http` and `https` URLs are sent as links. Sending the email does not add project membership and does not change app-user access. ## Merge or hand off app users Project admins can use **Merge or hand off app users** for two related jobs: - **Duplicate email** merges app-user identity when two linked accounts have the same email after lowercasing. This is useful when a person first joined with one email capitalization and later authenticated with another. - **Hand-off** grants app-channel access from a source app user to a target app user even when their emails differ. Use this when responsibility for text-channel conversations, Personal Assistant conversations, or folders needs to move to another person. 1. Open **Settings → App users**. 2. Click **Merge or hand off app users**. 3. Choose **Duplicate email** or **Hand-off**. 4. For duplicate email cleanup, select the duplicate email group. 5. Choose the **Source app user** that should lose direct project or app-channel access. 6. Choose the **Target app user** that should keep or receive app access. 7. Click **Preview merge** or **Preview hand-off** and review the summary. 8. Click **Merge app users** or **Hand off app users**. Duplicate email cleanup keeps historical audit entries and creator fields as they were, moves project app-user content to the target user, and removes the source user's direct project assignment when possible. Gaia only allows duplicate cleanup when the two emails match after lowercasing. Hand-off keeps historical audit entries and creator fields as they were, grants the target app user access to source-created text and Personal Assistant channel conversations, grants the target access to related folders, moves project app-user content to the target user, and removes the source user's direct project assignment when possible. If the source user still has access through team membership or another inherited path, resolve that access path before merging or handing off. ## Access requirements - Viewing app users requires **View app users** permission. - Adding, removing, or changing app users requires **Manage app users** permission. - Merging duplicate app users or handing off app users requires project admin access. - Available app roles come from **Settings → App user roles**. ## Troubleshooting - **Cannot edit app users:** Ask a project admin to grant **Manage app users** or make the change for you. - **Role missing from the selector:** Create or update the role first in [App user roles](#doc-settings-app-user-roles). - **Cannot merge duplicate app users:** Confirm the two linked accounts use the same email after lowercasing and that the source user does not still inherit access through team membership. - **Cannot hand off app users:** Confirm the source and target are different project-scoped app users and that the source user does not still inherit access through team membership.