tool executors #658

pgrayy · 2025-08-11T22:02:06Z

Description

Allow users to decide whether tools should run concurrently or sequentially.
- Currently, we execute all tools concurrently.
- Sequential execution can however be useful (e.g., user wants agent to first use browser tool to navigate to a website and then snapshot tool to take a picture).

For more details, please see comments in file diff.

Usage

Sequential

from strands import Agent
from strands.tools.executors import SequentialToolExecutor

agent = Agent(tool_executor=SequentialToolExecutor(), tools=[screenshot_tool, email_tool])
agent("Please take a screenshot and then email the screenshot to my friend")

Assuming the model returns screenshot_tool and email_tool use requests, the SequentialToolExecutor will execute both sequentially in the order given.

Concurrent

from strands import Agent
from strands.tools.executors import ConcurrentToolExecutor

agent = Agent(tool_executor=ConcurrentToolExecutor(), tools=[weather_tool, time_tool])
agent("What is the weather and time in New York?")

Assuming the model returns weather_tool and time_tool use requests, the ConcurrentToolExecutor will execute both concurrently. Note, this is the default executor and so Agent(tools=[weather_tool, time_tool]) will result in the same behavior.

Related Issues

#614

Documentation PR

Will follow up

Type of Change

New feature

Testing

How have you tested the change? Verify that the changes do not break functionality or introduce warnings in consuming repositories: agents-docs, agents-tools, agents-cli

I ran hatch run prepare: Wrote new unit and integration tests

Checklist

I have read the CONTRIBUTING document
I have added any necessary tests that prove my fix is effective or my feature works
I have updated the documentation accordingly
I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
My changes generate no new warnings
Any dependent changes have been merged and published

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

Follow Up

Will document the following items in an issue tracker after PR approval:

Add tool executors page to our docs.
Simplify/reorganize the before and after tool execution logic.
- Currently, the base Executor class implements _stream and _stream_with_trace methods to wrap the tool execution with additional logic that includes tracing, hooks, exception handling, etc. It is a bit cumbersome and would maybe make more sense to be placed in the AgentTool implementations.
Finalize the execute method interface.
- We should be able to remove tool_results. execute could instead work as a generator that yields results upon completion that the caller (inside event_loop.py) collects. For this to work however, we require strongly typed events.
- See if we can remove invocation_state as this parameter is on a deprecation path.
Expose Executor as a public interface after clean up.
Accept custom thread pools for sync tool execution.

src/strands/agent/agent.py

pgrayy · 2025-08-11T22:11:36Z

src/strands/event_loop/event_loop.py

@@ -306,122 +304,6 @@ async def recurse_event_loop(agent: "Agent", invocation_state: dict[str, Any]) -
    recursive_trace.end()


-async def run_tool(agent: "Agent", tool_use: ToolUse, invocation_state: dict[str, Any]) -> ToolGenerator:


Moved logic into strands.executors._executor.Executor._stream

src/strands/experimental/tools/executors/executor.py

src/strands/tools/executors/concurrent.py

src/strands/tools/validator.py

src/strands/tools/decorator.py

src/strands/experimental/tools/executors/executor.py

src/strands/agent/agent.py

pgrayy · 2025-08-12T16:23:16Z

src/strands/agent/agent.py


                async def acall() -> ToolResult:
-                    # Pass kwargs as invocation_state
-                    async for event in run_tool(self._agent, tool_use, kwargs):


Moved run_tool logic into new ToolExecutor._stream method.

pgrayy · 2025-08-12T16:24:07Z

src/strands/experimental/tools/executors/executor.py

