Agentic loop implementation

[Unshure]

Agentic Loop Implementation

Create an async iterator agent loop that coordinates execution between model providers and tools. The event loop manages the conversation flow by streaming model responses, executing tools when needed, and continuing until completion.

Implementation Requirements

Based on repository analysis and clarification discussions, this task involves implementing a core agent loop function without the full Agent class (which will come later).

Architecture Overview

The agent loop follows a simple top-level loop pattern that calls out to different steps:

1. Model invocation - Send messages to model provider and stream responses
2. Tool execution - Execute tools when model requests them
3. Loop continuation - Return to model invocation with tool results

Reference: Strands Agent Loop Documentation

Technical Specifications

1. Agent Loop Function (src/agent_loop.ts)

Create a new file src/agent_loop.ts with:

async function* agent_loop(
  messages: Message[],
  toolRegistry: ToolRegistry,
  systemPrompt: SystemPrompt | undefined,
  modelProvider: Model<BaseModelConfig>
): AsyncGenerator<AgentStreamEvent, Message[], never>

Key behaviors:

• Returns an async generator that yields AgentStreamEvent objects
• Returns final list of messages when complete
• Does NOT create an Agent class (that comes later)
• Uses existing ToolRegistry class from src/tools/registry.ts

2. Event Types (src/agent/streaming.ts or in agent_loop.ts)

Create AgentStreamEvent type that includes:

• All ModelStreamEvent types (passthrough from model provider)
• Additional agent-specific events:
  • BeforeModelEvent - Before invoking model
  • AfterModelEvent - After model completes
  • BeforeToolsEvent - Before executing tools
  • AfterToolsEvent - After tools complete
  • BeforeInvocationEvent - Start of agent loop iteration
  • AfterInvocationEvent - End of agent loop iteration

3. Message Handling (Transactional)

Critical requirement: Do NOT add user messages to the messages array until the model provider returns its first event.

• Wait for first event from model provider
• Only then add the user message to the messages array
• If model provider throws error before first event, do NOT add message
• Return the complete messages array at the end

Reference: PR #57 contains guidance on this pattern (ContentBlock construction)

4. Model Provider Invocation

• Call modelProvider.stream(messages, options) with:
  • Current messages array
  • toolSpecs extracted from ToolRegistry using toolRegistry.list().map(t => t.toolSpec)
  • systemPrompt if provided
• Stream all ModelStreamEvent objects to the caller (yield each one)
• Accumulate content blocks from streaming events to construct response message

5. ContentBlock Construction

• Use patterns from PR Issue #56: Collect Model Streamed Events Implementation #57 as guidance
• Accumulate streaming deltas to build complete ContentBlocks:
  • textDelta → TextBlock
  • toolUseStart + toolUseInputDelta → ToolUseBlock
  • reasoningDelta → ReasoningBlock
• Construct assistant message with all content blocks at end of stream

6. Stop Reason Detection & Tool Execution

When stopReason === 'toolUse':

• Extract all ToolUseBlock objects from the assistant message
• Execute tools sequentially (one at a time, not in parallel)
• For each tool:
  1. Look up tool in registry: toolRegistry.get(toolName)
  2. Execute: tool.stream({ toolUse, invocationState: {} })
  3. Yield all ToolStreamEvent objects in real-time
  4. Collect the final ToolResult from the generator
  5. Create a ToolResultBlock and add to messages array
• After all tools executed, create user message with all ToolResultBlocks
• Continue the loop (invoke model again)

When stopReason !== 'toolUse':

• Yield a final AfterInvocationEvent
• Return the complete messages array
• Terminate the loop

7. Error Handling

Model provider errors (before first event):

• Throw immediately
• Do NOT add user message to messages array

Model provider errors (after first event):

• Propagate the error
• Messages array state is preserved up to error point

Tool execution errors:

• If tool throws exception, re-raise it (potentially with additional context)
• Note: Well-behaved tools should NOT throw - they should return ToolResult with status: 'error'

MaxTokens stop reason:

• Throw an error (this is an unrecoverable state)
• Should throw MaxTokensReachedException or similar

