feat(ai-agent): Phase 3 — explain_query tool, parallel/sequential execution, DB gating (#1187)
- Add explain_query tool with structured EXPLAIN result, gated on supports_explain_plan() - Add supports_sql_query() to gate execute_query/get_sample_data for non-SQL DBs (Redis, ES, MongoDB, etc.) - Split agent loop tool dispatch: execute_query runs sequentially, all others run in parallel via join_all - Wire explain_query result button to ExplainPlanViewer in AiAssistant + App.vue - Fix O(n²) agentSteps rebuild: incremental O(1) push per event during streaming - finally block falls back to full rebuild only when streaming push did not occur
This commit is contained in:
1 parent
a3c972c367
commit
d845a318c6
8 files changed
+284
-42
No files matched your search
@@ -37,6 +37,10 @@ pub struct ToolResult {
|
||||
pub tool_name: String,
|
||||
pub content: String,
|
||||
pub is_error: bool,
|
||||
/// Structured explain data (QueryResult) for explain_query tool results.
|
||||
/// Set only by execute_explain_query; None for all other tools.
|
||||
#[serde(skip_serializing_if = "Option::is_none")]
|
||||
pub explain_data: Option<serde_json::Value>,
|
||||
}
|
||||
|
||||
/// Definition of a tool available to the agent.
|
||||
@@ -46,6 +50,9 @@ pub struct ToolDefinition {
|
||||
pub description: &'static str,
|
||||
pub parameters: serde_json::Value,
|
||||
pub read_only: bool,
|
||||
/// Whether this tool can be executed in parallel with other tools.
|
||||
/// false = must run sequentially (e.g. execute_query).
|
||||
pub parallel_ok: bool,
|
||||
}
|
||||
|
||||
impl ToolDefinition {
|
||||
|
||||
@@ -1,10 +1,11 @@
|
||||
use std::sync::Arc;
|
||||
|
||||
use futures::future::join_all;
|
||||
use futures::FutureExt;
|
||||
use serde_json::json;
|
||||
use tokio::sync::Notify;
|
||||
|
||||
use crate::agent_events::{AgentEvent, ToolCall, ToolDefinition};
|
||||
use crate::agent_events::{AgentEvent, ToolCall, ToolDefinition, ToolResult};
|
||||
use crate::agent_tools;
|
||||
use crate::ai::{self, AiCompletionRequest, AiConfig, AiMessage, AiProvider, AiStreamChunk};
|
||||
use crate::connection::AppState;
|
||||
@@ -65,7 +66,7 @@ pub async fn run_agent_loop(
|
||||
)
|
||||
.await;
|
||||
}
|
||||
let tools = if is_agent_mode { agent_tools::all_tools() } else { agent_tools::read_only_tools() };
|
||||
let tools = if is_agent_mode { agent_tools::all_tools(agent_ctx.db_type) } else { agent_tools::read_only_tools() };
|
||||
let mut conversation_messages: Vec<AiMessage> = messages.to_vec();
|
||||
let mut final_text = String::new();
|
||||
|
||||
@@ -126,32 +127,71 @@ pub async fn run_agent_loop(
|
||||
}
|
||||
|
||||
// Execute each tool call
|
||||
// Emit all ToolCallStart events first
|
||||
for tc in &collected_tool_calls {
|
||||
on_event(AgentEvent::ToolCallStart {
|
||||
tool_call_id: tc.id.clone(),
|
||||
tool_name: tc.name.clone(),
|
||||
args: tc.arguments.clone(),
|
||||
});
|
||||
}
|
||||
|
||||
let result = agent_tools::execute_tool(
|
||||
tc,
|
||||
&agent_ctx.state,
|
||||
&agent_ctx.connection_id,
|
||||
&agent_ctx.database,
|
||||
&agent_ctx.db_type,
|
||||
)
|
||||
.await;
|
||||
// Execute tool calls: parallel for read tools, sequential for execute_query
|
||||
let state2 = Arc::clone(&agent_ctx.state);
|
||||
let conn2 = agent_ctx.connection_id.clone();
|
||||
let db2 = agent_ctx.database.clone();
|
||||
let db_type = agent_ctx.db_type;
|
||||
|
||||
// Split by index into parallel and sequential groups using tool metadata
|
||||
let tool_parallel_map: std::collections::HashMap<&str, bool> =
|
||||
tools.iter().map(|t| (t.name, t.parallel_ok)).collect();
|
||||
let (parallel_indices, sequential_indices): (Vec<usize>, Vec<usize>) = (0..collected_tool_calls.len())
|
||||
.partition(|&i| *tool_parallel_map.get(collected_tool_calls[i].name.as_str()).unwrap_or(&false));
|
||||
|
||||
let make_tc =
|
||||
|tc: &ToolCall| ToolCall { id: tc.id.clone(), name: tc.name.clone(), arguments: tc.arguments.clone() };
|
||||
|
||||
// Run parallel group
|
||||
let parallel_futures: Vec<_> = parallel_indices
|
||||
.iter()
|
||||
.map(|&i| {
|
||||
let tc = make_tc(&collected_tool_calls[i]);
|
||||
let state = Arc::clone(&state2);
|
||||
let conn = conn2.clone();
|
||||
let db = db2.clone();
|
||||
async move { agent_tools::execute_tool(&tc, &state, &conn, &db, &db_type).await }
|
||||
})
|
||||
.collect();
|
||||
let parallel_results = join_all(parallel_futures).await;
|
||||
|
||||
// Run sequential group one-by-one
|
||||
let mut sequential_results = Vec::with_capacity(sequential_indices.len());
|
||||
for &i in &sequential_indices {
|
||||
let tc = make_tc(&collected_tool_calls[i]);
|
||||
sequential_results.push(agent_tools::execute_tool(&tc, &state2, &conn2, &db2, &db_type).await);
|
||||
}
|
||||
|
||||
// Merge results back into original order
|
||||
let mut results: Vec<Option<ToolResult>> = vec![None; collected_tool_calls.len()];
|
||||
for (pos, &i) in parallel_indices.iter().enumerate() {
|
||||
results[i] = Some(parallel_results[pos].clone());
|
||||
}
|
||||
for (pos, &i) in sequential_indices.iter().enumerate() {
|
||||
results[i] = Some(sequential_results[pos].clone());
|
||||
}
|
||||
let results: Vec<ToolResult> = results.into_iter().map(|r| r.unwrap()).collect();
|
||||
|
||||
// Process results in order, emitting ToolCallEnd events
|
||||
for (tc, result) in collected_tool_calls.iter().zip(results) {
|
||||
on_event(AgentEvent::ToolCallEnd {
|
||||
tool_call_id: tc.id.clone(),
|
||||
tool_name: tc.name.clone(),
|
||||
result: json!({ "content": result.content }),
|
||||
result: match &result.explain_data {
|
||||
Some(ed) => json!({ "content": result.content, "explain_data": ed }),
|
||||
None => json!({ "content": result.content }),
|
||||
},
|
||||
is_error: result.is_error,
|
||||
});
|
||||
|
||||
// Add tool result to conversation for the next LLM call
|
||||
// Uses "tool" role per OpenAI convention; provider-specific conversion
|
||||
// happens in ai::stream_with_tools when building provider API requests.
|
||||
conversation_messages.push(AiMessage {
|
||||
role: "tool".to_string(),
|
||||
content: result.content.clone(),
|
||||
@@ -260,14 +300,14 @@ async fn build_schema_prompt(agent_ctx: &AgentLoopContext, system_prompt: &str)
|
||||
|
||||
match tables_result {
|
||||
Ok(tables) if !tables.is_empty() => {
|
||||
enriched.push_str("\n\n## Database Schema (for context 鈥?no tools available)\n");
|
||||
enriched.push_str("\n\n## Database Schema (for context — no tools available)\n");
|
||||
enriched.push_str(&format!("Database: {}\n", agent_ctx.database));
|
||||
enriched.push_str("Tables:\n");
|
||||
for t in &tables {
|
||||
enriched.push_str(&format!(" - {} ({})", t.name, t.table_type));
|
||||
if let Some(ref comment) = t.comment {
|
||||
if !comment.trim().is_empty() {
|
||||
enriched.push_str(&format!(" 鈥?{}", comment.trim()));
|
||||
enriched.push_str(&format!(" — {}", comment.trim()));
|
||||
}
|
||||
}
|
||||
enriched.push('\n');
|
||||
|
||||
@@ -6,6 +6,7 @@ use crate::agent_events::{ToolCall, ToolDefinition, ToolResult};
|
||||
use crate::connection::AppState;
|
||||
use crate::models::connection::DatabaseType;
|
||||
use crate::query::QueryExecutionOptions;
|
||||
use crate::query_execution_sql::{build_explain_sql, supports_explain_plan, supports_sql_query, ExplainSqlOptions};
|
||||
use crate::sql_risk::SqlRisk;
|
||||
use crate::types::QueryResult;
|
||||
|
||||
@@ -21,14 +22,24 @@ const SAMPLE_DATA_LIMIT: usize = 20;
|
||||
/// Absolute maximum rows any query tool may request.
|
||||
const MAX_ALLOWED_ROWS: usize = 100;
|
||||
|
||||
/// Get all available tool definitions for Phase 1 (read-only tools).
|
||||
/// Get read-only tool definitions (list_tables + get_columns).
|
||||
pub fn read_only_tools() -> Vec<ToolDefinition> {
|
||||
vec![list_tables_tool(), get_columns_tool()]
|
||||
}
|
||||
|
||||
/// Get all available tool definitions (Phase 2: read-only + execute_query + get_sample_data).
|
||||
pub fn all_tools() -> Vec<ToolDefinition> {
|
||||
vec![list_tables_tool(), get_columns_tool(), execute_query_tool(), get_sample_data_tool()]
|
||||
/// Get all available tool definitions for the given database type.
|
||||
/// Includes read-only tools plus execute_query, get_sample_data, and
|
||||
/// explain_query for database types that support them.
|
||||
pub fn all_tools(db_type: DatabaseType) -> Vec<ToolDefinition> {
|
||||
let mut tools = vec![list_tables_tool(), get_columns_tool()];
|
||||
if supports_sql_query(db_type) {
|
||||
tools.push(execute_query_tool());
|
||||
tools.push(get_sample_data_tool());
|
||||
}
|
||||
if supports_explain_plan(Some(db_type)) {
|
||||
tools.push(explain_query_tool());
|
||||
}
|
||||
tools
|
||||
}
|
||||
|
||||
/// list_tables tool definition.
|
||||
@@ -47,6 +58,7 @@ fn list_tables_tool() -> ToolDefinition {
|
||||
"required": []
|
||||
}),
|
||||
read_only: true,
|
||||
parallel_ok: true,
|
||||
}
|
||||
}
|
||||
|
||||
@@ -73,9 +85,10 @@ fn get_columns_tool() -> ToolDefinition {
|
||||
"required": ["table"]
|
||||
}),
|
||||
read_only: true,
|
||||
parallel_ok: true,
|
||||
}
|
||||
}
|
||||
/// execute_query tool definition (Phase 2).
|
||||
/// execute_query tool definition.
|
||||
fn execute_query_tool() -> ToolDefinition {
|
||||
ToolDefinition {
|
||||
name: "execute_query",
|
||||
@@ -97,10 +110,11 @@ fn execute_query_tool() -> ToolDefinition {
|
||||
"required": ["sql"]
|
||||
}),
|
||||
read_only: true,
|
||||
parallel_ok: false,
|
||||
}
|
||||
}
|
||||
|
||||
/// get_sample_data tool definition (Phase 2).
|
||||
/// get_sample_data tool definition.
|
||||
fn get_sample_data_tool() -> ToolDefinition {
|
||||
ToolDefinition {
|
||||
name: "get_sample_data",
|
||||
@@ -124,6 +138,30 @@ fn get_sample_data_tool() -> ToolDefinition {
|
||||
"required": ["table"]
|
||||
}),
|
||||
read_only: true,
|
||||
parallel_ok: true,
|
||||
}
|
||||
}
|
||||
|
||||
/// explain_query tool definition (Phase 3).
|
||||
fn explain_query_tool() -> ToolDefinition {
|
||||
ToolDefinition {
|
||||
name: "explain_query",
|
||||
description: "Get the execution plan for a SQL query using EXPLAIN. \
|
||||
Shows how the database will execute the query (scan type, indexes, cost). \
|
||||
Only read-only queries (SELECT, WITH, SHOW, DESCRIBE, EXPLAIN) are allowed. \
|
||||
Use this to analyze query performance and suggest index optimizations.",
|
||||
parameters: json!({
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"sql": {
|
||||
"type": "string",
|
||||
"description": "The SQL query to explain (must be read-only)"
|
||||
}
|
||||
},
|
||||
"required": ["sql"]
|
||||
}),
|
||||
read_only: true,
|
||||
parallel_ok: true,
|
||||
}
|
||||
}
|
||||
|
||||
@@ -140,6 +178,30 @@ pub async fn execute_tool(
|
||||
"get_columns" => execute_get_columns(tool_call, state, connection_id, database, db_type).await,
|
||||
"execute_query" => execute_execute_query(tool_call, state, connection_id, database, db_type).await,
|
||||
"get_sample_data" => execute_get_sample_data(tool_call, state, connection_id, database, db_type).await,
|
||||
"explain_query" => {
|
||||
let (text_result, explain_data) =
|
||||
execute_explain_query(tool_call, state, connection_id, database, db_type).await;
|
||||
match text_result {
|
||||
Ok(content) => {
|
||||
return ToolResult {
|
||||
tool_call_id: tool_call.id.clone(),
|
||||
tool_name: tool_call.name.clone(),
|
||||
content,
|
||||
is_error: false,
|
||||
explain_data,
|
||||
};
|
||||
}
|
||||
Err(err) => {
|
||||
return ToolResult {
|
||||
tool_call_id: tool_call.id.clone(),
|
||||
tool_name: tool_call.name.clone(),
|
||||
content: format!("Error: {err}"),
|
||||
is_error: true,
|
||||
explain_data: None,
|
||||
};
|
||||
}
|
||||
}
|
||||
}
|
||||
_ => Err(format!("Unknown tool: {}", tool_call.name)),
|
||||
};
|
||||
|
||||
@@ -149,12 +211,14 @@ pub async fn execute_tool(
|
||||
tool_name: tool_call.name.clone(),
|
||||
content,
|
||||
is_error: false,
|
||||
explain_data: None,
|
||||
},
|
||||
Err(err) => ToolResult {
|
||||
tool_call_id: tool_call.id.clone(),
|
||||
tool_name: tool_call.name.clone(),
|
||||
content: format!("Error: {err}"),
|
||||
is_error: true,
|
||||
explain_data: None,
|
||||
},
|
||||
}
|
||||
}
|
||||
@@ -409,3 +473,79 @@ async fn execute_get_sample_data(
|
||||
};
|
||||
execute_execute_query(&synthetic_call, state, connection_id, database, db_type).await
|
||||
}
|
||||
|
||||
/// Execute an EXPLAIN query via the explain_query tool.
|
||||
/// Returns (text_for_llm, optional_explain_data_for_frontend).
|
||||
async fn execute_explain_query(
|
||||
tool_call: &ToolCall,
|
||||
state: &Arc<AppState>,
|
||||
connection_id: &str,
|
||||
database: &str,
|
||||
db_type: &DatabaseType,
|
||||
) -> (Result<String, String>, Option<serde_json::Value>) {
|
||||
let sql = match tool_call.arguments.get("sql").and_then(|v| v.as_str()) {
|
||||
Some(s) => s.trim(),
|
||||
None => return (Err("Missing required parameter: sql".to_string()), None),
|
||||
};
|
||||
|
||||
if sql.is_empty() {
|
||||
return (Err("SQL query cannot be empty".to_string()), None);
|
||||
}
|
||||
|
||||
// Classify SQL risk – only ReadOnly queries can be explained
|
||||
let db_type_str = format!("{:?}", db_type).to_lowercase();
|
||||
let risk = match crate::sql_risk::classify_sql_risk(sql, &db_type_str) {
|
||||
Ok(r) => r,
|
||||
Err(e) => return (Err(e), None),
|
||||
};
|
||||
match risk {
|
||||
SqlRisk::ReadOnly => { /* proceed */ }
|
||||
_ => {
|
||||
return (
|
||||
Err(format!(
|
||||
"Blocked: {} statement detected. Only read-only queries (SELECT, SHOW, DESCRIBE, EXPLAIN) can be analyzed.",
|
||||
risk
|
||||
)),
|
||||
None,
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
// Build the database-specific EXPLAIN SQL
|
||||
let explain_result = build_explain_sql(ExplainSqlOptions { database_type: Some(*db_type), sql: sql.to_string() });
|
||||
|
||||
let explain_sql = match (explain_result.ok, explain_result.sql) {
|
||||
(true, Some(sql)) => sql,
|
||||
(true, None) => return (Err("EXPLAIN SQL is empty".to_string()), None),
|
||||
(false, _) => {
|
||||
let reason = explain_result.reason.unwrap_or_else(|| "unknown".to_string());
|
||||
return (Err(format!("Cannot explain this query: {}. The database type may not support EXPLAIN, or the query may be unsafe.", reason)), None);
|
||||
}
|
||||
};
|
||||
|
||||
// Execute the EXPLAIN query
|
||||
let options = QueryExecutionOptions { max_rows: Some(100), timeout_secs: Some(30), ..Default::default() };
|
||||
let result = match crate::query::execute_sql_statement_with_options(
|
||||
state,
|
||||
connection_id,
|
||||
database,
|
||||
&explain_sql,
|
||||
None,
|
||||
None,
|
||||
options,
|
||||
)
|
||||
.await
|
||||
{
|
||||
Ok(r) => r,
|
||||
Err(e) => return (Err(e), None),
|
||||
};
|
||||
|
||||
// Serialize the raw QueryResult for the frontend ExplainPlanViewer
|
||||
let explain_data = serde_json::to_value(&result).ok();
|
||||
let text = match format_query_result_as_text(&result, 100) {
|
||||
Ok(t) => t,
|
||||
Err(e) => return (Err(e), None),
|
||||
};
|
||||
|
||||
(Ok(text), explain_data)
|
||||
}
|
||||
@@ -79,6 +79,20 @@ pub fn supports_explain_plan(database_type: Option<DatabaseType>) -> bool {
|
||||
)
|
||||
}
|
||||
|
||||
/// Returns true for databases that support SQL query execution (execute_query / get_sample_data).
|
||||
/// Non-SQL databases (Redis, MongoDB, Elasticsearch, InfluxDB, Neo4j, etcd) are excluded.
|
||||
pub fn supports_sql_query(database_type: DatabaseType) -> bool {
|
||||
!matches!(
|
||||
database_type,
|
||||
DatabaseType::Redis
|
||||
| DatabaseType::MongoDb
|
||||
| DatabaseType::Elasticsearch
|
||||
| DatabaseType::InfluxDb
|
||||
| DatabaseType::Neo4j
|
||||
| DatabaseType::Etcd
|
||||
)
|
||||
}
|
||||
|
||||
pub fn is_safe_dameng_autotrace_sql(sql: &str) -> bool {
|
||||
let source = strip_trailing_semicolons(sql.trim());
|
||||
if source.is_empty() || has_extra_statement_after_semicolon(&source) {
|
||||
|
||||
Reference in new issue
Block a user