Building a Tool-Using Agent with Function Calling

A single function call is easy. The interesting part is the loop around it, because a model rarely gets what it needs on the first call. It looks something up, sees the result, and decides what to ask for next. This tutorial builds a command line agent that answers questions about a SQLite database it has never seen. It has no schema in its prompt. It gets three read-only tools and works the rest out itself:

python agent.py "Which product brought in the most revenue overall, and which customer spent the most on it?"

Along the way we will:

Give the model a database and three tools that read it
Describe those tools so the model knows when to reach for each one
Run the loop that turns tool calls into tool results
Watch it request several tools at once
Hand errors back to the model instead of raising them
Draw the line between what the model will not do and what it cannot do

The Function Calling guide covers the request shape on its own. This page is about what happens after the first response comes back.

Setup

You need Python 3.9 or newer, the requests package, and a Venice API key. See Generating an API Key if you do not have one. Everything else is in the standard library.

pip install requests
export VENICE_API_KEY="your-api-key-here"

Create agent.py with the imports and the header block every call reuses:

from __future__ import annotations

import json
import os
import sqlite3
import sys

import requests

BASE_URL = "https://api.venice.ai/api/v1"
HEADERS = {
    "Authorization": f"Bearer {os.environ['VENICE_API_KEY']}",
    "Content-Type": "application/json",
}
DB_PATH = "shop.db"

Not every model can call tools, and the model IDs change, so ask the API which one to use rather than pinning a name that will age:

def default_tool_model() -> str:
    response = requests.get(f"{BASE_URL}/models/traits", headers=HEADERS, timeout=30)
    response.raise_for_status()
    return response.json()["data"]["function_calling_default"]

print(default_tool_model())

zai-org-glm-5-2

GET /models/traits maps stable trait names onto whatever model currently fills that role. Reading function_calling_default at startup means your agent keeps working when the underlying model is replaced. See Models for the full trait list.

1. A database worth asking about

Any SQLite file will do. This one is a small shop with customers, products, and the orders that join them, which is enough that a real question needs a join and an aggregate:

SEED = """
CREATE TABLE customers (
    id INTEGER PRIMARY KEY,
    name TEXT NOT NULL,
    country TEXT NOT NULL,
    signed_up TEXT NOT NULL
);
CREATE TABLE products (
    id INTEGER PRIMARY KEY,
    name TEXT NOT NULL,
    category TEXT NOT NULL,
    unit_price REAL NOT NULL
);
CREATE TABLE orders (
    id INTEGER PRIMARY KEY,
    customer_id INTEGER NOT NULL REFERENCES customers(id),
    product_id INTEGER NOT NULL REFERENCES products(id),
    quantity INTEGER NOT NULL,
    ordered_on TEXT NOT NULL
);
INSERT INTO customers VALUES
    (1,'Aria Bekele','ET','2025-11-02'), (2,'Tomas Vidal','ES','2026-01-14'),
    (3,'Mei Lin','SG','2026-02-03'),     (4,'Jonas Weber','DE','2026-02-27'),
    (5,'Priya Nair','IN','2026-03-19');
INSERT INTO products VALUES
    (1,'Field Notebook','stationery',12.5), (2,'Fountain Pen','stationery',48.0),
    (3,'Desk Lamp','lighting',89.0),        (4,'Cable Organiser','desk',9.75),
    (5,'Monitor Arm','desk',156.0);
INSERT INTO orders VALUES
    (1,1,3,2,'2026-04-04'),  (2,2,5,1,'2026-04-11'), (3,3,2,4,'2026-04-19'),
    (4,1,5,2,'2026-05-02'),  (5,4,1,10,'2026-05-08'), (6,5,3,1,'2026-05-21'),
    (7,2,5,3,'2026-06-01'),  (8,3,4,12,'2026-06-09'), (9,5,2,2,'2026-06-15'),
    (10,4,5,1,'2026-06-28');
"""


def build_db() -> None:
    if os.path.exists(DB_PATH):
        return
    db = sqlite3.connect(DB_PATH)
    db.executescript(SEED)
    db.commit()
    db.close()

2. Three tools the model can reach for

The tools mirror how a person meets an unfamiliar database: find out what is in it, look at one table closely, then query it.

