SQL Agent

Guide 6 showed the agent loop in the abstract: a model that decides, acts, observes, and repeats. Guide 7 introduced the KnowledgeBase — a typed, queryable store backed by DuckDB. This guide combines the two. An SQL Agent is an agent whose tool set is pre-wired for working with a knowledge base via SQL: it can discover the schema, sample rows, and run read-only SELECT queries. The user asks a question in natural language; the agent writes the SQL.

When Do You Want One?

A plain Generator answers from prompt context alone. A RAG pipeline retrieves text and pastes it into the prompt. Neither knows about structure: the difference between a row, a column, a join. When the answer requires:

joining tables (top customers by order total),
aggregations (count, sum, group-by),
filters that need exact-typed comparisons (price < 50, status = "pending"),

an SQL agent is the right shape. The model writes one SELECT, the engine computes the answer, and the model summarizes it. No embedding similarity, no chunking, no recall problem — just the right tuples.

The Three Tools

synalinks.SQLAgent wraps a FunctionCallingAgent and pre-wires three tools, all bound to a single KnowledgeBase you supply:

Tool	Purpose
`get_database_schema()`	Returns every table with its columns, types, and descriptions.
`get_table_sample(table_name, limit, offset)`	Fetch a few rows from a table to see what the values actually look like. Page-bounded by the agent's `k`.
`run_sql_query(sql_query)`	Execute a read-only `SELECT` query and return the rows. Wrapped server-side with an outer `LIMIT k` so even an unbounded query can't drain a giant table into the conversation.

The agent's default instructions already include the list of available tables, so a trivial question can skip get_database_schema and jump straight to run_sql_query.

Why these three, and not just one

You could imagine giving the agent a single "ask the DB" tool. But the LM needs to know the schema before it can write SQL, and reading the schema repeatedly into every prompt wastes tokens. The three-tool split lets the LM:

Discover the schema once.
Optionally peek at sample values when a column's type isn't enough to know what's in it ("status" — is it pending/paid, or 0/1?).
Then write its query.

Each tool returns just what's needed for the next step.

Safety Model

Safety is the knowledge base's responsibility, not the agent's. The run_sql_query tool always passes read_only=True to kb.sql(...). The DuckDB adapter enforces that flag in two layers — both using DuckDB's own machinery, so there are no hand-rolled keyword blocklists (which leak false negatives through comments, string literals, casing, and stacked statements like SELECT 1; DROP TABLE x):

Parser layer. Each statement is parsed with DuckDB's parser and rejected unless it's a SELECT. This catches multi-statement injection, COPY (SELECT ...) TO '/path' filesystem exfiltration, ATTACH, EXPORT, and every other side-effecting statement.
Connection sandbox. The persistent connection had enable_external_access=false applied at construction time, so SELECT table functions that touch the host filesystem or network — read_csv, read_parquet, read_json, read_blob, glob, httpfs/S3 variants — return a permission error.

That means the run_sql_query tool body is trivial: pass the SQL through and surface any error so the agent can read it and retry with corrected SQL.

The `k` Cap

Both get_table_sample and run_sql_query are capped server-side at the agent's k setting (default 50):

get_table_sample: the LM's limit argument is clamped to min(limit, k).
run_sql_query: the LM's SQL is wrapped in SELECT * FROM ({sql}) LIMIT k. A LIMIT inside the LM's own SQL still applies first, so LIMIT 5 returns 5 rows even when the cap is higher.

Result dicts include row_cap and may_have_more so the LM can detect truncation and refine the query (add filters, ORDER BY ... LIMIT n) rather than asking for more rows.

Building the Agent

The constructor signature mirrors FunctionCallingAgent exactly — every parameter on that class is accepted with identical semantics. The additions are SQL-specific:

Param	Required	Default	Notes
`knowledge_base`	yes	—	The `KnowledgeBase` to query.
`k`	no	`50`	Max rows per call (samples and queries).
`output_format`	no	`"csv"`	How result sets render to the LM. `"csv"` is compact; `"json"` returns a list of dicts.
`tools`	no	`None`	Extra `Tool` instances or async functions to append to the three built-ins. Same name-collision and no-leading-underscore rules as `FunctionCallingAgent`.

import synalinks

lm = synalinks.LanguageModel(model="ollama/qwen3:8b")
kb = synalinks.KnowledgeBase(
    uri="duckdb://my_database.db",
    data_models=[Customer, Product, SalesOrder],
)

class Query(synalinks.DataModel):
    query: str = synalinks.Field(description="A natural-language question")

class SQLAnswer(synalinks.DataModel):
    answer: str = synalinks.Field(description="A natural-language answer")
    sql_query: str = synalinks.Field(description="The SQL that produced it")

inputs = synalinks.Input(data_model=Query)
outputs = await synalinks.SQLAgent(
    knowledge_base=kb,
    language_model=lm,
    data_model=SQLAnswer,
)(inputs)
agent = synalinks.Program(inputs=inputs, outputs=outputs)

data_model=SQLAnswer is a common pattern: the agent's final output is a structured object with both the natural-language answer and the SQL that produced it. That gives downstream code something to display and lets users verify the query.

A Worked Example

A small end-to-end task: ask the agent to find the top customers by order total against the demo data populated in this guide's main() (three customers, four orders). The agent has to discover both tables (Customer and SalesOrder), figure out the join key, write a GROUP BY query, and summarize the result.

result = await agent(Query(query="Who are the top 2 customers by total order amount?"))

print(result["answer"])
# "Alice and Carol are tied as the top customers, each with $1,500
#  in total order amount."

print(result["sql_query"])
# SELECT c.name, SUM(o.total_amount) AS total
# FROM Customer c JOIN SalesOrder o ON c.id = o.customer_id
# GROUP BY c.name
# ORDER BY total DESC
# LIMIT 2

What the agent typically does:

get_database_schema() if the table list in the instructions doesn't give it enough information about columns.
get_table_sample("SalesOrder", limit=3, offset=0) to see whether customer_id matches Customer.id and what total_amount looks like.
run_sql_query(...) with the JOIN + GROUP BY + ORDER BY.
Stop calling tools; produce the final SQLAnswer.

If the query has a typo or a non-existent column, the result dict carries the error and the agent retries.

Compared to Other Agents

SQLAgent is one of several specialized agents that wrap a FunctionCallingAgent with a workload-specific tool set:

Agent	Bound to	Tools
`FunctionCallingAgent`	nothing	whatever you pass in
`SQLAgent`	a `KnowledgeBase`	schema discovery, table sample, read-only SQL
`VectorRAGAgent`	a `KnowledgeBase`	schema discovery, semantic / keyword / hybrid search, get-by-id
`DeepAgent`	a workdir	list, search, read, write, edit, bash

When to pick SQLAgent over VectorRAGAgent: the data is structured (rows and columns), and the question requires computation (joins, aggregations, exact filters). When the data is documents and the question is "find me the passage that talks about X", reach for VectorRAGAgent instead.

API References

`Customer`

Bases: DataModel

A customer.

Source code in guides/23_sql_agent.py

class Customer(synalinks.DataModel):
    """A customer."""

    id: str = synalinks.Field(description="Customer ID")
    name: str = synalinks.Field(description="Customer name")
    country: str = synalinks.Field(description="Customer country")

`Query`

Bases: DataModel

A natural-language question about the data.

Source code in guides/23_sql_agent.py

class Query(synalinks.DataModel):
    """A natural-language question about the data."""

    query: str = synalinks.Field(description="The question")

`SQLAnswer`

Bases: DataModel

The agent's structured answer.

Source code in guides/23_sql_agent.py

class SQLAnswer(synalinks.DataModel):
    """The agent's structured answer."""

    answer: str = synalinks.Field(description="Natural-language answer")
    sql_query: str = synalinks.Field(description="SQL that produced the answer")

`SalesOrder`

Bases: DataModel

An order.

Source code in guides/23_sql_agent.py

class SalesOrder(synalinks.DataModel):
    """An order."""

    id: str = synalinks.Field(description="Order ID")
    customer_id: str = synalinks.Field(description="Customer ID")
    total_amount: float = synalinks.Field(description="Order total")

Source

import asyncio
import os

from dotenv import load_dotenv

import synalinks


class Customer(synalinks.DataModel):
    """A customer."""

    id: str = synalinks.Field(description="Customer ID")
    name: str = synalinks.Field(description="Customer name")
    country: str = synalinks.Field(description="Customer country")


class SalesOrder(synalinks.DataModel):
    """An order."""

    id: str = synalinks.Field(description="Order ID")
    customer_id: str = synalinks.Field(description="Customer ID")
    total_amount: float = synalinks.Field(description="Order total")


class Query(synalinks.DataModel):
    """A natural-language question about the data."""

    query: str = synalinks.Field(description="The question")


class SQLAnswer(synalinks.DataModel):
    """The agent's structured answer."""

    answer: str = synalinks.Field(description="Natural-language answer")
    sql_query: str = synalinks.Field(description="SQL that produced the answer")


async def main():
    load_dotenv()
    synalinks.clear_session()
    synalinks.enable_logging()

    db_path = "./guides/sql_agent_guide.db"
    if os.path.exists(db_path):
        os.remove(db_path)

    # Build the knowledge base with two related tables.
    kb = synalinks.KnowledgeBase(
        uri=f"duckdb://{db_path}",
        data_models=[Customer, SalesOrder],
        wipe_on_start=True,
        name="sql_agent_guide_kb",
    )

    # Sample data — enough to make a top-N query non-trivial.
    customers = [
        Customer(id="C1", name="Alice", country="USA"),
        Customer(id="C2", name="Bob", country="UK"),
        Customer(id="C3", name="Carol", country="Spain"),
    ]
    orders = [
        SalesOrder(id="O1", customer_id="C1", total_amount=1200.0),
        SalesOrder(id="O2", customer_id="C1", total_amount=300.0),
        SalesOrder(id="O3", customer_id="C2", total_amount=150.0),
        SalesOrder(id="O4", customer_id="C3", total_amount=1500.0),
    ]
    for c in customers:
        await kb.update(c.to_json_data_model())
    for o in orders:
        await kb.update(o.to_json_data_model())

    language_model = synalinks.LanguageModel(model="ollama/qwen3:8b")

    # Build the agent. The data_model param sets the schema of the
    # final answer — the LM is required to produce both a natural-
    # language explanation and the SQL it used.
    inputs = synalinks.Input(data_model=Query)
    outputs = await synalinks.SQLAgent(
        knowledge_base=kb,
        language_model=language_model,
        data_model=SQLAnswer,
        max_iterations=10,
    )(inputs)

    agent = synalinks.Program(
        inputs=inputs,
        outputs=outputs,
        name="sql_agent",
        description="A SQL agent that answers questions about the database.",
    )
    agent.summary()

    # Ask a non-trivial question that requires a JOIN + GROUP BY.
    result = await agent(
        Query(query="Who are the top 2 customers by total order amount?")
    )
    print("Answer:", result["answer"])
    print("SQL:", result["sql_query"])

    if os.path.exists(db_path):
        os.remove(db_path)


