[NEW CONTENT] Limit agent execution in productoin

[Unshure]

Proposed Content

We should include information that some kind of limit should be applied to agents when deployed in production. This could be a timeout, token, or agent loop limit for agents.

Location

https://strandsagents.com/latest/documentation/docs/user-guide/deploy/operating-agents-in-production/

Rationale

Give instruction that agents should have clear execution boundaries, and should not be able to run forever.

Content Outline (Optional)

No response

References

related: #189

---

Implementation Requirements

Based on repository analysis and clarification discussion, this task involves adding documentation about execution limits to the production guide.

Target File

docs/user-guide/deploy/operating-agents-in-production.md

Placement

Integrate into the existing "Performance Optimization" section as a new subsection covering execution limits and safety boundaries.

Content to Add

Execution Limits Subsection

Add conceptual guidance covering the following limit types:

1. Agent Loop Iteration Limits

   • Limiting the maximum number of LLM calls per agent invocation
   • Reference: Hook-based approach using BeforeModelCallEvent / AfterModelCallEvent

2. Tool Invocation Limits

   • Limiting how many times tools can be called
   • Reference: Existing LimitToolCounts hook example in Hooks - Cookbook

3. Token Consumption Budgets

   • Model-level max_tokens configuration for response limits
   • Reference: Agent Loop - Stop Reasons

4. Execution Timeouts

   • Wall-clock time limits for agent invocations
   • Hook-based or external wrapper approaches

Multi-Agent Safety Mechanisms Reference

Include a subsection referencing built-in safety mechanisms for multi-agent patterns:

• Swarm: max_handoffs, max_iterations, execution_timeout, node_timeout
  • Reference: Swarm - Safety Mechanisms
• Graph: set_max_node_executions(), set_execution_timeout(), set_node_timeout()
  • Reference: Graph - GraphBuilder

Code Examples

• Conceptual guidance only - point to existing hook examples rather than creating new code
• Include Python examples with TypeScript equivalents where the feature is available
• Use {{ ts_not_supported_code() }} macro for features not yet available in TypeScript

Documentation Style

• Follow existing documentation patterns in operating-agents-in-production.md
• Use cross-references to existing documentation sections
• Include rationale for why execution limits are important (cost control, preventing infinite loops, resource management)

Files to Modify

• docs/user-guide/deploy/operating-agents-in-production.md - Add execution limits subsection

Acceptance Criteria

• New "Execution Limits" subsection added under "Performance Optimization"
• All four limit types covered with conceptual guidance
• Cross-references to existing hook documentation (hooks.md)
• Cross-references to multi-agent safety mechanisms (swarm.md, graph.md)
• Python examples included
• TypeScript equivalents included where available (or macro used for unavailable features)
• Documentation builds successfully (mkdocs build)
• TypeScript validation passes (npm run test)

Related Issues

• Issue [DOCS] Limit maximum number of LLM calls in the agent loop #189 covers hooks-specific documentation for limiting LLM calls (separate concern, not duplicated here)

Notes for Implementation

• The existing LimitToolCounts hook in hooks.md provides a good pattern to reference
• Multi-agent patterns (Swarm/Graph) have built-in limits that should be highlighted as best practices
• Consider adding a brief note about monitoring token usage (ties into existing "Monitoring and Observability" section)

[Unshure]

/strands

[github-actions]

Repository Analysis & Clarifying Questions

I've analyzed the repository structure and existing documentation patterns. Here's what I found and some questions to ensure proper implementation:

Repository Context

Target File: docs/user-guide/deploy/operating-agents-in-production.md

This file currently covers model configuration, tool management, security considerations, conversation management, streaming, error handling, deployment patterns, and monitoring. It does not currently address execution limits.

Existing Execution Limit Patterns Found

I discovered several existing patterns for limiting agent execution in the codebase:

1. Hook-based Limits (hooks.md - Cookbook section):

   • LimitToolCounts hook example: Limits per-tool invocation counts
   • Works via BeforeToolCallEvent to cancel tools after threshold

2. Multi-Agent Swarm Limits (swarm.md):

   • max_handoffs, max_iterations, execution_timeout, node_timeout
   • Safety mechanisms for preventing infinite loops

3. Multi-Agent Graph Limits (graph.md):

   • set_max_node_executions(), set_execution_timeout(), set_node_timeout()

4. Community Provider Patterns (sglang.md):

   • ToolIterationLimiter hook for limiting tool iterations

5. Agent Loop Stop Reasons (agent-loop.md):

   • Model-level max_tokens for response truncation

Related Issue

Issue #189 also requests documentation on limiting maximum LLM calls in the agent loop, specifically targeting the hooks section. These issues appear closely related.

---

Clarifying Questions

1. Scope of Coverage

Should this documentation cover:

• a) Single-agent execution limits only?
• b) Reference multi-agent patterns (Swarm/Graph safety mechanisms) as well?
• c) Both with clear separation?

2. Relationship to Issue #189

Issue #189 asks for documentation on limiting LLM calls specifically in the hooks section. Should:

• a) These issues be combined into one task?
• b) This issue focus on production guidance while [DOCS] Limit maximum number of LLM calls in the agent loop #189 focuses on hooks documentation?
• c) This issue address both concerns?

3. Implementation Examples

Should the documentation include:

• a) Conceptual guidance only (pointing to existing hook examples)?
• b) New code examples showing timeout/limit implementations?
• c) Both conceptual guidance and code examples?

4. TypeScript Coverage

The repository supports both Python and TypeScript. Should the examples:

• a) Be Python only (noting TypeScript feature availability)?
• b) Include TypeScript equivalents where available?

5. Specific Limit Types

Which limit types should be covered?

• Agent loop iteration limits (max LLM calls per invocation)
• Token consumption budgets (total tokens per invocation)
• Execution timeouts (wall-clock time limits)
• Tool invocation limits (max tool calls)
• All of the above?

6. Placement in Document

Should this be:

• a) A new top-level section in operating-agents-in-production.md?
• b) Integrated into the existing "Performance Optimization" section?
• c) A completely new page linked from the production guide?

[Unshure]

/strands

1. both
2. b
3. a
4. b
5. all of the above
6. b

[Unshure]

/strands implement

[github-actions]

Unable to create pull request via API. You can create it manually by clicking here.