def list_tables() -> str:
    db = sqlite3.connect(DB_PATH)
    rows = db.execute(
        "SELECT name FROM sqlite_master WHERE type='table' ORDER BY name"
    ).fetchall()
    db.close()
    return json.dumps([row[0] for row in rows])


def describe_table(table: str) -> str:
    db = sqlite3.connect(DB_PATH)
    rows = db.execute(f"PRAGMA table_info({table})").fetchall()
    db.close()
    if not rows:
        return json.dumps({"error": f"no table named {table}"})
    return json.dumps([{"name": row[1], "type": row[2]} for row in rows])


def run_query(sql: str) -> str:
    if not sql.strip().lower().startswith("select"):
        return json.dumps({"error": "only SELECT statements are allowed"})

    db = sqlite3.connect(DB_PATH)
    try:
        cursor = db.execute(sql)
        columns = [d[0] for d in cursor.description]
        rows = [dict(zip(columns, row)) for row in cursor.fetchmany(50)]
        return json.dumps(rows)
    except (sqlite3.Error, sqlite3.Warning) as error:
        return json.dumps({"error": f"{type(error).__name__}: {error}"})
    finally:
        db.close()

Every one of them returns a JSON string, including the failures. That is deliberate, and section 5 is about why. Now describe them for the model. The description is not a comment. It is the only thing the model reads when deciding which tool to call and what to put in it:

TOOLS = [
    {
        "type": "function",
        "function": {
            "name": "list_tables",
            "description": "List every table in the shop database.",
            "parameters": {"type": "object", "properties": {}},
        },
    },
    {
        "type": "function",
        "function": {
            "name": "describe_table",
            "description": "Return the column names and types for one table.",
            "parameters": {
                "type": "object",
                "properties": {
                    "table": {"type": "string", "description": "Exact table name."}
                },
                "required": ["table"],
            },
        },
    },
    {
        "type": "function",
        "function": {
            "name": "run_query",
            "description": "Run a read-only SQL SELECT against the shop database.",
            "parameters": {
                "type": "object",
                "properties": {
                    "sql": {"type": "string", "description": "A single SELECT statement."}
                },
                "required": ["sql"],
            },
        },
    },
]

TOOL_IMPLS = {
    "list_tables": lambda: list_tables(),
    "describe_table": lambda table: describe_table(table),
    "run_query": lambda sql: run_query(sql),
}

3. The loop

Function calling is a conversation, not a request. The model answers with tool calls, you run them, you append the results, and you ask again. It ends when the model replies with content instead of calls.

SYSTEM = (
    "You answer questions about a shop database. "
    "Inspect the schema with the tools before writing a query. "
    "Answer with the figures you retrieved, not from memory."
)


def ask(question: str, model: str, max_rounds: int = 8) -> str:
    messages = [
        {"role": "system", "content": SYSTEM},
        {"role": "user", "content": question},
    ]

    for _ in range(max_rounds):
        response = requests.post(
            f"{BASE_URL}/chat/completions",
            headers=HEADERS,
            json={
                "model": model,
                "messages": messages,
                "tools": TOOLS,
                "tool_choice": "auto",
                "temperature": 0,
                "venice_parameters": {"include_venice_system_prompt": False},
            },
            timeout=180,
        )
        response.raise_for_status()
        message = response.json()["choices"][0]["message"]

        calls = message.get("tool_calls") or []
        if not calls:
            return message["content"]

        messages.append(message)
        for call in calls:
            name = call["function"]["name"]
            arguments = json.loads(call["function"]["arguments"] or "{}")
            print(f"  {name}({arguments})", file=sys.stderr)
            messages.append(
                {
                    "role": "tool",
                    "tool_call_id": call["id"],
                    "content": TOOL_IMPLS[name](**arguments),
                }
            )

    raise RuntimeError(f"No answer after {max_rounds} rounds.")

Three details in that loop matter more than they look. The unmodified assistant message goes back into messages before the results do. It carries the tool_calls the results are answering, and on a reasoning model it also carries a reasoning_content field. Rebuilding the message by hand and dropping fields you did not expect is the most common way to break the second round. Each result is matched to its call by tool_call_id. Nothing else identifies it. max_rounds is a real limit, not a formality. A model that keeps querying without concluding will otherwise loop until you run out of patience or credit.

