KnowledgeCopy Anchor Link

Attach one or more organization Knowledge Base collections on the Knowledge card in Action Agent Studio. When at least one collection is attached, the Agent runtime adds two model-visible tools:

• search_knowledge: search extracted text and file names in the attached collections.
• read_document: read one 4,000-character slice from a document returned by search.

The tools are rebuilt from the saved Agent configuration during runtime phases. The selection is not pinned to the configVersion observed at session creation.

Upload and extraction lifecycleCopy Anchor Link

Create a collection, upload a supported document, and wait for extraction to finish before relying on body-text search.

Supported uploads cover plain text and markup (txt, text, md, markdown, mdx, html, htm, json, jsonl, ndjson, xml, yaml, yml, toml, ini, cfg, conf, log, rst, adoc, asciidoc, tex, sql, graphql, gql), business records (eml, mbox, ics, vcf, srt, vtt, sbv), spreadsheets (csv, tsv, xls, xlsx, xlsm, xlt, xltx, xltm, xlsb, ods, ots, fods, numbers), word processing (pdf, doc, docx, docm, dot, dotx, dotm, rtf, odt, ott, odm, fodt, pages, epub), presentations (ppt, pptx, pptm, pps, ppsx, ppsm, pot, potx, potm, odp, otp, fodp, key), other OpenDocument packages (odg, otg, fodg, odc, odi, odf, otf), images (png, gif, jpg, jpeg, webp, bmp, tif, tiff, svg, heic, heif, avif, ico), and audio or video (mp3, wav, mp4, mov, webm). The uploader can also accept a supported MIME type when the extension is absent. Images, audio, video, EPUB, and Apple Numbers or Keynote files are stored and can be found by file name. Body text is recovered from text files, email, calendars, contacts, transcripts, and from Office and OpenDocument packages.

Each Knowledge document has an extraction status:

The extraction task retries up to three attempts. The Knowledge Base UI shows the current status.

No-text behaviorCopy Anchor Link

If extraction completes but cannot recover text, the document is still marked ready. ActionFlows stores the literal marker no text extracted in both extractError and extractedText.

That state can produce a search result when the query matches the marker or file name, but read_document does not contain the original document's text. Replace or supplement a no-text file with a text-extractable source. An image-only PDF is a common example.

Retrieval modesCopy Anchor Link

Retrieval is gated so a new index cannot change what an Agent answers on the first deploy. The deployment selects one of three modes, and the default is the first one:

A fourth control overrides all three: the retrieval kill switch returns every organization to legacy-fts whatever the configured mode is. In hybrid mode, cache writes additionally require that the FTS baseline comparison has been measured and passed; until then, hybrid retrieval is served from the index and nothing is written to the cache.

legacy-fts and hybrid-shadow return the same five fields a document-level search always returned. hybrid returns those five plus the chunk fields listed below.

Search behaviorCopy Anchor Link

search_knowledge accepts a non-empty query. It returns at most 8 hits under the default configuration, and an organization retrieval policy may raise that bound to as much as 50. Each hit contains:

• documentId;
• collectionId;
• fileName;
• a relevance score;
• a snippet; and
• under hybrid, chunkId, chunkOrdinal, headingPath, and indexGeneration.

score and snippet change meaning with the mode, and their scale is not comparable across modes: score is a ts_rank under the document-level search and a reciprocal rank fusion score under an index, and snippet is a MaxWords=32 headline under the document-level search and up to the chunk character ceiling of raw chunk text under an index.

Search uses PostgreSQL's simple full-text configuration. Under legacy-fts and hybrid-shadow it runs over extractedText and also performs a case-insensitive file-name match; under hybrid it runs over the indexed chunk text, with the same file-name match carried over, plus vector similarity. It returns an empty array when the query or attached collection list is empty.

Search scopeCopy Anchor Link

Every search is constrained by both:

• the Agent's organizationId; and
• the current list of attached, non-deleted collection IDs.

read_document applies the same organization and collection constraints. A document ID from another organization, an unattached collection, or a deleted record is not readable even if the caller knows its ID.

The document-level SQL does not explicitly filter on extraction status. In practice:

• a pending document normally has no extracted text yet, but a file-name match can still return it;
• a failed document can retain stale extractedText from an earlier successful extraction, and that stale content remains searchable;
• a file-name match can return a document regardless of extraction status; and
• a ready no-text document contains the marker described above.

Always check the extraction status before treating an empty or surprising result as a collection-scope problem.

Indexing lifecycleCopy Anchor Link

Indexing is a background step that follows extraction, and a collection is answered by the document-level search until it is complete:

An indexed collection is answered from the generation that was ready when the search started. A document upload, edit, or removal advances the collection revision, which is what makes a cached result for the previous content unreachable. read_document always reads the current extracted text, whatever the retrieval mode is.

Read behaviorCopy Anchor Link

read_document accepts:

Each call returns at most 4,000 characters, the file name, and totalLength. Read another offset when offset + returned text length is below totalLength.

If the document is not in the current organization and attached collection scope, the tool returns a Document not found tool error. The model can respond with that limitation; the tool does not fall back to a different collection.

Attach collectionsCopy Anchor Link

1. Open the organization Knowledge Base and create or choose a collection.
2. Upload documents and confirm they reach ready with usable extracted text.
3. In Action Agent Studio, attach one or more collections on the Knowledge card.
4. Save, then start the next message. Agent-owned configuration writes increment configVersion; a later runtime phase can reload the new attachment list during an in-flight turn.

Catalog Generate Text, Generate JSON, and Generate File Flow nodes can use Knowledge separately; those nodes are not Agent tools.

Storage boundaryCopy Anchor Link

Knowledge files are organization uploads with ArtifactType.uploaded, not generated Agent artifacts. CMS storage settings currently calculate and display organization usage but do not enforce a write-time quota on Knowledge uploads or generated Agent files. See Limits.

RelatedCopy Anchor Link

• Knowledge Base
• Limits
• Model selection
• Tools
• Artifacts
• Troubleshooting