# 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.

Note
Every action the AI takes is visible in the chat stream. Tool calls appear as expandable cards showing the exact command, query, or API request that was executed. Nothing happens in the background — you can verify every decision the AI makes before acting on the results.

## Objective

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.

## Prerequisites

- Signed in to Treasure AI Studio ([Getting Started](/products/ai-studio/getting-started))
- Familiarity with the chat interface ([AI Chat Interface](/products/ai-studio/chat/chat))
- Recommended: active skills for your domain ([Skills & Marketplace](/products/ai-studio/skills/skills))


## Why Understanding Orchestration Matters

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


## How a Request Is Processed

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

### 1. Context Assembly

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

| Context Layer | What It Contains | Source |
|  --- | --- | --- |
| **System prompt** | Core behavior rules, available tools, execution environment | Platform (built-in) |
| **Project context** | Project instructions, default database, custom rules | Your project settings |
| **Active skills** | Domain-specific playbooks (SQL patterns, segment schemas, etc.) | Your skill selections |
| **Conversation history** | Prior messages, tool results, and AI responses in this session | Current chat |
| **In-session memory** | Key facts the AI has noted during the conversation | AI-maintained (see [In-Session Memory](/products/ai-studio/chat/in-session-memory)) |


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()`.

Technical Note
Context is assembled at session start and updated as the conversation progresses. Skills are locked at session start — changing skill selections mid-conversation requires starting a new chat. Project context and conversation history update in real time.

### 2. Task Decomposition

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.

Pro Tip
For complex tasks, start your request with "Plan first, then execute:" — this prompts the AI to show its execution plan before taking action, giving you a chance to adjust before any tools are called.

### 3. Tool Selection

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

| Factor | How It Influences Selection |
|  --- | --- |
| **Task type** | Query tasks → Bash with `tdx query`, file generation → write tools, data exploration → `tdx describe` |
| **Active skills** | Skills teach the AI tool-specific patterns — the Trino skill guides it toward `tdx query -e trino` instead of generic SQL |
| **Prior results** | Output from step N informs tool choice for step N+1 — a failed query might trigger the optimizer skill |
| **User instructions** | Explicit direction ("use Hive for this") overrides the AI's default choice |


#### Available Tool Categories

| Category | Tools | What They Do |
|  --- | --- | --- |
| **Query execution** | `tdx query` via Bash | Run Trino/Hive SQL against your Treasure AI databases |
| **Data exploration** | `tdx databases`, `tdx tables`, `tdx describe` | Browse databases, list tables, inspect schemas |
| **File operations** | Read, Write, Edit, Glob, Grep | Read and write files in the working directory |
| **CDP operations** | `tdx ps`, `tdx sg`, `tdx journey` | Manage parent segments, child segments, and journeys |
| **File presentation** | `open_file` | Display generated files (HTML charts, documents, images) in the file viewer |
| **Workflow management** | `tdx wf` commands | Create, monitor, and debug Treasure Workflows |
| **External integrations** | MCP server tools (when connected) | Query Google Calendar, search Glean, manage HubSpot contacts |


### 4. Execution and Streaming

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.

Chat stream showing multi-step execution with expandable tool call cards
### 5. Result Assembly

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


## Multi-Turn Orchestration

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.

### Conversation Continuity

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.

### Session Resumption

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


Technical Note
Studio uses session-level state resumption rather than replaying the conversation as text. This preserves the AI's full internal context, including tool results and reasoning chains, so reopened conversations behave identically to continuous ones.

### Context Management for Long Conversations

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

| Mechanism | What It Does |
|  --- | --- |
| **Auto-compact** | When context fills up, the AI summarizes older messages while preserving recent context and key facts |
| **`/compact` command** | Manually trigger compaction to free context space |
| **`/context` command** | Check how much context is currently in use |
| **`/clear` command** | Clear the conversation and start fresh with a clean context |


Pro Tip
For long analytical sessions, use `/compact` proactively before starting a new analytical thread. This preserves the key findings from earlier work while freeing space for new tool calls and results.

## Execution Patterns

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

### Query → Analyze → Visualize

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..."
```

### Explore → Build → Validate

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
```

### Debug → Diagnose → Fix

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
```

