An LLM-powered agent assistant for Datasette
See Datasette Agent, an extensible AI assistant for Datasette for more about this project, including tips on running it on your own machine.
Install this plugin in the same environment as Datasette.
datasette install datasette-agentVisit /-/agent to start a conversation with the chat assistant.
The agent uses datasette-llm to call language models. Configure a default model for it before visiting /-/agent, for example in datasette.yml:
plugins:
datasette-llm:
default_model: gpt-5.4-miniThe "Explore with AI agent" entries that appear in the database and table action menus launch a background agent that explores the selected database or table and writes a report. Reports live under /-/agent/explore/.
Visit /-/agent/background to launch background agents directly. Each one is given a goal and runs toward it without further input. The listing includes a Stop button for cancelling agents that are still running.
The agent has a built-in save_query tool that saves SQL it has written as a Datasette stored query. The query can be read-only or write SQL - Datasette analyzes it to decide which, and named :parameters become form fields on the saved query page.
Saving always requires human approval: the agent shows you the full SQL plus the proposed name, database and visibility, and nothing is stored until you click Yes. Validation and persistence run through Datasette's own /-/queries/analyze and /-/queries/store endpoints as the requesting actor, so the actor needs execute-sql and store-query on the target database (plus the relevant row permissions for write queries) - the same rules as the query creation web UI. Saved queries default to private.
This plugin registers three independent permissions:
datasette-agent— required to use the chat assistant under/-/agent.datasette-agent-explore— required to see the "Explore with AI agent" entries in the database/table action menus and to use the explorer routes under/-/agent/explore/.datasette-agent-background— required to use thespawn_background_agentandcheck_background_agenttools from chat, and to access the/-/agent/backgroundpage and/-/agent/api/background/*endpoints. The background-agent endpoints require bothdatasette-agentanddatasette-agent-background.
The three permissions are independent: an actor may hold any subset. The --root user holds all of them.
Other Datasette plugins can register additional tools for the agent using the register_agent_tools plugin hook.
Create a Datasette plugin that implements the register_agent_tools hook, returning a list of AgentTool instances:
from datasette import hookimpl
from datasette_agent.tools import AgentTool
@hookimpl
def register_agent_tools(datasette):
return [
AgentTool(
name="my_tool",
description="Description of what this tool does, used by the LLM to decide when to call it.",
input_schema={
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "The query to run",
},
"style": {
"type": "string",
"enum": ["brief", "detailed"],
"description": "Output style",
},
},
"required": ["query"],
},
fn=my_tool_handler,
# Optional: name a Datasette permission action that gates this tool.
# required_permission="myplugin-write",
),
]AgentTool accepts an optional required_permission: str | None field. When set, the agent harness calls datasette.allowed(action=required_permission, actor=actor) for the current actor before sending the tool list to the LLM. If the actor lacks the permission, the tool is filtered out of the list — the model never sees it and cannot call it. There is no runtime "permission denied" branch your fn needs to handle.
Your plugin is responsible for registering the action via Datasette's register_actions plugin hook:
from datasette import hookimpl
from datasette.permissions import Action
from datasette_agent.tools import AgentTool
@hookimpl
def register_actions():
return [
Action(
name="myplugin-write",
description="Allow my plugin's write tools",
),
]
@hookimpl
def register_agent_tools(datasette):
return [
AgentTool(
name="my_write_tool",
description="Writes things",
input_schema={"type": "object", "properties": {}},
fn=my_write_handler,
required_permission="myplugin-write",
),
]For a working example see this plugin's own spawn_background_agent and check_background_agent tools, which use required_permission="datasette-agent-background".
Each tool's fn must be an async function that accepts datasette and actor as keyword arguments, plus any parameters defined in input_schema. It must return a JSON string:
import json
async def my_tool_handler(datasette, actor, query, style=None):
# Do work here...
return json.dumps({
"result": "Tool output that the LLM will see",
})To render rich HTML inline in the chat UI, include an _html key in the returned JSON. Any top-level key whose name starts with _ is removed before the tool result is sent to the LLM, so the HTML is shown to the user but not passed back to the model:
return json.dumps({
"_html": '<div class="my-widget">Rich content here</div>',
"summary": "Widget rendered successfully",
})A tool can pause mid-execution and ask the human user a question. Declare a context parameter on your handler and call await context.ask_user(...):
import json
async def edit_files(datasette, actor, context, path):
ok = await context.ask_user(
"Is it OK to edit files in {}?".format(path)
)
if not ok:
return json.dumps({"cancelled": True})
mode = await context.ask_user(
"How should I apply this?", options=["dry-run", "apply"]
)
note = await context.ask_user("Any notes?", free_text=True)
# ... do the work ...
return json.dumps({"edited": path, "mode": mode, "note": note})Three kinds of question are supported:
await context.ask_user("Approve?")- yes/no, returns aboolawait context.ask_user("Which?", options=["a", "b"])- multiple choice, returns the selectedstrawait context.ask_user("Describe it", free_text=True)- freeform, returns astr
Pass html= to display trusted HTML above the question - use this to show the user exactly what they are approving, for example the full SQL of a query inside a <pre> tag. Escape any interpolated content yourself (e.g. with html.escape()); the string is rendered as-is in the chat UI.
When ask_user() has no answer yet it suspends the agent turn: the question is rendered as a form in the chat UI, and persisted to the internal database so it survives a server restart - the form re-renders when the conversation page is reloaded. Once the user answers, the tool function is re-executed from the top; previously answered questions return their stored answers immediately and execution proceeds past the ask_user() call. Because of this replay model you should call ask_user() before performing side effects.
The context object also exposes context.actor, context.conversation_id, context.tool_name, context.arguments and context.tool_call_id.
In contexts with no human watching - background agents and datasette agent chat on the CLI - ask_user() raises QuestionsNotSupported, which surfaces to the model as a tool error so it can proceed without input. Tools that only declare datasette and actor are unaffected by all of this.
Tool plugins can render rich HTML inline in the chat UI by returning a JSON object with an _html key. The HTML is rendered directly in the conversation. The remaining keys are returned to the LLM as the tool result, with any key whose name starts with _ removed first.
Example tool implementation:
import json
async def _render_widget(datasette, actor, database, sql):
html = (
'<script src="/-/static-plugins/my-plugin/widget.js" type="module"></script>\n'
'<my-widget>\n'
f'<script type="application/json">{json.dumps({"database": database, "sql": sql})}</script>\n'
'</my-widget>'
)
return json.dumps({
"_html": html,
"database": database,
"sql": sql,
"summary": "Widget rendered successfully",
})The _html value is inserted into the chat as raw HTML, so it can include custom elements, scripts, and styles. The other keys (database, sql, and summary in this example) are what the LLM receives as the tool result.
If your plugin runs SQL and displays the results in HTML, add a link below the rendered output using Datasette Agent's built-in SQL link styling:
<p class="agent-sql-edit-link"><a href="/data/-/query?sql=select+1">View SQL query</a></p>- datasette-agent-charts - renders charts from SQL query results using Observable Plot
- datasette-agent-openai-imagegen - generates images using OpenAI's image generation API
Start an interactive chat session with the agent from the command line:
datasette agent chat mydata.dbYou can pass multiple database files, use :memory: for an in-memory database, specify a model, or send a single prompt:
datasette agent chat mydata.db -m gpt-5.4-mini
datasette agent chat mydata.db -m gpt-5.4-mini -p "List all tables"Options:
-p,--prompt— Send a single prompt and exit (non-interactive mode)-m,--model— LLM model to use
To see all registered agent tools, grouped by plugin:
datasette agent toolsOutput:
agent:
list_databases_and_tables
List all available databases and their tables
describe_table
Get column names, types, and foreign keys for a table
sql_query
Execute a read-only SQL query against a database
Add --json for machine-readable output:
datasette agent tools --jsonTo set up this plugin locally, first checkout the code. Run the tests like this:
cd datasette-agent
uv run pytestTo run the development server with a persistent internal database and GPT-5.5 as the model:
uv run datasette --internal internal.db \
--root --secret 1 \
-s plugins.datasette-llm.default_model gpt-5.5Add extra database files to that command to enable the agent to query them.
This plugin vendors streaming-markdown by Damian Tarnawski, MIT licensed.