Agent Tables - Duckie

Agent Tables give autonomous agents a small structured workspace they can query and update while they work. Use them when an agent needs more than conversational memory, but you do not want to give it raw database access or make a customer system the scratchpad.

What Agent Tables Are

An Agent Table is a workspace-level table definition with a name, description, row scope, and column schema. You create and manage table definitions in Build -> Tables, then attach tables to autonomous agents from the agent’s Tables configuration. During a run, the agent can use table tools to:

list the tables available to the run
inspect a table’s schema and row scope
query visible rows with filters and sorting
insert rows or replace rows with the same stable row_key
update or delete selected rows

Agent Tables are not raw SQL tables exposed to the model. Duckie owns the table definition, validates rows against the schema, and applies row visibility from the table’s configured scope.

What Tables Can Do

Pattern	Scope to start with	How it helps
Run scratchpad	Run	Collect candidates, intermediate results, or decisions that only matter during one run
Ticket checklist	Ticket	Track missing facts, completed steps, or follow-up state across turns on the same ticket
Agent working set	Agent	Give one specialist agent a private structured list it can reuse across runs
Workspace queue	Workspace	Share lightweight review items or triage rows between agents in the same workspace
Organization registry	Organization	Keep a shared structured list that agents can reference across the organization boundary
Parent and sub-agent collaboration	Agent or ticket	Let child agents contribute rows that the parent agent can read later in the same scoped workspace

Good table use cases have a clear shape: rows, columns, and a small number of actions the agent should take. If the data already belongs in Zendesk, Salesforce, your database, or another system of record, use tools to read or update that system instead.

Choose A Row Scope

The row scope controls which rows are visible when an agent reads or writes the table.

Row scope	Use it when
`run`	Rows should reset between individual runs
`ticket`	Rows should follow the current support ticket or conversation
`agent`	Rows should belong to the configured agent, and the table should be explicitly attached
`workspace`	Agents in the current workspace should share the same row set
`org`	The row set should be shared at the organization level

Start with the narrowest scope that still supports the job. A per-ticket checklist should not be organization scoped. A shared escalation review list should not be run scoped.

Design The Schema

Agent Tables support columns with these types: text, number, boolean, date, datetime, and json. Keep schemas small and task-shaped:

Use names that describe the agent’s job, such as case_id, status, next_step, or needs_review.
Mark a column required only when every row should have it.
Use json for flexible metadata, not as a place to hide an entire unstructured document.
Include a stable identifier column when the agent will need to update the same real-world item later.

When the agent writes rows, prefer stable row_key values. Reusing the same row_key lets the agent replace the same row instead of creating duplicates.

Write Instructions For The Agent

Attaching a table makes it available, but instructions tell the agent how to use it. A good instruction says:

when to call list_agent_tables
which table to read or update
what each row represents
which row_key to use for repeatable updates
when to update, delete, or leave rows alone

Example:

Use the Ticket Checklist table to track support steps for this ticket.
Call list_agent_tables before writing. Use one row per checklist item.
Use row_key values like eligibility_checked, customer_confirmed, and refund_submitted.
Update a row when the step status changes instead of creating a duplicate row.

Avoid These Misuses

Do not use Agent Tables as the source of truth for customer records, billing state, inventory, or permissions.
Do not store secrets or credentials in table rows.
Do not create a broad organization-scoped table when ticket or agent scope would work.
Do not rely on table rows alone for compliance-sensitive approval. Use workflows, approvals, guardrails, and run history where review matters.

Agent Configuration

Attach tables to autonomous agents.

Context, Knowledge, and Memory

Decide what should be context, knowledge, memory, or a structured table.

Tools, Permissions, and Side Effects

Design safe agent actions.

Run History

Inspect what agents read, wrote, and called during a run.

​What Agent Tables Are

​What Tables Can Do

​Choose A Row Scope

​Design The Schema

​Write Instructions For The Agent

​Avoid These Misuses

​Related Docs