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]

We MUST handle interrupts!