### Iterate → Refine → Export

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
```

## Working Effectively with the Orchestrator

### Tips for Better Results

| Practice | Why It Helps |
|  --- | --- |
| **Be specific about data sources** | "Query the `marketing.campaigns` table" is faster than "look at campaign data" — the AI skips the exploration step |
| **Name the output format** | "Show this as a funnel chart" prevents the AI from guessing the wrong visualization |
| **Provide constraints** | "Use only the last 30 days and the US region" narrows the query and reduces execution time |
| **Reference prior results** | "Use the same filters as the previous query" leverages context instead of rebuilding |
| **Activate relevant skills** | Domain skills teach the AI your platform's specific patterns and functions |


### When Things Go Wrong

| Symptom | Likely Cause | Fix |
|  --- | --- | --- |
| AI runs too many queries | Request is ambiguous — AI is exploring to understand your data | Be more specific: name the table, columns, and time range |
| Wrong chart type | AI's default selection doesn't match your intent | Ask explicitly: "Show this as a bar chart" |
| Query fails with syntax error | AI used a function not available on your engine | Activate the **trino** or **hive** skill to guide correct syntax |
| AI asks too many questions | The AI is uncertain about your intent | Provide more context upfront |
| Context running low in long session | Too many tool results filling the context window | Run `/compact` to summarize older messages |
| AI repeats a failed approach | The AI may not have learned from the error | Explicitly state what went wrong: "That query timed out — use a smaller time range" |


## Architecture Overview

For users who want to understand the full system:


```mermaid
flowchart TD
    A["Your Message"] --> B["Context Assembly<br/>System prompt + Project context<br/>+ Active skills + Conversation<br/>history + In-session memory"]
    B --> C["Claude AI Model<br/>(Opus / Sonnet / Haiku)<br/>Plans steps, selects tools,<br/>reasons about results"]
    C --> D["Tool Calls<br/>(Streaming)"]
    C --> E["Text Output<br/>(Streaming)"]
    D --> F["Tool Execution Layer"]
    F --> G["TDX CLI"]
    F --> H["File Ops"]
    F --> I["Open File"]
    F --> J["MCP Servers"]
    G & H & I & J --> K["Results → AI → Next Step<br/>(Cycle until task complete)"]
    K -.-> C
```

### Web vs. Desktop Execution

| Aspect | Web | Desktop (Mac) |
|  --- | --- | --- |
| **Execution environment** | Server-side sandbox (secure worker) | Server-side sandbox (same as Web) |
| **Tool availability** | Same core tools — queries, file ops, charts | Same core tools as Web |
| **Session management** | Server-managed with worker pool | Server-managed (connected via API) |
| **Context persistence** | Server-side storage | Server-side storage with local transcript |
| **Streaming** | SSE via stream API | SSE via stream API (relayed through Electron IPC) |


Technical Note
Both Web and Desktop connect to the same server-side execution infrastructure. Each chat session is backed by a dedicated worker instance running the Claude Agent SDK with your account's plugins pre-installed. Desktop adds native macOS integration (menu bar, auto-update, deep links) but uses the same API and streaming layer as Web.

## Verification

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


## Troubleshooting

| Issue | Solution |
|  --- | --- |
| AI seems to "forget" earlier context | Long conversations may have auto-compacted. Run `/context` to check, or reference specific results explicitly |
| Tool calls are slow | Large queries or complex operations take time. Check the tool call card for progress |
| AI chose the wrong tool | Provide explicit guidance: "Use `tdx query` with Hive engine for this" |
| Session feels different after reopening | Desktop resumes from transcript; Web restores from server state. Both should be seamless — if not, start a fresh chat |


## Next Steps

- [AI Chat Interface](/products/ai-studio/chat/chat) — Learn the chat UI interactions in detail
- [Skills & Marketplace](/products/ai-studio/skills/skills) — Configure skills that guide orchestration
- [In-Session Memory](/products/ai-studio/chat/in-session-memory) — How the AI remembers context within a session
- [Security & Permissions](/products/ai-studio/security) — Security and audit logging
- [TDX Commands](/products/ai-studio/query/tdx-commands) — The CLI tools the orchestrator calls