8. Loop Termination

The loop terminates when:

• stopReason !== 'toolUse' (normal completion)
• stopReason === 'maxTokens' (error - throw exception)
• Any unhandled exception occurs (error propagation)

Dependencies & Integration

Existing code to use:

• ✅ src/tools/registry.ts - ToolRegistry class for managing tools
• ✅ src/models/model.ts - Model interface for model providers
• ✅ src/models/streaming.ts - ModelStreamEvent types
• ✅ src/types/messages.ts - Message, ContentBlock, SystemPrompt types
• ✅ src/tools/tool.ts - Tool interface and ToolStreamEvent
• ✅ src/tools/types.ts - ToolSpec, ToolUse, ToolResult types

Model provider compatibility:

• Must work with both BedrockModel and OpenAIModel
• Use the base Model interface, not provider-specific implementations
• No provider-specific handling needed

Testing Requirements

Unit Tests (src/agent/__tests__/agent_loop.test.ts)

Create comprehensive unit tests using:

• Mock model provider - Create if one doesn't exist in src/models/__tests__/test-utils.ts
• Mock tools - Create helper for generating mock Tool implementations if needed
• Test scenarios:
  1. Simple completion without tools (endTurn stop reason)
  2. Single tool use cycle (toolUse → execute → continue → endTurn)
  3. Multiple tool uses in sequence
  4. Multiple agentic loop iterations
  5. Transactional message handling (message not added on early error)
  6. Error propagation from model provider
  7. Error propagation from tool execution
  8. MaxTokens stop reason (should throw)
  9. Event streaming (verify all events yielded)
  10. ContentBlock construction from streaming events

Integration Tests

NOT required for this task - Will be added later when Agent class is implemented

File Structure

src/
├── agent_loop.ts              # Main agent loop function (NEW)
├── agent/
│   ├── streaming.ts           # AgentStreamEvent types (NEW)
│   └── __tests__/
│       └── agent_loop.test.ts # Comprehensive unit tests (NEW)
├── models/
│   └── __tests__/
│       └── test-utils.ts      # Add mock model provider if needed
└── tools/
    └── __tests__/
        └── test-utils.ts      # Add mock tool helper if needed (NEW)

Acceptance Criteria

• agent_loop function implemented with correct signature
• AgentStreamEvent type defined with all required event types
• Transactional message handling: messages not added before first model event
• Model provider streaming events yielded to caller
• ContentBlocks correctly constructed from streaming events
• Tool execution triggered on toolUse stop reason
• Tools executed sequentially with real-time event streaming
• Tool results added to messages and loop continues
• Loop terminates correctly on non-toolUse stop reasons
• MaxTokens stop reason throws error
• Error handling for model provider errors
• Error handling for tool execution errors
• Unit tests cover all major scenarios
• 80%+ test coverage maintained
• All tests pass
• Code follows TypeScript coding patterns from AGENTS.md
• TSDoc documentation for all exported functions
• No linting errors
• Types exported from src/index.ts

Notes & Future Considerations

Extensibility considerations (do NOT implement now):

• Allow entry point to jump directly into tool-execution (based on if last message was a toolUse)
• This will be implemented later but keep in mind during design

Agent class (do NOT implement now):

• Full Agent class will be implemented in a separate task
• This task focuses only on the core loop mechanism

Integration tests (do NOT implement now):

• Integration tests with real model providers will be added after Agent class exists

Repository Documentation Updates

After implementation, update:

• AGENTS.md - Add agent loop to directory structure if new directories created
• README.md - Update development status to mark agent loop as complete

---

Original Context

Create an async iterator agent loop that coordinates execution between model providers and tools. The event loop manages the conversation flow by streaming model responses, executing tools when needed, and continuing until completion.

Exit Criteria

A working agent loop async iterator that coordinates model provider streaming and tool execution, properly constructs ContentBlocks from responses, handles tool_use cycles, streams all events back to the caller, and passes comprehensive unit tests.

[zastrowm]

/strands review

Architecturally-wise, we want a simple top-level loop that then calls out to different steps like:

