Published Pages
Knowledge page methods, immutable results, configuration, and errors.
These APIs are available when Knowledge has a configured page_store. See Published Pages for installation, PostgreSQL requirements, and examples.
Knowledge methods
| Method | Parameters | Result |
|---|---|---|
setup() / asetup() | None | Prepares the page store and indexes |
sync_pages() / async_sync_pages() | Keyword-only url; optional public_url=None, transform=None, index_version="1", reindex=False, validate_discovery=None | SyncReport |
search_pages() / asearch_pages() | query; keyword-only alternatives=None, limit=10, max_output_bytes=24000 | SearchResult |
read_page() / aread_page() | path; keyword-only revision=None, offset=0, max_chars=12000 | PageRead |
list_pages() / alist_pages() | Keyword-only prefix="/", cursor=None, limit=100 | PageList |
grep_pages() / agrep_pages() | query; keyword-only prefix="/", ignore_case=False, limit=20 | GrepResult |
max_output_bytes accepts 24,000–32,000 bytes, including serialized result metadata. Read offsets count Unicode code points. Listing cursors bind to the namespace revision; check restart_required. A grep result with complete=False cannot establish absence.
validate_discovery(discovered_count, published_count) is a synchronous callback under the namespace sync lock, before fetching or publication. Return None to accept the discovered index or raise ValueError to abort.
Result types
Import these immutable Pydantic models from agno.knowledge.page. Each result includes schema_version; serialize with model_dump() or model_dump_json().
| Type | Fields |
|---|---|
Page | content_id, namespace, path, url, title, revision, digest, index_fingerprint, filesystem_version, expected_chunk_count |
SearchHit | path, url, title, revision, chunk_id, content, score, rank |
SearchResult | results, partial=False, truncated=False, omitted_count=0, warnings |
PageRead | path, url, title, revision, text, offset, next_offset, total_chars, truncated |
PageList | pages, next_cursor=None, restart_required=False |
GrepMatch | path, url, revision, line_number, text |
GrepResult | matches, complete=True, stop_reason=None (limit, output_limit, or deadline when incomplete) |
SyncReport | status (unchanged, completed, or partial), discovered, updated, deleted, failed, unknown, errors |
Pass a search hit's revision into a page read. Continue a partial read with its revision and next_offset, and handle a changed page by restarting retrieval or keeping the original excerpts.
Errors and tools
PageError is the base for page-service errors. tool_error(error) converts a page error or invalid input into a JSON string with schema_version and an error code. A PageChanged error may include current_revision. Application tools choose how to surface unavailable, partial, or changed results to their callers.
PageFileSystem(knowledge=...) provides run_command(), arun_command(), and an opt-in tools() toolkit. It interprets bounded read-only commands over published pages and adds no prompt. See the guide for tool registration.
PageSearchConfig
Pass PageSearchConfig(...) as Knowledge(page_search=...). These settings apply to the search transaction; None inherits the database setting.
| Field | Default | Values |
|---|---|---|
plan_cache_mode | "force_custom_plan" | "auto", "force_custom_plan", "force_generic_plan", or None |
enable_seqscan | None | Boolean or None |
parallel_setup_cost | None | Nonnegative finite float or None |
parallel_tuple_cost | None | Nonnegative finite float or None |
max_parallel_workers_per_gather | None | Integer from 0 to 1024, or None |
min_parallel_table_scan_size | None | Integer from 0 to 2147483647, measured in PostgreSQL blocks, or None |
Parallel alternative queries use zero PostgreSQL parallel workers. Configure HNSW search breadth through PgVector's HNSW.ef_search.
PageFileSystem bounds
The constructor requires keyword-only knowledge and accepts these bounds:
| Parameter | Default |
|---|---|
max_output_chars | 30000 |
max_pattern_chars | 256 |
regex_match_timeout | 0.05 seconds |
regex_command_seconds | 2.0 seconds |
command_seconds | 10.0 seconds |
max_cached_bytes | 33554432 |
max_cached_entries | 8192 |
max_read_chars | 33554432 |
max_catalog_entries | 100000 |
tools(tool_name="query_pages", description=None) creates the opt-in toolkit. Direct command calls can raise PageError for service failures; toolkit wrappers return a tool_error() JSON response. get_corpus(lazy=False, prefix="/") returns a view of the published corpus.