Agno Release Notes

Changelog

New Features

• Live progress & cancellation for page sync: Knowledge.stream_sync_pages() / astream_sync_pages() yield typed PageSyncProgress snapshots plus one terminal SyncReport, and sync_pages / async_sync_pages accept an on_progress observer. A workflow function step can now yield StepProgress(content=..., data=...) before its StepOutput, emitted as a native StepProgressEvent under the existing workflow run/step ID — AgentOS streams it over the existing workflow REST/SSE route, and AgentOSClient.run_workflow_stream() parses it. Cancelling a sync now actually reaches the work instead of draining to the end. (#10098)
• Page sync reports name failed pages: SyncReport.failed_paths lists the site paths of pages that failed to publish/delete (capped at the first 20, like errors; failed keeps the full count; defaults to () so existing callers/stored reports are unaffected). Logs now name the page and its cause chain, e.g. Page sync failed for /guides/setup.md (SyncFailed: sync_failed <- ConnectError: [Errno 104] Connection reset by peer), plus a new Page delete failed for … warning on the prune path. (#10729)

Bug Fixes …

New Features

• User Management / Authorization (RBAC): a new agno.os.authz package adds role-based access control to AgentOS — a role store, scope policy, audit log, user directory and an admin router, with pluggable authorization engines (a native engine plus a fine-grained fga engine). Scopes and auth middleware were extended to enforce it.
• AgentOS Filesystem: a new agno.fs filesystem (DbFileSystem) with dedicated /filesystem routes (list/read/manage files) backed by an agno_fs table.
• MCP config / auth updates: refreshed MCP server config and built-in MCP auth handling.
• AIMLAPITools: new toolkit for image, video, speech and transcription via the AI/ML API.

⚠️ Breaking Changes

• Filesystem table re-key (agno_fs): v3.1 keys the filesystem table by (namespace, user_id, path), where user_id is the user partition ("" for the shared/no-user partition). A table created by an earlier release is refused with SchemaOutdatedError until upgraded — the re-key never runs automatically. Upgrade once, with the application stopped, using the script for your database (#10530):

This affects you only if you use DbFileSystem. The table is managed by DbFileSystem (its own schema, buildable from a bare db_url), so it is deliberately not part of MigrationManager.

python libs/agno/migrations/migrate_filesystem_postgres.py   # PostgreSQL
python libs/agno/migrations/migrate_filesystem_sqlite.py     # SQLite …

Changelog

New Features:

• Knowledge Retrieval Pipeline: Knowledge.search() now runs a knowledge level retrieval pipeline that can widen the candidate pool before a reranker reorders it, so rerankers no longer need to be implemented per vector db.
• MMR Reranker: Added MMRReranker (Maximal Marginal Relevance) as a retrieval strategy that balances relevance against diversity so near-duplicate chunks do not crowd out the result set.
• Page Source Relocation: Added Knowledge.inspect_page_source / ainspect_page_source and guarded migrate_page_source / amigrate_page_source to move an indexed documentation source to a new hostname. Migration is a dry run by default.
• Recency Reranker: Added RecencyReranker, which blends the search score with an exponential decay on a timestamp so newer revisions outrank superseded ones. Built on the knowledge level pipeline, focused on pgvector.
• Typed Page Tool Results: Added PageCommandResult and PageFileSystem.run_command_result / arun_command_result with explicit error, completeness and truncation metadata. Knowledge.get_tools(page_results=True) returns ranked SearchResult objects, including as MCP structured output.
• Y-API: Added YAPI as an OpenAI-compatible model provider. …

Changelog

New Features:

• Azure OpenAI Responses: Added AzureOpenAIResponses to use the Responses API with Azure OpenAI deployments. See cookbook.
• Elasticsearch: Added Elasticsearch vector database with vector, keyword and hybrid search. See cookbook.
• DocumentationMarkdown: Added a transform for Knowledge.sync_pages that converts Mintlify and Fumadocs components into plain Markdown. See cookbook.

Improvements:

• MCPConfig: Added root_host, path and path_aliases to serve MCP on a dedicated hostname or a custom endpoint path.
• MCP Server Card: /mcp/server-card now returns pretty-printed JSON.

Bug Fixes:

• MCP Tools: Preserve AudioContent from MCP tool results as audio artifacts.
• Slack: Deduplicate event retries by event_id instead of dropping them.
• Remote Agents: RemoteAgent.role and RemoteTeam.role are now properties that return the role instead of a bound method; use .role, not .role().
• Readers: TextReader, MarkdownReader and FieldLabeledCSVReader now accept text streams.
• PPTXReader: Read text inside grouped shapes. …

What's Changed

• fix: clean startup logs and initialize durable queue storage by @ashpreetbedi in https://github.com/agno-agi/agno/pull/10071
• fix: preserve Control Plane access with public surfaces by @ashpreetbedi in https://github.com/agno-agi/agno/pull/10074
• Release: v3.0.9 by @ashpreetbedi in https://github.com/agno-agi/agno/pull/10076

Full Changelog: https://github.com/agno-agi/agno/compare/v3.0.8...v3.0.9

Changelog

New Features

• Complete page reads: Knowledge.read_full_page and aread_full_page return an entire published page from one bounded SQL read and read-only snapshot. Both support revision pinning, character limits and deadlines. Oversized pages return None; missing or changed pages retain typed errors. Calls share the existing eight-slot page-read worker pool. (feat: add bounded full-page reads and shared fence tracking #10063)
• Shared PostgreSQL engine factories: create_postgres_engine and create_async_postgres_engine expose Agno's connection-pool and JSON serialization defaults with configurable SQLAlchemy options. Plain postgres:// and postgresql:// URLs select Psycopg 3 in these new factories; explicit drivers and TLS settings are preserved. Existing database constructor driver selection is unchanged. (feat: add PostgreSQL engine factories with shared defaults #10062)

Improvements

• Shared Markdown fence tracking: agno.utils.markdown.advance_code_fence exposes the page chunker's fence rules for application transforms that need to preserve code examples. A full-page cookbook demonstrates reads and prose normalization. (feat: add bounded full-page reads and shared fence tracking #10063) …

Changelog

New Features

• Page storage in agno.knowledge.page. Knowledge atomically publishes catalog metadata, filesystem text and vectors, preserves previous revisions when a refresh fails, and exposes bounded sync and async setup, source synchronization, search, read, list and grep APIs. Installed through the new agno[pages] extra. (#9963)
  • Knowledge(page_search=PageSearchConfig(...)) provides typed, transaction-local planner controls. Unset scan preferences, costs, worker counts and thresholds inherit the PostgreSQL settings.
• PublicSurface for public serving: serves selected Agents, native stateless MCP and authenticated durable-sync Workflows, with shared quotas, request and output bounds, CORS and internal-service authentication. (#9963)
  • Explicitly selected Teams are now servable too, with REST and gzip support. They share the Agent admission, execution and output limits; the roster is reduced and member routes stay private unless independently selected. (#9996)
• PageFileSystem(knowledge=...): a bounded read-only page filesystem toolkit with sync and async execution, exposed explicitly through files.tools(). Commands read pages lazily against pinned revisions, list scoped metadata and run bounded literal grep; they cannot execute a shell or write files. (#9997) …

Changelog

New Features

• Stateless MCP serving. MCPConfig(stateless=True) serves /mcp without session tracking, so any replica can answer any request and a multi-instance deployment needs no session affinity. Costs server-initiated notifications and SSE resumability, so it stays off by default. See cookbook.
• MCPTools(protocol_mode=...) selects which MCP protocol era to negotiate. Defaults to "legacy", preserving today's session-based behaviour; "auto" negotiates the newest era both sides support (sessionless from 2026-07-28). Existing servers are unaffected — a modern server still accepts the legacy handshake. Internally, MCP clients are now built on fastmcp.Client. See cookbook.
• AgentOS MCP Server Card at GET /mcp/server-card, listing the served tools and carrying a configurable name, version and instructions.
• .zip and .eml file uploads in AgentOS. See cookbook.
• AuthorizationConfig.excluded_route_paths marks custom routes public without disabling auth globally.
• Bedrock: pass your own async client to the model or embedder.

Bug Fixes …

Changelog

Breaking Changes

• Embedding failures are surfaced, not masked. Ingestion now reports embedding failures instead of returning success. Content that previously showed completed may now show failed or partial — those ingests were always incomplete, they were only reported as successful. The ContentStatus enum in the API (/openapi.json) gains partial, changing from ["processing","completed","failed"] to ["processing","completed","partial","failed"]. No schema migration is required (the status column is already varchar).
• Embedders raise EmbeddingError instead of returning an empty vector on failure. Calling a vector DB's search() directly now raises where it previously returned []; Knowledge.search() is unaffected and still returns no results.
• AWS Bedrock embedding failures raise EmbeddingError, not ModelProviderError. Existing except ModelProviderError handlers around Bedrock embedding will stop catching — switch to except EmbeddingError.
• GET /knowledge/content/{id}/status returns 404 for missing/non-owned content instead of 200 with status: "failed".
• skip_if_exists=True no longer skips content recorded as failed or partial, so incomplete content is re-embedded rather than silently marked complete.

New Features …

Changelog

Behavior Changes

• KnowledgeManagementTools constructor flags renamed, ingest_path now opt-in: the 2.x-style enable_ingest / enable_remove flags are replaced by flags named after the tools they register — ingest_url, ingest_path, ingest_text, remove_content (the old names are no longer recognised and are ignored if passed). ingest_path defaults to off: it reads any path the server process can read, and under scope="shared" what it loads becomes readable by every agent on that knowledge base, so registering it is now an explicit choice. list_content and ingest_status stay unflagged — they only read. (#9861)
• agno.tools.knowledge_management import path moved: KnowledgeManagementTools (introduced in 3.0.3) now lives at agno.tools.knowledge; the old module path is gone. from agno.tools.file_generation import FileGenerationTools keeps working through a compatibility shim. (#9861)

Improvements

• agno.tools.file and agno.tools.knowledge are packages: FileTools and FileGenerationTools share agno.tools.file; KnowledgeTools (read side) and KnowledgeManagementTools (write side) share agno.tools.knowledge, following the agno.tools.mcp and agno.tools.finance layout. Names resolve on first access, so importing FileTools no longer pulls reportlab and python-docx in behind it — measured at 44.8 ms with both installed, previously paid on every FilesystemContextProvider import. (#9861) …

Changelog

New Features

• Per-page website ingestion: loading a website into a knowledge base now lands one content row per page, with each row's id equal to the content_id its vectors carry, so pages can be listed, refreshed, and deleted individually. The parent row becomes the site row — named after the host, aggregating status ("9 of 10 pages loaded; failed: …"), and cascading deletes to every page and its vectors. Re-ingest is digest-driven: unchanged pages skip embedding entirely, changed pages replace only their own vectors, failed pages retry, and pages that left the sitemap are pruned. (#9856)
• Folder and file ingestion with per-file rows: a directory insert lands as a folder row owning one child row per file (nested folders flattened), with the same contract websites got — byte-digest refresh (unchanged files skip the read and the embed), failure isolation (a file whose reader raises becomes a FAILED child row with the reason and never aborts the folder), prune of files deleted from the folder, and cascade delete. An emptied or unenumerable folder keeps every previous row instead of reading as mass removal. Single-file inserts are byte-for-byte unchanged. (#9858) …

Changelog

Behavior Changes

• Run metadata precedence: metadata now resolves as component, then session, then call-site on Agent, Team, and Workflow, so a metadata= passed to run() wins over agent.metadata where the component value previously won. A run no longer assigns session metadata back onto the shared component, so code that read agent.metadata after a run to observe session values now sees the constructor value. The session layer only applies where the dispatch pre-reads the session, so Team.arun and the async-DB agent and workflow paths still resolve from component and call-site alone. (#9104)
• MCPConfig rejects unknown fields: MCPConfig/MCPServerConfig now raise on unrecognised keyword arguments at construction instead of ignoring them, so a typo such as tool= fails at boot rather than silently serving a different tool surface. (#9819)
• BaseRemote.acancel_run signature: the abstract method gained an auth_token parameter that the cancel surfaces pass by keyword, so a third-party BaseRemote subclass must accept it. (#9819) …

Changelog

Improvements

• Faster agent runs with many tools: Tool schemas are now derived once and cached across runs, cutting per-run overhead for agents that carry large toolkits. (#9771)
• Faster long conversations: Session history is loaded incrementally per turn, so response time stays flat as a conversation grows instead of scaling with its length. (#9775)
• PubMed request timeout: PubmedTools now accepts a timeout and passes it to both NCBI E-utilities requests, so a stalled PubMed response cannot hold a tool call indefinitely. (#9463)

Bug Fixes

• Strict-mode tool schemas without properties: Function.process_schema_for_strict no longer raises KeyError on schemas that omit properties (for example MCP server schemas registered verbatim). (#9578, fixes #9409)
• Gemini tool-result media: Images and document blobs returned from tools are now nested inside FunctionResponse.parts for Gemini 3 and later models instead of being emitted as sibling inline_data parts; legacy models keep the previous representation. URI-backed response media on Vertex AI is only sent when the MIME type is supported. (#9647)
• Location lookup on core-only installs: agno.utils.location used the undeclared requests package, so add_location_to_context=True raised ModuleNotFoundError without extras installed. It now uses httpx. (#9793, fixes #9772) …

⚠️ Breaking release. A database migration is required before v3.0 serves traffic. Read the v3 Migration Guide first, and see the full v3.0 Changelog for every change.

New Features

• Tool result offloading: Agent(offload_tool_results=True) / Team(...) writes any tool result over 16,000 chars to AgentFS and leaves a short envelope (preview, size, result_id) in the message; the agent gets read_result / search_result (+ async) to fetch the rest. No model call on the write path. Tune via ResultStore(threshold_chars=..., ttl_seconds=...). (#9436, #9684)
• Media offloading: media_storage=S3MediaStorage(bucket=...) on an Agent/Team/Workflow uploads images, audio, video and files to local disk, S3 or GCS before persistence; the row keeps a small MediaReference instead of base64 (a 113 KB JPEG drops from ~151,000 chars to 2,897). No schema change. (#9340) Docs …

What's Changed

• test: stop three suites reading state they do not control by @ashpreetbedi in https://github.com/agno-agi/agno/pull/9736
• fix: state the team leader's delegation rule as need, not as a comparison with itself by @ashpreetbedi in https://github.com/agno-agi/agno/pull/9737
• fix: refuse dispatch cycles and bound dispatch depth in the Studio dispatch tools by @ashpreetbedi in https://github.com/agno-agi/agno/pull/9745
• fix: end a no-task tasks run by answering, and forbid joined member ids on nested rosters by @ashpreetbedi in https://github.com/agno-agi/agno/pull/9746
• fix: answer 422 with the validator's message when request validation fails by @ashpreetbedi in https://github.com/agno-agi/agno/pull/9744
• fix: give every eval run its own run_id by @harshsinha03 in https://github.com/agno-agi/agno/pull/9739
• feat: opt-in self_dispatch knob for the Studio dispatch guard by @ashpreetbedi in https://github.com/agno-agi/agno/pull/9749
• fix: complete the workspace credential excludes, and stop Studio taking version 0 literally by @ashpreetbedi in https://github.com/agno-agi/agno/pull/9752
• fix: hide inner sub-team member ids from the outer roster, and open with the leader's purpose by @ashpreetbedi in https://github.com/agno-agi/agno/pull/9754
• fix: close a fail-open in the Studio edit guard, and make the bigger exclude list affordable by @ashpreetbedi in https://github.com/agno-agi/agno/pull/9756 …

What's Changed

• feat: run SqliteDb in WAL journal mode and restore the durable benchmark row by @ashpreetbedi in https://github.com/agno-agi/agno/pull/9707
• cookbook: install pydantic-ai-slim in the perf environment by @ashpreetbedi in https://github.com/agno-agi/agno/pull/9706
• chore: v3.0 release readiness - put the database suites under CI and fix the gates that never ran by @ashpreetbedi in https://github.com/agno-agi/agno/pull/9712
• feat: add MiniMax video generation tools by @octo-patch in https://github.com/agno-agi/agno/pull/9529
• fix: stop test-a2a installing a lockfile that names an unpublished agnoctl by @ashpreetbedi in https://github.com/agno-agi/agno/pull/9714
• fix: let expected_current_version guard a first publish by @ashpreetbedi in https://github.com/agno-agi/agno/pull/9728
• fix: enforce Workspace exclude_patterns as an access boundary by @ashpreetbedi in https://github.com/agno-agi/agno/pull/9730
• feat: make all telemetry calls fire-and-forget by @ashpreetbedi in https://github.com/agno-agi/agno/pull/6458
• fix: let the team's own identity open its prompt, and stop the prompt describing a runtime we don't ship by @ashpreetbedi in https://github.com/agno-agi/agno/pull/9731
• chore: bump agno to 3.0.0a4 and release agnoctl as 0.2.0a1 by @ashpreetbedi in https://github.com/agno-agi/agno/pull/9735

Full Changelog: https://github.com/agno-agi/agno/compare/v3.0.0a3...v3.0.0a4

What's Changed

• fix: keep a workflow session's runs to its own runs by @harshsinha03 in https://github.com/agno-agi/agno/pull/9634
• fix: point invalid-schema table errors at the migration path by @ysolanky in https://github.com/agno-agi/agno/pull/9631
• fix: cache resolved tables in SQL adapters to avoid per-query existence checks by @kausmeows in https://github.com/agno-agi/agno/pull/9623
• fix: install a usable Postgres driver with the postgres and dev extras by @ashpreetbedi in https://github.com/agno-agi/agno/pull/9635
• fix: workflow event serialization survives cyclic object graphs by @ysolanky in https://github.com/agno-agi/agno/pull/9641
• fix: file-generation import warnings fire only when PDF/DOCX is requested by @ashpreetbedi in https://github.com/agno-agi/agno/pull/9640
• fix: AgentOSTools reports failed schedules, windows and refreshes correctly by @ashpreetbedi in https://github.com/agno-agi/agno/pull/9242
• test: assert the archive race by what landed, not by which call raised by @ashpreetbedi in https://github.com/agno-agi/agno/pull/9654
• fix: match a learnings record owner against the caller by value, not by type by @ashpreetbedi in https://github.com/agno-agi/agno/pull/9655
• fix: isolate entity memory rows per user under namespace="user" by @ashpreetbedi in https://github.com/agno-agi/agno/pull/9322
• feat: SuperGrok OAuth device-code auth for the xAI model by @Himanshu040604 in https://github.com/agno-agi/agno/pull/9616 …

What's Changed

• chore: remove deprecated enable_user_memories, search_session_history, num_history_sessions and num_past_session_runs params by @sannya-singal in https://github.com/agno-agi/agno/pull/7834
• feat: evals user-isolation by @harshsinha03 in https://github.com/agno-agi/agno/pull/8262
• chore: remove v3.0.0 evals migration by @harshsinha03 in https://github.com/agno-agi/agno/pull/8448
• refactor: drop flat HITL kwargs in favor of human_review=HumanReview(...) by @sannya-singal in https://github.com/agno-agi/agno/pull/8354
• feat: consolidate AgentOS metadata routes by @ysolanky in https://github.com/agno-agi/agno/pull/7647
• feat: add id to Toolkit by @ysolanky in https://github.com/agno-agi/agno/pull/8724
• feat: denormalize sessions table in db by @kausmeows in https://github.com/agno-agi/agno/pull/8350
• fix: derive runs table name from session_table to prevent silent run … by @kausmeows in https://github.com/agno-agi/agno/pull/9388
• feat: reliable background execution for AgentOS - bounded, observable, durable by @ysolanky in https://github.com/agno-agi/agno/pull/9079
• cookbook: make the at-most-once default discoverable where testers hit it by @ysolanky in https://github.com/agno-agi/agno/pull/9492
• fix: forward-port unified-continue gate removal to the agents door by @ysolanky in https://github.com/agno-agi/agno/pull/9392 …

Changelog

New Features

• StudioRunnerTools: New identity-aware dispatch toolkit (agno.tools.studio_runner.StudioRunnerTools) that splits execution out of StudioTools. Any component (team lead, router) can mount it to discover and run Studio-built agents/teams/workflows without getting the Studio's create/edit/delete surface. run_* tools thread the caller's user_id into the sub-run so per-user state lands on the right person.
• list_components name filter: Added a name filter to list_components.

Bug Fixes

• A2A: Fixed the A2A stream client dropping Task-level metadata by breaking on status-update.
• Workflow (WebSocket): Honor the selected workflow version over WebSocket.
• Team HITL: Persist paused member runs so team HITL resume survives a session reload.
• Rehydration: Preserve toolkit instructions on rehydration.
• Framework annotations: Guard framework return annotations.

Behaviour & Breaking Changes …

Changelog

New Features

• AdvisorTools: Added AdvisorTools for asking advisor models for feedback.
• OpenRouteService Toolkit: Added OpenRouteService toolkit for accurate routing.
• StudioTools: Added component-aware schedule tools and history parameters.
• FileSystemTools: Allow overriding the FileSystemTools toolkit name.

Bug Fixes

• Persisted Components: Fixed toolkit-qualified tool rehydration for persisted components.
• Cohere: Stop dropping zero-valued sampling params (temperature, top_k, seed, frequency_penalty, presence_penalty now respect an explicit 0).
• HITL: Propagate top-level confirmation to tool_execution on requirement deserialization.
• Team.load: Fixed crash on SQLite with unexpected keyword argument label.
• Audio Tools: More robust audio tool-result handling (and switched the Smallest AI cookbook to Gemini).
• Dependencies: Exclude nltk 3.10.1, which breaks the unstructured import chain.

What's Changed

• fix: exclude nltk 3.10.1, which breaks the unstructured import chain by @sannya-singal in https://github.com/agno-agi/agno/pull/9320
• fix: robust audio tool-result handling, switch Smallest AI cookbook to Gemini by @harshitajain165 in https://github.com/agno-agi/agno/pull/9331
• fix: Team.load crashes on SQLite with unexpected keyword argument 'label' by @Himanshu040604 in https://github.com/agno-agi/agno/pull/9337 …