strands-agents

name	strands-agents
description	Activate when the user chooses Strands or asks about Strands SDK concepts

Strands Agents SDK Guide

Comprehensive reference for building, enhancing, and deploying football agents with the Strands Agents SDK.

Sample Agent File Structure

sample-agent-strands/
├── src/main.py              # Main agent with Strands SDK
├── test_local.py            # Local testing
├── requirements.txt         # strands-agents dependency
└── .bedrock_agentcore.yaml  # AgentCore config

What the sample does:

1. Creates a Strands Agent with Agent(model=BedrockModel(...), system_prompt=...)
2. Summarizes game state JSON into readable text
3. Invokes the agent: response = agent(state_summary)
4. Parses the response into game commands
5. Falls back to rule-based logic if the LLM fails

Key code pattern:

from strands import Agent
from strands.models import BedrockModel

model = BedrockModel(model_id="us.amazon.nova-micro-v1:0")
agent = Agent(model=model, system_prompt=SYSTEM_PROMPT)

response = agent(state_summary)
commands = parse_commands(str(response), team_id)

Core Strands SDK Concepts (23 Total)

1. Structured Output

Return validated, type-safe responses using Pydantic models instead of raw text.

from pydantic import BaseModel, Field
from strands import Agent

class FootballAction(BaseModel):
    commandType: str = Field(description="MOVE_TO, SHOOT, PASS, etc.")
    playerId: int
    parameters: dict
    duration: int = 0

agent = Agent(system_prompt="Analyze game state, return ONE action.")
result = agent("Ball at (10,5), I'm at (0,0).", structured_output_model=FootballAction)
action = result.structured_output  # Type-safe FootballAction

2. Custom Tools

Give your agent callable functions for tactical analysis:

from strands import Agent, tool

@tool
def should_shoot(player_x: float, goal_x: float) -> dict:
    """Determine if player should shoot based on distance to goal.
    Args:
        player_x: Player's x coordinate
        goal_x: Goal's x coordinate (55 or -55)
    """
    distance = abs(player_x - goal_x)
    return {'should_shoot': distance < 30, 'power': max(0.5, min(1.0, 1.0 - distance/100))}

agent = Agent(tools=[should_shoot], system_prompt="Use tools to decide actions.")

3. Model Providers

Switch between models easily:

from strands.models import BedrockModel

model = BedrockModel(model_id="us.amazon.nova-micro-v1:0")  # Fast, cheap
# model = BedrockModel(model_id="anthropic.claude-sonnet-4-20250514-v1:0")  # More capable
agent = Agent(model=model)

4. Observability

Track tokens, latency, and tool usage:

result = agent("What should I do?")
summary = result.metrics.get_summary()
print(f"Tokens: {summary['accumulated_usage']['totalTokens']}")
print(f"Latency: {summary['accumulated_metrics']['latencyMs']}ms")
print(f"Tool calls: {summary['tool_usage']}")

5. Hooks

Monitor and control agent behavior at lifecycle points:

from strands.hooks import HookProvider, HookRegistry, BeforeToolCallEvent, AfterToolCallEvent

class FootballMonitoringHook(HookProvider):
    def register_hooks(self, registry: HookRegistry) -> None:
        registry.add_callback(BeforeToolCallEvent, self.log_start)
        registry.add_callback(AfterToolCallEvent, self.log_end)
    def log_start(self, event: BeforeToolCallEvent) -> None:
        print(f"Calling: {event.tool_use['name']}")
    def log_end(self, event: AfterToolCallEvent) -> None:
        print(f"Result: {event.result}")

agent = Agent(tools=[should_shoot], hooks=[FootballMonitoringHook()])

Advanced: limit tool calls per invocation with BeforeInvocationEvent to reset counters and BeforeToolCallEvent to check limits via event.cancel_tool.

6. Guardrails

Content filtering and safety via Bedrock Guardrails:

model = BedrockModel(
    model_id="us.amazon.nova-micro-v1:0",
    guardrail_id="your-guardrail-id", guardrail_version="1", guardrail_trace="enabled"
)
agent = Agent(model=model)
result = agent("Some prompt")
if result.stop_reason == "guardrail_intervened":
    print("Blocked by guardrails")

7. Direct Tool Invocation

Call tools programmatically without LLM reasoning:

distance = agent.tool.calculate_distance(pos1={"x": 0, "y": 0}, pos2={"x": 10, "y": 5})

8. Community Tools

Pre-built tools from strands-agents-tools:

