# Breaking changes in v3.0

> The condensed reference for every 2.x user upgrading to v3.0, covering storage, AgentOS, agents, teams and workflows, tools, knowledge, the scheduler, evals and models. The database migration is mandatory.

- Published: 2026-08-24
- Author: Kaustubh Shukla
- Categories: Changelog
- Canonical: https://www.agno.com/articles/breaking-changes-in-v3-0
- Markdown: https://www.agno.com/articles/breaking-changes-in-v3-0.md

Every 2.x user needs to read this before upgrading, and the database migration is mandatory. This is the condensed reference; the [v3.0 changelog](https://docs.agno.com/other/v3-changelog) has the complete list and the [migration guide](https://docs.agno.com/other/v3-migration) has step-by-step instructions.

### Storage

- Runs moved out of the sessions table into `agno_runs`. Run the migration before serving traffic.
- `page` without a `limit`, or `page < 1`, now raises `ValueError` instead of returning unbounded results.

### AgentOS

- `JWTMiddleware` and `authorization_config` dropped `secret_key` in favor of `verification_keys` (a list).
- `GET /models` is removed; model data now lives in `GET /config` under `available_models`, and `GET /info` is the single unauthenticated metadata endpoint.
- `enable_mcp_server` and `mcp_config` collapsed into a single `mcp_server=`.
- Background execution now requires a `db` on the component and returns a 400 without one.

### 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` is removed; set `reasoning_model=` explicitly.
- `continue_run` dropped `updated_tools` in favor of `requirements`.
- The Culture feature is removed entirely; use Knowledge for shared cross-user info.

### Teams and Workflows

- The `Workflow` constructor is keyword-only: `Workflow(name=..., steps=[...])`.
- Flat HITL kwargs on Step, Steps, Loop, Condition, and Router are removed. Use `human_review=HumanReview(...)` from `agno.workflow.types`, where `hitl_max_retries` → `max_retries` and `hitl_timeout` → `timeout`.

### Tools

- `MultiMCPTools` is deleted; use one `MCPTools` per server.
- Flat Google tool modules (`agno.tools.gmail`, `agno.tools.googlesheets`, and the rest) are removed; import from `agno.tools.google.*`.
- `DuckDuckGoTools.duckduckgo_search` → `web_search`, and `duckduckgo_news` → `search_news`.
- `SQLTools` and Google Sheets read, describe, and run flags became bare method names.
- The `StudioTool` alias is removed; use `StudioTools`.

### Knowledge and vector DBs

- `Knowledge.add_content` and its variants → `insert()`, `ainsert()`, and `ainsert_many()`.
- `GDriveContextProvider` → `GoogleDriveContextProvider`.
- Searching a pre-v3 vector table with a `user_id` now raises `ValueError` pointing at the vector-DB migration.

### Scheduler

- `update_schedule` is now allow-listed and rejects unknown keys with `ValueError`; ownership and lock state can no longer be written through it.
- The schedules unique key changes from `name` to `(user_id, name)`. Deduplicate schedule names per user before migrating, or the migration aborts.

### Evals

- `eval_id` → `run_id` throughout. The `{eval_id}` placeholder in result-path templates is no longer accepted (use `{run_id}`), and re-runs no longer overwrite each other.

### Models and learning

- Mistral requires `mistralai>=2.0.0`; the v1 compat layer is removed.
- `agno.models.metrics` and the `Metrics` alias moved to `agno.metrics` (`RunMetrics`).
- `Model.classify_error` → `ModelProviderError.classify(error)`.
- Entity memory under `namespace="user"` is now per-user isolated and re-keyed by the migration.

### Deprecated but still working

- `knowledge_retriever(dependencies=...)` → prefer `run_context`.
- Scopes `system:read` and `system:write` → `config:read` and `config:write`; the old names still work.
- `RedisDB` (vector) → `RedisDb`.