feat: add programmatic tool caller

[mkmeral]

Description

Adds programmatic_tool_caller tool that enables code-based tool invocation. Agents can write Python code that calls other tools as async functions, reducing API round-trips and enabling complex orchestration patterns like loops, parallel execution, and chaining.

Note: Does not work on Windows.

Key Features

• Async-first design: Tools exposed as await tool_name(...) - code runs in async context automatically
• Only print() output returned: Tool results stay in code execution context, don't enter agent's context window unless explicitly printed
• Pluggable executor: Custom Executor implementations for sandboxed environments (Docker, Lambda, etc.)
• Security controls: Code validation for dangerous patterns, user confirmation (bypassable via BYPASS_TOOL_CONSENT), configurable allowed tools

Example Usage

from strands import Agent
from strands_tools import programmatic_tool_caller, calculator

agent = Agent(tools=[programmatic_tool_caller, calculator])

result = agent.tool.programmatic_tool_caller(
    code="""
# Simple tool call
result = await calculator(expression="2 + 2")
print(f"Result: {result}")

# Loop with tool calls
total = 0
for i in range(1, 6):
    square = await calculator(expression=f"{i} ** 2")
    total += int(square)
print(f"Sum of squares: {total}")

# Parallel execution
results = await asyncio.gather(
    calculator(expression="10 * 1"),
    calculator(expression="10 * 2"),
    calculator(expression="10 * 3"),
)
print(f"Parallel results: {results}")
"""
)

Environment Variables

Variable	Description
BYPASS_TOOL_CONSENT	Skip user confirmation if "true"
PROGRAMMATIC_TOOL_CALLER_ALLOWED_TOOLS	Comma-separated list of tools to expose (default: all except self)

Custom Executors

from strands_tools.programmatic_tool_caller import programmatic_tool_caller, Executor

class DockerExecutor(Executor):
    def execute(self, code: str, namespace: dict) -> str:
        # Run in sandboxed container
        ...

programmatic_tool_caller.executor = DockerExecutor()

Related Issues

• [FEATURE] Code-Based Tool Execution similar to smolagents sdk-python#1540
• [FEATURE] Support for Anthropic advanced tool use sdk-python#1349

Type of Change

New Tool

Testing

• Unit tests for executor, tool execution, validation, and allowed tools filtering
• Integration tests with real Agent and tools
• Tests cover async execution, loops, asyncio.gather, custom executors, user cancellation

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 (README.md)
• I have added an appropriate example to the documentation to outline the feature
• My changes generate no new warnings

[mkmeral]

Interrupt limitation with programmatic tool calls

Tools that use interrupts (human-in-the-loop) will raise a RuntimeError when invoked through the programmatic tool caller. The SDK's _ToolCaller has two guards:

• If an interrupt is already active when a direct tool call is made → RuntimeError("cannot directly call tool during interrupt")
• If a tool raises an interrupt during a direct call → RuntimeError("cannot raise interrupt in direct tool call")

This is a known SDK limitation — direct/programmatic tool calls have no mechanism to pause execution, collect human input, and resume. The error surfaces as a failed tool result back to the agent, so the agent can reason about it and try an alternative approach.

[agent-of-mkmeral]

🔴 Adversarial Testing Result: FAIL — 3 issues found

Scope: Full adversarial testing of programmatic_tool_caller — input boundaries, stdout/stderr restoration, async execution, namespace security, tool execution error paths, env var handling, contract verification, BaseException handling, indentation/wrapping, and concurrency.

Tests written: 47
Tests passing: 47 (all findings confirmed with reproducible artifacts)
Tests failing (findings): 3 bugs found and proven

Findings Summary

#	Category	Severity	Description
1	Bug	Critical	SystemExit and KeyboardInterrupt escape the tool — sys.exit() in user code kills the host process
2	Bug	Medium	Empty code and comment-only code cause SyntaxError due to async wrapping producing empty function body
3	Bug	Medium	Tool named asyncio shadows the required asyncio module in namespace, breaking all async functionality

---

Finding 1 — BaseException Escape (Critical)

Category: Bug
Severity: Critical

Reproduction:

# This kills the host process:
result = programmatic_tool_caller(code="import sys; sys.exit(42)", tool_context=ctx)
# ^^^ SystemExit propagates past except Exception — host dies

# This also escapes:
result = programmatic_tool_caller(code="raise KeyboardInterrupt()", tool_context=ctx)
# ^^^ KeyboardInterrupt propagates to caller

