How an agent finds an answer in your documents

Two questions arrive at the same documents. What does the contract say about termination? Where does invoice 4471 appear? The agent answers the first by meaning and the second by exact string, because it holds a separate tool for each. The shape of the corpus you upload therefore decides which questions come back with a usable answer.

Your code calls none of these tools. The model calls them during a task, so what you control is the corpus you build and the Libraries each agent can reach. The rest of this page is corpus design.

Choose the tool that answers the question

Each tool matches something different, and the model chooses one for each call.

The last column holds the names you see in a task trace. They are not a versioned interface. Read them as current trace output, not as an API.

The Find tool is semantic search: it orders passages by what they mean, and it is not a literal keyword search. An invoice number, an error code, or a part reference therefore goes to the Match tool, which matches the string literally.

Meaning can also carry across languages. A query written in French can retrieve a passage written in English, and the reverse, so one set of documents can serve readers in several working languages without a translation pass.

Retrieval across languages is not equally strong in every language, and Duale AI publishes no per-language figure. If a working language of yours is not among the widely used ones, test it on your own questions before you commit a set of documents to it.

What a question by meaning reads, and when to ask for an exact string insteadA question asked by meaning reads both the words in your documents and the pictures inside them, and returns one list of passages in order, best first. It does not perform a literal match. A question that names an exact string, such as an invoice number, goes to the literal match instead, which returns the places that string appears rather than an ordered list.

Two behaviors change how the model works through an answer:

• The Match tool reports the first match inside each passage, not every occurrence. It answers where to look, and the Read tool then reads around one of those places.
• The List tool lists documents in any state, including the ones the platform is still processing, and reports that state. A document that the Find tool does not return can still be on its way to ready. Manage libraries defines each status and shows how to wait.

Each tool returns at most a fixed number of results for one call, and the Read tool reads one document for one call. Limits states each ceiling. Your own code passes none of them.

Read an answer that stopped early

A partial answer is a normal answer. A search and a literal match both report whether they finished, and the platform marks a result incomplete when it stopped before reading everything the agent can reach.

So an empty result that reports it stopped means the search ran out of effort, not that your documents hold no match. Read that answer as one pass over part of everything the agent can reach.

What an agent can read follows the identity that runs the task, not the documents that the task attached. Agent harness states which agent holds which tool.

One document search covers every Library the agent can reach, and the effort it is allowed belongs to the call rather than to each Library. A search across more Libraries is therefore more likely to stop before it has read everything.

Two actions bring back a complete answer:

• Narrow the question. A tighter question reaches its matches sooner.
• Reduce the Libraries the agent can reach. Design your Libraries covers how to split a corpus so that each agent reaches what its work needs and no more.

What the platform reads, and what comes back

The platform makes extracted text and pictures it can decode searchable. A document can reach ready with either kind of content.

The platform uses optical character recognition (OCR) to read characters in pictures. The words OCR recovers join the searchable text, while the picture remains searchable as a picture. A picture with no readable OCR can therefore still answer a visual question.

What the platform reads from a document, and what a question gets backYou upload a document. The platform extracts its text, runs optical character recognition on its pictures, and keeps the pictures it can decode. It follows a document nested inside the source in the same way. Extracted text, words recovered from pictures, and decoded pictures become searchable. A question searches them together. A text result names its page. A matching picture reaches the model only when the tenant's model pool has an image-capable model that can carry it.

Four consequences follow:

• Nesting is followed. A file inside an archive, or a PDF inside a word-processor document, is opened and read the same way as the document that carried it.
• A hit brings its place with it. An answer names the page the text sat on, so an agent can read around it and quote it.
• OCR and picture search are separate. OCR can add words to the searchable text. A picture remains searchable when OCR recovers no readable words.
• The model must accept a matching picture. The tenant’s model pool needs an image-capable model whose limits admit the image before the picture itself reaches the answer. Attach documents covers setup, limits, and the result when no configured model can carry it.

Extraction is best effort rather than a fidelity guarantee, especially when meaning is visual. When a document has to be exactly right, extract it yourself and upload the text.

How a page becomes passages

A passage never crosses a page boundary. Keeping one logical record on one page therefore prevents a page break from dividing it, but a long page can still produce several passages.

For extracted text, the platform preserves page boundaries and splits each page into passages. Consecutive passages inside one page overlap, so a sentence that lands on a boundary stays whole in one of them.

A page with no readable text produces no text passage. If the page contains a picture the platform can decode, that picture remains searchable and the document can still reach ready. An extraction failure means the platform produced neither searchable text nor a searchable picture, or extraction stopped with the cause that the error details name. Read the status after each upload.

One consequence to design for: a table that breaks across a page becomes two passages that do not share context. Keep one logical record on one page where the source lets you. Best practices covers the other source habits that make a document index well, and Manage libraries covers the upload and the states a document moves through.

Use the order of the results

Order carries the signal. Any relevance number beside it does not.

Results come back best first, and that order is the whole of what the platform is telling you. A relevance number attached to a result is not a similarity and not a probability, and two different questions do not produce comparable numbers.

So a threshold carried over from another retrieval system does not transfer reliably. Take the first few results in the order they arrive and let the model read them.

Troubleshoot a missing answer

Start from the symptom the agent or Dashboard shows. After each change, ask the same question through the same agent. Recovery means the expected string or passage appears and the answer no longer reports that it stopped early.

Plan the corpus for the questions you expect

Decide the shape of the corpus before you upload it. Each need below has a pattern that fits these four tools.

How many Libraries to create, and which agent reaches each, is the decision that carries the rest. Design your Libraries covers it.