Agent Orchestrator

When you ask Studio to "find our top 10 customers by revenue and build a segment for re-engagement," the AI doesn't just answer — it plans. It breaks the request into steps, selects the right tools for each step, executes them in sequence, and assembles the results into a coherent response. Understanding this orchestration makes you a more effective collaborator.

Understand the internal logic that drives how Studio processes requests — task decomposition, tool selection, multi-turn execution, and context management — so you can write better prompts, anticipate the AI's behavior, and troubleshoot when things don't go as expected.

• Signed in to Treasure AI Studio (Getting Started)
• Familiarity with the chat interface (AI Chat Interface)
• Recommended: active skills for your domain (Skills & Marketplace)

The AI is not a search engine — it's an agent that plans, acts, and adapts. Knowing how it thinks helps you:

• Write better prompts — Specific requests produce more efficient execution plans
• Predict tool selection — Understanding which tools exist helps you guide the AI toward the right approach
• Debug unexpected results — When output isn't right, you can trace back through the tool calls to find where the logic diverged

Every message you send follows the same orchestration pipeline. Here's what happens behind the scenes:

Before the AI reads your message, Studio assembles its working context:

This layered context is what makes the AI "know" your environment. A request like "query the top customers" works because the project context includes your default database and the active Trino skill teaches the AI to use td_interval().

The AI reads your message in the context of everything above and decomposes it into a plan. This happens during the thinking phase — the "Thinking..." indicator you see before the response begins.

Simple request (single step):

"How many rows are in the pageviews table?"
→ Plan: Run one query (SELECT COUNT(*) FROM pageviews)

Complex request (multi-step):

"Find our top 10 customers by revenue, build a segment for them,
 and create an email campaign for re-engagement"
→ Plan:
   1. Query customer revenue data (Trino SQL)
   2. Analyze results to define segment criteria
   3. Generate segment YAML with the criteria
   4. Validate the segment definition
   5. Generate email campaign content
   6. Preview the campaign

The AI doesn't always announce the plan explicitly, but you can see it unfold through the sequence of tool calls in the chat stream.

For each step in its plan, the AI selects from the available tools based on:

Once a tool is selected, the AI executes it and streams the results back in real time:

1. Tool call card appears — Shows the tool name, a description of what it's doing, and a loading indicator
2. Execution runs — The command, query, or API call is executed server-side
3. Result returns — The tool call card updates with the result (or error)
4. AI processes result — The AI reads the result and decides on the next step
5. Cycle repeats — Steps 1-4 repeat for each planned step until the task is complete

You can expand any tool call card to see the exact input and output — the query that was run, the API response that came back, or the file that was written.

After all steps complete, the AI assembles the results into a coherent response:

• Text summary — Key findings, recommendations, or explanations
• Generated files — Charts, tables, or dashboards rendered in the file panel
• File outputs — Generated PPTX, DOCX, XLSX, or PDF files available for preview and download
• Next step suggestions — The AI often suggests follow-up actions based on the results

Complex analytical work rarely fits in a single message. The orchestrator is designed for iterative, multi-turn workflows where each message builds on the previous results.

The AI maintains full context of the conversation, including:

• Every query it ran and the results returned
• Every file it generated or modified
• Your corrections and refinements ("No, filter by the US region only")
• Tool call outcomes (including errors and retries)

This means you can say "Now break that down by region" and the AI knows which query result you're referring to, which database to query, and which skill patterns to apply.

If you close and reopen a conversation:

• Web — The full session state is restored from the server, including tool call history and context
• Desktop — The session resumes from a persisted transcript, restoring full conversation state without re-running tools

Long conversations eventually approach the AI's context window limit. Studio manages this automatically:

Understanding common orchestration patterns helps you anticipate the AI's behavior:

The most common pattern for data analysis:

You: Show me the trend in daily signups over the last 90 days

AI: 1. [Tool: tdx query] Runs Trino SQL with td_interval(-90d)
    2. [Thinking] Analyzes the result set — identifies trend, spikes, anomalies
    3. [Tool: open_file] Opens a generated HTML chart in the file viewer
    4. [Text] Summarizes findings: "Signups show a 23% upward trend..."

Common for CDP configuration tasks:

You: Build a segment for users who purchased in the last 30 days

AI: 1. [Tool: tdx ps desc] Inspects parent segment schema for available attributes
    2. [Tool: tdx query] Queries to verify data availability and row counts
    3. [Thinking] Determines the correct segment rule operators and field names
    4. [Tool: Write] Generates segment YAML definition
    5. [Tool: tdx sg validate] Validates the YAML against the CDP API spec
    6. [Text] Presents the validated segment with a push command

Common for troubleshooting workflows or queries:

You: Why did workflow daily_etl fail last night?

AI: 1. [Tool: tdx wf sessions] Lists recent workflow sessions
    2. [Tool: tdx wf attempt logs] Reads the failure logs from last night's run
    3. [Thinking] Identifies the root cause (e.g., table not found, timeout)
    4. [Text] Explains the failure and suggests a fix
    5. [Tool: Write] Generates an updated .dig file with error handling

Common for building deliverables:

You: Create a quarterly business review deck from Q1 data

AI: 1. [Tool: tdx query] Runs multiple queries for revenue, users, engagement
    2. [Tool: open_file] Opens generated HTML charts for each metric
    3. [Tool: Write] Creates PPTX with slides for each section
    4. [Text] Presents the deck for review

You: Add a slide comparing Q1 to Q4 and make the revenue chart a stacked bar

AI: 5. [Tool: tdx query] Runs comparative query
    6. [Tool: Write] Updates the PPTX with the new slide and chart type
    7. [Text] Presents the updated deck

For users who want to understand the full system:

After reading this guide, you can:

• Explain the five stages of request processing (context assembly, decomposition, tool selection, execution, result assembly)
• Describe how the AI decides which tool to use for a given task
• Use /compact and /context to manage long conversations
• Trace a multi-step execution by expanding tool call cards in the chat stream
• Write prompts that produce efficient execution plans

• AI Chat Interface — Learn the chat UI interactions in detail
• Skills & Marketplace — Configure skills that guide orchestration
• In-Session Memory — How the AI remembers context within a session
• Security & Permissions — Security and audit logging
• TDX Commands — The CLI tools the orchestrator calls