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

Purposes an agent can hold. Each purpose maps a name to the Postgres role that an agent's tool calls run as. Members of aidb_users can read this view. Change it with the purpose management functions.

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)
    purpose              => NULL,                    -- optional; name of a purpose from aidb.purpose_registry. Default: NULL (tool calls 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);

Purpose management functions

Only members of the aidb_governance role can call these functions.

aidb.create_purpose

Creates a purpose. If a purpose with this name was deleted earlier, it's reactivated with the new role and description.

Parameters

Returns

VOID. Raises an error if an active purpose with this name already exists.

Example

SELECT aidb.create_purpose('sales_reporting', 'reporting_role', 'Read-only access to the sales schema');

aidb.update_purpose

Changes a purpose's role or description. The change applies to every agent holding the purpose from its next invocation.

Parameters

Returns

VOID. Raises an error if no active purpose has this name.

Example

SELECT aidb.update_purpose('sales_reporting', role => 'sales_readonly');

aidb.delete_purpose

Deletes a purpose. The row stays in aidb.purpose_registry with deleted_at set. An agent holding a deleted purpose is refused when invoked.

Parameters

Returns

VOID. Raises an error if the purpose doesn't exist or is already deleted.

Example

SELECT aidb.delete_purpose('sales_reporting');

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.