if __name__ == "__main__":
    asyncio.run(main())

Run log

This guide calls synalinks.enable_logging(), so a full run traces every module call. The log below is the unedited output of running the guide above with local models.

Full run log — guides/23_sql_agent.log

(DEBUG) [Synalinks]
Call ID: f7655a84-f9fd-411b-98ee-038ab250ac43
Parent call ID: None
Module: SQLAgent
Module Name: sql_agent
Module Description: A ready-to-use SQL agent backed by a knowledge base.
Data Model JSON Schema:
[
  {
    "additionalProperties": false,
    "description": "A natural-language question about the data.",
    "properties": {
      "query": {
        "description": "The question",
        "title": "Query",
        "type": "string"
      }
    },
    "required": [
      "query"
    ],
    "title": "Query",
    "type": "object"
  }
]

(DEBUG) [Synalinks]
Call ID: e53ac34f-6d42-472f-8883-3ff461293671
Parent call ID: f7655a84-f9fd-411b-98ee-038ab250ac43
Module: Generator
Module Name: tool_calls_generator_sql_agent
Module Description: Use a `LanguageModel` to generate a data model from an arbitrary input data model.
Data Model JSON Schema:
[
  {
    "additionalProperties": false,
    "description": "A natural-language question about the data.",
    "properties": {
      "query": {
        "description": "The question",
        "title": "Query",
        "type": "string"
      }
    },
    "required": [
      "query"
    ],
    "title": "Query",
    "type": "object"
  }
]

(DEBUG) [Synalinks]
Call ID: e53ac34f-6d42-472f-8883-3ff461293671
Parent call ID: f7655a84-f9fd-411b-98ee-038ab250ac43
Module: Generator
Module Name: tool_calls_generator_sql_agent
Module Description: Use a `LanguageModel` to generate a data model from an arbitrary input data model.
Data Model JSON Schema:
[
  {
    "$defs": {
      "ChatRole": {
        "description": "The chat message roles",
        "enum": [
          "system",
          "developer",
          "user",
          "assistant",
          "tool",
          "function"
        ],
        "title": "ChatRole",
        "type": "string"
      },
      "ToolCall": {
        "additionalProperties": false,
        "description": "A tool call, shaped like an OpenAI Chat Completions tool call.\n\nMirrors the wire envelope (`{id, type, function: {name, arguments}}`)\nexcept that `arguments` stays a parsed dict rather than a JSON-encoded\nstring, so modules and agents can read it directly. The string encoding\nis applied only at the wire edge (see `backend.pydantic.chat_completions`).",
        "properties": {
          "id": {
            "description": "The id of the tool call",
            "title": "Id",
            "type": "string"
          },
          "type": {
            "const": "function",
            "default": "function",
            "description": "The tool call type (always `function` today)",
            "title": "Type",
            "type": "string"
          },
          "function": {
            "$ref": "#/$defs/ToolCallFunction",
            "description": "The function invocation (name + arguments)"
          }
        },
        "required": [
          "id",
          "function"
        ],
        "title": "ToolCall",
        "type": "object"
      },
      "ToolCallFunction": {
        "additionalProperties": false,
        "description": "The `function` payload of a tool call (name + parsed arguments).",
        "properties": {
          "name": {
            "description": "The name of the function called",
            "title": "Name",
            "type": "string"
          },
          "arguments": {
            "additionalProperties": true,
            "description": "The arguments of the tool call",
            "title": "Arguments",
            "type": "object"
          }
        },
        "required": [
          "name",
          "arguments"
        ],
        "title": "ToolCallFunction",
        "type": "object"
      }
    },
    "additionalProperties": false,
    "description": "A chat message",
    "properties": {
      "role": {
        "$ref": "#/$defs/ChatRole",
        "description": "The chat message role"
      },
      "reasoning_content": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ],
        "default": null,
        "description": "The reasoning/thinking content of the message. Keyed to match the litellm/DeepSeek `reasoning_content` chat-completion field (a provider extension, not part of the base OpenAI spec), so the message API stays a subset of the litellm-extended chat-completion message.",
        "title": "Reasoning Content"
      },
      "thinking_blocks": {
        "anyOf": [
          {
            "items": {
              "additionalProperties": true,
              "type": "object"
            },
            "type": "array"
          },
          {
            "type": "null"
          }
        ],
        "default": null,
        "description": "Opaque provider-native thinking blocks (e.g. Anthropic's signed `thinking_blocks`; a litellm extension, not part of the base OpenAI spec). Carried through verbatim on assistant-message re-injection so multi-turn tool-use round-trips preserve signatures. None for providers that emit reasoning only as text.",
        "title": "Thinking Blocks"
      },
      "content": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "items": {
              "additionalProperties": true,
              "type": "object"
            },
            "type": "array"
          },
          {
            "additionalProperties": true,
            "type": "object"
          },
          {
            "type": "null"
          }
        ],
        "default": null,
        "description": "The content of the message",
        "title": "Content"
      },
      "tool_call_id": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ],
        "default": null,
        "description": "The id of the tool call if role is `tool`",
        "title": "Tool Call Id"
      },
      "tool_calls": {
        "anyOf": [
          {
            "items": {
              "$ref": "#/$defs/ToolCall"
            },
            "type": "array"
          },
          {
            "type": "null"
          }
        ],
        "default": null,
        "description": "The tool calls of the agent",
        "title": "Tool Calls"
      }
    },
    "required": [
      "role"
    ],
    "title": "ChatMessage",
    "type": "object"
  }
]

(DEBUG) [Synalinks]
Call ID: b56ac0c9-3df4-42e3-ad7a-1e598e260dc2
Parent call ID: e53ac34f-6d42-472f-8883-3ff461293671
Module: Generator
Module Name: tool_calls_generator_sql_agent
Module Description: Use a `LanguageModel` to generate a data model from an arbitrary input data model.
Data Model JSON Schema:
[
  {
    "additionalProperties": false,
    "description": "A natural-language question about the data.",
    "properties": {
      "query": {
        "description": "The question",
        "title": "Query",
        "type": "string"
      }
    },
    "required": [
      "query"
    ],
    "title": "Query",
    "type": "object"
  }
]

(DEBUG) [Synalinks]
Call ID: b56ac0c9-3df4-42e3-ad7a-1e598e260dc2
Parent call ID: e53ac34f-6d42-472f-8883-3ff461293671
Module: Generator
Module Name: tool_calls_generator_sql_agent
Module Description: Use a `LanguageModel` to generate a data model from an arbitrary input data model.
Data Model JSON Schema:
[
  {
    "$defs": {
      "ChatRole": {
        "description": "The chat message roles",
        "enum": [
          "system",
          "developer",
          "user",
          "assistant",
          "tool",
          "function"
        ],
        "title": "ChatRole",
        "type": "string"
      },
      "ToolCall": {
        "additionalProperties": false,
        "description": "A tool call, shaped like an OpenAI Chat Completions tool call.\n\nMirrors the wire envelope (`{id, type, function: {name, arguments}}`)\nexcept that `arguments` stays a parsed dict rather than a JSON-encoded\nstring, so modules and agents can read it directly. The string encoding\nis applied only at the wire edge (see `backend.pydantic.chat_completions`).",
        "properties": {
          "id": {
            "description": "The id of the tool call",
            "title": "Id",
            "type": "string"
          },
          "type": {
            "const": "function",
            "default": "function",
            "description": "The tool call type (always `function` today)",
            "title": "Type",
            "type": "string"
          },
          "function": {
            "$ref": "#/$defs/ToolCallFunction",
            "description": "The function invocation (name + arguments)"
          }
        },
        "required": [
          "id",
          "function"
        ],
        "title": "ToolCall",
        "type": "object"
      },
      "ToolCallFunction": {
        "additionalProperties": false,
        "description": "The `function` payload of a tool call (name + parsed arguments).",
        "properties": {
          "name": {
            "description": "The name of the function called",
            "title": "Name",
            "type": "string"
          },
          "arguments": {
            "additionalProperties": true,
            "description": "The arguments of the tool call",
            "title": "Arguments",
            "type": "object"
          }
        },
        "required": [
          "name",
          "arguments"
        ],
        "title": "ToolCallFunction",
        "type": "object"
      }
    },
    "additionalProperties": false,
    "description": "A chat message",
    "properties": {
      "role": {
        "$ref": "#/$defs/ChatRole",
        "description": "The chat message role"
      },
      "reasoning_content": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ],
        "default": null,
        "description": "The reasoning/thinking content of the message. Keyed to match the litellm/DeepSeek `reasoning_content` chat-completion field (a provider extension, not part of the base OpenAI spec), so the message API stays a subset of the litellm-extended chat-completion message.",
        "title": "Reasoning Content"
      },
      "thinking_blocks": {
        "anyOf": [
          {
            "items": {
              "additionalProperties": true,
              "type": "object"
            },
            "type": "array"
          },
          {
            "type": "null"
          }
        ],
        "default": null,
        "description": "Opaque provider-native thinking blocks (e.g. Anthropic's signed `thinking_blocks`; a litellm extension, not part of the base OpenAI spec). Carried through verbatim on assistant-message re-injection so multi-turn tool-use round-trips preserve signatures. None for providers that emit reasoning only as text.",
        "title": "Thinking Blocks"
      },
      "content": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "items": {
              "additionalProperties": true,
              "type": "object"
            },
            "type": "array"
          },
          {
            "additionalProperties": true,
            "type": "object"
          },
          {
            "type": "null"
          }
        ],
        "default": null,
        "description": "The content of the message",
        "title": "Content"
      },
      "tool_call_id": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ],
        "default": null,
        "description": "The id of the tool call if role is `tool`",
        "title": "Tool Call Id"
      },
      "tool_calls": {
        "anyOf": [
          {
            "items": {
              "$ref": "#/$defs/ToolCall"
            },
            "type": "array"
          },
          {
            "type": "null"
          }
        ],
        "default": null,
        "description": "The tool calls of the agent",
        "title": "Tool Calls"
      }
    },
    "required": [
      "role"
    ],
    "title": "ChatMessage",
    "type": "object"
  }
]