from strands_tools import calculator, python_repl
agent = Agent(tools=[calculator, python_repl])

Useful for football: calculator (math), python_repl (complex calculations), current_time (match timing).

9. Conversation Management

Control how message history is handled:

from strands.agent.conversation_manager import (
    NullConversationManager, SlidingWindowConversationManager, SummarizingConversationManager
)

# Keep recent messages (default)
agent = Agent(conversation_manager=SlidingWindowConversationManager(window_size=10))

# No trimming
agent = Agent(conversation_manager=NullConversationManager())

# Summarize old messages
agent = Agent(conversation_manager=SummarizingConversationManager(
    summary_ratio=0.3, preserve_recent_messages=10
))

For football: typically stateless per tick (fresh agent each time).

10. Agent State Management

Key-value storage across invocations — not sent to the model:

from strands import tool, ToolContext

@tool(context=True)
def track_opponent(opponent_id: int, tendency: str, tool_context: ToolContext) -> str:
    """Record an opponent's tendency.
    Args:
        opponent_id: Opponent player ID
        tendency: Observed tendency
    """
    tendencies = tool_context.agent.state.get("opponent_tendencies") or {}
    tendencies[str(opponent_id)] = tendency
    tool_context.agent.state.set("opponent_tendencies", tendencies)
    return f"Recorded: player {opponent_id} → {tendency}"

agent = Agent(tools=[track_opponent], state={"opponent_tendencies": {}})

11. Session Management

Persist state and conversation across restarts:

from strands.session.file_session_manager import FileSessionManager

session_mgr = FileSessionManager(session_id="team-alpha", storage_dir="./sessions")
agent = Agent(session_manager=session_mgr, state={"patterns": {}})
# After redeployment, restore with same session_id

Use S3SessionManager for cloud deployments.

12. Retry Strategies

Handle model throttling during high-frequency ticks:

from strands import ModelRetryStrategy
agent = Agent(retry_strategy=ModelRetryStrategy(max_attempts=3, initial_delay=2, max_delay=60))
# Or disable: agent = Agent(retry_strategy=None)

13. Streaming

Monitor decisions in real-time with async iterators:

async for event in agent.stream_async("Ball at (30,10), should I shoot?"):
    if "data" in event:
        print(event["data"], end="")
    elif "current_tool_use" in event and event["current_tool_use"].get("name"):
        print(f"Using tool: {event['current_tool_use']['name']}")

14. Class-Based Tools

Share state across related tools using classes:

class MatchAnalytics:
    def __init__(self):
        self.shots_taken = 0
    @tool
    def record_shot(self, result: str) -> str:
        """Record a shot attempt. Args: result: 'goal', 'saved', or 'missed'"""
        self.shots_taken += 1
        return f"Shot #{self.shots_taken}: {result}"

analytics = MatchAnalytics()
agent = Agent(tools=[analytics.record_shot])

15. MCP Tools

Connect to external tool servers via Model Context Protocol:

from strands.tools.mcp import MCPClient
from mcp.client.sse import sse_client

mcp_client = MCPClient(lambda: sse_client("http://localhost:8000/sse"))
with mcp_client:
    agent = Agent(tools=mcp_client.list_tools_sync())

16. Multi-Agent — Agents as Tools

Wrap specialist agents as tools for an orchestrator:

@tool
def defensive_analyst(game_state: str) -> str:
    """Analyze defensive positioning.
    Args: game_state: Current game state summary"""
    return str(Agent(system_prompt="You are a defensive analyst.")(game_state))

@tool
def offensive_strategist(game_state: str) -> str:
    """Plan attacking moves.
    Args: game_state: Current game state summary"""
    return str(Agent(system_prompt="You are an attacking strategist.")(game_state))

coach = Agent(tools=[defensive_analyst, offensive_strategist],
    system_prompt="Route to the right specialist based on game situation.")

17. Multi-Agent — Swarm

Collaborative agents that autonomously hand off tasks:

from strands.multiagent import Swarm

scout = Agent(name="scout", system_prompt="Analyze opponent weaknesses.")
tactician = Agent(name="tactician", system_prompt="Design game plans.")
coach = Agent(name="coach", system_prompt="Finalize tactics.")

swarm = Swarm([scout, tactician, coach], entry_point=scout, max_handoffs=10)
result = swarm("Prepare a plan against a 4-4-2 high-pressing team")

18. Multi-Agent — Graph

Structured pipeline with defined execution order:

from strands.multiagent import GraphBuilder

