Library design: layout, paths, and Agent Identity reach
Plan Library count, paths, and Agent Identity reach before uploading, covering three layouts and path-based access rules.
This page covers Library boundary decisions, Agent Identity access sizing, the three common layouts, path-based access rules, multi-customer tenant design, and Task attachment Library management.
- Reader-group boundaries and Library split decisions.
- Agent Identity access sizing and Library reach.
- Three layouts: Tenant, Agent, and Task attachment paths.
- Path-based access rules and Library identifier behavior.
- Multi-customer tenant design and Task attachment Library cleanup.
Summaries were generated by AI.
Use this page before your first upload to decide how many Libraries to create, at which paths, and which Agent Identity reaches each. Moving a document or a corpus later means uploading it again.
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 states what each grant covers.
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.
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 is authorized for these documents? The answer names the Grant subject.
- 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 Identity the fewest Libraries its work needs
The number of Libraries allowed to one Agent Identity can change the completeness of retrieval, not only its speed.
Every Library search covers every Library that the Task’s Agent Identity can reach. The effort allowed belongs to the search rather than to each Library. Wider access is therefore more likely to produce an answer that stopped before it read everything. Library retrieval covers how to read an answer that stopped early.
Access follows the Task’s Agent Identity, not the documents attached to that Task. A Task can therefore search every Library allowed to that identity, including during a Task that concerns only one of them. Access and isolation states that boundary.
Two moves keep a reach small:
- Split one wide identity boundary into several narrow Agent Identities. Each then holds only the Grants its work needs.
- Grant a shared reference Library only to the Agent Identities that need it, rather than to every identity in the Tenant.
Three layouts, and the paths that name them
Three layouts cover the common cases, and one application can use all three.
Conventional path
| Tenant knowledge base | Agent knowledge base | Task attachment Library |
|---|---|---|
tenant/<tenant_id>/<name> | agent/<agent_id>/<name> | agent/<agent_id>/task/<task_id> |
What it holds
| Tenant knowledge base | Agent knowledge base | Task attachment Library |
|---|---|---|
| Reference material several teams read: a handbook, a policy set | Material for one Agent Identity: playbooks and templates | The files submitted with one Task |
Which Agent Identity reaches it
| Tenant knowledge base | Agent knowledge base | Task attachment Library |
|---|---|---|
| Each one you grant | That Agent Identity, by default | The Task’s Agent Identity, by default |
The SDK creates the third one for you at the path shown, so your code never names it. Attach documents covers that flow, and Manage libraries covers the first two.
The path decides access; the identifier names the Library
The path holds 1 to 300 characters and takes free-form segments separated by slashes. It needs no prefix, cannot
contain {, } or *, and two Libraries can carry the same path. The three paths above are conventions that keep a
list readable; Duale AI requires none of them. The agent/<agent_id>/ prefix does matter for access, because each
Agent Identity reaches its own folder by default.
Tenant access policies and Library Grants name the path, not the Library identifier. A rename therefore moves a Library to the new path’s access and leaves its Grants on the old path. Access and isolation states the full rule. Settle a naming scheme before you grant access, and treat a rename as an access change.
The Library identifier names one Library. Duale AI creates it with the Library, and it never changes. 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 can separate end-customer Agent Identities through authorization, but not people who hold supplied human tiers.
Give each end customer its own Agent Identity. Keep that customer’s Libraries under the identity’s own
agent/<agent_id>/ path, which its default access covers, or grant it each customer Library that lives elsewhere. With
no wider Tenant policy for that identity, its Tasks can search only those Libraries.
One Agent Identity per end customer also keeps each customer’s earlier requests and final answers apart, because Recall reaches only earlier Tasks of the same Agent Identity. Context continuity explains that reach.
That layout holds against an Agent Identity. The supplied Viewer and Editor tiers read every Library in the Tenant, so anyone holding one of those tiers reads every customer’s documents. A customer who needs a boundary against a person needs a separate tenant. Access and isolation names those tiers.
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
- One corpus per department
- The layout that serves it
- One Tenant knowledge base per department, granted to that department’s Agent Identities
- Why
- The readers change at the department line, so the Library changes there too.
- What you need
- A corpus several identities share
- The layout that serves it
- One Tenant knowledge base, granted to each Agent Identity that needs it
- Why
- One upload serves every reader, and its Grant list shows the explicit identity Grants.
- What you need
- A corpus one Agent Identity works on alone
- The layout that serves it
- One Agent knowledge base at the
agent_idpath - Why
- That identity’s default access covers the path; Tenant policies can still allow others.
- What you need
- A corpus per end customer
- The layout that serves it
- One Agent Identity per customer, with that customer’s Libraries under its
agent_idpath - Why
- Each identity reaches only its own path unless a policy or Grant allows wider access.
- What you need
- Short-lived Task files
- The layout that serves it
- The Task attachment Library the SDK creates
- Why
- The files travel with the Task, and your code never names a Library.
- What you need
- A corpus that mixes public and restricted material
- The layout that serves it
- Two Libraries, split at the restriction line
- Why
- 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 remain part of recorded stored volume 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 covers the upload, and Limits states the
recorded-volume and optional metering boundary. A person deletes a whole Library in the Dashboard: it needs
library:delete and aal3 authentication, which an API token does not have.
Manage libraries covers that prerequisite.
Give that deletion an owner. Three habits keep the total predictable:
- Delete the Library when the work it supported is finished. Deleting it in the Dashboard 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.