• Model invocation
• Tool execution

Similar to how it's invoked at https://strandsagents.com/latest/documentation/docs/user-guide/concepts/agents/agent-loop/

We should also consider top-level extensibility like:

• Allowing an entry point to jump directly into tool-execution (based on if the last message was a toolUse)

But we don't want to implement that now, just keep it in mind

[github-actions]

Repository Analysis & Clarifying Questions

I've analyzed the repository structure and have identified several areas that need clarification to ensure proper implementation of the agentic loop.

Repository Context

• Framework: TypeScript SDK with Node.js 20+
• Testing: Vitest for unit and integration tests
• Existing Infrastructure:
  • ✅ Message types and ContentBlock types defined (src/types/messages.ts)
  • ✅ Model provider interface with streaming (src/models/model.ts)
  • ✅ Tool interface with streaming support (src/tools/tool.ts)
  • ✅ BedrockModel and OpenAIModel implementations
  • ✅ ModelStreamEvent types for streaming events
  • ❌ Agent class (not yet implemented)
  • ❌ ToolRegistry (not yet implemented)
  • ❌ Event loop mechanism (not yet implemented)

Clarifying Questions

1. Agent Interface Design & File Structure

• Where should the Agent class be located? Should it be src/agent.ts or in a subdirectory like src/agent/?
• What should the Agent constructor accept? Should it take: { tools, modelProvider, systemPrompt, ...other options }?
• Should the agent loop be implemented as a method on the Agent class (e.g., agent.stream()) or as a separate function?
• Should we create multiple files (e.g., agent.ts, event-loop.ts, content-builder.ts) or keep it in one file?

2. Tool Registry Design

• What is the tool_registry mentioned in the requirements? Should it be:
  • A simple array of Tool objects: Tool[]
  • A Map for fast lookup: Map<string, Tool>
  • A dedicated ToolRegistry class with methods like register(), lookup(), getSpecs()?
• Where should ToolRegistry be defined if it's a class?

3. ContentBlock Construction from Streaming Events

• How should ContentBlocks be built from streaming ModelStreamEvents?
• Should we accumulate delta events and construct blocks at the end of each content block, or construct them incrementally?
• For ToolUseBlock, should we parse the JSON input incrementally as strings arrive, or wait for the complete input?
• Should there be a dedicated ContentBlockBuilder helper class?

4. Transactional Message Handling - Timing

• The requirement says "wait for model provider to return first event before adding user message to messages array"
• Should the user message be added:
  • After the first event (any event type) is received?
  • After the modelMessageStartEvent specifically?
  • After successful initialization but before yielding any events to the caller?
• What happens if the model provider throws an error before yielding any event? Should we still add the user message for retry purposes?

5. Agent Loop Return Type & Event Streaming

• What should the agent loop async iterator yield to the caller?
  • Only ModelStreamEvent objects?
  • Only ToolStreamEvent objects?
  • Both types (union type)?
  • A new AgentStreamEvent type that wraps both?
• Should the caller be able to distinguish between events from the model vs events from tool execution?

6. Tool Execution Strategy

• When multiple tools are requested in a single response, should they:
  • Execute sequentially (one at a time)?
  • Execute in parallel (all at once)?
• Should tool execution stream events be yielded in real-time, or only after completion?

7. Loop Termination & Stop Reasons

• When stop_reason is NOT tool_use, should the loop:
  • Terminate immediately and return?
  • Yield a final event before terminating?
  • Just stop without any special handling?
• What should happen with maxTokens stop reason? Should it be an error or graceful completion?

8. Error Handling & Propagation

• For model provider errors (before first event), should we:
  • Throw immediately?
  • Yield an error event?
  • Retry with exponential backoff?
• For tool execution errors:
  • Should they create a ToolResult with status: 'error'?
  • Should they stop the loop or continue?
  • Should error details be included in the ToolResult content?

9. Integration with Multiple Model Providers

• The repository has both BedrockModel and OpenAIModel implementations. Should the agent loop:
  • Work seamlessly with both?
  • Have any provider-specific handling?
• Are there any known differences in how these providers stream events that the agent loop needs to handle?