Tool calls also carry an index field, and it is tempting to use it to line results up with calls. Do not. When the model requests three tools at once, all three can arrive with the same index, because it numbers the assistant turn rather than the call within it. Only id is unique.

4. What it actually does

Wire up a main block and run it:

if __name__ == "__main__":
    build_db()
    question = " ".join(sys.argv[1:]) or "What are the three biggest orders?"
    print(ask(question, default_tool_model()))

python agent.py "Which product brought in the most revenue overall, and which customer spent the most on it?"

The tool calls print to stderr as they happen, so you can watch it work:

  list_tables({})
  describe_table({'table': 'customers'})
  describe_table({'table': 'orders'})
  describe_table({'table': 'products'})
  run_query({'sql': 'SELECT p.id, p.name, SUM(o.quantity * p.unit_price) AS total_revenue FROM orders o JOIN products p ON o.product_id = p.id GROUP BY p.id, p.name ORDER BY total_revenue DESC LIMIT 1;'})
  run_query({'sql': 'SELECT c.id, c.name, SUM(o.quantity * p.unit_price) AS amount_spent FROM orders o JOIN products p ON o.product_id = p.id JOIN customers c ON o.customer_id = c.id WHERE o.product_id = 5 GROUP BY c.id, c.name ORDER BY amount_spent DESC LIMIT 1;'})

- **Top product by revenue:** **Monitor Arm** (product ID 5) brought in the most
  revenue overall, totaling **$1,092.00**.
- **Top customer for that product:** **Tomas Vidal** (customer ID 2) spent the most
  on the Monitor Arm, contributing **$624.00**, more than half of the product's
  total revenue.

That took five rounds. The shape of them is worth reading closely, because it is the whole argument for the loop:

Round	What the model did
1	Called `list_tables`, having been given no schema
2	Called `describe_table` three times in one response
3	Wrote the revenue query, now knowing the column names
4	Used product 5 from the previous result to write a second query
5	Answered, with no tool calls

Round 4 is the part a single function call cannot do. The model could not write that query until it had seen the answer to the one before it. Your run will not match this one call for call. The model sometimes describes all three tables at once and sometimes one at a time, and it occasionally skips list_tables and guesses a name. The figures are stable because they come from the database; the route to them is not.

Round 2 returned three tool calls in one response, and the loop above runs them one after another. They are independent, so a ThreadPoolExecutor here is worth having as soon as your tools do real I/O. Keep the tool messages in the same order as the calls that produced them.

Each round resends the whole conversation, so the prompt grows as the agent works. Venice caches the stable prefix automatically, and the usage block shows it paying off:

{"prompt_tokens": 1020, "completion_tokens": 103, "prompt_tokens_details": {"cached_tokens": 960}}

By the last round, 960 of 1020 prompt tokens were served from cache. Prompt Caching covers how to keep that prefix stable.

5. Let errors reach the model

The instinct is to raise on a bad query. Resist it. An error is information, and the model can act on it. Ask for a table that does not exist:

python agent.py "How many rows are in the 'purchases' table?"

  run_query({'sql': 'SELECT COUNT(*) AS row_count FROM purchases'})
  list_tables({})

There is no `purchases` table in this database. The available tables are
customers, orders, and products. It's possible that the orders table is what
you're looking for. Would you like me to check the row count there instead?

The first query failed. Because run_query returned {"error": "OperationalError: no such table: purchases"} as an ordinary tool result rather than raising, the model read it, called list_tables to find out what did exist, and corrected itself. Had the exception propagated, the script would have died on a typo. This is why every tool returns JSON on the failure path too. The rule is simple: if a human debugging your tool would want to see the message, so does the model.

6. What it will not do, and what it cannot do

Ask the agent to destroy something:

python agent.py "Delete every order placed by customers in Spain."

Run that twice and you may get two different behaviors. Once, it declined before touching a tool:

I'm unable to help with that. The tools I have access to are read-only, so I can
only run SELECT queries. I cannot perform DELETE, UPDATE, or INSERT operations.

Another time it went looking first, ran a SELECT for Spanish customers, found none because the column stores ES rather than Spain, and reported that instead:

