Agent Behavior
The Vibedata 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. |
| Intent Facts | Intent and domain configuration | The Intent's fixed settings (branch, workdir, domain, platform, Secret Store kind); others looked up on request. |
| Tool arguments | Intent and domain IDs | Which 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. |
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. |
| 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 or This Domain's memory. Hover the chip to see the fuller wording, 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
Vibedata 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: Vibedata-specific tools and built-in SDK tools.
Vibedata Tools
These are custom tools specific to Vibedata'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 Domain or Ephemeral target on any supported Data Platform (Fabric, MotherDuck, DuckDB, Redshift, Databricks, BigQuery, or Snowflake), 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. Vibedata 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.
Ask about another Intent's history
Ask the agent to inspect the conversation of another Intent you can read in the same Domain. It can retrieve the saved history without waking that Intent. You can ask for a time range or particular kinds of events, such as messages or tool results.
The agent writes the transcript to a temporary Markdown file and reads the relevant parts as needed. The transcript is not automatically added to your project's files.
Text search finds a starting point in indexed history. The agent can search messages, tool actions, tool results, agent errors, rejected actions, and condensation summaries. Searching other event kinds is rejected. An Intent that has not been indexed cannot be searched by text, but its saved history can still be exported without text search. Search coverage can be incomplete, and large exports can be truncated; the agent receives those limits with the result.
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 directly above the composer. The prompt presents one question at a time and can collect suggested-option or free-text answers.
Answering Questions
- Read the question. When the agent asked several, the card's header shows Question N of N.
- 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.
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 the activity line before the reply and expand the ask_user_question entry 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
Use the profile selector below the chat input to choose an LLM profile. The trigger shows the profile name; its menu shows each profile's model and identifies the default profile. You can search the list when several profiles are available.
Changing an existing Intent's profile applies to its next Turn. Before creating an Intent, the selector previews the organization's default profile. For an existing Intent with no bound profile, if no profiles are configured, the control links to Settings. An Intent without a profile needs a selection before you can send a message.
Agent Selection
The agent determines the orchestration strategy and tool configuration. Its name appears beside the profile selector. The primary agent is selected when the Intent is created; the composer displays that agent without offering a separate agent picker.
Recovering from a data-tool failure
A failed profile, comparison, summary, visualization, or export call leaves the conversation running. Results from other completed calls remain available. Ask the agent to retry a failed read when its diagnostic says retrying is safe.
If a load into the Ephemeral Workspace reports an unknown commit outcome, ask the agent to check the destination before loading again. The data may already have been written; repeating the load can replace or duplicate it.
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 | Model configured in the organization's default LLM profile |
| Primary agent | Agent selected when the Intent is created |
| Profile changes | Apply to the next Turn |
| 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 |