docs: add tool simulator example

[ybdarrenwang]

Description

Adds comprehensive documentation and examples for the ToolSimulator framework introduced in strands-agents/evals. Demonstrates realistic multi-turn agent evaluation scenarios with simulated tools.

Key additions:

• Complete smart home example (tool_simulator.py) showcasing all three simulation modes working together with shared state
• Multi-agent workflow demonstration with agent-as-tool pattern using hvac_control_assistant sub-agent
• State inspection utilities showing how to track state changes across tool invocations

Related Issues

strands-agents/evals#93

Type of Change

• New content

Checklist

• I have read the CONTRIBUTING document
• My changes follow the project's documentation style
• I have tested the documentation locally using mkdocs serve
• Links in the documentation are valid and working

---

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

[poshinchen]

After viewing the example on how people initiates and access the simulator, I think we have to make these changes:

1. ToolSimulator._get_instance() -> We should directly allow simulator = ToolSimulator(). But this ends up to a question, does ToolSimulator have to be singleton?

• With this approach we could just do @simulator.function_tool()

2. simulator._state_registry.get_state("room_environment") -> we should directly allow simulator.get_state("room"environment") instead of telling users to access the private state_registry

[strands-agent]

Documentation Deployment Complete

Your documentation preview has been successfully deployed!

Preview URL: https://d3ehv1nix5p99z.cloudfront.net/pr-500/

[ybdarrenwang]

After viewing the example on how people initiates and access the simulator, I think we have to make these changes:

1. ToolSimulator._get_instance() -> We should directly allow simulator = ToolSimulator(). But this ends up to a question, does ToolSimulator have to be singleton?

• With this approach we could just do @simulator.function_tool()

2. simulator._state_registry.get_state("room_environment") -> we should directly allow simulator.get_state("room"environment") instead of telling users to access the private state_registry

These changes are made in the latest revision.

[strands-agent]

Documentation Deployment Complete

Your documentation preview has been successfully deployed!

Preview URL: https://d3ehv1nix5p99z.cloudfront.net/pr-500/

[strands-agent]

Documentation Deployment Complete

Your documentation preview has been successfully deployed!

Preview URL: https://d3ehv1nix5p99z.cloudfront.net/pr-500/

[strands-agent]

Documentation Deployment Complete

Your documentation preview has been successfully deployed!

Preview URL: https://d3ehv1nix5p99z.cloudfront.net/pr-500/