**Source URL:** https://general.veevavault.dev/ai/ai-agents/agents/query-agent

# Query Agent

<Aside type="note">
The functionality described on this page is only available to customers who have Vault AI enabled on their Vault.
</Aside>

Query Agent (`query_agent__sys`) translates natural-language questions into VQL queries, executes them, and returns structured results. You can invoke it from [Vault AI Chat](https://platform.veevavault.help/en/gr/950642) or programmatically using Vault API and [Vault AI MCP](/mcp/vault-mcp-server/).

## Modes

Query Agent supports two invocation modes:

| Mode | Invocation |
| --- | --- |
| Interactive | Vault AI Chat |
| Non-interactive | Vault API, Vault AI MCP |

Vault API and Vault AI MCP use non-interactive mode. Interactive MCP (Human-in-the-Loop) is not supported.

In interactive mode (Vault AI Chat), `actionOutputs` contains a single `text` entry whose value is a Markdown string, along with canvas metadata. In non-interactive mode via Vault API, `actionOutputs` contains two entries: a `text` entry with the Markdown summary, and a `json` entry whose `value` is the full structured result object. Using Vault AI MCP, the tool result is the structured JSON object directly. See [Retrieve Agent Action Execution Status](/vault-api/api-reference/26.2/ai/retrieve-agent-action-execution-status/) for the full response schema.

## Vault AI MCP Tool Name

Query Agent is accessible through the Vault AI MCP as `query_agent__sys-query_vault__sys`.

## Constraints

The following constraints apply when using Query Agent in non-interactive mode:

*   Query Agent cannot ask clarifying questions in non-interactive mode.
*   Vault API and Vault AI MCP support non-interactive mode only. Interactive MCP is not supported.
*   `sample_rows` in `vql_steps` contains up to 200 rows when invoked using Vault API or Vault AI MCP, and up to 20 rows in interactive mode.

---

**Previous:** [Agents](/ai/ai-agents/agents)  
**Next:** [API Reference](/ai/ai-agents/api)