v3.0.2

# 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)