analyzer = Agent(name="analyzer", system_prompt="Analyze game state.")
planner = Agent(name="planner", system_prompt="Create tactical plan.")
executor = Agent(name="executor", system_prompt="Convert plan to player actions.")

builder = GraphBuilder()
builder.add_node(analyzer, "analyze")
builder.add_node(planner, "plan")
builder.add_node(executor, "execute")
builder.add_edge("analyze", "plan")
builder.add_edge("plan", "execute")
builder.set_entry_point("analyze")
graph = builder.build()
result = graph("Possession in midfield, 1-1, 80th minute")

19. Interrupts

Pause execution for human input (coaching decisions):

from strands.hooks import BeforeToolCallEvent, HookProvider, HookRegistry

class SubstitutionApproval(HookProvider):
    def register_hooks(self, registry: HookRegistry) -> None:
        registry.add_callback(BeforeToolCallEvent, self.approve)
    def approve(self, event: BeforeToolCallEvent) -> None:
        if event.tool_use["name"] == "substitute_player":
            approval = event.interrupt("coach-approval",
                reason={"out": event.tool_use["input"]["player_out"],
                        "in": event.tool_use["input"]["player_in"]})
            if approval.lower() != "y":
                event.cancel_tool = "Coach rejected the substitution"

# Handle interrupt: check result.stop_reason == "interrupt", then respond

20. Agent Loop

The core cycle: invoke model → check for tool call → execute tool → re-invoke model → repeat until final response.

Stop reasons: end_turn (normal), tool_use (loop continues), max_tokens (truncated), guardrail_intervened (blocked), interrupt (paused).

result = agent("Ball at (30,10), should I shoot?")
print(f"Stop reason: {result.stop_reason}")
print(f"Messages: {len(agent.messages)}")

21. Tool Executors

Control concurrent vs sequential tool execution:

from strands.tools.executors import SequentialToolExecutor

agent = Agent(tools=[...])  # Default: concurrent (faster)
agent = Agent(tool_executor=SequentialToolExecutor(), tools=[...])  # Sequential

22. Multi-Modal Prompting

Send images/documents alongside text (useful for pre/post-match analysis):

with open("opponent_heatmap.png", "rb") as f:
    image_bytes = f.read()
result = agent([
    {"text": "Analyze this opponent heatmap. Where are the gaps?"},
    {"image": {"format": "png", "source": {"bytes": image_bytes}}}
])

Note: During live gameplay your agent receives JSON game state, not images.

23. Debug Logging

Enable detailed logs for diagnosing agent behavior:

import logging
logging.getLogger("strands").setLevel(logging.DEBUG)
logging.basicConfig(format="%(levelname)s | %(name)s | %(message)s",
    handlers=[logging.StreamHandler()])

Enhancement Patterns

Apply these to the sample agent — each maps to a core concept above:

Enhancement	How	Core Concept
Structured Output	Pass structured_output_model=GameCommand (Pydantic) to agent() — replaces manual parsing	#1
Custom Tools	Add @tool functions (e.g., shooting angle calculator) to Agent(tools=[...])	#2
Observability	Read result.metrics.get_summary() for tokens, latency, tool usage	#4
Hooks	Create a HookProvider subclass, register callbacks for BeforeInvocationEvent	#5
Model Switching	Swap BedrockModel(model_id=...) — Nova Micro for speed, Claude for complex tactics	#3
Guardrails	Add guardrail_id and guardrail_version to BedrockModel(...)	#6
State Tracking	Use tool_context.agent.state.get/set in @tool(context=True) functions	#10
Retry Strategy	Add retry_strategy=ModelRetryStrategy(max_attempts=3, initial_delay=1)	#12
Multi-Agent Pipeline	Use GraphBuilder to chain analyzer → planner → executor agents	#18

Deploying to AgentCore

Step 1: Test Locally

python test_local.py          # Without LLM
python test_local.py --llm    # With LLM

Step 2: Deploy

agentcore deploy

After deployment you receive a Runtime ARN — use it to register your agent for matches.

Step 3: View Logs

aws logs tail /aws/bedrock-agentcore/runtimes/<runtime-id>-DEFAULT \
  --log-stream-name-prefix "$(date +%Y/%m/%d)/[runtime-logs" --follow

Step 4: Register for Matches

Use the Runtime ARN from the AgentCore console to register your agent. You can use one ARN for all 5 players or create separate agents per player for diversity.

References

• See content-reference/en/strands-guide.md for full detail