Agents reference v7

Reference for agent-related functions, views, and types. For guide-style documentation, see Agents.

Catalog views

aidb.agents

Agent configuration. There's no dedicated "list agents" function — query this table directly.

aidb.agent_tasks

One row per agent_converse call (a "task"), including its lifecycle status.

aidb.conversation_log

Every user prompt and agent answer, across every conversation — the same rows aidb.get_conversation() returns, unfiltered by conversation_id. Tool calls, model requests, and other internal activity aren't included; query aidb_internal.action_log directly for the full activity history.

aidb.conversations

One row per conversation, aggregated from aidb.conversation_log.

Agent management functions

aidb.create_agent

Registers a new agent.

Parameters

Returns

TABLE(error TEXT) — no rows on success; a single row with error set on failure (never raises for a validation/name-collision failure).

Example

SELECT aidb.create_agent(
    name                 => 'db_helper',
    instructions         => 'You are a helpful assistant that answers questions about this database.',
    model                => 'my_gpt',
    tools                => ARRAY['run_sql_query'],  -- optional; tool names from aidb.tools. Default: NULL (no tools)
    delegates            => NULL,                    -- optional; names of other agents to delegate to. Default: NULL (no delegation)
    role                 => NULL,                    -- optional; Postgres role tool calls run as. Default: NULL (run as the calling role)
    output_type          => NULL,                    -- optional; structured output schema from aidb.output_type(). Default: NULL (plain-text answer)
    input_token_budget   => NULL,                    -- optional; input token cap per agent_converse call. Default: NULL (no limit)
    output_token_budget  => NULL,                    -- optional; output token cap per agent_converse call. Default: NULL (no limit)
    max_iterations       => NULL,                    -- optional; reasoning-round cap per call. Default: NULL (a hard ceiling of 25 always applies)
    timeout              => NULL,                    -- optional; wall-clock seconds cap per call. Default: NULL (300 seconds applied at runtime)
    budget_strategy      => 'attempt_complete',      -- optional; behavior when a budget is exceeded. Default: 'attempt_complete'
    preset               => NULL                     -- optional; reserved for future use, has no effect today. Default: NULL
);

aidb.update_agent

Updates an existing agent. Every parameter except name is optional and defaults to NULL, meaning "leave unchanged" — including budget_strategy, whose default here is NULL, not 'attempt_complete'.

Parameters

Same parameters as create_agent, all optional (defaulting to NULL) except name.

Returns

TABLE(error TEXT) — no rows on success; a single row with error set on failure (agent not found, invalid field value).

Example

SELECT aidb.update_agent('db_helper', model => 'my_new_gpt', max_iterations => 15);

aidb.delete_agent

Deletes an agent by name.

Parameters

Returns

TABLE(error TEXT) — no rows on success; a single row with error set on failure, including when the agent has conversation history and force wasn't passed.

Example

SELECT aidb.delete_agent('db_helper', force => true);

Conversation functions

aidb.agent_converse

Runs an agent's reasoning loop against a prompt and returns its answer.

Parameters

Returns

TABLE(message TEXT, conversation_id TEXT, error TEXT) — one row. Never raises for an agent-logic failure; error is populated instead, and message/conversation_id are NULL. conversation_id is also NULL for any read-only run, since nothing is persisted to attach an id to.

Example

SELECT * FROM aidb.agent_converse(
    agent_name      => 'db_helper',
    prompt          => 'How many rows are in the orders table?',
    conversation_id => NULL,  -- optional; continue an existing conversation by id. Default: NULL (starts a new conversation)
    read_only       => NULL,  -- optional; force read-only mode on/off. Default: NULL (auto: on for a read replica, off otherwise)
    output_type     => NULL,  -- optional; override the agent's structured output schema for this call. Default: NULL (use the agent's own configuration)
    debug           => NULL   -- optional; also emit every action as a NOTICE. Default: NULL (false)
);

aidb.start_agent_session

Mints a fresh conversation id for a named agent, ahead of the first agent_converse call that will use it.

Parameters

Returns

TABLE(conversation_id TEXT). Unlike agent_converse, this function raises (rather than returning an error column) if agent_name is empty or unknown.

Example

SELECT * FROM aidb.start_agent_session('db_helper');

aidb.get_conversation

Retrieves a conversation's messages — every user prompt and final answer, in chronological order. Excludes tool calls and other internal activity; see aidb_internal.action_log for the full activity history.

Parameters

Returns

TABLE(message_id TEXT, task_id TEXT, action_type TEXT, role TEXT, sender_id TEXT, contents TEXT) — one row per message. role is "user" or "agent"; sender_id is the specific sender (the prompt's own user field, or the agent's id). Raises (rather than returning an error column) if conversation_id is empty.

Example

SELECT * FROM aidb.get_conversation('8f14e45f-ceea-467e-9575-a3d1a2c1a123');

aidb.get_message

Retrieves one message's plain-text contents by id.

Parameters

Returns

TABLE(message TEXT, error TEXT) — one row. error (not message) is populated when no such message exists; doesn't raise.

Example

SELECT * FROM aidb.get_message('3fa85f64-5717-4562-b3fc-2c963f66afa6');

Structured output helpers

aidb.output_field

Builds one field of an agent's structured output schema.

Parameters

Returns

JSONB — pass one or more of these to aidb.output_type().

aidb.output_type

Builds a complete structured output schema from one or more fields.

Parameters

Returns

JSONB — pass to create_agent/update_agent's output_type parameter, or agent_converse's.

Example

SELECT aidb.create_agent(
    name         => 'sentiment_tagger',
    instructions => 'Classify the sentiment of the given text.',
    model        => 'my_gpt',
    output_type  => aidb.output_type(
        aidb.output_field('sentiment', 'TEXT', 'One of: positive, negative, neutral'),
        aidb.output_field('confidence', 'FLOAT')
    )
);

Types

aidb.budget_strategy

CREATE TYPE aidb.budget_strategy AS ENUM (
    'ignore',
    'error',
    'summarize',
    'attempt_complete'
);

See Budgets and limits for what each value does.

aidb.task_status

CREATE TYPE aidb.task_status AS ENUM (
    'PENDING',
    'IN_PROGRESS',
    'RECOVERY',
    'AWAIT_APPROVAL',
    'DENIED',
    'ERROR',
    'TIMEOUT',
    'CANCELED',
    'SUCCESS',
    'EVALUATING',
    'COMPLETE'
);

Surfaced through aidb.agent_tasks.status and aidb.conversations.status. Since every task today runs synchronously to completion within one agent_converse call, a task's terminal status is normally SUCCESS or ERROR; the remaining values are reserved for asynchronous/approval workflows that aren't implemented yet.