Agents reference

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

Catalog views

aidb.agents

Agent configuration. There’s no dedicated “list agents” function — query this table directly.

Column	Type	Description
id	uuid	Internal identifier.
name	text	Unique agent name.
instructions	text	The agent's instructions.
model	text	The model backing the agent.
role	text	Postgres role the agent's tool calls execute as, if configured.
delegates	text[]	Names of agents this agent may delegate to.
tools	text[]	Names of tools this agent may call.
output_type	jsonb	Structured output schema, built with aidb.output_type().
input_token_budget	integer	Input token budget per call.
output_token_budget	integer	Output token budget per call.
max_iterations	integer	Maximum reasoning iterations per call.
timeout_seconds	integer	Maximum wall-clock time per call.
budget_strategy	aidb.budget_strategy	Behavior when a budget is exceeded. See Types below.
preset	text	Stored, but not currently resolved to any behavior.
created_at	timestamptz	Creation time.
updated_at	timestamptz	Last update time.

aidb.agent_tasks

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

Column	Type	Description
task_id	uuid	Internal task identifier.
agent_id	uuid	The agent that ran this task (aidb.agents.id).
conversation_id	uuid	The conversation this task belongs to.
request_message_id	uuid	The triggering message's id in aidb.conversation_log.
response_message_id	uuid	The resulting answer's id in aidb.conversation_log, once complete.
caller_role	text	Postgres role that invoked agent_converse.
status	aidb.task_status	Current lifecycle status. See Types below.
blocking	boolean	Always true today — every task runs synchronously.
error	text	Error message, if the task failed.
created_at	timestamptz	When the task started.
completed_at	timestamptz	When the task finished, if it has.

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.

Column	Type	Description
id	uuid	Message id.
conversation_id	uuid	The conversation this message belongs to.
agent_id	uuid	The agent involved.
task_id	uuid	The task this message was part of.
action_type	aidb.action_type	user_prompt or answer.
payload	jsonb	The message's raw payload (a user_message or llm_response struct).
created_at	timestamptz	When the message was created.
completed_at	timestamptz	When it was completed.

aidb.conversations

One row per conversation, aggregated from aidb.conversation_log .

Column	Type	Description
conversation_id	uuid	The conversation's id.
agent_id	uuid	The agent involved.
parent_conversation_id	uuid	Always NULL — conversation forking isn't implemented.
forked_from_message_id	uuid	Always NULL — conversation forking isn't implemented.
status	aidb.task_status	Status of the most recent task in this conversation.
message_count	bigint	Number of messages in the conversation.
last_message_id	uuid	Id of the most recent message.
created_at	timestamptz	When the conversation started.
updated_at	timestamptz	When the conversation was last updated.

---

Agent management functions

aidb.create_agent

Registers a new agent.

Parameters

Parameter	Type	Default	Description
name	TEXT	Required	Unique name for the agent.
instructions	TEXT	Required	Instructions that define the agent's behavior.
model	TEXT	Required	Name of the model backing the agent. See Choosing a model .
tools	TEXT[]	NULL	Names of tools (from aidb.tools) the agent may call.
delegates	TEXT[]	NULL	Names of other agents this agent may delegate to.
role	TEXT	NULL	Postgres role the agent's tool calls execute as. Caller must be a member of this role.
output_type	JSONB	NULL	Structured output schema, built with :ref:``aidb.output_type()` <#aidboutput_type>` .
input_token_budget	INTEGER	NULL (no limit)	Input token budget per agent_converse call.
output_token_budget	INTEGER	NULL (no limit)	Output token budget per call.
max_iterations	INTEGER	NULL	Maximum reasoning iterations per call. A hard ceiling of 25 always applies regardless.
timeout	INTEGER	NULL (300 applied at runtime)	Maximum wall-clock seconds per call.
budget_strategy	TEXT	'attempt_complete'	One of 'ignore', 'error', 'summarize', 'attempt_complete'. See Budgets and limits .
preset	TEXT	NULL	Stored, but not currently resolved to any behavior.

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

Parameter	Type	Default	Description
name	TEXT	Required	Name of the agent to delete.
force	BOOLEAN	NULL (false)	If true, also deletes the agent's internal task/action-queue records so deletion can proceed even if it has conversation history. The conversation transcript itself (aidb.conversation_log) is preserved either way.

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

Parameter	Type	Default	Description
agent_name	TEXT	Required	Name of the agent to converse with.
prompt	TEXT	Required	The prompt to send.
conversation_id	TEXT	NULL	Continue an existing conversation. Omit to start a new one (an id is generated automatically).
read_only	BOOLEAN	NULL	Force Read-only mode on or off. Auto-enabled on a read replica when omitted.
output_type	JSONB	NULL	Overrides the agent's configured Structured output schema for this call only.
debug	BOOLEAN	NULL	If true, also emit every action as a NOTICE. See Debug mode .

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 agents structured output schema for this call. Default: NULL (use the agents 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

Parameter	Type	Description
agent_name	TEXT	Name of the agent to converse with.

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

Parameter	Type	Description
conversation_id	TEXT	The conversation's id.

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

Parameter	Type	Description
message_id	TEXT	The message's id.

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

Parameter	Type	Default	Description
name	TEXT	Required	The field's name.
field_type	TEXT	Required	The field's type (for example, 'TEXT', 'FLOAT', 'BOOLEAN').
description	TEXT	NULL	Description shown to the model.

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

Parameter	Type	Description
fields	VARIADIC JSONB[]	One or more aidb.output_field() results.

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.