(DEBUG) [Synalinks]
Call ID: f7655a84-f9fd-411b-98ee-038ab250ac43
Parent call ID: None
Module: SQLAgent
Module Name: sql_agent
Module Description: A ready-to-use SQL agent backed by a knowledge base.
Data Model JSON Schema:
[
  {
    "additionalProperties": false,
    "$defs": {
      "ChatMessage": {
        "additionalProperties": false,
        "description": "A chat message",
        "properties": {
          "role": {
            "$ref": "#/$defs/ChatRole",
            "description": "The chat message role"
          },
          "reasoning_content": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "The reasoning/thinking content of the message. Keyed to match the litellm/DeepSeek `reasoning_content` chat-completion field (a provider extension, not part of the base OpenAI spec), so the message API stays a subset of the litellm-extended chat-completion message.",
            "title": "Reasoning Content"
          },
          "thinking_blocks": {
            "anyOf": [
              {
                "items": {
                  "additionalProperties": true,
                  "type": "object"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Opaque provider-native thinking blocks (e.g. Anthropic's signed `thinking_blocks`; a litellm extension, not part of the base OpenAI spec). Carried through verbatim on assistant-message re-injection so multi-turn tool-use round-trips preserve signatures. None for providers that emit reasoning only as text.",
            "title": "Thinking Blocks"
          },
          "content": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "items": {
                  "additionalProperties": true,
                  "type": "object"
                },
                "type": "array"
              },
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "The content of the message",
            "title": "Content"
          },
          "tool_call_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "The id of the tool call if role is `tool`",
            "title": "Tool Call Id"
          },
          "tool_calls": {
            "anyOf": [
              {
                "items": {
                  "$ref": "#/$defs/ToolCall"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "The tool calls of the agent",
            "title": "Tool Calls"
          }
        },
        "required": [
          "role"
        ],
        "title": "ChatMessage",
        "type": "object"
      },
      "ChatRole": {
        "description": "The chat message roles",
        "enum": [
          "system",
          "developer",
          "user",
          "assistant",
          "tool",
          "function"
        ],
        "title": "ChatRole",
        "type": "string"
      },
      "ToolCall": {
        "additionalProperties": false,
        "description": "A tool call, shaped like an OpenAI Chat Completions tool call.\n\nMirrors the wire envelope (`{id, type, function: {name, arguments}}`)\nexcept that `arguments` stays a parsed dict rather than a JSON-encoded\nstring, so modules and agents can read it directly. The string encoding\nis applied only at the wire edge (see `backend.pydantic.chat_completions`).",
        "properties": {
          "id": {
            "description": "The id of the tool call",
            "title": "Id",
            "type": "string"
          },
          "type": {
            "const": "function",
            "default": "function",
            "description": "The tool call type (always `function` today)",
            "title": "Type",
            "type": "string"
          },
          "function": {
            "$ref": "#/$defs/ToolCallFunction",
            "description": "The function invocation (name + arguments)"
          }
        },
        "required": [
          "id",
          "function"
        ],
        "title": "ToolCall",
        "type": "object"
      },
      "ToolCallFunction": {
        "additionalProperties": false,
        "description": "The `function` payload of a tool call (name + parsed arguments).",
        "properties": {
          "name": {
            "description": "The name of the function called",
            "title": "Name",
            "type": "string"
          },
          "arguments": {
            "additionalProperties": true,
            "description": "The arguments of the tool call",
            "title": "Arguments",
            "type": "object"
          }
        },
        "required": [
          "name",
          "arguments"
        ],
        "title": "ToolCallFunction",
        "type": "object"
      }
    },
    "properties": {
      "messages": {
        "default": [],
        "description": "The list of chat messages",
        "items": {
          "$ref": "#/$defs/ChatMessage"
        },
        "title": "Messages",
        "type": "array"
      },
      "answer": {
        "description": "Natural-language answer",
        "title": "Answer",
        "type": "string"
      },
      "sql_query": {
        "description": "SQL that produced the answer",
        "title": "Sql Query",
        "type": "string"
      }
    },
    "required": [
      "answer",
      "sql_query"
    ],
    "title": "ChatMessages",
    "type": "object"
  }
]

Program: sql_agent
description: 'A SQL agent that answers questions about the database.'
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┓
┃ Module (type)               ┃ Output Schema                    ┃  Vars # ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━┩
│ input_module (InputModule)  │ Query:                           │       0 │
│                             │   query: str                     │         │
├─────────────────────────────┼──────────────────────────────────┼─────────┤
│ sql_agent (SQLAgent)        │ ChatRole: Literal['system',      │       2 │
│                             │ 'developer', 'user',             │         │
│                             │ 'assistant', 'tool', 'function'] │         │
│                             │                                  │         │
│                             │ ToolCallFunction:                │         │
│                             │   name: str                      │         │
│                             │   arguments: dict                │         │
│                             │                                  │         │
│                             │ ToolCall:                        │         │
│                             │   id: str                        │         │
│                             │   type: Literal['function'] =    │         │
│                             │ 'function'                       │         │
│                             │   function: ToolCallFunction     │         │
│                             │                                  │         │
│                             │ ChatMessage:                     │         │
│                             │   role: ChatRole                 │         │
│                             │   reasoning_content: str | None  │         │
│                             │ = None                           │         │
│                             │   thinking_blocks: list | None = │         │
│                             │ None                             │         │
│                             │   content: str | list | dict |   │         │
│                             │ None = None                      │         │
│                             │   tool_call_id: str | None =     │         │
│                             │ None                             │         │
│                             │   tool_calls: list[ToolCall] |   │         │
│                             │ None = None                      │         │
│                             │                                  │         │
│                             │ ChatMessages:                    │         │
│                             │   messages: list[ChatMessage] =  │         │
│                             │ []                               │         │
│                             │   answer: str                    │         │
│                             │   sql_query: str                 │         │
└─────────────────────────────┴──────────────────────────────────┴─────────┘
[Synalinks]
Call ID: e2c07505-2d33-4fdb-a51e-d003b5411d6e
Parent call ID: None
Module: Functional
Module Name: sql_agent
Module Description: A SQL agent that answers questions about the database.
Data Model JSON:
[
  {
    "query": "Who are the top 2 customers by total order amount?"
  }
]

[Synalinks]
Call ID: 8d65e7b4-a33d-4eb6-b29c-416b61ee4754
Parent call ID: e2c07505-2d33-4fdb-a51e-d003b5411d6e
Module: SQLAgent
Module Name: sql_agent
Module Description: A ready-to-use SQL agent backed by a knowledge base.
Data Model JSON:
[
  {
    "query": "Who are the top 2 customers by total order amount?"
  }
]

[Synalinks]
Call ID: 51e49204-d26a-4817-b0f3-ad72cd646f40
Parent call ID: 8d65e7b4-a33d-4eb6-b29c-416b61ee4754
Module: Generator
Module Name: tool_calls_generator_sql_agent
Module Description: Use a `LanguageModel` to generate a data model from an arbitrary input data model.
Data Model JSON:
[
  {
    "query": "Who are the top 2 customers by total order amount?",
    "messages": []
  }
]

[Synalinks]
Call ID: 213f8ba5-ffe1-4eeb-b477-e64fb7150efd
Parent call ID: 51e49204-d26a-4817-b0f3-ad72cd646f40
Module: LanguageModel
Module Name: language_model
Module Description: A language model API wrapper.
Data Model JSON:
[
  {
    "messages": [
      {
        "role": "system",
        "content": "<instructions>\nYou are an SQL analyst with read-only access to a knowledge base.\n\nAvailable tables: ['Customer', 'SalesOrder']\n\nPlan:\n1. If you don't already know the schema, call `get_database_schema` first.\n2. When you need to inspect representative values, call `get_table_sample`.\n3. Build a single `SELECT` query and execute it with `run_sql_query`. Iterate\n   on the query (read the error, fix the SQL, retry) until you have the data.\n4. Once you have an answer, stop calling tools and produce the final response.\n\nConstraints:\n- Only `SELECT` statements are accepted. `INSERT`, `UPDATE`, `DELETE`,\n  `DROP`, `ALTER`, `COPY ... TO`, and multi-statement queries are\n  rejected by the engine — don't waste turns trying them.\n- Table and column names are case-sensitive: tables are PascalCase\n  (e.g. ``Customer``), columns are snake_case (e.g. ``customer_id``).\n- Result sets are automatically capped server-side. If the result\n  shows ``may_have_more=true``, refine the query (add filters or\n  ``ORDER BY ... LIMIT n``) rather than asking for more rows.\n</instructions>\n"
      },
      {
        "role": "user",
        "content": "<input>\n{'query': 'Who are the top 2 customers by total order amount?'}\n</input>\n<output>\n"
      }
    ]
  }
]

[Synalinks]
Call ID: 213f8ba5-ffe1-4eeb-b477-e64fb7150efd
Parent call ID: 51e49204-d26a-4817-b0f3-ad72cd646f40
Module: LanguageModel
Module Name: language_model
Module Description: A language model API wrapper.
Data Model JSON:
[
  {
    "role": "assistant",
    "content": "",
    "reasoning_content": "Okay, let's tackle the user's question: \"Who are the top 2 customers by total order amount?\" \n\nFirst, I need to figure out which tables and columns are involved. The available tables are Customer and SalesOrder. The Customer table probably has customer information, and SalesOrder would have order details. To find the total order amount per customer, I'll need to link these two tables.\n\nI should check the schema to confirm the columns. The Customer table likely has a customer_id, and the SalesOrder table would have a customer_id foreign key, along with an amount column. But wait, the user mentioned \"total order amount,\" so maybe the SalesOrder table has an order_amount or similar column. \n\nSince I don't have the schema yet, I should call get_database_schema to understand the structure. Once I have the schema, I can determine the correct columns to join and aggregate.\n\nAssuming the schema shows that SalesOrder has customer_id and order_amount, the next step is to sum the order amounts per customer. Then, order those sums in descending order and pick the top 2. \n\nI'll need to join Customer and SalesOrder on customer_id, sum the order amounts, group by customer, then order by the sum descending. Finally, limit to 2 results. \n\nBut wait, the user might want the customer names, so the Customer table should have a name column. So the query would select customer.name, sum(order.amount), group by customer.id, order by sum desc, limit 2. \n\nI should also check if there are any other relevant columns or if there are multiple tables involved. Let me start by getting the schema to confirm the exact column names and relationships.\n",
    "tool_calls": [
      {
        "id": "call_q4hu3puq",
        "type": "function",
        "function": {
          "name": "get_database_schema",
          "arguments": {}
        }
      }
    ]
  }
]

[Synalinks]
Call ID: 51e49204-d26a-4817-b0f3-ad72cd646f40
Parent call ID: 8d65e7b4-a33d-4eb6-b29c-416b61ee4754
Module: Generator
Module Name: tool_calls_generator_sql_agent
Module Description: Use a `LanguageModel` to generate a data model from an arbitrary input data model.
Data Model JSON:
[
  {
    "role": "assistant",
    "content": "",
    "reasoning_content": "Okay, let's tackle the user's question: \"Who are the top 2 customers by total order amount?\" \n\nFirst, I need to figure out which tables and columns are involved. The available tables are Customer and SalesOrder. The Customer table probably has customer information, and SalesOrder would have order details. To find the total order amount per customer, I'll need to link these two tables.\n\nI should check the schema to confirm the columns. The Customer table likely has a customer_id, and the SalesOrder table would have a customer_id foreign key, along with an amount column. But wait, the user mentioned \"total order amount,\" so maybe the SalesOrder table has an order_amount or similar column. \n\nSince I don't have the schema yet, I should call get_database_schema to understand the structure. Once I have the schema, I can determine the correct columns to join and aggregate.\n\nAssuming the schema shows that SalesOrder has customer_id and order_amount, the next step is to sum the order amounts per customer. Then, order those sums in descending order and pick the top 2. \n\nI'll need to join Customer and SalesOrder on customer_id, sum the order amounts, group by customer, then order by the sum descending. Finally, limit to 2 results. \n\nBut wait, the user might want the customer names, so the Customer table should have a name column. So the query would select customer.name, sum(order.amount), group by customer.id, order by sum desc, limit 2. \n\nI should also check if there are any other relevant columns or if there are multiple tables involved. Let me start by getting the schema to confirm the exact column names and relationships.\n",
    "tool_calls": [
      {
        "id": "call_q4hu3puq",
        "type": "function",
        "function": {
          "name": "get_database_schema",
          "arguments": {}
        }
      }
    ]
  }
]

[Synalinks]
Call ID: b4bc05c6-9c3d-480b-bc7c-9d1eb46917ba
Parent call ID: 213f8ba5-ffe1-4eeb-b477-e64fb7150efd
Module: Tool
Module Name: get_database_schema
Module Description: Get the complete database schema including all tables and their columns.
Data Model JSON:
[
  {
    "schema": "Table: Customer\n  - id (string): \n  - name (string): \n  - country (string): \n\nTable: SalesOrder\n  - id (string): \n  - customer_id (string): \n  - total_amount (number): ",
    "table_count": 2
  }
]

[Synalinks]
Call ID: 88528108-8a35-4631-a8a8-cda560f264da
Parent call ID: b4bc05c6-9c3d-480b-bc7c-9d1eb46917ba
Module: Generator
Module Name: tool_calls_generator_sql_agent
Module Description: Use a `LanguageModel` to generate a data model from an arbitrary input data model.
Data Model JSON:
[
  {
    "query": "Who are the top 2 customers by total order amount?",
    "messages": [
      {
        "role": "assistant",
        "content": "",
        "reasoning_content": "Okay, let's tackle the user's question: \"Who are the top 2 customers by total order amount?\" \n\nFirst, I need to figure out which tables and columns are involved. The available tables are Customer and SalesOrder. The Customer table probably has customer information, and SalesOrder would have order details. To find the total order amount per customer, I'll need to link these two tables.\n\nI should check the schema to confirm the columns. The Customer table likely has a customer_id, and the SalesOrder table would have a customer_id foreign key, along with an amount column. But wait, the user mentioned \"total order amount,\" so maybe the SalesOrder table has an order_amount or similar column. \n\nSince I don't have the schema yet, I should call get_database_schema to understand the structure. Once I have the schema, I can determine the correct columns to join and aggregate.\n\nAssuming the schema shows that SalesOrder has customer_id and order_amount, the next step is to sum the order amounts per customer. Then, order those sums in descending order and pick the top 2. \n\nI'll need to join Customer and SalesOrder on customer_id, sum the order amounts, group by customer, then order by the sum descending. Finally, limit to 2 results. \n\nBut wait, the user might want the customer names, so the Customer table should have a name column. So the query would select customer.name, sum(order.amount), group by customer.id, order by sum desc, limit 2. \n\nI should also check if there are any other relevant columns or if there are multiple tables involved. Let me start by getting the schema to confirm the exact column names and relationships.\n",
        "tool_calls": [
          {
            "id": "call_q4hu3puq",
            "type": "function",
            "function": {
              "name": "get_database_schema",
              "arguments": {}
            }
          }
        ]
      },
      {
        "role": "tool",
        "content": {
          "schema": "Table: Customer\n  - id (string): \n  - name (string): \n  - country (string): \n\nTable: SalesOrder\n  - id (string): \n  - customer_id (string): \n  - total_amount (number): ",
          "table_count": 2
        },
        "tool_call_id": "call_q4hu3puq"
      }
    ]
  }
]

[Synalinks]
Call ID: 45a68d4e-ba1f-413b-bb86-4f841a70763c
Parent call ID: 88528108-8a35-4631-a8a8-cda560f264da
Module: LanguageModel
Module Name: language_model
Module Description: A language model API wrapper.
Data Model JSON:
[
  {
    "messages": [
      {
        "role": "system",
        "content": "<instructions>\nYou are an SQL analyst with read-only access to a knowledge base.\n\nAvailable tables: ['Customer', 'SalesOrder']\n\nPlan:\n1. If you don't already know the schema, call `get_database_schema` first.\n2. When you need to inspect representative values, call `get_table_sample`.\n3. Build a single `SELECT` query and execute it with `run_sql_query`. Iterate\n   on the query (read the error, fix the SQL, retry) until you have the data.\n4. Once you have an answer, stop calling tools and produce the final response.\n\nConstraints:\n- Only `SELECT` statements are accepted. `INSERT`, `UPDATE`, `DELETE`,\n  `DROP`, `ALTER`, `COPY ... TO`, and multi-statement queries are\n  rejected by the engine — don't waste turns trying them.\n- Table and column names are case-sensitive: tables are PascalCase\n  (e.g. ``Customer``), columns are snake_case (e.g. ``customer_id``).\n- Result sets are automatically capped server-side. If the result\n  shows ``may_have_more=true``, refine the query (add filters or\n  ``ORDER BY ... LIMIT n``) rather than asking for more rows.\n</instructions>\n"
      },
      {
        "role": "user",
        "content": "<input>\n{'query': 'Who are the top 2 customers by total order amount?'}\n</input>\n<output>\n"
      },
      {
        "role": "assistant",
        "reasoning_content": "Okay, let's tackle the user's question: \"Who are the top 2 customers by total order amount?\" \n\nFirst, I need to figure out which tables and columns are involved. The available tables are Customer and SalesOrder. The Customer table probably has customer information, and SalesOrder would have order details. To find the total order amount per customer, I'll need to link these two tables.\n\nI should check the schema to confirm the columns. The Customer table likely has a customer_id, and the SalesOrder table would have a customer_id foreign key, along with an amount column. But wait, the user mentioned \"total order amount,\" so maybe the SalesOrder table has an order_amount or similar column. \n\nSince I don't have the schema yet, I should call get_database_schema to understand the structure. Once I have the schema, I can determine the correct columns to join and aggregate.\n\nAssuming the schema shows that SalesOrder has customer_id and order_amount, the next step is to sum the order amounts per customer. Then, order those sums in descending order and pick the top 2. \n\nI'll need to join Customer and SalesOrder on customer_id, sum the order amounts, group by customer, then order by the sum descending. Finally, limit to 2 results. \n\nBut wait, the user might want the customer names, so the Customer table should have a name column. So the query would select customer.name, sum(order.amount), group by customer.id, order by sum desc, limit 2. \n\nI should also check if there are any other relevant columns or if there are multiple tables involved. Let me start by getting the schema to confirm the exact column names and relationships.\n",
        "content": "",
        "tool_calls": [
          {
            "id": "call_q4hu3puq",
            "type": "function",
            "function": {
              "name": "get_database_schema",
              "arguments": {}
            }
          }
        ]
      },
      {
        "role": "tool",
        "content": {
          "schema": "Table: Customer\n  - id (string): \n  - name (string): \n  - country (string): \n\nTable: SalesOrder\n  - id (string): \n  - customer_id (string): \n  - total_amount (number): ",
          "table_count": 2
        },
        "tool_call_id": "call_q4hu3puq"
      }
    ]
  }
]

[Synalinks]
Call ID: 45a68d4e-ba1f-413b-bb86-4f841a70763c
Parent call ID: 88528108-8a35-4631-a8a8-cda560f264da
Module: LanguageModel
Module Name: language_model
Module Description: A language model API wrapper.
Data Model JSON:
[
  {
    "role": "assistant",
    "content": "",
    "reasoning_content": "Okay, now that I have the schema, let's plan the query. The user wants the top 2 customers by total order amount. \n\nFirst, I need to connect the Customer table with the SalesOrder table. The SalesOrder has a customer_id, which should link to the Customer's id. \n\nThe goal is to sum the total_amount from SalesOrder for each customer and then order them in descending order to get the top 2. \n\nSo, I'll need to join Customer and SalesOrder on customer.id = salesorder.customer_id. Then, group by customer.id and customer.name to aggregate the total amounts. \n\nWait, but in SQL, when grouping, I should include all selected columns in the GROUP BY clause. Since I'm selecting customer.name and sum(total_amount), I need to group by customer.id and customer.name to ensure correctness. \n\nBut maybe the database allows grouping by just the id if name is functionally dependent. However, to be safe, I should include both. Alternatively, maybe the customer.id is unique, so grouping by id would suffice. Let me check the schema again. The Customer table has id and name. So, to avoid issues, I'll group by both id and name. \n\nThen, order the results by the sum of total_amount in descending order and limit to 2 rows. \n\nThe final query should select customer.name, sum(total_amount) as total, then group by customer.id and name, order by total desc, limit 2. \n\nWait, but the user might want the customer's name and their total. So the SELECT clause should include customer.name and the aggregated sum. \n\nLet me structure the query:\n\nSELECT \n  customer.name, \n  SUM(salesorder.total_amount) AS total_order_amount\nFROM \n  Customer\nJOIN \n  SalesOrder ON Customer.id = SalesOrder.customer_id\nGROUP BY \n  Customer.id, Customer.name\nORDER BY \n  total_order_amount DESC\nLIMIT 2;\n\nThat should do it. Now, I need to execute this query using run_sql_query. Let me make sure there are no syntax errors. The column names are correct? The SalesOrder has total_amount, and Customer has id and name. Yes. \n\nSo the next step is to call run_sql_query with this SQL statement.\n",
    "tool_calls": [
      {
        "id": "call_u0o1owdt",
        "type": "function",
        "function": {
          "name": "run_sql_query",
          "arguments": {
            "sql_query": "SELECT customer.name, SUM(salesorder.total_amount) AS total_order_amount FROM Customer JOIN SalesOrder ON Customer.id = SalesOrder.customer_id GROUP BY Customer.id, Customer.name ORDER BY total_order_amount DESC LIMIT 2;"
          }
        }
      }
    ]
  }
]

[Synalinks]
Call ID: 88528108-8a35-4631-a8a8-cda560f264da
Parent call ID: b4bc05c6-9c3d-480b-bc7c-9d1eb46917ba
Module: Generator
Module Name: tool_calls_generator_sql_agent
Module Description: Use a `LanguageModel` to generate a data model from an arbitrary input data model.
Data Model JSON:
[
  {
    "role": "assistant",
    "content": "",
    "reasoning_content": "Okay, now that I have the schema, let's plan the query. The user wants the top 2 customers by total order amount. \n\nFirst, I need to connect the Customer table with the SalesOrder table. The SalesOrder has a customer_id, which should link to the Customer's id. \n\nThe goal is to sum the total_amount from SalesOrder for each customer and then order them in descending order to get the top 2. \n\nSo, I'll need to join Customer and SalesOrder on customer.id = salesorder.customer_id. Then, group by customer.id and customer.name to aggregate the total amounts. \n\nWait, but in SQL, when grouping, I should include all selected columns in the GROUP BY clause. Since I'm selecting customer.name and sum(total_amount), I need to group by customer.id and customer.name to ensure correctness. \n\nBut maybe the database allows grouping by just the id if name is functionally dependent. However, to be safe, I should include both. Alternatively, maybe the customer.id is unique, so grouping by id would suffice. Let me check the schema again. The Customer table has id and name. So, to avoid issues, I'll group by both id and name. \n\nThen, order the results by the sum of total_amount in descending order and limit to 2 rows. \n\nThe final query should select customer.name, sum(total_amount) as total, then group by customer.id and name, order by total desc, limit 2. \n\nWait, but the user might want the customer's name and their total. So the SELECT clause should include customer.name and the aggregated sum. \n\nLet me structure the query:\n\nSELECT \n  customer.name, \n  SUM(salesorder.total_amount) AS total_order_amount\nFROM \n  Customer\nJOIN \n  SalesOrder ON Customer.id = SalesOrder.customer_id\nGROUP BY \n  Customer.id, Customer.name\nORDER BY \n  total_order_amount DESC\nLIMIT 2;\n\nThat should do it. Now, I need to execute this query using run_sql_query. Let me make sure there are no syntax errors. The column names are correct? The SalesOrder has total_amount, and Customer has id and name. Yes. \n\nSo the next step is to call run_sql_query with this SQL statement.\n",
    "tool_calls": [
      {
        "id": "call_u0o1owdt",
        "type": "function",
        "function": {
          "name": "run_sql_query",
          "arguments": {
            "sql_query": "SELECT customer.name, SUM(salesorder.total_amount) AS total_order_amount FROM Customer JOIN SalesOrder ON Customer.id = SalesOrder.customer_id GROUP BY Customer.id, Customer.name ORDER BY total_order_amount DESC LIMIT 2;"
          }
        }
      }
    ]
  }
]

[Synalinks]
Call ID: e5a7b2a1-a14e-41f2-821e-dc71ab51e0cb
Parent call ID: 45a68d4e-ba1f-413b-bb86-4f841a70763c
Module: Tool
Module Name: run_sql_query
Module Description: Execute a read-only SELECT query and return the rows.
Keyword Arguments:
{
  "sql_query": "SELECT customer.name, SUM(salesorder.total_amount) AS total_order_amount FROM Customer JOIN SalesOrder ON Customer.id = SalesOrder.customer_id GROUP BY Customer.id, Customer.name ORDER BY total_order_amount DESC LIMIT 2;"
}

[Synalinks]
Call ID: e5a7b2a1-a14e-41f2-821e-dc71ab51e0cb
Parent call ID: 45a68d4e-ba1f-413b-bb86-4f841a70763c
Module: Tool
Module Name: run_sql_query
Module Description: Execute a read-only SELECT query and return the rows.
Data Model JSON:
[
  {
    "success": true,
    "query": "SELECT customer.name, SUM(salesorder.total_amount) AS total_order_amount FROM Customer JOIN SalesOrder ON Customer.id = SalesOrder.customer_id GROUP BY Customer.id, Customer.name ORDER BY total_order_amount DESC LIMIT 2;",
    "row_count": 2,
    "row_cap": 50,
    "results": "\"name\",\"total_order_amount\"\n\"Carol\",1500\n\"Alice\",1500\n",
    "output_format": "csv",
    "may_have_more": false
  }
]

[Synalinks]
Call ID: a7a40b36-957b-411e-b915-97ee38d76790
Parent call ID: e5a7b2a1-a14e-41f2-821e-dc71ab51e0cb
Module: Generator
Module Name: tool_calls_generator_sql_agent
Module Description: Use a `LanguageModel` to generate a data model from an arbitrary input data model.
Data Model JSON:
[
  {
    "query": "Who are the top 2 customers by total order amount?",
    "messages": [
      {
        "role": "assistant",
        "content": "",
        "reasoning_content": "Okay, let's tackle the user's question: \"Who are the top 2 customers by total order amount?\" \n\nFirst, I need to figure out which tables and columns are involved. The available tables are Customer and SalesOrder. The Customer table probably has customer information, and SalesOrder would have order details. To find the total order amount per customer, I'll need to link these two tables.\n\nI should check the schema to confirm the columns. The Customer table likely has a customer_id, and the SalesOrder table would have a customer_id foreign key, along with an amount column. But wait, the user mentioned \"total order amount,\" so maybe the SalesOrder table has an order_amount or similar column. \n\nSince I don't have the schema yet, I should call get_database_schema to understand the structure. Once I have the schema, I can determine the correct columns to join and aggregate.\n\nAssuming the schema shows that SalesOrder has customer_id and order_amount, the next step is to sum the order amounts per customer. Then, order those sums in descending order and pick the top 2. \n\nI'll need to join Customer and SalesOrder on customer_id, sum the order amounts, group by customer, then order by the sum descending. Finally, limit to 2 results. \n\nBut wait, the user might want the customer names, so the Customer table should have a name column. So the query would select customer.name, sum(order.amount), group by customer.id, order by sum desc, limit 2. \n\nI should also check if there are any other relevant columns or if there are multiple tables involved. Let me start by getting the schema to confirm the exact column names and relationships.\n",
        "tool_calls": [
          {
            "id": "call_q4hu3puq",
            "type": "function",
            "function": {
              "name": "get_database_schema",
              "arguments": {}
            }
          }
        ]
      },
      {
        "role": "tool",
        "content": {
          "schema": "Table: Customer\n  - id (string): \n  - name (string): \n  - country (string): \n\nTable: SalesOrder\n  - id (string): \n  - customer_id (string): \n  - total_amount (number): ",
          "table_count": 2
        },
        "tool_call_id": "call_q4hu3puq"
      },
      {
        "role": "assistant",
        "content": "",
        "reasoning_content": "Okay, now that I have the schema, let's plan the query. The user wants the top 2 customers by total order amount. \n\nFirst, I need to connect the Customer table with the SalesOrder table. The SalesOrder has a customer_id, which should link to the Customer's id. \n\nThe goal is to sum the total_amount from SalesOrder for each customer and then order them in descending order to get the top 2. \n\nSo, I'll need to join Customer and SalesOrder on customer.id = salesorder.customer_id. Then, group by customer.id and customer.name to aggregate the total amounts. \n\nWait, but in SQL, when grouping, I should include all selected columns in the GROUP BY clause. Since I'm selecting customer.name and sum(total_amount), I need to group by customer.id and customer.name to ensure correctness. \n\nBut maybe the database allows grouping by just the id if name is functionally dependent. However, to be safe, I should include both. Alternatively, maybe the customer.id is unique, so grouping by id would suffice. Let me check the schema again. The Customer table has id and name. So, to avoid issues, I'll group by both id and name. \n\nThen, order the results by the sum of total_amount in descending order and limit to 2 rows. \n\nThe final query should select customer.name, sum(total_amount) as total, then group by customer.id and name, order by total desc, limit 2. \n\nWait, but the user might want the customer's name and their total. So the SELECT clause should include customer.name and the aggregated sum. \n\nLet me structure the query:\n\nSELECT \n  customer.name, \n  SUM(salesorder.total_amount) AS total_order_amount\nFROM \n  Customer\nJOIN \n  SalesOrder ON Customer.id = SalesOrder.customer_id\nGROUP BY \n  Customer.id, Customer.name\nORDER BY \n  total_order_amount DESC\nLIMIT 2;\n\nThat should do it. Now, I need to execute this query using run_sql_query. Let me make sure there are no syntax errors. The column names are correct? The SalesOrder has total_amount, and Customer has id and name. Yes. \n\nSo the next step is to call run_sql_query with this SQL statement.\n",
        "tool_calls": [
          {
            "id": "call_u0o1owdt",
            "type": "function",
            "function": {
              "name": "run_sql_query",
              "arguments": {
                "sql_query": "SELECT customer.name, SUM(salesorder.total_amount) AS total_order_amount FROM Customer JOIN SalesOrder ON Customer.id = SalesOrder.customer_id GROUP BY Customer.id, Customer.name ORDER BY total_order_amount DESC LIMIT 2;"
              }
            }
          }
        ]
      },
      {
        "role": "tool",
        "content": {
          "success": true,
          "query": "SELECT customer.name, SUM(salesorder.total_amount) AS total_order_amount FROM Customer JOIN SalesOrder ON Customer.id = SalesOrder.customer_id GROUP BY Customer.id, Customer.name ORDER BY total_order_amount DESC LIMIT 2;",
          "row_count": 2,
          "row_cap": 50,
          "results": "\"name\",\"total_order_amount\"\n\"Carol\",1500\n\"Alice\",1500\n",
          "output_format": "csv",
          "may_have_more": false
        },
        "tool_call_id": "call_u0o1owdt"
      }
    ]
  }
]

[Synalinks]
Call ID: d82fecf6-5956-40c0-9bc5-84f4422ed02c
Parent call ID: a7a40b36-957b-411e-b915-97ee38d76790
Module: LanguageModel
Module Name: language_model
Module Description: A language model API wrapper.
Data Model JSON:
[
  {
    "messages": [
      {
        "role": "system",
        "content": "<instructions>\nYou are an SQL analyst with read-only access to a knowledge base.\n\nAvailable tables: ['Customer', 'SalesOrder']\n\nPlan:\n1. If you don't already know the schema, call `get_database_schema` first.\n2. When you need to inspect representative values, call `get_table_sample`.\n3. Build a single `SELECT` query and execute it with `run_sql_query`. Iterate\n   on the query (read the error, fix the SQL, retry) until you have the data.\n4. Once you have an answer, stop calling tools and produce the final response.\n\nConstraints:\n- Only `SELECT` statements are accepted. `INSERT`, `UPDATE`, `DELETE`,\n  `DROP`, `ALTER`, `COPY ... TO`, and multi-statement queries are\n  rejected by the engine — don't waste turns trying them.\n- Table and column names are case-sensitive: tables are PascalCase\n  (e.g. ``Customer``), columns are snake_case (e.g. ``customer_id``).\n- Result sets are automatically capped server-side. If the result\n  shows ``may_have_more=true``, refine the query (add filters or\n  ``ORDER BY ... LIMIT n``) rather than asking for more rows.\n</instructions>\n"
      },
      {
        "role": "user",
        "content": "<input>\n{'query': 'Who are the top 2 customers by total order amount?'}\n</input>\n<output>\n"
      },
      {
        "role": "assistant",
        "reasoning_content": "Okay, let's tackle the user's question: \"Who are the top 2 customers by total order amount?\" \n\nFirst, I need to figure out which tables and columns are involved. The available tables are Customer and SalesOrder. The Customer table probably has customer information, and SalesOrder would have order details. To find the total order amount per customer, I'll need to link these two tables.\n\nI should check the schema to confirm the columns. The Customer table likely has a customer_id, and the SalesOrder table would have a customer_id foreign key, along with an amount column. But wait, the user mentioned \"total order amount,\" so maybe the SalesOrder table has an order_amount or similar column. \n\nSince I don't have the schema yet, I should call get_database_schema to understand the structure. Once I have the schema, I can determine the correct columns to join and aggregate.\n\nAssuming the schema shows that SalesOrder has customer_id and order_amount, the next step is to sum the order amounts per customer. Then, order those sums in descending order and pick the top 2. \n\nI'll need to join Customer and SalesOrder on customer_id, sum the order amounts, group by customer, then order by the sum descending. Finally, limit to 2 results. \n\nBut wait, the user might want the customer names, so the Customer table should have a name column. So the query would select customer.name, sum(order.amount), group by customer.id, order by sum desc, limit 2. \n\nI should also check if there are any other relevant columns or if there are multiple tables involved. Let me start by getting the schema to confirm the exact column names and relationships.\n",
        "content": "",
        "tool_calls": [
          {
            "id": "call_q4hu3puq",
            "type": "function",
            "function": {
              "name": "get_database_schema",
              "arguments": {}
            }
          }
        ]
      },
      {
        "role": "tool",
        "content": {
          "schema": "Table: Customer\n  - id (string): \n  - name (string): \n  - country (string): \n\nTable: SalesOrder\n  - id (string): \n  - customer_id (string): \n  - total_amount (number): ",
          "table_count": 2
        },
        "tool_call_id": "call_q4hu3puq"
      },
      {
        "role": "assistant",
        "reasoning_content": "Okay, now that I have the schema, let's plan the query. The user wants the top 2 customers by total order amount. \n\nFirst, I need to connect the Customer table with the SalesOrder table. The SalesOrder has a customer_id, which should link to the Customer's id. \n\nThe goal is to sum the total_amount from SalesOrder for each customer and then order them in descending order to get the top 2. \n\nSo, I'll need to join Customer and SalesOrder on customer.id = salesorder.customer_id. Then, group by customer.id and customer.name to aggregate the total amounts. \n\nWait, but in SQL, when grouping, I should include all selected columns in the GROUP BY clause. Since I'm selecting customer.name and sum(total_amount), I need to group by customer.id and customer.name to ensure correctness. \n\nBut maybe the database allows grouping by just the id if name is functionally dependent. However, to be safe, I should include both. Alternatively, maybe the customer.id is unique, so grouping by id would suffice. Let me check the schema again. The Customer table has id and name. So, to avoid issues, I'll group by both id and name. \n\nThen, order the results by the sum of total_amount in descending order and limit to 2 rows. \n\nThe final query should select customer.name, sum(total_amount) as total, then group by customer.id and name, order by total desc, limit 2. \n\nWait, but the user might want the customer's name and their total. So the SELECT clause should include customer.name and the aggregated sum. \n\nLet me structure the query:\n\nSELECT \n  customer.name, \n  SUM(salesorder.total_amount) AS total_order_amount\nFROM \n  Customer\nJOIN \n  SalesOrder ON Customer.id = SalesOrder.customer_id\nGROUP BY \n  Customer.id, Customer.name\nORDER BY \n  total_order_amount DESC\nLIMIT 2;\n\nThat should do it. Now, I need to execute this query using run_sql_query. Let me make sure there are no syntax errors. The column names are correct? The SalesOrder has total_amount, and Customer has id and name. Yes. \n\nSo the next step is to call run_sql_query with this SQL statement.\n",
        "content": "",
        "tool_calls": [
          {
            "id": "call_u0o1owdt",
            "type": "function",
            "function": {
              "name": "run_sql_query",
              "arguments": {
                "sql_query": "SELECT customer.name, SUM(salesorder.total_amount) AS total_order_amount FROM Customer JOIN SalesOrder ON Customer.id = SalesOrder.customer_id GROUP BY Customer.id, Customer.name ORDER BY total_order_amount DESC LIMIT 2;"
              }
            }
          }
        ]
      },
      {
        "role": "tool",
        "content": {
          "success": true,
          "query": "SELECT customer.name, SUM(salesorder.total_amount) AS total_order_amount FROM Customer JOIN SalesOrder ON Customer.id = SalesOrder.customer_id GROUP BY Customer.id, Customer.name ORDER BY total_order_amount DESC LIMIT 2;",
          "row_count": 2,
          "row_cap": 50,
          "results": "\"name\",\"total_order_amount\"\n\"Carol\",1500\n\"Alice\",1500\n",
          "output_format": "csv",
          "may_have_more": false
        },
        "tool_call_id": "call_u0o1owdt"
      }
    ]
  }
]

[Synalinks]
Call ID: d82fecf6-5956-40c0-9bc5-84f4422ed02c
Parent call ID: a7a40b36-957b-411e-b915-97ee38d76790
Module: LanguageModel
Module Name: language_model
Module Description: A language model API wrapper.
Data Model JSON:
[
  {
    "role": "assistant",
    "content": "The top 2 customers by total order amount are:\n\n1. **Carol** - $1500\n2. **Alice** - $1500\n\nBoth customers have the same total order amount, so they are tied for first place.",
    "reasoning_content": "Okay, let me check the results. The query returned two rows with names Carol and Alice, both having 1500 as total_order_amount. Wait, but the user asked for the top 2 customers. If they have the same total, they are tied. But maybe there's a mistake here. Let me verify the data.\n\nWait, the sample data from the query result shows both Carol and Alice with 1500. But maybe there's more data that wasn't shown due to the limit. However, the may_have_more flag is false, so the result is complete. But the user might expect different amounts. Did I make a mistake in the query?\n\nWait, the initial schema shows SalesOrder has total_amount. The query sums that correctly. Maybe the actual data has those two customers with the same total. Alternatively, perhaps the query needs to handle ties differently, but the user just wants the top two, even if they're tied. \n\nAlternatively, maybe there's an error in the query. Let me check the SQL again. The JOIN is correct, grouping by id and name, ordering by sum descending. The limit is 2. The results are correct as per the data. So the answer is Carol and Alice as the top two, each with 1500. But the user might want the names and the amounts. The final answer should list them.\n"
  }
]

[Synalinks]
Call ID: a7a40b36-957b-411e-b915-97ee38d76790
Parent call ID: e5a7b2a1-a14e-41f2-821e-dc71ab51e0cb
Module: Generator
Module Name: tool_calls_generator_sql_agent
Module Description: Use a `LanguageModel` to generate a data model from an arbitrary input data model.
Data Model JSON:
[
  {
    "role": "assistant",
    "content": "The top 2 customers by total order amount are:\n\n1. **Carol** - $1500\n2. **Alice** - $1500\n\nBoth customers have the same total order amount, so they are tied for first place.",
    "reasoning_content": "Okay, let me check the results. The query returned two rows with names Carol and Alice, both having 1500 as total_order_amount. Wait, but the user asked for the top 2 customers. If they have the same total, they are tied. But maybe there's a mistake here. Let me verify the data.\n\nWait, the sample data from the query result shows both Carol and Alice with 1500. But maybe there's more data that wasn't shown due to the limit. However, the may_have_more flag is false, so the result is complete. But the user might expect different amounts. Did I make a mistake in the query?\n\nWait, the initial schema shows SalesOrder has total_amount. The query sums that correctly. Maybe the actual data has those two customers with the same total. Alternatively, perhaps the query needs to handle ties differently, but the user just wants the top two, even if they're tied. \n\nAlternatively, maybe there's an error in the query. Let me check the SQL again. The JOIN is correct, grouping by id and name, ordering by sum descending. The limit is 2. The results are correct as per the data. So the answer is Carol and Alice as the top two, each with 1500. But the user might want the names and the amounts. The final answer should list them.\n"
  }
]

[Synalinks]
Call ID: 91e9b2d0-bfce-4029-a689-10546f684048
Parent call ID: d82fecf6-5956-40c0-9bc5-84f4422ed02c
Module: Generator
Module Name: final_generator_sql_agent
Module Description: Use a `LanguageModel` to generate a data model from an arbitrary input data model.
Data Model JSON:
[
  {
    "query": "Who are the top 2 customers by total order amount?",
    "messages": [
      {
        "role": "assistant",
        "content": "",
        "reasoning_content": "Okay, let's tackle the user's question: \"Who are the top 2 customers by total order amount?\" \n\nFirst, I need to figure out which tables and columns are involved. The available tables are Customer and SalesOrder. The Customer table probably has customer information, and SalesOrder would have order details. To find the total order amount per customer, I'll need to link these two tables.\n\nI should check the schema to confirm the columns. The Customer table likely has a customer_id, and the SalesOrder table would have a customer_id foreign key, along with an amount column. But wait, the user mentioned \"total order amount,\" so maybe the SalesOrder table has an order_amount or similar column. \n\nSince I don't have the schema yet, I should call get_database_schema to understand the structure. Once I have the schema, I can determine the correct columns to join and aggregate.\n\nAssuming the schema shows that SalesOrder has customer_id and order_amount, the next step is to sum the order amounts per customer. Then, order those sums in descending order and pick the top 2. \n\nI'll need to join Customer and SalesOrder on customer_id, sum the order amounts, group by customer, then order by the sum descending. Finally, limit to 2 results. \n\nBut wait, the user might want the customer names, so the Customer table should have a name column. So the query would select customer.name, sum(order.amount), group by customer.id, order by sum desc, limit 2. \n\nI should also check if there are any other relevant columns or if there are multiple tables involved. Let me start by getting the schema to confirm the exact column names and relationships.\n",
        "tool_calls": [
          {
            "id": "call_q4hu3puq",
            "type": "function",
            "function": {
              "name": "get_database_schema",
              "arguments": {}
            }
          }
        ]
      },
      {
        "role": "tool",
        "content": {
          "schema": "Table: Customer\n  - id (string): \n  - name (string): \n  - country (string): \n\nTable: SalesOrder\n  - id (string): \n  - customer_id (string): \n  - total_amount (number): ",
          "table_count": 2
        },
        "tool_call_id": "call_q4hu3puq"
      },
      {
        "role": "assistant",
        "content": "",
        "reasoning_content": "Okay, now that I have the schema, let's plan the query. The user wants the top 2 customers by total order amount. \n\nFirst, I need to connect the Customer table with the SalesOrder table. The SalesOrder has a customer_id, which should link to the Customer's id. \n\nThe goal is to sum the total_amount from SalesOrder for each customer and then order them in descending order to get the top 2. \n\nSo, I'll need to join Customer and SalesOrder on customer.id = salesorder.customer_id. Then, group by customer.id and customer.name to aggregate the total amounts. \n\nWait, but in SQL, when grouping, I should include all selected columns in the GROUP BY clause. Since I'm selecting customer.name and sum(total_amount), I need to group by customer.id and customer.name to ensure correctness. \n\nBut maybe the database allows grouping by just the id if name is functionally dependent. However, to be safe, I should include both. Alternatively, maybe the customer.id is unique, so grouping by id would suffice. Let me check the schema again. The Customer table has id and name. So, to avoid issues, I'll group by both id and name. \n\nThen, order the results by the sum of total_amount in descending order and limit to 2 rows. \n\nThe final query should select customer.name, sum(total_amount) as total, then group by customer.id and name, order by total desc, limit 2. \n\nWait, but the user might want the customer's name and their total. So the SELECT clause should include customer.name and the aggregated sum. \n\nLet me structure the query:\n\nSELECT \n  customer.name, \n  SUM(salesorder.total_amount) AS total_order_amount\nFROM \n  Customer\nJOIN \n  SalesOrder ON Customer.id = SalesOrder.customer_id\nGROUP BY \n  Customer.id, Customer.name\nORDER BY \n  total_order_amount DESC\nLIMIT 2;\n\nThat should do it. Now, I need to execute this query using run_sql_query. Let me make sure there are no syntax errors. The column names are correct? The SalesOrder has total_amount, and Customer has id and name. Yes. \n\nSo the next step is to call run_sql_query with this SQL statement.\n",
        "tool_calls": [
          {
            "id": "call_u0o1owdt",
            "type": "function",
            "function": {
              "name": "run_sql_query",
              "arguments": {
                "sql_query": "SELECT customer.name, SUM(salesorder.total_amount) AS total_order_amount FROM Customer JOIN SalesOrder ON Customer.id = SalesOrder.customer_id GROUP BY Customer.id, Customer.name ORDER BY total_order_amount DESC LIMIT 2;"
              }
            }
          }
        ]
      },
      {
        "role": "tool",
        "content": {
          "success": true,
          "query": "SELECT customer.name, SUM(salesorder.total_amount) AS total_order_amount FROM Customer JOIN SalesOrder ON Customer.id = SalesOrder.customer_id GROUP BY Customer.id, Customer.name ORDER BY total_order_amount DESC LIMIT 2;",
          "row_count": 2,
          "row_cap": 50,
          "results": "\"name\",\"total_order_amount\"\n\"Carol\",1500\n\"Alice\",1500\n",
          "output_format": "csv",
          "may_have_more": false
        },
        "tool_call_id": "call_u0o1owdt"
      }
    ]
  }
]

[Synalinks]
Call ID: 48abeab6-0c2b-4a6b-8042-e06d9e840f58
Parent call ID: 91e9b2d0-bfce-4029-a689-10546f684048
Module: LanguageModel
Module Name: language_model
Module Description: A language model API wrapper.
Data Model JSON:
[
  {
    "messages": [
      {
        "role": "system",
        "content": "<instructions>\nYou are an SQL analyst with read-only access to a knowledge base.\n\nAvailable tables: ['Customer', 'SalesOrder']\n\nPlan:\n1. If you don't already know the schema, call `get_database_schema` first.\n2. When you need to inspect representative values, call `get_table_sample`.\n3. Build a single `SELECT` query and execute it with `run_sql_query`. Iterate\n   on the query (read the error, fix the SQL, retry) until you have the data.\n4. Once you have an answer, stop calling tools and produce the final response.\n\nConstraints:\n- Only `SELECT` statements are accepted. `INSERT`, `UPDATE`, `DELETE`,\n  `DROP`, `ALTER`, `COPY ... TO`, and multi-statement queries are\n  rejected by the engine — don't waste turns trying them.\n- Table and column names are case-sensitive: tables are PascalCase\n  (e.g. ``Customer``), columns are snake_case (e.g. ``customer_id``).\n- Result sets are automatically capped server-side. If the result\n  shows ``may_have_more=true``, refine the query (add filters or\n  ``ORDER BY ... LIMIT n``) rather than asking for more rows.\n</instructions>\n"
      },
      {
        "role": "user",
        "content": "<input>\n{'query': 'Who are the top 2 customers by total order amount?'}\n</input>\n<output>\n"
      },
      {
        "role": "assistant",
        "reasoning_content": "Okay, let's tackle the user's question: \"Who are the top 2 customers by total order amount?\" \n\nFirst, I need to figure out which tables and columns are involved. The available tables are Customer and SalesOrder. The Customer table probably has customer information, and SalesOrder would have order details. To find the total order amount per customer, I'll need to link these two tables.\n\nI should check the schema to confirm the columns. The Customer table likely has a customer_id, and the SalesOrder table would have a customer_id foreign key, along with an amount column. But wait, the user mentioned \"total order amount,\" so maybe the SalesOrder table has an order_amount or similar column. \n\nSince I don't have the schema yet, I should call get_database_schema to understand the structure. Once I have the schema, I can determine the correct columns to join and aggregate.\n\nAssuming the schema shows that SalesOrder has customer_id and order_amount, the next step is to sum the order amounts per customer. Then, order those sums in descending order and pick the top 2. \n\nI'll need to join Customer and SalesOrder on customer_id, sum the order amounts, group by customer, then order by the sum descending. Finally, limit to 2 results. \n\nBut wait, the user might want the customer names, so the Customer table should have a name column. So the query would select customer.name, sum(order.amount), group by customer.id, order by sum desc, limit 2. \n\nI should also check if there are any other relevant columns or if there are multiple tables involved. Let me start by getting the schema to confirm the exact column names and relationships.\n",
        "content": "",
        "tool_calls": [
          {
            "id": "call_q4hu3puq",
            "type": "function",
            "function": {
              "name": "get_database_schema",
              "arguments": {}
            }
          }
        ]
      },
      {
        "role": "tool",
        "content": {
          "schema": "Table: Customer\n  - id (string): \n  - name (string): \n  - country (string): \n\nTable: SalesOrder\n  - id (string): \n  - customer_id (string): \n  - total_amount (number): ",
          "table_count": 2
        },
        "tool_call_id": "call_q4hu3puq"
      },
      {
        "role": "assistant",
        "reasoning_content": "Okay, now that I have the schema, let's plan the query. The user wants the top 2 customers by total order amount. \n\nFirst, I need to connect the Customer table with the SalesOrder table. The SalesOrder has a customer_id, which should link to the Customer's id. \n\nThe goal is to sum the total_amount from SalesOrder for each customer and then order them in descending order to get the top 2. \n\nSo, I'll need to join Customer and SalesOrder on customer.id = salesorder.customer_id. Then, group by customer.id and customer.name to aggregate the total amounts. \n\nWait, but in SQL, when grouping, I should include all selected columns in the GROUP BY clause. Since I'm selecting customer.name and sum(total_amount), I need to group by customer.id and customer.name to ensure correctness. \n\nBut maybe the database allows grouping by just the id if name is functionally dependent. However, to be safe, I should include both. Alternatively, maybe the customer.id is unique, so grouping by id would suffice. Let me check the schema again. The Customer table has id and name. So, to avoid issues, I'll group by both id and name. \n\nThen, order the results by the sum of total_amount in descending order and limit to 2 rows. \n\nThe final query should select customer.name, sum(total_amount) as total, then group by customer.id and name, order by total desc, limit 2. \n\nWait, but the user might want the customer's name and their total. So the SELECT clause should include customer.name and the aggregated sum. \n\nLet me structure the query:\n\nSELECT \n  customer.name, \n  SUM(salesorder.total_amount) AS total_order_amount\nFROM \n  Customer\nJOIN \n  SalesOrder ON Customer.id = SalesOrder.customer_id\nGROUP BY \n  Customer.id, Customer.name\nORDER BY \n  total_order_amount DESC\nLIMIT 2;\n\nThat should do it. Now, I need to execute this query using run_sql_query. Let me make sure there are no syntax errors. The column names are correct? The SalesOrder has total_amount, and Customer has id and name. Yes. \n\nSo the next step is to call run_sql_query with this SQL statement.\n",
        "content": "",
        "tool_calls": [
          {
            "id": "call_u0o1owdt",
            "type": "function",
            "function": {
              "name": "run_sql_query",
              "arguments": {
                "sql_query": "SELECT customer.name, SUM(salesorder.total_amount) AS total_order_amount FROM Customer JOIN SalesOrder ON Customer.id = SalesOrder.customer_id GROUP BY Customer.id, Customer.name ORDER BY total_order_amount DESC LIMIT 2;"
              }
            }
          }
        ]
      },
      {
        "role": "tool",
        "content": {
          "success": true,
          "query": "SELECT customer.name, SUM(salesorder.total_amount) AS total_order_amount FROM Customer JOIN SalesOrder ON Customer.id = SalesOrder.customer_id GROUP BY Customer.id, Customer.name ORDER BY total_order_amount DESC LIMIT 2;",
          "row_count": 2,
          "row_cap": 50,
          "results": "\"name\",\"total_order_amount\"\n\"Carol\",1500\n\"Alice\",1500\n",
          "output_format": "csv",
          "may_have_more": false
        },
        "tool_call_id": "call_u0o1owdt"
      }
    ]
  }
]

[Synalinks]
Call ID: 48abeab6-0c2b-4a6b-8042-e06d9e840f58
Parent call ID: 91e9b2d0-bfce-4029-a689-10546f684048
Module: LanguageModel
Module Name: language_model
Module Description: A language model API wrapper.
Data Model JSON:
[
  {
    "answer": "The top 2 customers by total order amount are:\n1. Carol with a total of $1500\n2. Alice with a total of $1500",
    "sql_query": "SELECT customer.name, SUM(salesorder.total_amount) AS total_order_amount FROM Customer JOIN SalesOrder ON Customer.id = SalesOrder.customer_id GROUP BY Customer.id, Customer.name ORDER BY total_order_amount DESC LIMIT 2;"
  }
]

[Synalinks]
Call ID: 91e9b2d0-bfce-4029-a689-10546f684048
Parent call ID: d82fecf6-5956-40c0-9bc5-84f4422ed02c
Module: Generator
Module Name: final_generator_sql_agent
Module Description: Use a `LanguageModel` to generate a data model from an arbitrary input data model.
Data Model JSON:
[
  {
    "answer": "The top 2 customers by total order amount are:\n1. Carol with a total of $1500\n2. Alice with a total of $1500",
    "sql_query": "SELECT customer.name, SUM(salesorder.total_amount) AS total_order_amount FROM Customer JOIN SalesOrder ON Customer.id = SalesOrder.customer_id GROUP BY Customer.id, Customer.name ORDER BY total_order_amount DESC LIMIT 2;"
  }
]

[Synalinks]
Call ID: 8d65e7b4-a33d-4eb6-b29c-416b61ee4754
Parent call ID: e2c07505-2d33-4fdb-a51e-d003b5411d6e
Module: SQLAgent
Module Name: sql_agent
Module Description: A ready-to-use SQL agent backed by a knowledge base.
Data Model JSON:
[
  {
    "messages": [
      {
        "role": "assistant",
        "reasoning_content": "Okay, let's tackle the user's question: \"Who are the top 2 customers by total order amount?\" \n\nFirst, I need to figure out which tables and columns are involved. The available tables are Customer and SalesOrder. The Customer table probably has customer information, and SalesOrder would have order details. To find the total order amount per customer, I'll need to link these two tables.\n\nI should check the schema to confirm the columns. The Customer table likely has a customer_id, and the SalesOrder table would have a customer_id foreign key, along with an amount column. But wait, the user mentioned \"total order amount,\" so maybe the SalesOrder table has an order_amount or similar column. \n\nSince I don't have the schema yet, I should call get_database_schema to understand the structure. Once I have the schema, I can determine the correct columns to join and aggregate.\n\nAssuming the schema shows that SalesOrder has customer_id and order_amount, the next step is to sum the order amounts per customer. Then, order those sums in descending order and pick the top 2. \n\nI'll need to join Customer and SalesOrder on customer_id, sum the order amounts, group by customer, then order by the sum descending. Finally, limit to 2 results. \n\nBut wait, the user might want the customer names, so the Customer table should have a name column. So the query would select customer.name, sum(order.amount), group by customer.id, order by sum desc, limit 2. \n\nI should also check if there are any other relevant columns or if there are multiple tables involved. Let me start by getting the schema to confirm the exact column names and relationships.\n",
        "content": "",
        "tool_calls": [
          {
            "id": "call_q4hu3puq",
            "type": "function",
            "function": {
              "name": "get_database_schema",
              "arguments": {}
            }
          }
        ]
      },
      {
        "role": "tool",
        "content": {
          "schema": "Table: Customer\n  - id (string): \n  - name (string): \n  - country (string): \n\nTable: SalesOrder\n  - id (string): \n  - customer_id (string): \n  - total_amount (number): ",
          "table_count": 2
        },
        "tool_call_id": "call_q4hu3puq"
      },
      {
        "role": "assistant",
        "reasoning_content": "Okay, now that I have the schema, let's plan the query. The user wants the top 2 customers by total order amount. \n\nFirst, I need to connect the Customer table with the SalesOrder table. The SalesOrder has a customer_id, which should link to the Customer's id. \n\nThe goal is to sum the total_amount from SalesOrder for each customer and then order them in descending order to get the top 2. \n\nSo, I'll need to join Customer and SalesOrder on customer.id = salesorder.customer_id. Then, group by customer.id and customer.name to aggregate the total amounts. \n\nWait, but in SQL, when grouping, I should include all selected columns in the GROUP BY clause. Since I'm selecting customer.name and sum(total_amount), I need to group by customer.id and customer.name to ensure correctness. \n\nBut maybe the database allows grouping by just the id if name is functionally dependent. However, to be safe, I should include both. Alternatively, maybe the customer.id is unique, so grouping by id would suffice. Let me check the schema again. The Customer table has id and name. So, to avoid issues, I'll group by both id and name. \n\nThen, order the results by the sum of total_amount in descending order and limit to 2 rows. \n\nThe final query should select customer.name, sum(total_amount) as total, then group by customer.id and name, order by total desc, limit 2. \n\nWait, but the user might want the customer's name and their total. So the SELECT clause should include customer.name and the aggregated sum. \n\nLet me structure the query:\n\nSELECT \n  customer.name, \n  SUM(salesorder.total_amount) AS total_order_amount\nFROM \n  Customer\nJOIN \n  SalesOrder ON Customer.id = SalesOrder.customer_id\nGROUP BY \n  Customer.id, Customer.name\nORDER BY \n  total_order_amount DESC\nLIMIT 2;\n\nThat should do it. Now, I need to execute this query using run_sql_query. Let me make sure there are no syntax errors. The column names are correct? The SalesOrder has total_amount, and Customer has id and name. Yes. \n\nSo the next step is to call run_sql_query with this SQL statement.\n",
        "content": "",
        "tool_calls": [
          {
            "id": "call_u0o1owdt",
            "type": "function",
            "function": {
              "name": "run_sql_query",
              "arguments": {
                "sql_query": "SELECT customer.name, SUM(salesorder.total_amount) AS total_order_amount FROM Customer JOIN SalesOrder ON Customer.id = SalesOrder.customer_id GROUP BY Customer.id, Customer.name ORDER BY total_order_amount DESC LIMIT 2;"
              }
            }
          }
        ]
      },
      {
        "role": "tool",
        "content": {
          "success": true,
          "query": "SELECT customer.name, SUM(salesorder.total_amount) AS total_order_amount FROM Customer JOIN SalesOrder ON Customer.id = SalesOrder.customer_id GROUP BY Customer.id, Customer.name ORDER BY total_order_amount DESC LIMIT 2;",
          "row_count": 2,
          "row_cap": 50,
          "results": "\"name\",\"total_order_amount\"\n\"Carol\",1500\n\"Alice\",1500\n",
          "output_format": "csv",
          "may_have_more": false
        },
        "tool_call_id": "call_u0o1owdt"
      }
    ],
    "answer": "The top 2 customers by total order amount are:\n1. Carol with a total of $1500\n2. Alice with a total of $1500",
    "sql_query": "SELECT customer.name, SUM(salesorder.total_amount) AS total_order_amount FROM Customer JOIN SalesOrder ON Customer.id = SalesOrder.customer_id GROUP BY Customer.id, Customer.name ORDER BY total_order_amount DESC LIMIT 2;"
  }
]

[Synalinks]
Call ID: e2c07505-2d33-4fdb-a51e-d003b5411d6e
Parent call ID: None
Module: Functional
Module Name: sql_agent
Module Description: A SQL agent that answers questions about the database.
Data Model JSON:
[
  {
    "messages": [
      {
        "role": "assistant",
        "reasoning_content": "Okay, let's tackle the user's question: \"Who are the top 2 customers by total order amount?\" \n\nFirst, I need to figure out which tables and columns are involved. The available tables are Customer and SalesOrder. The Customer table probably has customer information, and SalesOrder would have order details. To find the total order amount per customer, I'll need to link these two tables.\n\nI should check the schema to confirm the columns. The Customer table likely has a customer_id, and the SalesOrder table would have a customer_id foreign key, along with an amount column. But wait, the user mentioned \"total order amount,\" so maybe the SalesOrder table has an order_amount or similar column. \n\nSince I don't have the schema yet, I should call get_database_schema to understand the structure. Once I have the schema, I can determine the correct columns to join and aggregate.\n\nAssuming the schema shows that SalesOrder has customer_id and order_amount, the next step is to sum the order amounts per customer. Then, order those sums in descending order and pick the top 2. \n\nI'll need to join Customer and SalesOrder on customer_id, sum the order amounts, group by customer, then order by the sum descending. Finally, limit to 2 results. \n\nBut wait, the user might want the customer names, so the Customer table should have a name column. So the query would select customer.name, sum(order.amount), group by customer.id, order by sum desc, limit 2. \n\nI should also check if there are any other relevant columns or if there are multiple tables involved. Let me start by getting the schema to confirm the exact column names and relationships.\n",
        "content": "",
        "tool_calls": [
          {
            "id": "call_q4hu3puq",
            "type": "function",
            "function": {
              "name": "get_database_schema",
              "arguments": {}
            }
          }
        ]
      },
      {
        "role": "tool",
        "content": {
          "schema": "Table: Customer\n  - id (string): \n  - name (string): \n  - country (string): \n\nTable: SalesOrder\n  - id (string): \n  - customer_id (string): \n  - total_amount (number): ",
          "table_count": 2
        },
        "tool_call_id": "call_q4hu3puq"
      },
      {
        "role": "assistant",
        "reasoning_content": "Okay, now that I have the schema, let's plan the query. The user wants the top 2 customers by total order amount. \n\nFirst, I need to connect the Customer table with the SalesOrder table. The SalesOrder has a customer_id, which should link to the Customer's id. \n\nThe goal is to sum the total_amount from SalesOrder for each customer and then order them in descending order to get the top 2. \n\nSo, I'll need to join Customer and SalesOrder on customer.id = salesorder.customer_id. Then, group by customer.id and customer.name to aggregate the total amounts. \n\nWait, but in SQL, when grouping, I should include all selected columns in the GROUP BY clause. Since I'm selecting customer.name and sum(total_amount), I need to group by customer.id and customer.name to ensure correctness. \n\nBut maybe the database allows grouping by just the id if name is functionally dependent. However, to be safe, I should include both. Alternatively, maybe the customer.id is unique, so grouping by id would suffice. Let me check the schema again. The Customer table has id and name. So, to avoid issues, I'll group by both id and name. \n\nThen, order the results by the sum of total_amount in descending order and limit to 2 rows. \n\nThe final query should select customer.name, sum(total_amount) as total, then group by customer.id and name, order by total desc, limit 2. \n\nWait, but the user might want the customer's name and their total. So the SELECT clause should include customer.name and the aggregated sum. \n\nLet me structure the query:\n\nSELECT \n  customer.name, \n  SUM(salesorder.total_amount) AS total_order_amount\nFROM \n  Customer\nJOIN \n  SalesOrder ON Customer.id = SalesOrder.customer_id\nGROUP BY \n  Customer.id, Customer.name\nORDER BY \n  total_order_amount DESC\nLIMIT 2;\n\nThat should do it. Now, I need to execute this query using run_sql_query. Let me make sure there are no syntax errors. The column names are correct? The SalesOrder has total_amount, and Customer has id and name. Yes. \n\nSo the next step is to call run_sql_query with this SQL statement.\n",
        "content": "",
        "tool_calls": [
          {
            "id": "call_u0o1owdt",
            "type": "function",
            "function": {
              "name": "run_sql_query",
              "arguments": {
                "sql_query": "SELECT customer.name, SUM(salesorder.total_amount) AS total_order_amount FROM Customer JOIN SalesOrder ON Customer.id = SalesOrder.customer_id GROUP BY Customer.id, Customer.name ORDER BY total_order_amount DESC LIMIT 2;"
              }
            }
          }
        ]
      },
      {
        "role": "tool",
        "content": {
          "success": true,
          "query": "SELECT customer.name, SUM(salesorder.total_amount) AS total_order_amount FROM Customer JOIN SalesOrder ON Customer.id = SalesOrder.customer_id GROUP BY Customer.id, Customer.name ORDER BY total_order_amount DESC LIMIT 2;",
          "row_count": 2,
          "row_cap": 50,
          "results": "\"name\",\"total_order_amount\"\n\"Carol\",1500\n\"Alice\",1500\n",
          "output_format": "csv",
          "may_have_more": false
        },
        "tool_call_id": "call_u0o1owdt"
      }
    ],
    "answer": "The top 2 customers by total order amount are:\n1. Carol with a total of $1500\n2. Alice with a total of $1500",
    "sql_query": "SELECT customer.name, SUM(salesorder.total_amount) AS total_order_amount FROM Customer JOIN SalesOrder ON Customer.id = SalesOrder.customer_id GROUP BY Customer.id, Customer.name ORDER BY total_order_amount DESC LIMIT 2;"
  }
]

Answer: The top 2 customers by total order amount are:
1. Carol with a total of $1500
2. Alice with a total of $1500
SQL: SELECT customer.name, SUM(salesorder.total_amount) AS total_order_amount FROM Customer JOIN SalesOrder ON Customer.id = SalesOrder.customer_id GROUP BY Customer.id, Customer.name ORDER BY total_order_amount DESC LIMIT 2;

SQL Agent

SQL Agent

When Do You Want One?

The Three Tools

Why these three, and not just one

Safety Model

The k Cap

Building the Agent

A Worked Example

Compared to Other Agents

API References

Customer

Query

SQLAnswer

SalesOrder

Source

Run log

The `k` Cap

`Customer`

`Query`

`SQLAnswer`

`SalesOrder`