Agno Release Notes

Changelog

New Features

Durable External Agent Sessions: ClaudeAgent sessions now resume on any replica. The Claude SDK session id is stored on the Agno session (#10903), and with a database that supports transcript storage (PostgresDb, AsyncPostgresDb, SqliteDb, AsyncSqliteDb) every transcript line is mirrored into the new agno_transcripts table, so a later turn on another machine resumes from the database instead of a local file. A stored session that cannot be resumed falls back to a fresh SDK session seeded with the Agno history. Claude and Codex non-streaming runs now keep tool calls and results in run history. See cookbook. (#10904)

Background Runs & Cancellation for External Agents: ClaudeAgent and CodexAgent support background=True, durable-queue run ids, resumable indexed SSE and cancellation through /agents/{id}/runs/{run_id}/cancel, sharing the background task, slot and event-stream infrastructure of native agents. Claude uses a per-run SDK client and Codex retains turn handles, so the owning process can interrupt either SDK. See cookbook. (#10905)

Step Replay for ClaudeAgent: ClaudeAgent.continue_run / acontinue_run take the same continue_from, fork and input arguments as Agent.continue_run, with stream=True and background=True. Each tool result is a checkpoint listed by GET /agents/{id}/runs/{run_id}/checkpoints; continuing forks the stored SDK transcript at that message, so the model only remembers what happened up to it, and continue_from="last_user" replays the turn. A finished run is never rewritten in place: its continuation is a new sibling run. See cookbook. (#10917)

Retries for External Agents: ClaudeAgent and CodexAgent take retries, delay_between_retries and exponential_backoff with the same defaults as Agent. A failed attempt is retried with the same run id and resumes the SDK session or Codex thread it started; limits (max_turns, max_budget_usd, Codex budget and usage limits) and permanent errors (authentication, billing, bad requests, context window, policy) are not retried. Tool calls from failed attempts are kept exactly once, streaming consumers get a type: "retry" warning event between attempts, a retried run records metadata["attempts"], and the durable queue fails a job at once when the agent marks its error non-retryable, including across worker restarts. See cookbook. (#10937)

Metrics for External Agents: Every ClaudeAgent and CodexAgent run reports tokens, cache usage and cost (Claude) on RunOutput.metrics, with one entry per model in metrics.details["model"], plus Agno's wall-clock duration and time_to_first_token. Completed runs accumulate into the session's session_metrics, which AgentOS shows in the sessions list, the session view and /metrics. Codex sums every model request in a turn, not only the last one. See cookbook. (#10925)

Compaction for External Agents: Claude Code's /compact works through the database-backed session store, so a compacted session resumes from its summary on any replica, and CodexAgent.compact / acompact compact the Codex thread behind an Agno session. Compaction refuses while a run on the session is in flight. See cookbook. (#10924)

Stored Events for External Agents: BaseExternalAgent takes store_events and events_to_skip like Agent. AgentOS turns it on for external agents, so the run view and /agents/{id}/runs/{run_id}/resume replay a finished run from the database once the event stream's retention has expired, in order and honouring last_event_index. (#10957, #10958)

Structured Output for External Agents: output_schema on ClaudeAgent and CodexAgent takes a Pydantic model or a JSON Schema dict, on the agent or per run, and the run's content is the parsed model (or dict) with content_type set, as for Agent. Claude delivers the object through its structured output tool, which is not recorded as a tool call; Codex receives a strict schema. The schema must describe a JSON object; an array or scalar root is refused before the run. The AgentOS per-request output_schema form field now applies to external agents. See cookbook. (#10965)

Media for External Agents: Images and files can be attached to ClaudeAgent and CodexAgent runs, directly and through the AgentOS API and UI. Attachments are staged under <cwd>/.agno/uploads/<run_id>/, named in the prompt (Codex also receives images natively), recorded on the run's input, restored for later turns on any replica and removed after the run unless keep_uploads=True. Audio and video are rejected with a 400 instead of a server error. See cookbook. (#10926)

External Agent Identity on Session APIs: GET /sessions, GET /sessions/{session_id} and the session run reads carry the same metadata.sdk value as the agents API ("codex", "claude-agent-sdk"), overlaid at read time from the agent_data external agents already persist, so existing sessions are labelled with no migration and stored metadata is untouched. Native, team and workflow sessions are unchanged. RunSchema gains a metadata field, which also surfaces run metadata such as retry attempts and warnings. (#11020)

AnakinTools: New toolkit for Anakin.io's scrape, crawl, map and search APIs as four flag-gated methods, polling asynchronous jobs until they complete so the model receives page content or links rather than a job id. See cookbook. (#10650)

Improvements

External Agent APIs: ClaudeAgent and CodexAgent take typed native options (tools, permissions, MCP servers, thread and turn options) instead of untyped _kwargs dictionaries, which still work with a warning. Adapter constructors are keyword-only, agent.sdk names the SDK (API and session metadata emit only sdk; the framework alias remains on the Python object), and print_response / aprint_response return the final run and raise on failure. Framework cookbooks were reworked with native SDK comparisons, a sample project and a reproducible reliability kit. (#10926)

Model Identity for External Agents: ClaudeAgent and CodexAgent runs record model and model_provider like native agents, so they count on the Models Runs card of the AgentOS metrics page. When no model is set on the agent or in its options, model defaults to claude-sonnet-4-6 for Claude and gpt-5.6-luna for Codex, as a native model has a default id; the default is what the SDK is asked to run. A model set in options still wins. Previously an unset model left the choice to the CLI. (#11018)

Queued Turns Per Session: Queued external-agent turns on one session no longer claim attempts together and burn them on SessionBusyError. Each built-in queue store (Postgres, Redis, in-memory) elects the next turn for a session before it spends an attempt or a worker slot. (#10974)

Harness Cookbooks: The Claude and Codex cookbooks were refreshed after Phase 1 acceptance testing with typed native options throughout, a corrected reliability runner, and live results recorded in each folder's test log. (#10973)

One Turn Per Session: Claude Code and Codex keep one conversation per session on their side, so a second turn started while one is in flight is now refused with SessionBusyError (HTTP 409, error_type: session_busy) instead of being accepted and failing later. Cancelling a run left pending or running by a crash frees its session. (#10958)

Subagent Tool Lineage: Tool calls made by Claude subagents carry parent_tool_call_id on ToolExecution and on tool events, so tracing shows nested tool spans under the delegating tool. See cookbook. (#10959)

Development Setup: scripts/dev_setup.sh and scripts/demo_setup.sh install the same dependencies, so cookbooks run from either environment. (#10920)

Bug Fixes

Session Busy Keep-Alive: The 409 for a busy external-agent session is answered by a dedicated SessionBusyError handler instead of the catch-all, so the keep-alive connection stays open and the conflict is logged as a warning rather than a traceback. The response body is unchanged and no other exception takes the new path. See cookbook. (#11017)

Attachment Staging: Files attached to external-agent runs are staged and restored only under the active workspace, with the harness told when historical paths moved. A failed staging rolls back every file it created, including partial writes and with keep_uploads=True, while preexisting files are preserved. Traversal run ids and symlinked upload paths are rejected. (#10971)

Run Input Validation: Malformed JSON images, audio, videos and input_files on run requests are rejected with HTTP 422 before dispatch instead of vanishing or failing mid-run, and a malformed or scalar-root output_schema is rejected instead of being silently dropped. (#11005)

CodexAgent: Failed tool calls (a non-zero exit, a declined command, an MCP tool error) are stored with tool_call_error=True instead of null, on streamed and non-streamed runs. (#10958)

CodexAgent: When a thread cannot be resumed, the history replayed into the fresh thread now includes earlier tool calls and their results, truncated to 2000 characters each, instead of only user and assistant text. (#10909)

External Agent Resume: /resume on a run submitted with stream=false reports the run's real status and says to poll the run endpoint, instead of claiming the run completed while it was still running. (#10958)

Tests: The partial-tool collision test no longer depends on FastMCP's tool naming. (#10914)

What's Changed

fix: persist ClaudeAgent SDK session id across restarts by @ysolanky in #10903
fix: make partial-tool collision test independent of FastMCP's naming by @sannya-singal in #10914
fix: include tool calls in Codex fallback history prompt by @ysolanky in #10909
feat: persist external agent transcripts and tool results by @ashpreetbedi in #10904
[feat] Add AnakinTools: scrape, crawl, map and search via Anakin.io by @aryan-anakin in #10650
feat: add background lifecycle and cancellation to external agents by @ashpreetbedi in #10905
chore: align dev and demo setup environments by @ashpreetbedi in #10920
feat: continue ClaudeAgent runs from a step by @ysolanky in #10917
feat: capture ext agent harness metrics by @kausmeows in #10925
fix: keep failed attempts' tools and announce retries to streaming consumers by @kausmeows in #10937
feat: compaction cookbooks for Claude and Codex, CodexAgent.compact by @kausmeows in #10924
feat: store run events for external agents by @kausmeows in #10957
feat: preserve Claude subagent tool lineage for tracing by @kausmeows in #10959
feat: output_schema for external agents (Claude, Codex) by @ysolanky in #10965
fix: harness soak follow-ups: tool errors, resume status, one turn per session by @kausmeows in #10958
feat: improve external agent APIs and framework cookbooks by @ashpreetbedi in #10926
fix: serialize queued external-agent turns before claiming attempts by @ashpreetbedi in #10974
fix: confine harness attachment staging and roll back failures by @ashpreetbedi in #10971
fix: reject malformed run media and output schema inputs by @ashpreetbedi in #11005
cookbook: validate Phase 1 harness examples and reliability contracts by @ashpreetbedi in #10973
fix: answer a busy session without closing the client connection by @kausmeows in #11017
fix: record the model and provider on external agent runs by @kausmeows in #11018
feat: expose the external agent sdk on session and run reads by @kausmeows in #11020
feat: Release v3.1.3 by @kausmeows in #10984

New Contributors

@aryan-anakin made their first contribution in #10650

Full Changelog: v3.1.2...v3.1.3

Original source

Changelog

New Features

Conversation Compaction: Agent(compaction=True) keeps long sessions inside the context window by folding older turns into a summary. Stored messages are never rewritten: a CompactionRecord in the new agno_compactions table drives a derived model payload, so removing the record restores the full conversation. Tune with Compaction(model=..., compact_at_tokens=..., uncompacted_runs=...), fold on demand with agent.compact() / acompact(), and inspect run.compaction. With searchable=True the agent gets a search_compacted_history tool, a regex grep over the archived transcript. See cookbook. (#9873)

Codex External Agent: Added CodexAgent, an adapter for OpenAI Codex built on the openai-codex SDK, alongside the Claude Agent SDK, LangGraph, DSPy and Antigravity adapters. Codex runs its own agent loop; the adapter translates its notifications into Agno run and tool-call events, maps each Agno session to one Codex thread (persisted when a db is set), and exposes sandbox, approval_mode, reasoning_effort, output_schema and MCP config. Works standalone and through AgentOS. See cookbook. (#10901)

HyDE Query Transform: Added QueryTransformer as a new retrieval hook and HyDE as its first implementation: Knowledge(vector_db=..., query_transformer=HyDE()) searches with a hypothetical answer instead of the raw question, while rerankers still score against the original query. HyDE uses its own model, then the calling agent or team's model, then the framework default. See cookbook. (#10527)

Browser Origin Policy: Added AgentOS(cors=CORSConfig(origins=..., origin_regex=..., merge_base_app=...)) and opt-in PublicSurface(enforce_browser_origins=True). One origin policy is now shared by CORS preflights, public run and cancel admission, auth error headers, workflow WebSockets and MCP aliases, and CORS is the outermost middleware so error responses carry consistent headers. cors_allowed_origins keeps its existing behaviour. See cookbook. (#10869)

Configurable Follow-ups: followups: bool | FollowupConfig on Agent and Team. FollowupConfig sets a count range (num_followups or min_followups / max_followups), a separate model and custom instructions that go only to the follow-up call. The default prompt now stays within the answer's boundaries and no longer re-offers a request the answer declined. Existing num_followups callers keep getting exactly N suggestions. See cookbook. (#10087)

Heabsy: Added Heabsy as an OpenAI-compatible model provider, also resolvable as "heabsy:<model>". See cookbook. (#10828)

FlexAI: Added FlexAI as an OpenAI-compatible model provider for open-weight models, also resolvable as "flexai:<model>". See cookbook. (#10871)

SixtyDBTools: New toolkit for the 60db hosted speech API: discover workspace voices and generate speech as WAV audio artifacts. See cookbook. (#10786)

Improvements

Page Sync Logs: Page synchronization now logs lock waits, discovery, progress every 25 pages and final counts, so long syncs show progress without a custom callback. Added an AgentOS cookbook that syncs documentation into PostgreSQL-backed knowledge pages and exposes them through the agent's filesystem. See cookbook. (#10868)

OpenAIResponses & OpenRouterResponses: Recognise GPT-6 (OpenAI) and GPT-5/6 (OpenRouter) as reasoning models, so reasoning-state chaining and encrypted reasoning replay apply and tool-call follow-ups no longer fail with missing reasoning-item errors. (#10830)

PerplexitySearch: Requests now send an X-Pplx-Integration: agno header so Perplexity can attribute traffic from the integration. (#10827)

Bug Fixes

Approvals: Each @approval tool call in a run now gets its own approval record, for agents and teams. Previously a second pause in the same run created no record and the next continue ran the new call against the approval resolved for the first one. (#10812)

Model Response Cache: Pydantic output_schema classes are keyed by their JSON schema instead of their class name, so two schemas with the same name but different fields no longer share a cached response. (#10621)

Usage Metrics: MessageMetrics.cache_write_tokens is now populated from OpenAI Chat Completions and Responses usage (#10313) and from LiteLLM's prompt_tokens_details (#10476). Previously it was always zero.

JsonDb: Tables are serialized to a staging file and published with os.replace, so a failed write leaves the last successfully saved table readable instead of a truncated file. (#10794)

MongoDb & MongoVectorDb: session_name, search_content and keyword-search filters are regex-escaped, so a value like (draft no longer returns HTTP 500 from GET /sessions and GET /memories, and v1.2 no longer matches v1x2. (#10709)

Tool Schemas: Annotated[T, ...] hints are unwrapped to T before JSON schema generation instead of falling through to an empty object schema. (#10858)

SQLTools: Connection URLs are built with URL.create, so a password like p@ssword is no longer split into password p and host ssword@.... (#10800)

FileTools: replace_file_chunk rejects negative, reversed and out-of-bounds line ranges with an error and leaves the file untouched; a valid replacement preserves the trailing newline. (#10798)

GoogleCalendarTools: find_available_slots compares the full slot end against closing time on its start date, so a 45 minute slot is no longer offered at 16:30 for a 17:00 close and slots cannot cross midnight. (#10878)

BaiduSearchTools, Searxng & SpiderTools: An explicit max_results=0 / fixed_max_results=0 now means no results instead of falling back to the default. (#10877)

Readers: TextReader, MarkdownReader (#10779) and JSONReader (#10634) accept streams whose name is an integer or None, such as descriptor-backed temporary files, instead of returning nothing or raising.

Cookbooks: Fixed the DynamoDb import path in the DynamoDB storage README. (#10788)

What's Changed

• [fix] Handle non-string stream names in JSONReader by @Jim-jimu in #10634
• [cookbook] Fix DynamoDb import path in the DynamoDB cookbook README by @Xx-173 in #10788
• [fix] Read text and Markdown streams with non-string names by @pei711 in #10779
• fix: create a separate approval record for each approval-required tool call in a run by @kausmeows in #10812
• [fix] Reject invalid file replacement line ranges by @LeonSGP43 in #10798
• [feat] Add Perplexity integration attribution by @qirh in #10827
• [fix] Preserve reserved characters in SQLTools credentials by @wToTw123 in #10800
• [fix] Preserve saved JsonDb tables when writes fail by @rudycelekli in #10794
• fix: recognize GPT reasoning models in OpenAI and OpenRouter Responses by @Ayush0054 in #10830
• [feat] Add 60db workspace voice tools by @uditgoenka in #10786
• fix: match Mongo text filters as literal text by @devYRPauli in #10709
• cookbook: add knowledge filesystem example and sync progress logs by @Ayush0054 in #10868
• [fix] Include response schema in model cache keys by @charan-rathore in #10621
• fix: keep configurable follow-ups within response boundaries by @ashpreetbedi in #10087
• [feat] Add FlexAI as an OpenAI-compatible model provider by @sundar-flex in #10871
• [fix] Preserve OpenAI cache-write usage metrics by @basnijholt in #10313
• [fix] Preserve cache-write tokens in the LiteLLM usage parser by @HardMax71 in #10476
• chore: auto-close external PRs that skip triage or the PR template by @kausmeows in #10866
• [fix] Unwrap Annotated types in tool JSON schema generation by @michaelkillgta in #10858
• fix: honor zero max_results in BaiduSearch, Searxng and Spider toolkits by @Madin-H23 in #10877
• [feat] Add Heabsy as an OpenAI-compatible model provider by @kafomichev in #10828
• feat: unify browser origin policy across AgentOS surfaces by @ysolanky in #10869
• [fix] Keep Google Calendar slots within working hours by @lux-liang in #10878
• feat: add HyDE query transform by @sannya-singal in #10527
• feat: add support for codex harness external agent by @kausmeows in #10901
• feat: auto compaction with a searchable archive by @kausmeows in #9873
• chore: Release v3.1.2 by @kausmeows in #10892

New Contributors

@Jim-jimu made their first contribution in #10634

@Xx-173 made their first contribution in #10788

@pei711 made their first contribution in #10779

@LeonSGP43 made their first contribution in #10798

@qirh made their first contribution in #10827

@wToTw123 made their first contribution in #10800

@rudycelekli made their first contribution in #10794

@uditgoenka made their first contribution in #10786

@charan-rathore made their first contribution in #10621

@sundar-flex made their first contribution in #10871

@HardMax71 made their first contribution in #10476

@michaelkillgta made their first contribution in #10858

@Madin-H23 made their first contribution in #10877

@kafomichev made their first contribution in #10828

@lux-liang made their first contribution in #10878

Full Changelog: v3.1.1...v3.1.2

Original source

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

Retry transient page-fetch failures with backoff: on large corpora (e.g. docs.agno.com, 3,913 pages) 1–2 random pages failed per run with Connection reset by peer. Each attempt previously consumed the entire 30s fetch deadline (leaving no time to retry) and retries were too short — both are fixed with a bounded per-attempt timeout and backoff. (#10730)

Complete page sync for Mintlify-style sites: large Mintlify sites (e.g. docs.langchain.com) synced as partial even when every page indexed — and a partial result skips pruning, so removed pages stayed searchable indefinitely. Discovery now skips links to non-page files (.json, .yaml, .xml, .csv, .pdf, images/audio/video, archives, fonts — while keeping .js/.css as valid page names like /guides/node.js), and handles nested indexes, MDX code blocks and redirect aliases. Off-host page links still block pruning (by design). (#10726)

What's Changed

feat: name failed pages and their causes in page sync reports by @kausmeows in #10729

fix: retry transient page fetch failures with backoff by @kausmeows in #10730

feat: add AgentOS lifecycle support for Knowledge page synchronization by @ashpreetbedi in #10098

fix: complete page sync for Mintlify-style sites (non-page links, nested indexes, MDX code, redirect aliases) by @kausmeows in #10726

chore: Release v3.1.1 by @kausmeows in #10736

Full Changelog: v3.1.0...v3.1.1

Original source

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

MCP default & lifecycle tools are now opt-in: MCPConfig(tools=[...]) now publishes exactly the tools you list — both default_tools and lifecycle_tools default to False. Previously a tools=[...] config also served the built-in default tools (and the lifecycle continue_run / cancel_run).

Bug Fixes

HITL: continuing a paused run with background + stream no longer duplicates the paused run in its own history.

OpenAIResponses: recover requests when the chained (previous) response is gone.

DB: an async delete that failed is no longer reported as a run that wasn't there — the two cases are distinguished.

Structured output: don't crash when a JSON fragment provides a scalar before a list.

Python tool results: distinguish Nonevalued results from missing variables.

Chunking: reject an overlap that is not smaller than the chunk size.

CSV readers: handle CR (\r) record endings.

CsvTools: honor explicit zero row limits.

Shell / workspace command tools: honor an explicit zero tail.

GeminiTools: store raw video bytes in the generate_video artifact.

GithubTools: build branch links from the repository web URL (#10509); get_file_content preserves valid non-ASCII UTF-8 text

LocalFileSystemTools: read and write local files as UTF-8.

PubMed: preserve metadata for short abstracts.

Claude citations: preserve nullable document titles.

What's Changed

[fix] Honor explicit zero row limits in CsvTools by @hfg369 in #10492

[fix] GithubTools.get_file_content: preserve valid non-ASCII UTF-8 text by @indexGin in #10480

fix: recover OpenAIResponses requests when the chained response is gone by @ysolanky in #10395

[feat] Add AIMLAPITools: image, video, speech and transcription via AI/ML API by @hugoaimlapi in #10276

test: abort the create name prompt with Ctrl-D instead of SIGINT by @ysolanky in #10541

fix: Add GPT 6 series to reasoning list and Add GPT-6 Astra reasoning cookbook example by @RayST3 in #10542

fix: make test_encoded_sse_cannot_bypass_public_error_inspection test more robust by @sannya-singal in #10533

[fix] Read and write local files as UTF-8 in LocalFileSystemTools by @yetuge in #10538

[fix] Build GithubTools branch links from repository web URL by @jiangjiang248 in #10509

fix: reject an overlap that is not smaller than the chunk size by @sclfcz in #10321

fix: store raw video bytes in GeminiTools.generate_video artifact by @BlueX888 in #10554

[fix] Honor explicit zero tail in shell and workspace command tools by @yetuge in #10593

chore: move Docling knowledge tests into their own CI job by @sannya-singal in #10499

[fix] Preserve nullable document titles in Claude citations by @basnijholt in #10147

[fix] Preserve PubMed metadata for short abstracts by @zyouekiri in #10640

[fix] Distinguish None-valued Python tool results from missing variables by @icearia0219 in #10637

[fix] Handle CR record endings in CSV readers by @lakers-abing in #10657

fix: HITL continue with background and stream duplicates the paused run in its own history by @kausmeows in #10597

[fix] db: an async delete that failed is not a run that was not there by @ericdelorefice in #10682

[fix] Don't crash when a JSON fragment provides a scalar before a list by @inchang-ing in #10654

feat: v3.1 by @kausmeows in #10530

feat: make MCPConfig default and lifecycle tools opt-in by @ashpreetbedi in #10285

feat: Release v3.1.0 by @kausmeows in #10702

New Contributors

@hfg369 made their first contribution in #10492

@indexGin made their first contribution in #10480

@jiangjiang248 made their first contribution in #10509

@sclfcz made their first contribution in #10321

@zyouekiri made their first contribution in #10640

@icearia0219 made their first contribution in #10637

@lakers-abing made their first contribution in #10657

@ericdelorefice made their first contribution in #10682

@inchang-ing made their first contribution in #10654

Full Changelog: v3.0.11...v3.1.0

Original source

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.

Cancellation Stage: Added a machine-readable cancellation_stage (PENDING, EXECUTING, INTERRUPTED, or unknown) to RunOutput, TeamRunOutput, WorkflowRunOutput and the run API schemas, so clients no longer match on the cancellation message text.

OpenAIResponses: Added use_previous_response_id so store=True no longer forces automatic previous_response_id chaining.

Improvements:

MCP Tool Schemas: Every argument on the AgentOS MCP tools now carries a description in its inputSchema, and get_sessions bounds limit and page to a minimum of 1.

Reasoning Detection: DeepSeek thinking-mode model IDs are recognised as reasoning models when served through any OpenAILike provider such as DashScope.

Tools: Removed phantom Args entries from tool docstrings and corrected streaming docstring parameter names in two model classes.

Bug Fixes:

Tool Hooks: Sync hooks that return function_call(**arguments) now work in the async execution path. Previously the chain treated the unawaited coroutine as the tool result and the tool body never ran.

MCP Server Card: Bare mcp=True now installs the same routing layer as MCPConfig, so the Host check and mount prefix apply on both spellings. Dropped the unimplemented ETag / If-None-Match CORS headers.

MCP Tools: Tool discovery over a raw ClientSession now collects every tools/list page instead of only the first.

AG-UI: Support ag-ui-protocol 1.0, including list-valued tool result content on resume.

Workflows over WebSocket: Version-pinned submissions are no longer queued without their pin, session ownership is checked on the write path, and a missing session id mints a new session like HTTP.

JSONReader: Preserve scalar JSON roots.

CSVReader: Read text streams, not only byte streams.

CSVReader & FieldLabeledCSVReader: Validate page_size before reading, so zero or negative values raise ValueError instead of silently returning no documents.

Structured Output Parsing: Ignore unmatched closing braces in prose when extracting JSON objects from model output.

GoogleDriveTools: Read text inside grouped shapes and honour line breaks when extracting .pptx text.

UTF-8 Files: read_yaml_file / write_yaml_file, AntigravityTools and AirflowTools now read and write files as UTF-8 regardless of locale.

DuckDbTools: Escape CSV delimiters.

TavilyTools: Forward extract options.

Cookbooks & Docs: Replaced dead links in knowledge sources and fixed a duplicated word in the V3 migration guide. Added Inspeximus memory and Confident AI observability examples.

Deprecations:

Vector DB Reranker: The reranker parameter on vector databases is deprecated in favour of the reranker on Knowledge, which applies to every vector db and supports async.

What's Changed

chore: remove phantom Args entries in the tool docstrings by @simpleqt in #10229

cookbook: add Confident AI observability example by @kausmeows in #10257

fix: correct streaming docstring parameter names in two model classes by @simpleqt in #10228

feat: add knowledge level retrieval pipeline and MMR reranker by @sannya-singal in #10115

fix: bring WebSocket workflow submissions in line with the HTTP admission rules by @ysolanky in #10179

[fix] Paginate MCP tool discovery for ClientSession by @sicauzxl in #10012

fix: support ag-ui-protocol 1.0 in the AG-UI interface by @Himanshu040604 in #10283

[feat] Add Y-API as an OpenAI-compatible model provider by @jiweiyeah in #10326

[fix] Correct duplicated word in V3 migration guide by @yetuge in #10315

[fix] replace dead links in cookbook knowledge sources and docs references by @Theater-ahyeon in #10160

[cookbook] Add inspeximus memory integration example by @DanceNitra in #10146

fix: recognize DeepSeek thinking-mode IDs in OpenAILike reasoning detection by @yetuge in #10342

[fix] Validate page_size in FieldLabeledCSVReader by @tdog54646 in #10358

fix: decouple OpenAI response storage from automatic chaining by @ashpreetbedi in #10075

feat: deprecate the vector db level reranker by @sannya-singal in #10385

feat: add guarded documentation source relocation API by @ashpreetbedi in #10096

feat: expose typed page command and search tool results by @ashpreetbedi in #10097

[fix] read text streams in CSVReader instead of only byte streams by @harbinresearcher in #10355

[fix] Escape CSV delimiters in DuckDbTools by @imexlovery in #10415

[fix] Forward Tavily extract options by @daleselaji-dev in #10403

[fix] Preserve scalar JSON roots in JSONReader by @daleselaji-dev in #10402

fix: route bare mcp=True like MCPConfig for the MCP server card by @ysolanky in #10418

fix: describe and bound the MCP tool arguments by @ysolanky in #10419

[fix] Validate CSVReader page sizes before reading by @emme1t in #10437

feat: add cancellation_stage to cancelled runs by @ysolanky in #10411

fix: read and write YAML, Antigravity and Airflow files as UTF-8 by @MohammadHijjawi97 in #10242

fix: read grouped shapes and line breaks in Drive pptx text by @devYRPauli in #10473

[fix] Ignore unmatched closing braces when extracting JSON objects by @makiaveli1 in #10421

feat: add recency reranker by @sannya-singal in #10396

fix: await sync hook continuations in async chains by @kausmeows in #10481

fix: drop IMDB CSV from knowledge URL tests to stop CI timeouts by @sannya-singal in #10498

chore: Release v3.0.11 by @kausmeows in #10444

New Contributors

@sicauzxl made their first contribution in #10012

@jiweiyeah made their first contribution in #10326

@yetuge made their first contribution in #10315

@Theater-ahyeon made their first contribution in #10160

@DanceNitra made their first contribution in #10146

@tdog54646 made their first contribution in #10358

@harbinresearcher made their first contribution in #10355

@imexlovery made their first contribution in #10415

@emme1t made their first contribution in #10437

@MohammadHijjawi97 made their first contribution in #10242

@makiaveli1 made their first contribution in #10421

Full Changelog: v3.0.10...v3.0.11

Original source

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.
• JSONReader: async_read() now uses the chunking strategy's async achunk().
• Chunking: Preserve newlines and tabs when cleaning text before chunking.
• CSVReader: async_read() keeps every data row across pages with RowChunking(skip_header=True).
• SitemapReader: Keep filenames like myindex.html intact and continue discovery past an invalid .xml.gz sitemap.
• Tools & Workflows: Keep falsy values like 0, False and [] in sync tool results and Parallel workflow step outputs.
• agnoctl: agno connect now reads and writes client configs as UTF-8 (agnoctl 0.2.1).
• DynamoDB: Serialize booleans as native BOOL values.

Breaking Changes

• CodingTools: run_shell is now opt-in (enable_run_shell=True), and restricted mode runs commands without a shell.
• PublicSurface: With authorization=True and PublicSurface(mcp=True), MCP now accepts only localhost by default; add your domain to MCPConfig(allowed_hosts=[...]).

What's Changed

• fix: read text from grouped shapes in PPTXReader by @devYRPauli in #10037
• feat: add support for Elasticsearch vector database by @sannya-singal in #10018
• [feat] Add Azure OpenAI Responses model by @rastagan-git in #9841
• [fix] Accept text streams in FieldLabeledCSVReader by @n1uz1 in #10020
• [fix] Preserve MCP AudioContent as audio artifacts by @devansh173 in #10036
• fix: serialize booleans as BOOL instead of {"N": "True"} in DynamoDB storage by @Anai-Guo in #9978
• [fix] Use UTF-8 for infra file helpers by @Ghraven in #10113
• docs: fix broken external links in cookbook by @Shxiao101 in #9980
• fix: pretty-print MCP server-card JSON by @ashpreetbedi in #10084
• fix: detect public MCP access alongside JWT REST auth by @ashpreetbedi in #10083
• feat: add optional documentation Markdown source transform by @ashpreetbedi in #10094
• feat: configure MCP hostname and endpoint routing by @ashpreetbedi in #10090
• fix: add missing @Property to RemoteAgent.role and RemoteTeam.role by @kausmeows in #10172
• cookbook: export DocumentationMarkdown and make its example run end to end by @sannya-singal in #10178
• fix: accept text streams in MarkdownReader by @Minouccc in #10168
• [fix] Await async chunking in JSONReader by @Kyousuk1e in #10167
• [fix] Preserve non-index filenames during sitemap URL canonicalization by @yyydddkkk in #10189
• fix: repair cookbook import, dead links and typo by @Shxiao101 in #10134
• fix: dedupe Slack event retries by event_id instead of dropping them by @Himanshu040604 in #10073
• fix: docs correct the Perplexity and v0 base_url defaults in their docstrings by @xizhuomengcontin in #10192
• [fix] Accept text streams in TextReader by @RaycarlLei in #10203
• fix: dependency bump urllib3 to 2.7.0 and requests to 2.33.0 in mcp_toolbox_demo by @katsugtgz in #10184
• test: fix flaky test_tool_hook_receives_messages by @harshsinha03 in #10212
• [fix] keep falsy tool results (0, False, []) on the sync tool execution path by @BlueX888 in #9948
• fix: CONTRIBUTING paths, agno_infra license note, and docstring accuracy by @simpleqt in #9722
• fix: retain falsy values in previous workflow content by @guanzhuohe273-hub in #10208
• fix: Preserve CSV data rows when skipping headers across pages by @baba9811 in #9995
• fix: document PythonTools has no code sandbox by @ysolanky in #10218
• fix: harden CodingTools run_shell against interpreter RCE by @ysolanky in #10210
• [fix] Continue sitemap discovery after invalid gzip data by @RaycarlLei in #10213
• fix: use UTF-8 for agnoctl client config text by @Ghraven in #10038
• fix: run CodingTools restricted shell without a shell to neutralize operator injection by @ysolanky in #10220
• fix: Preserve newlines and tabs in clean_text by @icn5381 in #9985

New Contributors

• @rastagan-git made their first contribution in #9841
• @n1uz1 made their first contribution in #10020
• @devansh173 made their first contribution in #10036
• @Shxiao101 made their first contribution in #9980
• @Minouccc made their first contribution in #10168
• @Kyousuk1e made their first contribution in #10167
• @yyydddkkk made their first contribution in #10189
• @xizhuomengcontin made their first contribution in #10192
• @RaycarlLei made their first contribution in #10203
• @katsugtgz made their first contribution in #10184
• @simpleqt made their first contribution in #9722
• @guanzhuohe273-hub made their first contribution in #10208
• @baba9811 made their first contribution in #9995
• @icn5381 made their first contribution in #9985

Full Changelog: v3.0.9...v3.0.10

Original source

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)

Magic Hour hosted MCP cookbook: an example for image and video generation covers bearer authentication, long render timeouts, project ID reuse and output URL handling. (feat: add Magic Hour hosted MCP cookbook #10057)

Bug Fixes

Session data integrity (SQLite): bulk upsert_sessions() in SqliteDb / AsyncSqliteDb now applies the same owner check as the single-row upsert_session() — previously a batch containing another user's session_id would reassign the row and overwrite its data. Rows the predicate refuses are omitted from the returned list, matching Postgres and the single-row path. (#9937)

Public MCP validates the tools actually exposed. Custom-function configurations such as MCPConfig(tools=[custom_function], default_tools=False, stateless=True) now work without an unnecessary lifecycle_tools=False override. Public exposure of agents, teams or workflows still requires disabling the automatically added lifecycle tools with lifecycle_tools=False or exclude_tags={"lifecycle"}. (fix: validate effective public MCP lifecycle tools #10060)

What's Changed

feat: add Magic Hour hosted MCP cookbook by @runshouse in #10057

fix: validate effective public MCP lifecycle tools by @ashpreetbedi in #10060

feat: add PostgreSQL engine factories with shared defaults by @ashpreetbedi in #10062

feat: add bounded full-page reads and shared fence tracking by @ashpreetbedi in #10063

fix: stop double-encoding session JSON fields in the SQLite adapters by @ashpreetbedi in #9797

[fix] agno 3.x: apply the session owner check to SqliteDb bulk upserts by @basnijholt in #9937

Release: v3.0.8 by @ashpreetbedi in #10066

New Contributors

@runshouse made their first contribution in #10057

Full Changelog: v3.0.7...v3.0.8

Original source

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)

Agent dependency callables can receive run_input and session, alongside the existing agent and run_context. Resolution runs before pre-hooks and reuses successful values on model retries. add_dependencies_to_context still defaults to False. (#9963)

AIMLAPI: requests carry a fixed, analytics-only attribution header set, inspectable as agno.models.aimlapi.AIMLAPI_HEADERS and overridable per model via default_headers, where caller-supplied keys win. The headers carry no user data and do not affect routing, model selection or billing. The default model also moves from the retired gpt-4o-mini to gpt-5.6-terra. (#9898)

Improvements

Workflows report failed steps as StepError for both raised executor failures and explicitly failed outputs, carrying the current step's identity. Function reports are still preserved as StepOutput, and Agent, Team and nested Workflow content keeps its existing executor stream. Both console streaming printers render StepError explicitly, showing the original failure and clearing stale progress output. (#10001)

Bug Fixes

Failed workflow runs are finalized before their terminal streaming event. A workflow that paused during a background stream could fail during a non-streaming continuation, save ERROR to the database and leave its tracked stream stuck at PAUSED; fresh streaming failures yielded WorkflowError before the failed run was saved, so a consumer closing at that event could lose the run entirely. (#10001)

Nested workflow guardrail rejections are no longer retried, which previously replayed earlier child side effects. Explicit skip_on_failure is honored through the existing final-attempt policy and ordinary executor retries are preserved.

Meta Llama and AIMLAPI: every run crashed. Both providers' _format_message overrides had drifted from OpenAIChat, which passes compress_tool_results positionally, so each call raised TypeError: _format_message() takes 2 positional arguments but 3 were given. (#10031, #9898, fixes #9034)

Anthropic: empty tool arguments are preserved. A zero-argument Claude tool call is an empty input object, which the adapter treated as falsy and omitted function.arguments for. Streaming and non-streaming parsing now serialize every tool input, so empty input becomes "{}". (#8970, fixes #8971)

Cached tool wrappers no longer pin the caller's frame. validate_call stores the caller's f_locals on the wrapper it builds and Function caches those wrappers for the life of the process, so on Python 3.13 every cached tool kept the wrapping frame alive along with the Agent, session and run state on the stack. The namespace resolver is cleared once the validators are built. (#9941, fixes #9940)

Anonymous native Agent JSON no longer leaks diagnostics: a failed run returned HTTP 200 carrying status ERROR and nested model diagnostics, and is now a safe 503 run_failed, matching the streaming error protection. Authenticated operator diagnostics are unaffected. (#9963)

Page serving corrections across source retries, canonical-link deduplication, publication-time source binding, bounded page checkout and Agent continuation dependency ordering. (#9996)

Breaking Changes

Knowledge constructor arguments are keyword-only. Positional calls such as Knowledge("docs") must become Knowledge(name="docs"). content_db is now the preferred spelling; contents_db remains a supported read/write alias sharing the same dataclass field, so serialization, copy and dataclasses.replace(..., contents_db=...) are unchanged. Passing both keywords requires the same object. (#9963)

Page search honours the configured PgVector HNSW ef_search instead of silently forcing 200, so deployments that relied on the implicit 200 should set it explicitly. Page indexes built from interim main builds can carry an implicit ef_construction=64 and need an operator-managed rebuild; setup reports an actionable error rather than rebuilding automatically. (#9963)

What's Changed

feat: add coordinated pages and public docs serving by @ashpreetbedi in #9963

fix: correct page serving and add selected public teams by @ashpreetbedi in #9996

feat: extract bounded read-only page filesystem by @ashpreetbedi in #9997

[fix] agno 3.x: drop the caller-frame namespace pydantic keeps on cached tool wrappers by @basnijholt in #9941

[fix] Preserve empty Anthropic tool arguments by @basnijholt in #8970

[fix] AIMLAPI: repair broken integration, add revenue attribution headers by @hugoaimlapi in #9898

fix: forward compress_tool_results in LlamaOpenAI._format_message by @kausmeows in #10031

fix: finalize failed workflow runs before streaming errors by @ashpreetbedi in #10001

chore: release 3.0.7 by @ysolanky in #10055

New Contributors

@hugoaimlapi made their first contribution in #9898

Full Changelog: v3.0.6...v3.0.7

Original source

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

Anthropic: replay assistant turns verbatim so thinking blocks are no longer rejected.

Gemini: resolve image MIME type instead of hard-coding image/jpeg.

RecursiveChunking: stop emitting duplicate trailing chunks.

AG-UI: send wire fields instead of RunContext to remote entities.

AG-UI: expose streamed run errors.

Pin tree-sitter-language-pack<1.16 to unblock the chonkie code chunker.

What's Changed

[fix] Resolve Gemini image MIME type instead of hard-coding image/jpeg by @BlueX888 in #9887

fix: pin tree-sitter-language-pack<1.16 to unblock chonkie code chunker by @Himanshu040604 in #9901

feat: migrate MCP client and AgentOS server to mcp 2.x by @ProgrammerPlus1998 in #9269

[fix] expose streamed AG-UI run errors by @uuzzrm in #9487

feat: Support provided bedrock async client by @ddellspe-vl in #9531

fix: send wire fields instead of RunContext to remote entities over AG-UI by @Himanshu040604 in #9909

cookbook: add gemini-3.8-flash examples by @kausmeows in #9916

fix: stop RecursiveChunking from emitting duplicate trailing chunks by @devYRPauli in #9919

feat: name, version and instructions for the AgentOS MCP server by @ashpreetbedi in #9930

fix: replay Anthropic assistant turns verbatim so thinking blocks are not rejected by @ysolanky in #9924

feat: MCP Server Card at /mcp/server-card by @ashpreetbedi in #9932

feat: list the served tools on the MCP Server Card by @sannya-singal in #9949

feat: add AuthorizationConfig.excluded_route_paths for custom public routes by @kinKingen in #9295

feat: support .zip and .eml file uploads in AgentOS by @luisnmartins in #9193

chore: make AGENTS.md a symlink to CLAUDE.md by @ysolanky in #9813

feat: add stateless MCP transport and build MCP clients on fastmcp.Client by @sannya-singal in #9927

chore: Release v3.0.6 by @sannya-singal in #9907

New Contributors

@BlueX888 made their first contribution in #9887

@uuzzrm made their first contribution in #9487

@ddellspe-vl made their first contribution in #9531

@kinKingen made their first contribution in #9295

Full Changelog: v3.0.5...v3.0.6

Original source

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

partial content status: new ContentStatus.PARTIAL for files where some chunks embedded and others did not — searchable but incomplete, so neither completed nor failed. (#9814)

Optional embedding retry during ingestion (off by default): enable with Knowledge(max_embedding_retries=3, embedding_retry_backoff=1.0). Authentication failures ignore both settings and fail on the first attempt (the same credential is rejected every time). Note: each retry re-embeds the whole document.

GandrTools: new text-to-speech toolkit for the Gandr TTS API.

llmman model provider: new model provider.

Improvements

Actionable embedding failure messages: failure messages now name the chunk count, embedder, reason and recovery step, instead of "Could not insert embedding".

Re-ingest no longer destroys searchable chunks: an embed_before_replace guard embeds documents before deleting existing ones, so a failing re-ingest aborts before anything is removed (previously a failed re-embed could leave a document with zero chunks).

MCPTools accepts static headers=: connect-time auth headers can be passed directly on the url= path for Streamable HTTP and SSE, without constructing StreamableHTTPClientParams.

What's Changed

• feat: add headers= argument to MCPTools for connect-time auth by @LHMQ878 in #9444
• chore: re-enable litellm and crawl4ai extras by @RayST3 with @Copilot in #9868
• feat: Add GandrTools text to speech toolkit for the Gandr TTS API by @AALG123 in #9852
• [feat] Add llmman model provider by @ericcurtin in #9863
• fix: repair broken cookbook models, imports, and image URL by @Himanshu040604 in #9889
• fix: surface embedding failures during knowledge ingestion by @sannya-singal in #9814
• chore: Release v3.0.5 by @kausmeows in #9888

New Contributors

• @AALG123 made their first contribution in #9852
• @ericcurtin made their first contribution in #9863

Full Changelog: v3.0.4...v3.0.5

Original source

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)
AtomicMail reuses its auth handshake: the resolved context (capability JWT, API URL, account and inbox ids) is cached on the instance until the token nears expiry, in both sync and async paths, and keyed to the api_key it was minted from so re-registration is picked up on the next call. Warm tool calls drop from ~35 s to 0.4–3 s. (#9825)
AtomicMail proof-of-work parallelised: the scrypt nonce search splits across a bounded thread pool — new pow_workers argument, default min(4, cpu_count()), with pow_workers=1 matching the old sequential search exactly. Measured at difficulty 10: mean solve 25.9 s → 10.4 s on 4 workers. pow_timeout still bounds the search, and a worker that finds a solution wins over a concurrent timeout. (#9825)
Bug Fixes
AtomicMail list_inbox returned the agent's own sent mail: send_email files the outgoing message in the inbox mailbox with $draft set, and list_inbox queried that mailbox unfiltered, so an agent could not tell its own outgoing mail from a reply. The query now filters notKeyword: "$draft", the parser drops any $draft entry, and a rejected query is reported as an error instead of an empty inbox. (#9825)
Caller-supplied requires_confirmation_tools dropped the remove_content gate: KnowledgeManagementTools set its confirmation list with setdefault, so passing your own list silently removed the built-in confirmation requirement on remove_content — the one tool in the kit that destroys data. The lists now union. (#9861)

Original source

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)

SitemapReader: discovers a site's pages per the sitemap protocol — the URL itself, robots.txt Sitemap: lines, /sitemap.xml, /sitemap_index.xml, gzip and nested indexes — with canonical dedup and a max_pages cap. It is auto-selected for bare sitemap*.xml(.gz) URLs and registered in the reader factory, so it appears in the UI reader dropdown. Each page becomes one whole-page Document, chunked exactly once, and failed pages return as data rather than aborting the read. (#9856)

PageFetcher: a fetch seam below the URL readers. HttpxPageFetcher fetches with bounded concurrency and a redirect guard; ParallelPageFetcher resolves Parallel's keyed SDK, then its keyless MCP endpoint, then plain httpx — honoring retry-after with exponential backoff, falling back per page, and recording per-page extractor and attempts provenance. (#9856)

PDF sitemap entries become citable page rows: HttpxPageFetcher routes application/pdf responses — and %PDF- bytes served under a wrong content type — through PDFReader. A missing pypdf surfaces as a per-page error naming agno[pdf] rather than an exception through the read. (#9858)

KnowledgeManagementTools: the write-side operator toolkit for knowledge bases — ingest_url, ingest_text, ingest_path (file or folder), list_content (grouped by site and folder), ingest_status, and remove_content (requires confirmation by default), with sync and async variants under the same tool names, JSON envelopes, and scope="shared"|"user". (#9856, #9858)

AgentOS knowledge routes: GET /knowledge/content?parent_id= lists a site's or folder's rows with correct totals, and POST /knowledge/content/{id}/refresh re-runs a URL or path-sourced row's ingest in the background. (#9856, #9858)

Bug Fixes

Multi-page URL ingests orphaned their vectors on delete: WebsiteReader crawls and LLMsTxtReader wrote per-URL vector groups whose content_id matched no contents row (#6054 follow-on), so deleting the row from the Knowledge page left every page's vectors behind. Per-page content rows now own those vector groups — existing groups are adopted without re-embedding — so both per-page and cascade delete remove them. (#9856)

Aborted legacy-row promotion retried unguarded: when promoting a legacy multi-page row to per-page rows failed partway, the retry ran without its ownership guard and could land COMPLETED beside stale searchable legacy vectors. The ownership marker is now re-stamped across the attempt, so retries stay guarded until the stale vectors are cleared. (#9860)

Cap-truncated reads pruned live pages: a sitemap read that hit max_pages with entries remaining — the exact shape of POST /refresh — reported complete discovery, so reconciliation deleted every beyond-cap page row and its vectors. Cap truncation and never-opened index shards now mark discovery incomplete, which suppresses pruning and is reflected in the site status. (#9860)

Remote parent_id filtering: GET /knowledge/content?parent_id=… against a RemoteKnowledge silently dropped the filter and returned the full base as a filtered-looking response; it now returns 501, matching remote refresh. (#9860)

LightRag multi-page URL reads: the LightRag URL path now refuses multi-page reads with a clear FAILED message instead of silently ingesting only the first page, and no longer permanently mutates the shared reader's chunk flag. (#9856)

Cookbooks

New examples: cookbook/07_knowledge/01_getting_started/05_website_per_page.py (per-page website ingestion) and cookbook/91_tools/knowledge_management_tools.py (the management toolkit, including folder ingestion). (#9856, #9858)

Original source

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)

Reasoning detection asks the provider: native reasoning detection now queries the provider before falling back to model-id matching, so a Gemini or Claude model configured for thinking is classified as non-reasoning when the provider reports thinking unsupported. The lookup is a blocking HTTP call cached on the reasoning manager, with a 10 second timeout on the Ollama, OpenRouter, and Moonshot paths. Id-based fallbacks changed too: gpt-5 variants match on OpenAI and Azure OpenAI, Groq and Ollama match gpt-oss and qwen3, and Ollama's qwen2.5-coder is no longer treated as a reasoning model. (#8616)

MCP configuration renames: AgentOS(mcp=...), MCPConfig, and default_tools are the new spellings for mcp_server=, MCPServerConfig, and enable_builtin_tools. The old names keep working as aliases with removal targeted for 3.1; passing both spellings with different values raises. (#9819)

New Integrations

Synthorai model provider: Synthorai (agno.models.synthorai) talks to the Synthorai gateway over its OpenAI-compatible endpoint, reading SYNTHORAI_API_KEY and defaulting to https://synthorai.io/v1. It is registered in the provider lookup table, so model="synthorai:<model-id>" strings resolve as well. (#9788)

WaveSpeed image and video generation: WaveSpeedTools (pip install agno[wavespeed], key from WAVESPEED_API_KEY) generates media through the WaveSpeed API. generate_image and generate_video take a text prompt and return a ToolResult carrying Image/Video artifacts, polling synchronously within poll_interval and timeout. (#9620, fixes #9621)

Serply search toolkit: SerplyTools searches Google web, News, and Scholar through the Serply API, reading SERPLY_API_KEY. Web search is on by default; search_news, search_scholar, or all=True enable the others. A missing key or failed request returns an error field instead of raising. (#9780, fixes #9779)

AtomicMail toolkit: AtomicMailTools gives an agent its own inbox. register_inbox provisions one through AtomicMail's proof-of-work signup with no domain setup or human verification, and send_email and list_inbox work over JMAP. Credentials are cached to ~/.atomicmail/credentials.json so later runs reuse the same inbox, and pow_timeout (default 300s) caps the solve. (#9130)

Improvements

Agents, teams, and workflows as MCP tools: MCPConfig.tools now accepts Agent, Team, and Workflow instances, remote proxies, and component factories, publishing each as its own named MCP tool — chief, rather than run_agent(agent_id="chief"). component.as_tool(name=..., description=...) publishes one under a name and description of your choosing. continue_run and cancel_run register alongside exposed components even with default_tools=False, so a run that pauses on a confirmation stays resumable over MCP. (#9819)

Toolkits as MCP tools: MCPConfig.tools now accepts a Toolkit and publishes one MCP tool per registered method, narrowed by the toolkit's own enable_*/include_tools/exclude_tools, where it previously raised TypeError. Framework parameters (RunContext, Agent, Team, and the agno* channels) are kept out of the client-facing schema and filled server-side. A tool returning a ToolResult is rendered as MCP content blocks — text, image and audio, embedded resources for video and file bytes, and resource_link for url-only artifacts. A **kwargs entrypoint, which previously took get_app() down, now publishes its declared schema or its named parameters. (#9846)

MCP tool titles and behaviour annotations: as_tool() and @tool/Function now accept title and annotations, which AgentOS publishes over MCP for exposed components, custom tools, and its eight built-in tools. Exposed components publish a title even when you set none and assert readOnlyHint: False, destructiveHint: True, openWorldHint: True by default, with your overrides merged per key. Unknown annotation keys raise rather than travelling to the client. (#9844)

Context provider query_timeout and write_tools: every context provider accepts query_timeout, a wall-clock deadline applied to each query_<id> tool call that yields an error chunk instead of hanging the run. It needs Python 3.11 or later and raises at construction below that. The five write-capable providers also accept write_tools to replace the default write sub-agent toolset. (#9104)

Wiki GitBackend keeps the PAT off disk: the token is injected per git call through an ephemeral credential helper instead of being baked into the origin URL, and existing clones are rewritten to the bare URL on setup. This needs git 2.31 or later. (#9104)

Slack delivery options and safer approval cards: the Slack interface gains markdown, unfurl_links, and unfurl_media, now sent explicitly on every message. Approval cards make backticks, newlines, and angle brackets in model-produced tool args inert so they cannot break out of the inline code span. (#9104)

Headless Google OAuth: Google toolkits accept AuthConfig(interactive=False), or GOOGLE_OAUTH_NONINTERACTIVE=1, to raise instead of blocking on a browser OAuth flow that will never complete on a headless host. (#9104)

Schedule listing: new ScheduleManager.list_all() and alist_all() page the whole schedule catalog and surface database errors instead of returning an empty catalog, backed by a new raise_on_error argument on get_schedules. Listings now break created_at ties by id, so rows sharing a timestamp are no longer skipped or duplicated across pages. (#9104)

Moonshot and OpenRouter reasoning: MoonShot (Kimi) gains sync, async, and streaming reasoning handlers that read reasoning_content, and OpenRouter is routed through the OpenAI reasoning path. Previously both were picked up only when their id happened to contain deepseek-r1 or minimax-m2/m3. (#8616)

MCP configs scoped down to zero tools now warn: MCPConfig logs a warning at construction when the default tools are on but include_tags/exclude_tags scope out every tag and no custom tools were passed — the config that boots a /mcp endpoint listing nothing. The config is still accepted and the resolved tool surface is unchanged. (#9748)

Bug Fixes

CodeMode(allow_shell=False) on IPython 9.17: IPython 9.17 registers script magics lazily and recreates them on lookup, so removing bash from the cell-magic table no longer disabled it — %%bash still ran in a kernel configured to forbid shell access. The kernel now materialises the script-magic provider first and drops bash from both the lazy table and the live registry, so loading a sibling magic such as %%sh cannot re-register it.

Registry MCP toolkits from standalone processes: StudioTools now connects an unconnected registry MCP toolkit on demand while resolving tools, so creating or editing a component from a script, notebook, or eval run no longer fails with "Toolkits have no functions and cannot be persisted". eval.suite.cli/acli take a new mcp_tools=[...] argument that connects those toolkits before the cases run, and MCPToolbox clears its client state on close() and on a failed filter so a reconnect re-applies toolsets/tool_name. (#9845)

Executor errors in streaming workflow steps: when a Step's Agent or Team executor failed mid-stream, the streaming paths treated the error event as a finished step and emitted an empty StepOutput with success=True. Step.execute_stream and Step.aexecute_stream now raise a RuntimeError naming the step and its executor, so the failure goes through normal step error handling and the resulting StepOutput carries success=False and the error text. Failing streaming steps are now retried like any other step failure. (#9138, fixes #7185)

Truncated tool arguments in the paused-run panel: the human-in-the-loop panel built its argument list with rstrip(", "), which strips a set of characters rather than a suffix and so also ate trailing commas and spaces belonging to the last argument's own value. All three blocks now join arguments the way format_tool_calls already did. This is display-only; the arguments passed to the tool were never affected. (#9246, fixes #9248)

Cookbooks

Cookbook examples that pinned gpt-4o, gpt-4o-mini, or gpt-5.4-mini now use gpt-5.6-luna, across 355 files. Gateway examples were rewritten too, so LiteLLM, OpenRouter, AzureOpenAI, AzureAIFoundry, CometAPI, Requesty, LangDB, and AIMLAPI examples depend on that gateway or Azure deployment resolving gpt-5.6-luna. Specialized ids and dated snapshots are unchanged. (#8939)

Original source

⚠️ 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

CodeMode: CodeMode(tools=[...]) swaps a wide tool schema for one programmable IPython kernel that persists across a session — the model writes Python and calls tools as awaitable handles, composing them (variables, loops, helpers) without round-tripping through the transcript.

FinanceTools: One unified finance toolkit with swappable data providers.

RampRouter model: New model provider for Ramp Router (router.com).

SuperGrok OAuth: Device-code auth for the xAI model.

AtomicMail Toolkit: Adds an AtomicMail toolkit (AtomicMailTools) that gives an Agno agent its own email inbox

Database

Runs get their own table: each run is a row in agno_runs with real columns (session_id, run_type, agent_id, team_id, workflow_id, user_id, parent_run_id, status, run_index) + JSON payload. Takes session write amplification from O(N²) to O(N) and removes the DynamoDB/Firestore item-size ceiling. session.get_messages(), get_chat_history(), db.get_session() and AgentOS session routes are unchanged (runs re-attach on read). (#8350)

Direct run APIs: db.get_run(), db.get_runs(session_id=..., status=..., limit=..., page=...), db.upsert_run(), db.delete_run(), db.delete_runs() (sync + async); db.get_session(runs_limit=N) and db.get_sessions(include_runs=False). (#8350)

One-line migration: MigrationManager(db).up() creates the runs store and copies legacy runs across, non-destructively and idempotently, on 12 sync + 4 async backends; un-migrated DBs still work (reads merge runs table with legacy blob). Schema versions tracked on every adapter. (#8350)

Typed stale-DB errors: MigrationRequiredError / SchemaMismatchError name both remedies; AgentOS carries error_id: "migration_required_error" in the JSON body. (#9669, #9631)

Three new tables: agno_runs, agno_jobs (durable background queue), agno_tool_results (offload index) — all auto-created.

Per-user isolation

Extends beyond sessions to metrics, schedules, evals, knowledge, components, entity memory, and 17 vector databases. Metrics aggregate per user per day; unowned components/knowledge are shared (readable by all, editable by admin) so enabling isolation doesn't 404 pre-isolation building blocks. (#8245, #8262)

AgentOS & Studio

Durable background execution: AgentOS(queue=QueueConfig(durable=True)) — accepted runs are committed rows that survive crashes/restarts/deploys, executed by any replica. Bounded concurrency (default 32, AGNO_BACKGROUND_MAX_CONCURRENCY), cancellable while queued, Idempotency-Key dedupe, 429 on full queue. Queue REST surface (GET /queue/jobs, .../{job_id}, POST .../requeue, GET /queue/stats). Redis is optional coordination, never truth. (#9079, #9504)

Studio 3.0 — governed catalog: create_* writes a DRAFT that serves nobody until publish_component; compare-and-set guards (typed 409s), tombstoned deletes, archive/restore, dependent-tracking. StudioTools returns a machine-readable envelope ({ok, status, data, error{...}, warnings}) across ~31 tools. (#9604)

Tools

MiniMax video generation tools. (#9529)

Toolkits now have a stable id used by AgentOS to reference tools.

Model Updates

Cerebras / CerebrasOpenAI default to gpt-oss-120b (was llama-4-scout-17b-16e-instruct). (#9244)

Gemini defaults updated to 3.7 Flash. (#9666)

Groq: replaced deprecated llama-3.3-70b-versatile with openai/gpt-oss-120b. (#9588)

OpenAI: reasoning_effort, reasoning_summary, service_tier, verbosity accept the full API value set (widened types; no call breaks).

Claude works with anthropic 1.0.0 (#9686): SDK-compat update for Claude models

⚠️ Breaking Changes

Every 2.x user must read this. A database migration is required before v3.0 serves traffic.

Storage & migrations

Runs are no longer a JSON blob in the sessions table — they live in agno_runs. Run MigrationManager(db).up() (or AgentOS POST /databases/all/migrate) before serving. The v2→v3 migration preserves the legacy runs column as a backup; reclaim it with db.cleanup_legacy_runs_column() (SQL) / db.cleanup_legacy_runs_field() (document/KV) after verifying.

Stale/unmigrated databases raise typed errors instead of silently misbehaving.

Pagination: page without a limit (or page < 1) now raises ValueError instead of returning unbounded/negative results.

AgentOS

JWT: secret_key removed from JWTMiddleware and authorization_config — use verification_keys (a list).

Metadata routes: GET /models removed (model data moved to GET /config under available_models); GET / returns a minimal landing response; GET /info is the single unauthenticated metadata endpoint.

MCP server config: AgentOS(enable_mcp_server=..., mcp_config=...) removed — pass a single mcp_server= instead.

Background execution requires a db on the component (returns 400 without one). External-framework agents (LangGraph, Claude, DSPy, etc.) stream inline for background=true and are not resumable.

Agents

Renamed params:

• enable_user_memories → update_memory_on_run
• search_session_history → search_past_sessions
• num_history_sessions → num_past_sessions_to_search
• num_past_session_runs → num_past_session_runs_in_search

reasoning=True removed — set reasoning_model=<native reasoning model> explicitly.

continue_run / acontinue_run: updated_tools removed — pass requirements (list of RunRequirement from the paused run output).

Culture feature removed: enable_agentic_culture, add_culture_to_context, CulturalKnowledge, culture tools, and the agno_culture table. Use Knowledge for shared cross-user info.

Teams & Workflows

The Workflow constructor is keyword-only: Workflow(name=..., steps=[...]). Team is unchanged — Team([agent_1, agent_2]) still works, though Team(members=[...]) is preferred.

Flat HITL kwargs removed on Step/Steps/Loop/Condition/Router (requires_confirmation, confirmation_message, on_reject, requires_user_input, user_input_message, user_input_schema, requires_output_review, output_review_message, requires_iteration_review, iteration_review_message, on_error, hitl_max_retries, hitl_timeout, on_timeout). Use human_review=HumanReview(...) (from agno.workflow.types); names unchanged except hitl_max_retries → max_retries, hitl_timeout → timeout.

Tools

MultiMCPTools deleted (along with allow_partial_failure) — use one MCPTools per server.

MCPToolbox: auth_tokens / auth_headers removed — use auth_token_getters.

DuckDuckGoTools.duckduckgo_search → web_search, duckduckgo_news → search_news (now built on WebSearchTools).

Flat Google tool modules deleted (agno.tools.gmail, googlesheets, googlecalendar, google_maps, google_drive, google_bigquery) — import from agno.tools.google.*.

Google tools: creds_path / auth_port → credentials_path / oauth_port; Sheets enable_read_sheet etc. → bare method names.

FileTools.check_escape → Toolkit._check_path (LocalFileSystemTools.check_escape unaffected).

SQLTools: enable_list_tables / enable_describe_table / enable_run_sql_query → bare method names.

Seltz: max_documents → max_results; the legacy SDK path is removed (seltz>=1.2.0 required).

StudioTool alias removed — use StudioTools.

BrightData.get_screenshot: unused output_path removed. PgVector.enable_prefix_matching removed (dead helper).

Knowledge & Vector DBs

Knowledge.add_content / add_content_async / add_contents_async removed → use insert() / ainsert() / ainsert_many().

GDriveContextProvider renamed → GoogleDriveContextProvider.

LanceDB: use_tantivy removed/ignored.

Searching a pre-v3 vector table with a user_id raises ValueError (directing you to the vector DB migration) instead of returning empty results.

Scheduler

update_schedule is now allow-listed (only name, description, method, endpoint, payload, cron_expr, timezone, timeout_seconds, max_retries, retry_delay_seconds, enabled, next_run_at, disabled_reason); any other key raises ValueError. Ownership/provenance/lock state are no longer writable via the generic path. New provenance columns added by the v3.0.0 migration.

The schedules unique key changes from name to (user_id, name). If duplicate schedule names exist across the same user, the migration aborts — deduplicate before migrating.

Evals

eval_id → run_id (#9739): eval classes no longer carry eval_id; every run gets its own run_id. store_result_in_file renames the eval_id parameter to run_id, the {eval_id} placeholder in file_path_to_save_results templates is no longer accepted (use {run_id}), and POST /eval-runs returns the id the row was actually stored under (run_id). Re-runs no longer overwrite each other.

Models & Learning

Mistral: mistralai v1 compatibility layer removed — agno[mistral] requires mistralai>=2.0.0 (and is back in the models extra).

agno.models.metrics module and the Metrics alias removed → import from agno.metrics (RunMetrics).

Model.classify_error removed → use ModelProviderError.classify(error).

Entity memory under namespace="user" is now isolated per user (row keys embed a user_id digest); pre-v3 rows re-keyed by the v3.0.0 migration (agno.learn.migrations.rekey_user_entity_learnings); EntityMemoryStore.delete/get require a keyword-only user_id in that namespace.

Removed learn aliases: MemoriesConfig → UserMemoryConfig; MemoriesStore → UserMemoryStore; Decision → DecisionLog.

Deprecated (still working)

knowledge_retriever(dependencies=...) → prefer run_context. A retriever whose signature still names dependencies keeps working via an explicit backward-compat branch; run_context wins when both are present.

Scopes: system:read / system:write → config:read / config:write. The old names remain valid aliases and existing tokens keep working.

RedisDB (vector DB) → RedisDb. Note RedisVectorDb is also still exported, to disambiguate from the agno.db.redis storage adapter.

Migration quick-reference

Docs: Step-by-step guide, database migration, and a paste-into-your-coding-agent prompt

import asyncio
from agno.db.migrations.manager import MigrationManager
# Step 1: run before serving v3.0 traffic (up() is async)
asyncio.run(MigrationManager(db).up())
# Step 2: VERIFY the runs landed before any cleanup
assert len(db.get_runs(limit=5)) > 0, "Migration copied nothing - do NOT clean up"
# Step 3 (optional, destructive): reclaim the legacy blob column.
# The migration preserves it as a backup, so force=True is required.
db.cleanup_legacy_runs_column(force=True) # SQL adapters
# db.cleanup_legacy_runs_field(force=True) # document / KV adapters

On AgentOS: POST /databases/all/migrate. Full details in the v3.0 changelog docs.

What's Changed

Update Cerebras defaults and cookbook models by @ryanl-cerebras in #9244
[fix] Repair stale cookbook links by @CRDong233 in #9590
fix: replace the deprecated Groq llama-3.3-70b-versatile with openai/gpt-oss-120b by @sannya-singal in #9588
[cookbook] Add OpenUI client example for AgentOS AG-UI by @vishxrad in #9605
feat: add emem cookbook example by @kumari-jaya in #9624
chore: update gemini defaults to use 3.7 flash by @markmcd in #9666
fix: docs clarify human-readable ID collision guarantees by @daleselaji-dev in #9665
fix: typos in code comments and docstrings by @feizhuzheng in #9597
[cookbook] Align Team HITL examples with cookbook standards by @Math1987 in #9671
cookbook: add emem entry to MCP cookbook README index by @kumari-jaya in #9636
fix: repair four imports that do not resolve in cookbooks by @tonydzi in #9498
feat: add MiniMax video generation tools by @octo-patch in #9529
feat: v3.0 by @kausmeows in #8210
feat: Release v3.0.0 by @kausmeows in #9755

New Contributors

@ryanl-cerebras made their first contribution in #9244
@CRDong233 made their first contribution in #9590
@vishxrad made their first contribution in #9605
@kumari-jaya made their first contribution in #9624
@daleselaji-dev made their first contribution in #9665
@feizhuzheng made their first contribution in #9597
@Math1987 made their first contribution in #9671
@tonydzi made their first contribution in #9498

Full Changelog: v2.9.0...v3.0.0

Original source