--- title: "Design your Libraries by reader group and agent reach" description: "Library grouping in Duale AI follows reader groups, because a grant covers a whole Library and no per-document grants exist." lang: en status: public-preview lastUpdated: 2026-08-31 url: https://dev.duale.ai/en/docs/libraries/design --- ## AI-generated summary Design your Libraries by reader group, not document count. Fewer Libraries per agent improves answer completeness. Three layouts cover common cases; paths are labels, identifiers are stable. - A grant covers a whole Library, so two reader groups need two Libraries. - Three layouts: tenant knowledge base, agent knowledge base, and task attachment Library. - Paths are changeable display metadata; the Library identifier is the stable identity grants name. - One tenant separates end-customer agents; built-in viewer and editor roles read every Library. - Task attachment Libraries are ordinary Libraries; nothing expires them and documents are metered as storage. Summaries were generated by AI. Generative AI is experimental. --- A Library grouping can remain stable as documents and agents change. Renaming a Library does not change its grants, because each grant names the stable Library identifier rather than its path. Draw that line by who can read a document, not by how you would file it. A grant covers a whole Library, so the grouping you choose is the access control you get. Decide that line before you upload. A document belongs to the Library it entered, and no operation moves it: to change its Library you upload the file again and delete the original. ## Draw the line where the readers change Two sets of documents with different readers belong in two Libraries. A grant covers a whole Library, and there are no per-document grants. If a Library holds both a public price list and a restricted salary table, you can only grant or refuse access to both. [Access and isolation](https://dev.duale.ai/en/docs/libraries/access.md) states what each grant covers. Size a Library by its reader group, not by a document count. A Library of a dozen documents and a Library of many thousands are both normal. What makes a layout wrong is a reader who reaches a document you did not intend. Answer three questions before you create a Library: - **Who can read these documents?** The answer names the Library. - **Which agent identity asks the questions these documents answer?** The answer names the grant. - **What happens when a second reader group arrives?** If the answer is to grant them the same Library, the line is in the wrong place. ## Give each agent the fewest Libraries its work needs The number of Libraries one agent reaches changes the quality of its answers, not only their speed. Every search covers all the Libraries that agent can reach, and the effort one search is allowed belongs to the search rather than to each Library. An agent that can read many Libraries is therefore more likely to get an answer that stopped before it had read everything. [How an agent finds an answer](https://dev.duale.ai/en/docs/libraries/what-agents-can-do.md) covers how to read an answer that stopped early. Reach follows the agent identity that runs the task, not the documents the task attached. An agent that reaches ten Libraries reaches all ten on every task, including a task that concerns one of them. [Agent harness](https://dev.duale.ai/en/docs/agent-harness.md) states that boundary. Two moves keep a reach small: - **Split one wide agent into several narrow ones.** Each identity then holds the Libraries its own work needs. - **Grant a shared reference Library to the agents that quote it**, rather than to every agent in the tenant. ## Three layouts, and the paths that name them Three layouts cover the common cases, and one application can use all three. | Layout | Conventional path | What it holds | Who gets its Library-specific grant | | ----------------------- | --------------------------------- | ------------------------------------------------------------------- | ----------------------------------- | | Tenant knowledge base | `tenant/{tenant_id}/{name}` | Reference material several teams read: a handbook, a policy set | Each agent that needs it | | Agent knowledge base | `agent/{agent_id}/{name}` | The working material of one agent identity: playbooks and templates | One agent identity | | Task attachment Library | `agent/{agent_id}/task/{task_id}` | The files submitted with one task | The agent that runs the task | The SDK creates the third one for you at the path shown, so your code never names it. [Attach documents](https://dev.duale.ai/en/docs/sdk/attachments.md) covers that flow, and [Manage a Library](https://dev.duale.ai/en/docs/sdk/manage-libraries.md) covers the first two. ```mermaid flowchart LR accTitle: Library-specific grants for two agent identities accDescr { Two agent identities work inside one tenant. One tenant knowledge base holds shared reference material, and both identities receive a grant for it. Each identity also receives a grant for its own agent knowledge base. The support triage identity receives one more grant for the task attachment Library that the platform created for a single task. Access follows the agent identity rather than the task, so every Library an identity can read is open on every task that identity runs. Keep that set small. } Handbook["Tenant knowledge base"] SupportDocs["Agent knowledge base for support triage"] BillingDocs["Agent knowledge base for billing review"] TaskFiles["Task attachment Library for one task"] Support["Agent identity, support triage"] Billing["Agent identity, billing review"] Handbook --> Support Handbook --> Billing SupportDocs --> Support TaskFiles --> Support BillingDocs --> Billing ``` One tenant holds a limited number of Libraries that are not deleted. Track that total: a process that creates a Library on every task run reaches the ceiling much faster than a layout based on reader groups. [Limits](https://dev.duale.ai/en/docs/libraries/limits.md) states the number. ### A path is a label, not an identity The path is display metadata. It holds 1 to 300 characters and takes free-form segments separated by slashes. It needs no prefix. You can change it at any time, and two Libraries can carry the same path. The three paths above are conventions that keep a list readable, not rules the platform enforces. The Library identifier is the identity. The server creates it with the Library, it never changes, and a grant names it. So you can rename a Library, adopt a new naming scheme across the tenant, or fix a typo, and every grant keeps working. Show the path to people who read a list, and store the identifier everywhere your own code refers to a Library. ## Serve several end customers from one tenant One tenant separates end-customer agents, not people who hold tenant-wide roles. Give each end customer its own agent identity, and grant that identity only that customer's Libraries. You can then review the Library-specific grants for one customer's documents in one place. With no wider tenant policy for that agent, a task that runs for that customer reaches no other customer's Library. That layout holds against an agent. The built-in viewer and editor roles read every Library in the tenant, so anyone holding one of those roles reads every customer's documents. A customer who needs a boundary against a person needs a separate tenant. [Access and isolation](https://dev.duale.ai/en/docs/libraries/access.md) names those roles. Settle that question before the first customer arrives. A tenant is chosen at the start, and moving a corpus between tenants means uploading it again. ## Match a need to a layout Choose the row by who reads the documents. Document count does not decide the layout. | What you need | The layout that serves it | Why | | -------------------------------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | One corpus per department | One tenant knowledge base per department, granted to that department's agents | The readers change at the department line, so the Library changes there too. | | A corpus several agents share | One tenant knowledge base, granted to each agent that quotes it | One upload serves every reader, and its grant list shows the agent grants you set. | | A corpus one agent identity works on alone | One agent knowledge base at the agent path | Only that agent identity receives a Library-specific grant; tenant-wide roles and policies can still allow others. | | A corpus per end customer | One Library and one agent identity per customer | Separate grants keep the customer agents apart unless a tenant-wide policy allows wider access. | | Short-lived task files | The task attachment Library the SDK creates | The files travel with the task, and your code never names a Library. | | A corpus that mixes public and restricted material | Two Libraries, split at the restriction line | A grant covers a whole Library, so two reader groups need two Libraries. | ## Keep a task attachment Library predictable A task attachment Library is an ordinary Library. Nothing expires it, and its documents are metered as storage until someone deletes them. A process that attaches a file to every task therefore leaves one Library behind for every task it ran. [Attach documents](https://dev.duale.ai/en/docs/sdk/attachments.md) covers the upload, [Manage a Library](https://dev.duale.ai/en/docs/sdk/manage-libraries.md) covers the delete call, and [Limits](https://dev.duale.ai/en/docs/libraries/limits.md) states what the platform meters. Give that deletion an owner. Three habits keep the total predictable: - **Delete the Library when the work it supported is finished.** One delete call removes the Library and its documents. - **Put a file that several tasks read into a durable Library once**, rather than attaching it to each task. - **Count the Libraries at the task path on a schedule.** This check finds a cleanup step that stopped before the unused Libraries affect storage use. ## Related content - [The documents your agents can read](https://dev.duale.ai/en/docs/libraries.md) - [Manage Libraries and documents with the SDK](https://dev.duale.ai/en/docs/sdk/manage-libraries.md) - [Grant and review access to a Library](https://dev.duale.ai/en/docs/libraries/access.md) - [Know what the platform defends](https://dev.duale.ai/en/docs/security/threat-model.md) - [Secure your use of the platform](https://dev.duale.ai/en/docs/security.md) - [Application-facing SDK API reference](https://dev.duale.ai/en/docs/sdk/reference.md) --- ## Sitemap See the full [Markdown sitemap](https://dev.duale.ai/sitemap.md) for all pages.