10. Testing Strategy & Scope

• For unit tests, should we:
  • Mock the Model provider and Tool implementations?
  • Use real implementations with test doubles?
• For integration tests, should we:
  • Test with both Bedrock and OpenAI providers?
  • Only test with one provider?
  • Create mock tools or use real tools like calculator?

11. Task Scope & Breakdown

This task involves creating:

• Agent class implementation
• ToolRegistry system
• Event loop coordination logic
• ContentBlock construction from streaming events
• Transactional message handling
• Error handling throughout
• Comprehensive unit tests
• Integration tests

This seems quite large for a single PR. Should we consider breaking this down into smaller sub-tasks such as:

• Sub-task 65.1: Agent class structure with basic tool registry
• Sub-task 65.2: Event loop implementation with model invocation
• Sub-task 65.3: Tool execution and loop continuation logic
• Sub-task 65.4: ContentBlock construction and message handling
• Sub-task 65.5: Comprehensive testing

Or would you prefer this to be implemented as a single cohesive feature?

Please provide guidance on these questions when you have a chance. Based on my analysis, this implementation will require creating approximately 3-5 new files and extensive testing infrastructure.

[zastrowm]

/strands review

Repository Analysis & Clarifying Questions

I've analyzed the repository structure and have identified several areas that need clarification to ensure proper implementation of the agentic loop.

Repository Context

• Framework: TypeScript SDK with Node.js 20+

• Testing: Vitest for unit and integration tests

• Existing Infrastructure:

  • ✅ Message types and ContentBlock types defined (src/types/messages.ts)
  • ✅ Model provider interface with streaming (src/models/model.ts)
  • ✅ Tool interface with streaming support (src/tools/tool.ts)
  • ✅ BedrockModel and OpenAIModel implementations
  • ✅ ModelStreamEvent types for streaming events
  • ❌ Agent class (not yet implemented)
  • ❌ ToolRegistry (not yet implemented)
  • ❌ Event loop mechanism (not yet implemented)

Clarifying Questions

1. Agent Interface Design & File Structure

• Where should the Agent class be located? Should it be src/agent.ts or in a subdirectory like src/agent/?
• What should the Agent constructor accept? Should it take: { tools, modelProvider, systemPrompt, ...other options }?
• Should the agent loop be implemented as a method on the Agent class (e.g., agent.stream()) or as a separate function?
• Should we create multiple files (e.g., agent.ts, event-loop.ts, content-builder.ts) or keep it in one file?

Don't create an Agent class/interface. For now, create an agent_loop.ts class which has an entry point:

async agent_loop(...)

2. Tool Registry Design

• What is the tool_registry mentioned in the requirements? Should it be:

  • A simple array of Tool objects: Tool[]
  • A Map for fast lookup: Map<string, Tool>
  • A dedicated ToolRegistry class with methods like register(), lookup(), getSpecs()?

• Where should ToolRegistry be defined if it's a class?

This exists in https://github.com/strands-agents/sdk-typescript/blob/main/src/tools/registry.ts - don't re-create it. You may need to rebase from main

3. ContentBlock Construction from Streaming Events

• How should ContentBlocks be built from streaming ModelStreamEvents?
• Should we accumulate delta events and construct blocks at the end of each content block, or construct them incrementally?
• For ToolUseBlock, should we parse the JSON input incrementally as strings arrive, or wait for the complete input?
• Should there be a dedicated ContentBlockBuilder helper class?

This is being done as part of #57; use that for guidance of this task

4. Transactional Message Handling - Timing

• The requirement says "wait for model provider to return first event before adding user message to messages array"

• Should the user message be added:

  • After the first event (any event type) is received?
  • After the modelMessageStartEvent specifically?
  • After successful initialization but before yielding any events to the caller?

• What happens if the model provider throws an error before yielding any event? Should we still add the user message for retry purposes?

The agent_loop needs to return a list of messages; in the inner loop, do not add any messages until we receive a message out of the model provider (again see PR 57)

5. Agent Loop Return Type & Event Streaming

