131 lines
7.6 KiB
Markdown
131 lines
7.6 KiB
Markdown
# 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
|
|
```
|