Skip to content

Latest commit

 

History

History
170 lines (125 loc) · 4.08 KB

API.md

File metadata and controls

170 lines (125 loc) · 4.08 KB

SQLite Agent API Reference

Dependencies

Required:

Optional:

  • sqlite-vector – For vector search (auto-enabled in table mode)

Functions

agent_version()

Returns the extension version.

Syntax:

SELECT agent_version();

Returns: TEXT – Version string (e.g., "0.1.0")

Example:

SELECT agent_version();
-- 0.1.0

agent_run()

Runs an autonomous AI agent that uses MCP tools to accomplish a goal.

Syntax:

-- MODE 1: Text response
SELECT agent_run(goal);
SELECT agent_run(goal, max_iterations);

-- MODE 2: Table extraction
SELECT agent_run(goal, table_name);
SELECT agent_run(goal, table_name, max_iterations);
SELECT agent_run(goal, table_name, max_iterations, system_prompt);

Parameters:

Parameter Type Required Default Description
goal TEXT Yes - Task or goal for the agent
table_name TEXT No NULL Target table (NULL for text mode)
max_iterations INTEGER No 5 Maximum iterations
system_prompt TEXT No NULL Custom system prompt

Returns:

  • MODE 1 (text): TEXT – Agent's final response
  • MODE 2 (table): INTEGER – Number of rows inserted into the table

MODE 1: Text Response

Agent returns text after using tools.

SELECT agent_run('Find affordable apartments in Rome', 8);

Returns:

I found several affordable apartments in Rome:
1. Bright Studio - €85/night
2. Cozy Room - €72/night
3. Modern Apartment - €95/night

MODE 2: Table Extraction

Agent fetches data and populates a table.

CREATE TABLE listings (
  id INTEGER PRIMARY KEY,
  title TEXT,
  price REAL,
  embedding BLOB
);

SELECT agent_run('Find apartments in Rome under 100 EUR', 'listings', 8);
-- Returns: "Inserted 5 rows into listings"

Auto-Features (MODE 2):

  1. Schema Inspection – Reads table schema to understand target data structure
  2. Structured Extraction – Extracts data matching column names and types
  3. Transaction Safety – Wraps all insertions in BEGIN/COMMIT
  4. Auto-Embeddings – Generates embeddings for BLOB columns named *_embedding
  5. Auto-Vector Index – Initializes vector indices when embeddings are created

Custom System Prompt:

SELECT agent_run(
  'Find vegan restaurants',
  'restaurants',
  10,
  'You are a restaurant finder. Focus on highly-rated establishments.'
);

Error Handling

Common Errors:

-- Not connected to MCP
SELECT agent_run('Find apartments', 5);
-- Error: Not connected. Call mcp_connect() first

-- Table doesn't exist
SELECT agent_run('Find apartments', 'nonexistent', 5);
-- Error: Table does not exist or has no columns

-- LLM not loaded (table mode)
SELECT agent_run('Find apartments', 'listings', 5);
-- Error: Failed to create LLM chat context

Checking for Errors:

SELECT
  CASE
    WHEN result LIKE '%error%' OR result LIKE '%ERROR%'
    THEN 'Error occurred'
    ELSE 'Success'
  END
FROM (SELECT agent_run('Find apartments', 5) as result);

Performance

Timing:

  • Agent Iterations: 100ms-10s per iteration (LLM inference)
  • Tool Calls: 10-1000ms (network latency)
  • Embedding Generation: 10-100ms per text (model-dependent)
  • Vector Index: <100ms (initialization)

Tips:

  • Use appropriate max_iterations (default: 5)
  • Reuse MCP connections (global client persists)
  • Use the Agent in a separated thread

See Also