• What should the agent loop async iterator yield to the caller?

  • Only ModelStreamEvent objects?
  • Only ToolStreamEvent objects?
  • Both types (union type)?
  • A new AgentStreamEvent type that wraps both?

• Should the caller be able to distinguish between events from the model vs events from tool execution?

Yield everything coming out of the model, plus more. Create an AgentStreamEvent for now for additional events that we think we need.

For instance, we should have a BeforeModelEvent, AfterModelEvent, BeforeToolsEvent, AfterToolsEvent, BeforeInvocationEvent, AfterInvocationEvent

6. Tool Execution Strategy

• When multiple tools are requested in a single response, should they:

  • Execute sequentially (one at a time)?
  • Execute in parallel (all at once)?

• Should tool execution stream events be yielded in real-time, or only after completion?

For now, execute them sequentially. Yield in real time

7. Loop Termination & Stop Reasons

• When stop_reason is NOT tool_use, should the loop:

  • Terminate immediately and return?
  • Yield a final event before terminating?
  • Just stop without any special handling?

• What should happen with maxTokens stop reason? Should it be an error or graceful completion?

Yield a final event, then return

Max_tokens should be an error

8. Error Handling & Propagation

• For model provider errors (before first event), should we:

  • Throw immediately?
  • Yield an error event?
  • Retry with exponential backoff?

For now, throw

• For tool execution errors:

  • Should they create a ToolResult with status: 'error'?
  • Should they stop the loop or continue?
  • Should error details be included in the ToolResult content?

It's up to tools to not throw, so for tool execution, just re-reaise the exception (maybe with more information)

9. Integration with Multiple Model Providers

• The repository has both BedrockModel and OpenAIModel implementations. Should the agent loop:

  • Work seamlessly with both?
  • Have any provider-specific handling?

• Are there any known differences in how these providers stream events that the agent loop needs to handle?

There's a base model between those two; use that

10. Testing Strategy & Scope

• For unit tests, should we:

  • Mock the Model provider and Tool implementations?
  • Use real implementations with test doubles?

• Mock the model provider - I think there is a mock model provider already available for use
• If we don't already have a helper for mock tools, create one and use that

• For integration tests, should we:

  • Test with both Bedrock and OpenAI providers?
  • Only test with one provider?
  • Create mock tools or use real tools like calculator?

Use all UTs for this; once we have the Agent class we'll expand th etest

11. Task Scope & Breakdown

This task involves creating:

• Agent class implementation
• ToolRegistry system

Neither of these

• ContentBlock construction from streaming events
• Integration tests
  Nope

• Event loop coordination logic
• Transactional message handling
• Error handling throughout
• Comprehensive unit tests

Yes

This seems quite large for a single PR. Should we consider breaking this down into smaller sub-tasks such as:

• Sub-task 65.1: Agent class structure with basic tool registry
• Sub-task 65.2: Event loop implementation with model invocation
• Sub-task 65.3: Tool execution and loop continuation logic
• Sub-task 65.4: ContentBlock construction and message handling
• Sub-task 65.5: Comprehensive testing

Or would you prefer this to be implemented as a single cohesive feature?

Please provide guidance on these questions when you have a chance. Based on my analysis, this implementation will require creating approximately 3-5 new files and extensive testing infrastructure.

A single cohesive feature, as most of the other parts are in other PRs and will be ready before we begin this one

[github-actions]

✅ Task Review Complete - Ready for Implementation

I've completed the review of this task and updated the issue description with comprehensive implementation requirements.

Summary of Changes

The issue description now includes:

1. Clear Architecture Overview - Simple top-level loop with model invocation and tool execution steps

