7.6 KiB
7.6 KiB
Agent Loop Sequence Diagram
+---------+ +---------+ +------------+ +-------+ +-------+
| User | | Agent | | AgentLoop | | LLM | | Tool |
+---------+ +---------+ +------------+ +-------+ +-------+
| | | | |
| prompt(messages)| | | |
|---------------->--> | | |
| | normalizePrompt()| | |
| |----------------->>| | |
| | runPromptMessages| | |
| |----------------->>| | |
| | | | |
| | createLoopConfig | | |
| |----------------->>| | |
| | | | |
| | agentLoop() | | |
| |----------------->>| | |
| | | emit(AgentStart) | |
| | |------------------> | |
| | | | |
| | | transform_context() | |
| | |------------------> | |
| | | convert_to_llm() | |
| | |------------------> | |
| | | stream_function() | |
| | |-------------------------> |
| | | | response |
| | |<------------------------- |
| | | emit(MessageStart)| |
| | |------------------> | |
| | | emit(MessageEnd) | |
| | |------------------> | |
| | | | |
| | | extract_tool_calls()| |
| | |------------------> | |
| | | | |
| | | executeToolCalls() | |
| | |-------------------------> |
| | | | execute() |
| | |-------------------------> |
| | | | result |
| | |<------------------------- |
| | | emit(ToolExecutionEnd)| |
| | |------------------> | |
| | | createToolResult() | |
| | |------------------> | |
| | | emit(MessageEnd) | |
| | |------------------> | |
| | | | |
| | | emit(TurnEnd) | |
| | |------------------> | |
| | | | |
| | | prepare_next_turn() | |
| | |------------------> | |
| | | | |
| | | should_stop_check() | |
| | |------------------> | |
| | | | |
| | | drain(steering_queue)| |
| | |------------------> | |
| | | | |
| | | drain(follow_up_queue)| |
| | |------------------> | |
| | | | |
| | emit(AgentEnd) | | |
| |------------------>| | |
| | | | |
| | appendMessage() | | |
| |------------------> Session | |
|<----------------| | | |
| messages | | | |
| | | | |
Key Participants
User - Initiates conversation by calling prompt()
Agent - High-level wrapper managing state, queues, and events
AgentLoop - Low-level execution engine (agentLoop, runLoop)
LLM - Language model API (via stream_function)
Tool - Tool execution (bash, read, write, edit)
Session - Conversation history persistence
Main Loop Flow
1. [Agent] normalizePromptInput() - Convert input to messages
2. [Agent] runPromptMessages() - Start processing
3. [Agent] createLoopConfig() - Build loop configuration
4. [Agent] agentLoop() - Start low-level loop
5. [AgentLoop] emit(AgentStart) - Signal start
6. [AgentLoop] transform_context() - Optional context transform
7. [AgentLoop] convert_to_llm() - Convert to LLM messages
8. [AgentLoop] stream_function() - Call LLM
9. [AgentLoop] emit(MessageStart/End) - Stream response
10. [AgentLoop] extract_tool_calls() - Check for tool calls
11. [AgentLoop] executeToolCalls() - Execute tools (seq/parallel)
12. [AgentLoop] emit(TurnEnd) - Signal turn complete
13. [AgentLoop] prepare_next_turn() - Optional next turn setup
14. [AgentLoop] should_stop_check() - Check termination
15. [AgentLoop] drain queues() - Check steering/follow-up
16. [AgentLoop] emit(AgentEnd) - Signal completion
17. [Agent] appendMessage() - Persist to session
Queue Processing
steering_queue: Injected after assistant turn, before next LLM call
follow_up_queue: Run only when agent would otherwise stop (after loop exit)
Event Flow
AgentStart → [TurnStart → MessageStart → MessageEnd → ...] → TurnEnd → ...
↓
AgentEnd
Tool Execution Options
Sequential: One tool at a time, in order
Parallel: All tools spawned concurrently, results collected