> ## Documentation Index > Fetch the complete documentation index at: https://docs.duckie.ai/llms.txt > Use this file to discover all available pages before exploring further. # Agent Tables > Use scoped structured tables as working memory for autonomous agents 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: ```text theme={null} 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. ## Related Docs Attach tables to autonomous agents. Decide what should be context, knowledge, memory, or a structured table. Design safe agent actions. Inspect what agents read, wrote, and called during a run.