2. Technical Specifications - Detailed requirements for:

   • Agent loop function signature and location (src/agent_loop.ts)
   • Event types including AgentStreamEvent with 6 new event types
   • Transactional message handling (don't add messages until first model event)
   • Model provider invocation with streaming
   • ContentBlock construction patterns (reference PR Issue #56: Collect Model Streamed Events Implementation #57)
   • Tool execution strategy (sequential, real-time streaming)
   • Error handling for all scenarios
   • Loop termination conditions

3. Dependencies & Integration - Lists all existing code to leverage:

   • ToolRegistry (already exists in src/tools/registry.ts)
   • Model providers, streaming types, message types, etc.

4. Testing Requirements - Comprehensive unit test scenarios with mock providers

   • No integration tests needed for this task

5. File Structure - Clear layout of files to create

6. Acceptance Criteria - 17 specific checkboxes to verify completion

Scope Confirmation

Based on clarifications, this task is scoped to:

• ✅ Event loop coordination logic
• ✅ Transactional message handling
• ✅ Error handling throughout
• ✅ Comprehensive unit tests

Explicitly excluded (to be done in other PRs):

• ❌ Agent class (future task)
• ❌ ToolRegistry (already exists)
• ❌ ContentBlock construction (patterns in PR Issue #56: Collect Model Streamed Events Implementation #57)
• ❌ Integration tests (will be added after Agent class exists)

Implementation Estimate

This is a single cohesive feature that should take approximately 3-5 days for a developer to implement with proper testing.

Key files to create:

• src/agent_loop.ts (~200-300 lines)
• src/agent/streaming.ts (~100-150 lines)
• src/agent/__tests__/agent_loop.test.ts (~500-800 lines)
• Mock helpers if needed (~100-200 lines)

Next Steps

This issue is now ready for implementation. A developer can pick this up and begin work following the detailed specifications in the issue description.

References to check during implementation:

• PR Issue #56: Collect Model Streamed Events Implementation #57 for ContentBlock construction patterns
• src/tools/registry.ts for ToolRegistry usage
• Existing integration tests in tests_integ/bedrock.test.ts for model provider patterns

[zastrowm]

/strands implement

[github-actions]

Pull Request Ready

I've completed the implementation of the agentic loop. All tests are passing with excellent coverage.

Branch: agent-tasks/65
Commit: a41d71a

Summary

• ✅ Implemented agent_loop async generator function
• ✅ Added agent-specific streaming events (BeforeModel, AfterModel, BeforeTool, AfterTool, BeforeInvocation, AfterInvocation)
• ✅ Implemented transactional message handling
• ✅ Sequential tool execution with real-time streaming
• ✅ Added MaxTokensError for token limit handling
• ✅ 13 comprehensive test scenarios
• ✅ 90.29% coverage for agent_loop.ts, 94.24% overall
• ✅ All 190 tests passing
• ✅ Linting and type checking pass

Create Pull Request

Please create a pull request using this link:

https://github.com/strands-agents/sdk-typescript/compare/main...agent-tasks/65?quick_pull=1&title=Task%2065%3A%20Agentic%20Loop%20Implementation&body=Resolves%3A%20%2365%0A%0A%23%23%20Overview%0A%0AThis%20PR%20implements%20the%20core%20agent%20loop%20functionality%20that%20coordinates%20execution%20between%20model%20providers%20and%20tools.%0A%0A%23%23%20Implementation%20Details%0A%0A**src%2Fagent_loop.ts**%20-%20Main%20agent%20loop%20async%20generator%20function%0A**src%2Fagent%2Fstreaming.ts**%20-%20Agent-specific%20streaming%20event%20types%0A**src%2Ferrors.ts**%20-%20Added%20MaxTokensError%0A%0A%23%23%20Testing%0A-%2013%20new%20test%20scenarios%0A-%2090.29%25%20coverage%20for%20agent_loop.ts%0A-%2094.24%25%20overall%20coverage%0A-%20All%20190%20tests%20passing%0A%0A%23%23%20Changes%0A-%20Added%20agent%20loop%20implementation%20with%20streaming%0A-%20Transactional%20message%20handling%0A-%20Sequential%20tool%20execution%0A-%20MaxTokens%20error%20handling%0A-%20Comprehensive%20unit%20tests%0A%0A%23%23%20Validation%0A%E2%9C%85%20All%20tests%20pass%0A%E2%9C%85%20Linting%20passes%0A%E2%9C%85%20Type%20checking%20passes

Or create the PR manually from the branch agent-tasks/65.

Ready for your review!