+        return wrapper
+
+    @_trace
+    async def stream(


Logic copied from the now removed run_tool method in event_loop.py.

src/strands/experimental/tools/executors/executor.py

src/strands/tools/executors/concurrent.py

src/strands/agent/agent.py

src/strands/event_loop/event_loop.py

src/strands/experimental/tools/executors/executor.py

src/strands/tools/decorator.py

src/strands/experimental/tools/executors/__init__.py

src/strands/tools/executors/sequential.py

src/strands/tools/executors/concurrent.py

src/strands/experimental/tools/executors/executor.py

dbschmigelski · 2025-08-13T14:19:04Z

src/strands/event_loop/event_loop.py


+    validate_and_prepare_tools(message, tool_uses, tool_results, invalid_tool_use_ids)
+    tool_uses = [tool_use for tool_use in tool_uses if tool_use.get("toolUseId") not in invalid_tool_use_ids]


optional nit: any reason this needs to be modified in place? I know we do it in the code base but I find it harder to follow

We could follow up on this (and a lot of code in this PR). For now though, I figured I would just try to copy and paste as much as possible rather than fully alter the existing logic to simplify the PR. In other words, this PR more so focuses on code organization and placement rather than the logic.

src/strands/experimental/tools/executors/executor.py

src/strands/tools/validator.py

src/strands/agent/agent.py

…nto tool-execution

pgrayy · 2025-08-20T13:36:16Z

src/strands/agent/agent.py

@@ -35,6 +35,8 @@
 from ..session.session_manager import SessionManager
 from ..telemetry.metrics import EventLoopMetrics
 from ..telemetry.tracer import get_tracer, serialize
+from ..tools.executors import ConcurrentToolExecutor
+from ..tools.executors._executor import Executor as ToolExecutor


Per discussion, indicating that the base Executor class is private rather than experimental to discourage any use.

src/strands/agent/agent.py

pgrayy · 2025-08-20T13:40:30Z

src/strands/agent/agent.py


                async def acall() -> ToolResult:
-                    # Pass kwargs as invocation_state
-                    async for event in run_tool(self._agent, tool_use, kwargs):
+                    async for event in ToolExecutor._stream(self._agent, tool_use, tool_results, invocation_state):


Per discussion, member methods of the executor classes are also marked private to discourage customer use. We want to first cement the interface before exposing.

src/strands/tools/decorator.py

pgrayy · 2025-08-20T13:43:39Z

src/strands/tools/executors/_executor.py

+    """Abstract base class for tool executors."""
+
+    @staticmethod
+    async def _stream(


Logic is copy and pasted from run_tool in event_loop.py.

pgrayy · 2025-08-20T13:45:00Z

src/strands/tools/executors/_executor.py

+            tool_results.append(after_event.result)
+
+    @staticmethod
+    async def _stream_with_trace(


Previously I tried setting this up as a decorator. For more clarity, I went ahead and made it a separate method. Note, this logic is copied from tools/executor.py which is removed in this PR.

zastrowm · 2025-08-20T21:45:00Z

src/strands/agent/agent.py

Can you update the PR with:

The new public APIs being exposed

Expected way that the customer would use the new apis?

Also add a section about the expected follow-ups that are decided on - if this is a stepping stone to the long-term solution

Added "Usage" and "Follow Up" sections to the overview.

src/strands/agent/agent.py

src/strands/tools/decorator.py

src/strands/tools/executors/_executor.py

src/strands/tools/executors/concurrent.py

tests/strands/tools/executors/conftest.py

…nto tool-execution

pgrayy had a problem deploying to auto-approve August 11, 2025 22:02 — with GitHub Actions Failure

pgrayy mentioned this pull request Aug 11, 2025

[FEATURE] Add ability to disable parallel tool calling #614

Open

pgrayy had a problem deploying to auto-approve August 11, 2025 22:06 — with GitHub Actions Failure

pgrayy temporarily deployed to auto-approve August 11, 2025 22:11 — with GitHub Actions Inactive

tool executors

97a062e

pgrayy commented Aug 11, 2025

View reviewed changes

pgrayy force-pushed the tool-execution branch from 218de83 to 97a062e Compare August 11, 2025 22:23

pgrayy marked this pull request as ready for review August 11, 2025 22:24

pgrayy temporarily deployed to auto-approve August 11, 2025 22:24 — with GitHub Actions Inactive

pgrayy commented Aug 11, 2025

View reviewed changes

src/strands/experimental/tools/executors/executor.py Outdated Show resolved Hide resolved

tool executors - override type decorator

8a86a29

pgrayy temporarily deployed to auto-approve August 11, 2025 22:34 — with GitHub Actions Inactive

pgrayy commented Aug 12, 2025

View reviewed changes

src/strands/agent/agent.py Outdated Show resolved Hide resolved

executor - skip tracing member variable

45198c3

pgrayy temporarily deployed to auto-approve August 12, 2025 16:01 — with GitHub Actions Inactive

executors - pass tool results separately

c95154f

pgrayy temporarily deployed to auto-approve August 12, 2025 16:22 — with GitHub Actions Inactive

pgrayy commented Aug 12, 2025

View reviewed changes

src/strands/experimental/tools/executors/executor.py Outdated Show resolved Hide resolved

zastrowm requested changes Aug 13, 2025

View reviewed changes

dbschmigelski reviewed Aug 13, 2025

View reviewed changes

Merge branch 'main' of https://github.com/strands-agents/sdk-python i…

01327c2

…nto tool-execution

pgrayy marked this pull request as draft August 19, 2025 18:53

address feedback

7cc16e6

pgrayy temporarily deployed to auto-approve August 20, 2025 13:35 — with GitHub Actions Inactive

pgrayy commented Aug 20, 2025

View reviewed changes

src/strands/agent/agent.py Show resolved Hide resolved

pgrayy commented Aug 20, 2025

View reviewed changes

src/strands/tools/decorator.py Outdated Show resolved Hide resolved

pgrayy commented Aug 20, 2025

View reviewed changes

make tools validator private

4398086

pgrayy temporarily deployed to auto-approve August 20, 2025 13:50 — with GitHub Actions Inactive

pgrayy added 2 commits August 20, 2025 09:56

python agent tool - custom thread pool

b3249cc

python agent tool - pass thread pool

72e4238

pgrayy had a problem deploying to auto-approve August 20, 2025 14:44 — with GitHub Actions Failure

pgrayy temporarily deployed to auto-approve August 20, 2025 14:53 — with GitHub Actions Inactive

pgrayy marked this pull request as ready for review August 20, 2025 14:58

dbschmigelski requested review from dbschmigelski and zastrowm August 20, 2025 15:09

zastrowm requested changes Aug 20, 2025

View reviewed changes

executor - init - thread_pool - literal asyncio

946035c

pgrayy had a problem deploying to auto-approve August 21, 2025 14:20 — with GitHub Actions Failure

remove sa prefix

5740118

pgrayy temporarily deployed to auto-approve August 21, 2025 14:33 — with GitHub Actions Inactive

remove thread pool customization

56b51de

pgrayy temporarily deployed to auto-approve August 22, 2025 21:35 — with GitHub Actions Inactive

Merge branch 'main' of https://github.com/strands-agents/sdk-python i…

43af1ae

…nto tool-execution

pgrayy deployed to auto-approve August 22, 2025 21:50 — with GitHub Actions Active

pgrayy requested a review from zastrowm August 22, 2025 21:55

		@@ -306,122 +304,6 @@ async def recurse_event_loop(agent: "Agent", invocation_state: dict[str, Any]) -
		recursive_trace.end()


		async def run_tool(agent: "Agent", tool_use: ToolUse, invocation_state: dict[str, Any]) -> ToolGenerator:


		validate_and_prepare_tools(message, tool_uses, tool_results, invalid_tool_use_ids)
		tool_uses = [tool_use for tool_use in tool_uses if tool_use.get("toolUseId") not in invalid_tool_use_ids]

tool executors #658

Are you sure you want to change the base?

tool executors #658

Uh oh!

Conversation

pgrayy commented Aug 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Usage

Sequential

Concurrent

Related Issues

Documentation PR

Type of Change

Testing

Checklist

Follow Up

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

pgrayy Aug 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

pgrayy Aug 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

pgrayy commented Aug 11, 2025 •

edited

Loading

pgrayy Aug 11, 2025 •

edited

Loading

pgrayy Aug 12, 2025 •

edited

Loading