Skip to main content
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

PatternScope to start withHow it helps
Run scratchpadRunCollect candidates, intermediate results, or decisions that only matter during one run
Ticket checklistTicketTrack missing facts, completed steps, or follow-up state across turns on the same ticket
Agent working setAgentGive one specialist agent a private structured list it can reuse across runs
Workspace queueWorkspaceShare lightweight review items or triage rows between agents in the same workspace
Organization registryOrganizationKeep a shared structured list that agents can reference across the organization boundary
Parent and sub-agent collaborationAgent or ticketLet 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 scopeUse it when
runRows should reset between individual runs
ticketRows should follow the current support ticket or conversation
agentRows should belong to the configured agent, and the table should be explicitly attached
workspaceAgents in the current workspace should share the same row set
orgThe 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.