Design your Libraries by reader group and agent reach
Library grouping in Duale AI follows reader groups, because a grant covers a whole Library and no per-document grants exist.
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 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 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 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
- Tenant knowledge base
- Conventional path
tenant/{tenant_id}/{name}- What it holds
- Reference material several teams read: a handbook, a policy set
- Who gets its Library-specific grant
- Each agent that needs it
- Layout
- Agent knowledge base
- Conventional path
agent/{agent_id}/{name}- What it holds
- The working material of one agent identity: playbooks and templates
- Who gets its Library-specific grant
- One agent identity
- Layout
- Task attachment Library
- Conventional path
agent/{agent_id}/task/{task_id}- What it holds
- The files submitted with one task
- Who gets its Library-specific grant
- 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 covers that flow, and Manage a Library covers the first two.
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 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 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
- One corpus per department
- The layout that serves it
- One tenant knowledge base per department, granted to that department’s agents
- Why
- The readers change at the department line, so the Library changes there too.
- What you need
- A corpus several agents share
- The layout that serves it
- One tenant knowledge base, granted to each agent that quotes it
- Why
- One upload serves every reader, and its grant list shows the agent grants you set.
- What you need
- A corpus one agent identity works on alone
- The layout that serves it
- One agent knowledge base at the agent path
- Why
- Only that agent identity receives a Library-specific grant; tenant-wide roles and policies can still allow others.
- What you need
- A corpus per end customer
- The layout that serves it
- One Library and one agent identity per customer
- Why
- Separate grants keep the customer agents apart unless a tenant-wide policy 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 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 covers the upload, Manage a Library covers the delete call, and Limits 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.