It turns out there are no orders placed by customers in Spain, so there would be
nothing to delete. If you need to perform deletions, you'll need a tool with
write access.

Both are reasonable. Neither is a security control. The model read the word “read-only” in a tool description and chose to respect it, and a different model, a longer conversation, or a more insistent user can produce a different choice. The guard inside run_query is the part that does not depend on a choice:

print(run_query("DELETE FROM orders WHERE customer_id = 2"))
print(run_query("SELECT 1; DROP TABLE orders"))
print(run_query("SELECT COUNT(*) AS n FROM orders"))

{"error": "only SELECT statements are allowed"}
{"error": "Warning: You can only execute one statement at a time."}
[{"n": 10}]

Write the description so the model rarely tries. Write the guard so it does not matter when it does.

That second line is why run_query catches sqlite3.Warning alongside sqlite3.Error. Python’s driver refuses stacked statements, but it raises Warning for them, and Warning is not a subclass of Error. Catching only sqlite3.Error lets a stacked statement escape the handler and kill the loop instead of returning a message the model can read.

A prefix check stops writes, but it says nothing about reads. Any SELECT the model writes can reach every table in the file, including ones you never meant to expose. Two changes are worth making before this touches real data: open the database read-only with sqlite3.connect("file:shop.db?mode=ro", uri=True), which fails writes with attempt to write a readonly database no matter what the string check misses, and point the agent at a database or a set of views containing only the columns it is allowed to see.

Controlling when tools get used

tool_choice decides how much say the model has:

Value	Behavior
`"auto"`	The model decides. The right default
`"required"`	The model must call something before it can answer
`"none"`	Tools are visible but unavailable, useful for a final summarizing turn
`{"type": "function", "function": {"name": "run_query"}}`	Forces one specific tool

"required" is blunter than it looks. Asking this agent What is 2 + 2? with tool_choice set to "required" makes it call list_tables, look at a database it has no use for, and then answer 4 on the next round. With "auto" it answers 4 immediately and calls nothing. Reach for "required" when a tool genuinely must run, such as logging a request, and leave it alone otherwise.

Tuning the agent

Goal	What to change
Fewer rounds	Put the schema in the system prompt so the model can skip discovery
Lower cost	Drop `fetchmany(50)`, since wide result sets dominate the prompt as rounds accumulate
More reliable arguments	Add `"strict": true` to the function definition to constrain arguments to the schema
Faster wide steps	Run parallel tool calls concurrently, or set `parallel_tool_calls` to `false` to stop them
Less wandering	Lower `max_rounds` and say in the system prompt how many queries are reasonable

Next steps

The loop you now have is the same one behind most agents. Only the tools change.

Swap the SQL tools for HTTP calls and it becomes an API agent.
Add Web Search and Scraping as a tool and it can check the live web mid-answer.
Ask for a typed result instead of prose with Structured Responses.
See a larger version of this pattern in the Private Research Agent.

Function Calling

Reference for the tools array and tool_choice.

Structured Responses

Constrain the final answer to a JSON schema.

Prompt Caching

Keep the growing conversation cheap.

Private Research Agent

The same loop with web tools and a planner.

Docs

Getting Started

Text & Chat

Image

Video

Audio

Search & RAG

Agents & Integrations

Coding Tools

Agent Tooling

SDKs & Frameworks

Building a Tool-Using Agent with Function Calling

Setup

1. A database worth asking about

2. Three tools the model can reach for

3. The loop

4. What it actually does

5. Let errors reach the model

6. What it will not do, and what it cannot do

Controlling when tools get used

Tuning the agent

Next steps

Function Calling

Structured Responses

Prompt Caching

Private Research Agent

​Setup

​1. A database worth asking about

​2. Three tools the model can reach for

​3. The loop

​4. What it actually does

​5. Let errors reach the model

​6. What it will not do, and what it cannot do

​Controlling when tools get used

​Tuning the agent

​Next steps

Function Calling

Structured Responses

Prompt Caching

Private Research Agent

Setup

1. A database worth asking about

2. Three tools the model can reach for

3. The loop

4. What it actually does

5. Let errors reach the model

6. What it will not do, and what it cannot do

Controlling when tools get used

Tuning the agent

Next steps