Agent Behavior
The Studio AI agent is a long-lived process that maintains conversational context across multiple messages within an intent. This page explains how the agent assembles its knowledge, manages sessions, uses tools, delegates to sub-agents, asks you questions, and responds to your agent and model choices.
How the Agent Gets Its Knowledge (Context Assembly)
Each time a session starts, the agent receives dynamic context assembled from several sources. These are injected in the following order:
| Section | Source | What it provides |
|---|---|---|
| Git Disabled notice | Domain configuration | Shown only when no GitHub repository is configured. Instructs the agent to skip all git operations. |
| Domain-Specific Instructions | Custom instructions field in domain settings (2,000 character max) | Free-text guidance you write for the agent, sanitized before injection. |
| Domain Fabric Lakehouse | Domain configuration | Default Fabric Lakehouse, schema, and SQL endpoint for dbt execution. |
| Tool Context | Intent and domain IDs | Internal identifiers the agent passes to its tools (you do not interact with this directly). |
| Previous Session Summary | Compacted or resumed session | A summary of prior conversation turns, injected when continuing a previous session. |
| Additional Skills (not available in this domain) | Installed plugins not assigned to the current domain | Skills the agent knows about but cannot use. If one would help, the agent may suggest enabling it. |
The static agent identity, guardrails, and tool policies are loaded separately from the agent plugin configuration and are not rebuilt each turn.
What the Agent Remembers
Beyond the context assembled for each session, the agent can note a fact it learns during a conversation, so that a later review step can keep it. A noted fact is aimed at one of two memories, and the two reach very different audiences:
| Memory | Who it reaches |
|---|---|
| The acting user's | Only the person driving the conversation, in every domain they work in. |
| Domain | Everyone who works in the current domain. It is not carried to other domains. |
When the agent notes a fact, the chat shows a chip naming where that write was aimed — Acting user's memory · all Domains or This Domain's memory. Hover the chip to see the same audience in full, along with the file the agent wrote. If the agent writes a file other than its main memory file, the chip carries that file's name too, so two writes to the same memory stay distinguishable.
The chip is worded from the person driving the conversation, not from you as a reader: anyone watching the same conversation sees the same wording, so the acting user's memory is never mistaken for the watcher's own.
Two limitations are worth knowing:
- The chip names the memory the write targeted. It is not a guarantee the fact is kept: a later review step decides what is retained, and it can drop or reclassify a fact without changing the chip you already saw.
- A file the agent writes outside either memory is shown as an ordinary edited file, with no memory label. A turn in which the agent notes nothing shows no chip at all.
- If the agent takes back one of its own edits, no new chip appears for the reversal. A second chip would read as another fact having been noted rather than as the retraction it is.
You do not choose the memory yourself, and there is no chat control for editing or undoing a noted fact.
Session Model
Studio uses long-lived agent sessions. A single SDK subprocess stays alive across multiple messages within an intent, rather than spawning a new process for each turn.
How It Works
- First message — A new subprocess is created and begins processing your message.
- Subsequent messages — The existing subprocess receives your message through an internal message queue. No new process is spawned and no conversation history is reloaded.
- Session resume — If the subprocess has ended (idle timeout, server restart, or cancellation), sending a new message creates a fresh subprocess that resumes from the persisted session state stored in JSONL files.
Session Lifecycle
| Event | What happens |
|---|---|
| You send a message | The idle timer resets. If no live session exists, a new subprocess is created (resuming from saved state if available). |
| Idle timeout (10 minutes) | The session is torn down. The next message will create a fresh subprocess with resume. |
| Maximum lifetime (4 hours) | The session is torn down regardless of activity. |
| You stop the agent | The current turn is cancelled. The subprocess is aborted. The next message creates a new session with resume. |
| Server restart | All sessions end. The next message per intent creates a new session with resume. |
You do not need to manage sessions manually. The system handles creation, reuse, and cleanup automatically.
Tools the Agent Can Use
The agent has access to two categories of tools: Studio-specific tools and built-in SDK tools.
Studio Tools
These are custom tools specific to Studio's data engineering workflow:
| Tool | What it does |
|---|---|
| export_query_data | Runs one bounded read-only Domain or Ephemeral query and creates a temporary CSV, JSON, JSONL, Parquet, or Arrow file |
| lakehouse_query | Issues one bounded SQL statement against the Intent’s Fabric, MotherDuck, or DuckDB Domain or Ephemeral target, subject to that target’s own credential |
| lakehouse_schema | Inspects tables, columns, and views on the Intent’s Domain or Ephemeral target |
| profile_data | Profiles one local, Domain, or Ephemeral dataset |
| compare_data_profiles | Compares two independently selected local, Domain, or Ephemeral datasets |
| summarize_data | Summarizes local, Domain, Ephemeral, or inline datasets with bounded read-only SQL |
| visualize_data | Creates a visualization from one local, Domain, or Ephemeral dataset |
| artifact_write | Writes or updates intent documents (intent.md, design.md) with database tracking |
| workspace_info | Retrieves the intent working directory and git configuration |
| validate_output | Compares dbt model output against an expected CSV (validation reconciliation) |
When a Fabric query or schema inspection reports a connection failure, retry once and then ask an administrator to verify Fabric connectivity. A query-execution failure instead means the connection succeeded; inspect the SQL and selected schema before retrying. Studio does not expose the endpoint, credential, or driver diagnostic in either message.
Use export_query_data for straightforward projections, filters, aggregates, and joins. A successful export appears in Chat as query-data.csv, query-data.json, query-data.jsonl, query-data.parquet, or query-data.arrow. The file is temporary and remains available only while its AgentSession exists. Complex, expensive, or reusable transformations belong in dbt.
Built-in Runtime Tools
The agent also has access to general-purpose tools provided by the agent runtime:
- Read, Write, Edit — file operations
- Bash — shell command execution (used for dbt, git, and general scripting)
- Glob, Grep — file search and content search
- Agent — delegate a task to a sub-agent
- Task — structured task execution
- Skill — invoke a registered skill from an enabled plugin
Tool Access is Domain-Scoped
Not all tools are available in every domain. The set of allowed tools is determined by the domain's configuration and the plugins assigned to it. If the agent needs a tool from a plugin that is not enabled, it will suggest that you enable the plugin rather than failing silently.
Sub-Agent Behavior
The agent can delegate complex subtasks to sub-agents using the Agent tool. When this happens, you will see progress updates in the chat stream, but the detailed text output from the sub-agent is not shown in real time.
What You See
- Task started — A notification that a sub-agent has begun working on a subtask.
- Task progress — Periodic progress updates from the sub-agent.
- Task completed — The final result summary from the sub-agent.
What You Do Not See
The sub-agent's step-by-step narrative text (its "thinking out loud") does not appear in the parent chat stream. Only structured progress events and the final result are surfaced. This is a limitation of the SDK architecture, not a bug. The parent agent receives the sub-agent's full result and incorporates it into its response.
Why? The SDK only surfaces task_started, task_progress, and task_notification events from sub-agents. Real-time text streaming from sub-agents to the parent is not supported. The sub-agent's conversation is logged separately in JSONL files for debugging purposes.
Questions from the Agent
When the agent needs clarification before proceeding, Agent needs your input appears as a first-class prompt in the chat. The prompt presents one question at a time and can collect suggested-option or free-text answers.
Answering Questions
- Read the question and the Question N of N progress text.
- Click a suggested option, or type an answer when the question shows a free-text box.
- Click Next to move forward. Use Back to revisit the previous question.
- On the final question, click Answer after every question has a valid response.
- In a multi-question prompt, click Decline to skip only the displayed question, or Decline all to skip the complete prompt. A single-question prompt shows one Decline action.
Only the user who holds the Intent's Edit Lease can use the response controls. Other viewers can see the question without Answer or Decline controls.
Answer or decline in the Agent needs your input card, not in the main message composer. Messages sent from the composer while a question is pending are queued until the question resolves. The composer shows this distinction while the agent is waiting.
If submitting an answer or decline fails, the card explains the failure and restores its controls. Check your connection, then try Answer or Decline again; you do not need to refresh the conversation.
After the question finishes, open Tool Activity and expand ask_user_question to see its terminal state, such as Question answered, Question declined, Question expired, Question cancelled, or Question failed. For an answered or fully declined prompt, Tool result lists each question and the outcome returned to the agent, including User declined to answer beside skipped questions. It is the paired tool result; the response is not added as a new chat message.
How It Works
The agent calls the AskUserQuestion tool, which pauses the agent's processing until you respond. Your answers are sent back to the agent, which resumes immediately in the same turn without starting a new message. If you do not answer within five minutes, the question expires, its controls become unavailable, and the agent receives the normal tool error.
Model Selection
You choose the AI model in the AgentModelSelector dropdown, located in the bottom-left of the chat input bar.
- Click the model name (displayed as plain text next to the agent selector).
- A dropdown appears showing all available models with their display names and descriptions.
- Click a model to select it.
The default model is Claude Sonnet 4.5 (claude-sonnet-4-5-20250929).
Important: The model selection is locked after you send the first message in an intent. The tooltip changes to "Model locked after first message" and the dropdown becomes disabled. To use a different model, create a new intent.
Agent Selection
The agent determines the orchestration strategy and tool configuration used by the AI. You choose the agent in the AgentModelSelector dropdown, to the left of the model selector.
- Click the agent name (displayed with a bot icon in blue).
- A dropdown appears showing available agents with their labels.
- Click an agent to select it.
The default agent is Data Engineer (build).
Important: Like the model, the agent selection is locked after the first message. The tooltip changes to "Agent locked after first message". While agents are loading, a spinning loader appears in place of the bot icon.
Quick Reference
| Concept | Detail |
|---|---|
| Session idle timeout | 10 minutes of inactivity |
| Session max lifetime | 4 hours |
| Question timeout | 5 minutes to answer before the question expires |
| Default model | Claude Sonnet 4.5 (claude-sonnet-4-5-20250929) |
| Default agent | Data Engineer (build) |
| Agent/model lock | After first message in an intent |
| Sub-agent text visibility | Progress and final result only (no real-time narrative) |
| Custom instructions limit | 2,000 characters |
| Memory chip label | Names the memory a write targeted, not a retention guarantee |