NL2SQL Agent

Details
This page shows version v0.0.0 (dev). The current version can be found here.

The NL2SQL agent enables natural language queries against structured data in Oracle Database via the SQLcl MCP server.

flowchart TD
    prompt["Fetch system prompt (optimizer_nl2sql-tools-default)"] --> build["Build AgentSpec with MCPToolBox"]
    build --> load["Load into runtime"]
    load --> session["Create NL2SQL session with DB connection context"]
    session --> input["User query"]
    input --> agent["Agent autonomously selects and calls SQLcl MCP tools"]
    agent --> reply["Return natural language answer"]
  • NL2SQL uses an Agent with dynamic MCP tool discovery — it autonomously decides which SQLcl tools to call using the ReAct pattern, rather than following a fixed pipeline.
  • build_nl2sql_agentspec creates a portable AgentSpec Agent with an MCPToolBox that discovers available SQLcl tools at runtime (e.g. sqlcl_connect, sqlcl_schema-information, sqlcl_run-sql).
  • The session augments the agent’s system prompt with the configured database connection name, model, and thread ID so the LLM passes them to sqlcl_* tool calls.
  • The system prompt is fetched from the MCP server (optimizer_nl2sql-tools-default). If unavailable, a default instruction is used.
  • Requires a configured SQLcl MCP Server and a database connection.