first-class async tools via ctx.update()

[longcw]

Overview

Async tools are now first-class. Any @function_tool can call ctx.update() to stream progress and run in the background — no special type hint needed. AsyncRunContext is now an alias of RunContext, and per-tool duplicate policy / cancellation are explicit flags on @function_tool.

Summary

• AsyncRunContext is now a module-level alias of RunContext. Tools typed ctx: AsyncRunContext keep working unchanged.
• Per-tool flags replace type-hint-driven dispatch: @function_tool(on_duplicate="allow|reject|replace|confirm", allow_cancellation=False).
• Every tool routes through _ToolExecutor (voice/tool_executor.py). The default executor is owned by AgentActivity. Each AsyncToolset owns its own executor scoped to that toolset — when placed under AgentSession(tools=[...]) its in-flight tools and deferred replies survive agent handoff; under Agent(tools=[...]) they're bound to that agent.
• cancel_task / get_running_tasks companion tools are auto-exposed by AgentActivity.tools whenever any registered tool declares allow_cancellation=True (always-on, so the LLM-visible schema stays stable across turns and the prompt cache stays warm).
• AsyncToolPrompts template fields accept either a str.format() template or a callable receiving typed UpdatePromptArgs / DuplicatePromptArgs / ReplyPromptArgs. Resolved via AgentSession → Agent → AsyncToolset (most specific wins).

Deprecations

• AsyncToolset(on_duplicate_call=...) logs a warning at construction and is applied as a fallback override onto contained tools' on_duplicate. Prefer the per-tool @function_tool(on_duplicate=...) flag.

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.

[theomonnom]

Since AsyncToolset was in beta, I think we can safely remove AsyncRunContext?

[longcw]

maybe log a deprecation warning and notify them to use RunContext directly when it's used

[theomonnom]

Should we cancel the asyncio.Task? Or just mark the SpeechHandle as cancelled/interrupted?

My main concern is that most users don’t really understand asyncio cancellation logic. If we can hide that complexity from users, that would be great. (e.g not having to worry about all your method to be cancellation-safe)

[longcw]

we have allow_cancellation default with False, I think user should be aware of it if they enable it specifically. it could be useful to stop or revert some write operations like updating the db or ordering something, etc...

[theomonnom]

But should the user catch asyncio.CancelledErrorvs having something like if speech_handle.cancelled: ...?

[longcw]

perhaps something like ctx.wait_if_not_cancelled and ctx.cancelled since the speech handle is done after the first update. we have something similar using speech_handle.wait_if_not_interrupted in

agents/examples/voice_agents/long_running_function.py

Lines 44 to 51 in e3e992f

	wait_for_result = asyncio.ensure_future(self._a_long_running_task(query))
	await run_ctx.speech_handle.wait_if_not_interrupted([wait_for_result])
	if run_ctx.speech_handle.interrupted:
	logger.info(f"Interrupted searching the web for {query}")
	# return None to skip the tool reply
	wait_for_result.cancel()
	return None

[theomonnom]

🙌

[devin-ai-integration]

Devin Review found 1 new potential issue.

View 23 additional findings in Devin Review.

[devin-ai-integration]

🟡 _execute_tool logs ToolError and StopResponse with full traceback via logger.exception

In the new _ToolExecutor._execute_tool, all exceptions (including expected ToolError and signal-like StopResponse) are caught by the generic except Exception handler and logged with logger.exception, which emits a full traceback. These exceptions then propagate through first_update_fut to the caller in generation.py:658-674, where ToolError is properly handled as a warning and StopResponse is silently consumed. This results in expected errors being double-logged — once with a noisy full traceback in the executor and once properly in the caller.

In the old code, ToolError from prepare_function_arguments was caught directly in _execute_tools_task and handled at the appropriate log level. Now it flows through the executor's generic handler first. This is particularly noisy in production since ToolError is common (LLM sends bad arguments) and StopResponse is a deliberate signal, not an error at all.

Suggested change

	except Exception as e:
	output = e
	logger.exception(
	"error in tool execution",
	extra={"call_id": call_id, "function": fnc_name},
	except Exception as e:
	output = e
	if not isinstance(e, (ToolError, StopResponse)):
	logger.exception(
	"error in tool execution",
	extra={"call_id": call_id, "function": fnc_name},
	)

---

Was this helpful? React with 👍 or 👎 to provide feedback.