v3.0.0

⚠️ **Breaking release.** A database migration is required before v3.0 serves traffic. Read the **[v3 Migration Guide](https://docs.agno.com/other/v3-migration)** first, and see the full **[v3.0 Changelog](https://docs.agno.com/other/v3-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](https://github.com/agno-agi/agno/pull/9436)**, **[#9684](https://github.com/agno-agi/agno/pull/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](https://github.com/agno-agi/agno/pull/9340)**) [Docs](https://docs.agno.com/sessions/persisting-sessions/media-storage/overview)
- **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](http://router.com/)).
- **SuperGrok OAuth**: Device-code auth for the xAI model.

### **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](https://github.com/agno-agi/agno/pull/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](https://github.com/agno-agi/agno/pull/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](https://github.com/agno-agi/agno/pull/8350)**)
    - **Typed stale-DB errors**: `MigrationRequiredError` / `SchemaMismatchError` name both remedies; AgentOS carries `error_id: "migration_required_error"` in the JSON body. (**[#9669](https://github.com/agno-agi/agno/pull/9669)**, **[#9631](https://github.com/agno-agi/agno/pull/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](https://github.com/agno-agi/agno/pull/8245)**, **[#8262](https://github.com/agno-agi/agno/pull/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](https://github.com/agno-agi/agno/pull/9079)**, **[#9504](https://github.com/agno-agi/agno/pull/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](https://github.com/agno-agi/agno/pull/9604)**)

### **Tools**

- **MiniMax video generation tools**. (**[#9529](https://github.com/agno-agi/agno/pull/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](https://github.com/agno-agi/agno/pull/9244)**)
- **Gemini** defaults updated to 3.7 Flash. (**[#9666](https://github.com/agno-agi/agno/pull/9666)**)
- **Groq**: replaced deprecated `llama-3.3-70b-versatile` with `openai/gpt-oss-120b`. (**[#9588](https://github.com/agno-agi/agno/pull/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](https://github.com/agno-agi/agno/pull/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`.
- **`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](https://docs.agno.com/other/v3-migration): Step-by-step guide, database migration, and a paste-into-your-coding-agent prompt

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

## New Contributors
* @ryanl-cerebras made their first contribution in https://github.com/agno-agi/agno/pull/9244
* @CRDong233 made their first contribution in https://github.com/agno-agi/agno/pull/9590
* @vishxrad made their first contribution in https://github.com/agno-agi/agno/pull/9605
* @kumari-jaya made their first contribution in https://github.com/agno-agi/agno/pull/9624
* @daleselaji-dev made their first contribution in https://github.com/agno-agi/agno/pull/9665
* @feizhuzheng made their first contribution in https://github.com/agno-agi/agno/pull/9597
* @Math1987 made their first contribution in https://github.com/agno-agi/agno/pull/9671
* @tonydzi made their first contribution in https://github.com/agno-agi/agno/pull/9498

**Full Changelog**: https://github.com/agno-agi/agno/compare/v2.9.0...v3.0.0