datasette-agent 0.1a2

An LLM-powered agent assistant for Datasette

datasette-agent

An LLM-powered agent assistant for Datasette

Installation

Install this plugin in the same environment as Datasette.

datasette install datasette-agent

Usage

Visit /-/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-mini

The "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.

Permissions

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 the spawn_background_agent and check_background_agent tools from chat, and to access the /-/agent/background page and /-/agent/api/background/* endpoints. The background-agent endpoints require both datasette-agent and datasette-agent-background.

The three permissions are independent: an actor may hold any subset. The --root user holds all of them.

Registering additional tools from plugins

Other Datasette plugins can register additional tools for the agent using the register_agent_tools plugin hook.

Defining a tool

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",
        ),
    ]

Gating a tool with a permission

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".

Tool handler function

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",
})

Rendering custom HTML from tools

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.

Example plugins

• datasette-agent-charts - renders charts from SQL query results using Observable Plot
• datasette-agent-openai-imagegen - generates images using OpenAI's image generation API

CLI commands

Interactive chat

Start an interactive chat session with the agent from the command line:

datasette agent chat mydata.db

You 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

Listing available tools

To see all registered agent tools, grouped by plugin:

datasette agent tools

Output:

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 --json

Development

To set up this plugin locally, first checkout the code. Run the tests like this:

cd datasette-agent
uv run pytest

To 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.5

Add extra database files to that command to enable the agent to query them.

Credits

This plugin vendors streaming-markdown by Damian Tarnawski, MIT licensed.