Root cause: The exception handlers are:

except SyntaxError:
    ...
except Exception:
    ...

SystemExit and KeyboardInterrupt inherit from BaseException, NOT Exception. They bypass both catch blocks.

Observed behavior: SystemExit propagates up the call stack, killing the host process. KeyboardInterrupt similarly escapes.

Expected behavior: User code should never be able to kill the host. The tool should catch these and return an error dict.

Fix:

except SyntaxError:
    ...
except (SystemExit, KeyboardInterrupt) as e:
    error_msg = f"Execution error: {type(e).__name__}: {e}"
    console.print(Panel(error_msg, title="[bold red]Error[/]", border_style="red"))
    return {"status": "error", "content": [{"text": error_msg}]}
except Exception:
    ...

Artifact: TestFinding2_BaseExceptionEscape::test_system_exit_escapes_tool, test_keyboard_interrupt_escapes_tool

---

Finding 2 — Empty/Comment-Only Code SyntaxError (Medium)

Category: Unhandled Edge Case
Severity: Medium

Reproduction:

# Empty code → SyntaxError
result = programmatic_tool_caller(code="", tool_context=ctx)
# Returns: {"status": "error", "content": [{"text": "Syntax error: expected an indented block..."}]}

# Comment-only code → SyntaxError  
result = programmatic_tool_caller(code="# just a comment", tool_context=ctx)
# Same SyntaxError

Root cause: The async wrapping does:

indented_code = textwrap.indent(code, "    ")
wrapped_code = f"async def __user_code__():\n{indented_code}\n"

Empty code → async def __user_code__():\n\n → empty function body = SyntaxError.
Comment-only → async def __user_code__():\n # comment\n → comments aren't statements = SyntaxError.

Expected behavior: Empty/comment-only code should succeed with (no output), same as passing x = 42.

Fix: Add pass if code strip is empty or comments-only:

if not code.strip() or all(line.strip().startswith('#') for line in code.strip().splitlines()):
    indented_code = "    pass"
else:
    indented_code = textwrap.indent(code, "    ")

Artifact: TestFinding1_EmptyCodeWrapping::test_empty_code_string_fails, test_comment_only_code_fails

---

Finding 3 — asyncio Module Shadowing (Medium)

Category: Bug
Severity: Medium

Reproduction:

# If a tool named 'asyncio' exists in the registry:
ns = _build_namespace({"asyncio"}, agent)
assert ns["asyncio"] is not asyncio_module  # True! It's now a tool wrapper
# asyncio.gather(), asyncio.sleep() etc. are now broken

Root cause: In _build_namespace(), asyncio module is injected first, then tools overwrite by name:

namespace["asyncio"] = asyncio  # ← injected
for tool_name in available_tools:
    namespace[tool_name] = _create_async_tool_function(...)  # ← overwrites 'asyncio'

Expected behavior: Reserved names (asyncio, __name__, extra modules) should not be overwritable by tool names.

Fix: Either exclude reserved names from tool injection, or inject tools first and modules after:

# Option A: Exclude reserved names
RESERVED = {"asyncio", "__name__"}
for tool_name in available_tools - RESERVED:
    namespace[tool_name] = ...

# Option B: Inject tools first, then required modules (modules win)
for tool_name in available_tools:
    namespace[tool_name] = ...
namespace["asyncio"] = asyncio  # Overwrite any tool shadowing

Artifact: TestFinding3_AsyncioShadowing::test_asyncio_tool_overwrites_module

---

What Survived

41 adversarial tests passed without finding issues:

• ✅ stdout/stderr properly restored after RuntimeError, SyntaxError, and user-replaced stdout
• ✅ Unicode, null bytes, large output all handled correctly
• ✅ Async code with user-defined coroutines, asyncio.sleep, asyncio.gather all work
• ✅ Tool errors properly propagate to user code via try/except
• ✅ asyncio.gather with 20 concurrent calls completes correctly
• ✅ Sequential tool calls in loops work correctly
• ✅ Namespace isolation: agent object not leaked, __name__ properly set
• ✅ Self-exclusion: programmatic_tool_caller never available in namespace
• ✅ Return format consistent (always {"status": ..., "content": [{"text": ...}]})
• ✅ Env var edge cases (extra commas, whitespace, empty strings) handled correctly
• ✅ Complex code structures (decorators, classes, nested indentation) work through async wrapping

---

🤖 AI agent response. Strands Agents. Feedback welcome!