ton/YiemAgent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 6 Wiki Activity

update

Browse Source
This commit is contained in:
narawat
2026-07-28 09:57:23 +07:00
parent b18a5f34a8
commit 072d0e16af
1 changed files with 204 additions and 281 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/agent_loop_sequence_diagram.md
+204 -281
View File
@@ -1,298 +1,221 @@
# Agent Loop Sequence Diagram # Agent Loop Sequence Diagram (ASCII)
```mermaid ```
sequenceDiagram ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐ ┌───────────┐
participant User │ User │─────>│ Agent │─────>│ AgentLoop │─────>│ LLM │
participant Agent └─────────────┘ └─────────────┘ └─────────────────┘ └───────────┘
participant AgentLoop │
participant LLM ▼
participant Tool ┌─────────────┐ ┌─────────────────┐ ┌───────────┐ ┌─────────────┐
participant Session │ User │<─────│ AgentLoop │─────>│ Agent │─────>│ Session │
└─────────────┘ └─────────────────┘ └───────────┘ └─────────────┘
│
▼
┌─────────────┐
│ Session │
└─────────────┘
User->>Agent: prompt(messages) ┌─────────────────────────────────────────────────────────────────────────────────────────┐
activate Agent │ AGENT LOOP MAIN FLOW │
Agent->>Agent: normalizePromptInput(messages) └─────────────────────────────────────────────────────────────────────────────────────────┘
Agent->>Agent: runPromptMessages(messages)
User
alt Has queued steering messages │
Agent->>Agent: drain(steering_queue) │ prompt(messages)
Agent->>Agent: runPromptMessages(queued_steering) ▼
else Has follow-up messages Agent
Agent->>Agent: drain(follow_up_queue) │
Agent->>Agent: runPromptMessages(queued_follow_ups) │ normalizePromptInput()
else Normal prompt │ runPromptMessages()
Agent->>Agent: createLoopConfig(options) │
Agent->>Agent: createActiveRun() ├─ alt steering_queue has messages
│ │ drain(steering_queue)
Note over Agent,Session: Start AgentLoop │ │ runPromptMessages()
Agent->>AgentLoop: agentLoop(messages, context, config, signal, stream_fn) │
activate AgentLoop ├─ alt follow_up_queue has messages
│ │ drain(follow_up_queue)
Note over AgentLoop: Emit AgentStartEvent │ │ runPromptMessages()
AgentLoop->>AgentLoop: emit(AgentStartEvent()) │
└─ else (normal prompt)
loop For each prompt message │ createLoopConfig()
AgentLoop->>AgentLoop: emit(MessageStartEvent(msg)) │ createActiveRun()
AgentLoop->>AgentLoop: emit(MessageEndEvent(msg)) │
end ▼
AgentLoop
loop Main Agent Loop │
Note over AgentLoop: 1. Handle queued messages │ agentLoop(messages, context, config)
│
alt Steering/Follow-up messages exist ▼
AgentLoop->>AgentLoop: drain(steering_queue) ┌─────────────────────────────────────────────────────────────┐
loop For each pending message │ MAIN LOOP │
AgentLoop->>AgentLoop: emit(MessageStartEvent(msg)) ├─────────────────────────────────────────────────────────────┤
AgentLoop->>AgentLoop: push to context.messages │ │
AgentLoop->>AgentLoop: emit(MessageEndEvent(msg)) │ 1. Handle queued messages │
end │ ├─ drain(steering_queue) │
end │ ├─ emit(MessageStartEvent) │
│ ├─ push to context.messages │
Note over AgentLoop: 2. Get LLM Response │ └─ emit(MessageEndEvent) │
│ │
AgentLoop->>AgentLoop: transform_context?(messages) │ 2. Get LLM Response │
AgentLoop->>AgentLoop: convert_to_llm(messages) │ ├─ transform_context?(messages) │
AgentLoop->>LLM: stream_function(model, context, config) │ ├─ convert_to_llm(messages) │
activate LLM │ └─ stream_function(model, context, config) │
LLM-->>AgentLoop: response stream │ │
│ LLM │
alt Streaming enabled │ │ response stream │
loop For each event in stream │ └─ emit(MessageStartEvent) │
AgentLoop->>AgentLoop: emit(MessageStartEvent) │ └─ emit(MessageUpdateEvent) (streaming) │
AgentLoop->>AgentLoop: emit(MessageUpdateEvent) │ └─ emit(MessageEndEvent(final_message)) │
end │ │
LLM-->>AgentLoop: final message │ 3. Check for Tool Calls │
else Non-streaming │ └─ extract_tool_calls(message.content) │
LLM-->>AgentLoop: complete response │ │
end │ 4. Execute Tools (if any) │
│ ├─ emit(ToolExecutionStartEvent) │
deactivate LLM │ ├─ prepareToolCall() │
AgentLoop->>AgentLoop: emit(MessageEndEvent(final_message)) │ │ ├─ before_tool_call? (block if needed) │
AgentLoop->>AgentLoop: push message to context.messages │ │ └─ validateToolArguments() │
│ ├─ execute(tool_call_id, args) │
Note over AgentLoop: 3. Check for Tool Calls │ │ Tool │
│ │ │ execute() │
AgentLoop->>AgentLoop: extract_tool_calls(message.content) │ │ └─ on_update(partial_result) │
│ ├─ emit(ToolExecutionEndEvent) │
alt Tool calls exist │ └─ createToolResultMessage() │
Note over AgentLoop: 4. Execute Tools │ │
│ 5. Emit Turn End Event │
alt Sequential execution │ └─ emit(TurnEndEvent(message, tool_results)) │
AgentLoop->>AgentLoop: executeToolCallsSequential(...) │ │
activate AgentLoop │ 6. Prepare Next Turn │
│ └─ prepare_next_turn(context) │
loop For each tool call │ └─ AgentLoopTurnUpdate │
AgentLoop->>AgentLoop: emit(ToolExecutionStartEvent) │ │
│ 7. Check Stop Condition │
alt Tool not found │ └─ should_stop_after_turn? (break if true) │
AgentLoop->>AgentLoop: createErrorToolResult │ │
AgentLoop->>AgentLoop: emit(ToolExecutionEndEvent) │ 8. Get Steering/Follow-up Messages │
else Tool found │ ├─ drain(steering_queue) │
alt before_tool_call hook │ └─ drain(follow_up_queue) │
AgentLoop->>AgentLoop: before_tool_call(context, signal) │ │
alt Hook blocks │ 9. Continue or Break │
AgentLoop->>AgentLoop: createErrorToolResult │ ├─ alt pending messages exist → continue loop │
AgentLoop->>AgentLoop: emit(ToolExecutionEndEvent) │ └─ else → break │
else Execution allowed │ │
AgentLoop->>Agent: prepareToolCall(tool, tool_call, args) └─────────────────────────────────────────────────────────────┘
activate Agent │
▼
alt Has prepare_arguments AgentLoop
Agent->>Agent: prepare_arguments(args) │
deactivate Agent │ emit(AgentEndEvent(messages))
activate AgentLoop │
AgentLoop->>AgentLoop: validateToolArguments ▼
end Agent
│
alt Has before_tool_call hook │ appendMessage() → Session
AgentLoop->>Agent: before_tool_call(context, signal) │
alt Hook blocks ▼
AgentLoop->>AgentLoop: createErrorToolResult User (via promise)
else
AgentLoop->>Tool: execute(tool_call_id, args, signal, on_update)
activate Tool
Tool-->>AgentLoop: result
deactivate Tool
end
else No hooks
AgentLoop->>Tool: execute(tool_call_id, args, signal, on_update)
activate Tool
Tool-->>AgentLoop: result
deactivate Tool
end
alt Has after_tool_call hook
AgentLoop->>Agent: after_tool_call(context, signal)
alt Hook modifies result
AgentLoop->>AgentLoop: apply after_result
end
end
AgentLoop->>AgentLoop: emit(ToolExecutionEndEvent)
AgentLoop->>AgentLoop: createToolResultMessage
AgentLoop->>AgentLoop: emit(MessageStartEvent)
AgentLoop->>AgentLoop: emit(MessageEndEvent)
AgentLoop->>AgentLoop: push to context.messages
end
end
deactivate Agent
activate AgentLoop
end
alt Signal aborted
break
end
end
AgentLoop->>AgentLoop: return ExecutedToolCallBatch
deactivate AgentLoop
activate AgentLoop
end
alt Parallel execution
AgentLoop->>AgentLoop: executeToolCallsParallel(...)
activate AgentLoop
loop For each tool call
alt Tool not found or immediate
AgentLoop->>AgentLoop: execute synchronously
else Needs execution
AgentLoop->>AgentLoop: spawn async task
end
end
AgentLoop->>AgentLoop: wait for all tasks
AgentLoop->>AgentLoop: collect results
AgentLoop->>AgentLoop: return ExecutedToolCallBatch
deactivate AgentLoop
activate AgentLoop
end
Note over AgentLoop: 5. Emit Turn End Event
AgentLoop->>AgentLoop: emit(TurnEndEvent(message, tool_results))
Note over AgentLoop: 6. Prepare Next Turn
alt Has prepare_next_turn hook
AgentLoop->>Agent: prepare_next_turn(context)
activate Agent
alt Returns AgentLoopTurnUpdate
Agent->>Agent: update context
Agent->>Agent: update model
Agent->>Agent: update thinking_level
Agent->>AgentLoop: return updated config
deactivate Agent
activate AgentLoop
end
end
Note over AgentLoop: 7. Check Stop Condition
alt should_stop_after_turn returns true
AgentLoop->>AgentLoop: emit(AgentEndEvent)
break
end
Note over AgentLoop: 8. Get Next Steering Messages
AgentLoop->>AgentLoop: drain(steering_queue)
else No tool calls
Note over AgentLoop: 5. Emit Turn End Event
AgentLoop->>AgentLoop: emit(TurnEndEvent(message, []))
Note over AgentLoop: 6. Prepare Next Turn
alt Has prepare_next_turn hook
AgentLoop->>Agent: prepare_next_turn(context)
activate Agent
alt Returns AgentLoopTurnUpdate
Agent->>Agent: update context
Agent->>Agent: update model
Agent->>Agent: update thinking_level
Agent->>AgentLoop: return updated config
deactivate Agent
activate AgentLoop
end
end
Note over AgentLoop: 7. Check Stop Condition
alt should_stop_after_turn returns true
AgentLoop->>AgentLoop: emit(AgentEndEvent)
break
end
Note over AgentLoop: 8. Get Next Steering Messages
AgentLoop->>AgentLoop: drain(steering_queue)
end
alt Pending messages exist
loop Main Agent Loop
Note over AgentLoop: Continue loop
end
else Follow-up messages exist
AgentLoop->>AgentLoop: set pending_messages = follow_up
loop Main Agent Loop
Note over AgentLoop: Continue loop
end
end
break
end
Note over AgentLoop: 10. Final Agent End Event
AgentLoop->>AgentLoop: emit(AgentEndEvent(messages))
deactivate AgentLoop
deactivate Agent
Note over Agent,Session: Persist to Session
Agent->>Session: appendMessage(message)
User<<--Agent: messages (via promise)
end
Note over Agent: Resume normal operation
deactivate Agent
``` ```
## Key Components ## KEY COMPONENTS
### Agent Layer ### Agent Layer
- **Agent**: High-level wrapper managing state, queuing, and events ```
- **steering_queue**: Messages injected after assistant turn completes ┌──────────────────────────────────────────────────────────────┐
- **follow_up_queue**: Messages that run only when agent would otherwise stop │ Agent │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ state: AgentState │ │
│ │ - system_prompt │ │
│ │ - model │ │
│ │ - messages[] │ │
│ │ - tools[] │ │
│ └──────────────────────────────────────────────────────────┘ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Queues: │ │
│ │ - steering_queue: inject after assistant turn │ │
│ │ - follow_up_queue: run when agent stops │ │
│ └──────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────┘
```
### AgentLoop Layer ### AgentLoop Layer
- **agentLoop**: Entry point for new prompts ```
- **agentLoopContinue**: Continue from existing transcript ┌──────────────────────────────────────────────────────────────┐
- **runLoop**: Main execution loop handling: │ AgentLoop │
1. Pending message handling │ ┌──────────────────────────────────────────────────────────┐ │
2. LLM calls with streaming │ │ agentLoop() │ │
3. Tool execution (sequential/parallel) │ │ - Main loop execution │ │
4. Turn lifecycle events │ │ - Tool orchestration │ │
5. Next turn preparation │ │ - Event emission │ │
6. Stop condition checking │ └──────────────────────────────────────────────────────────┘ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ executeToolCallsSequential() │ │
│ │ executeToolCallsParallel() │ │
│ │ - Tool execution coordination │ │
│ │ - Hook invocation │ │
│ │ - Result collection │ │
│ └──────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────┘
```
### Lifecycle Events ### Lifecycle Events Flow
- `AgentStartEvent` / `AgentEndEvent` - Agent lifecycle boundaries ```
- `TurnStartEvent` / `TurnEndEvent` - Conversation turns AgentStartEvent
- `MessageStartEvent` / `MessageEndEvent` - Message processing │
- `ToolExecutionStartEvent` / `ToolExecutionEndEvent` - Tool execution ├─ TurnStartEvent
│ ├─ MessageStartEvent (user/assistant)
│ ├─ MessageEndEvent
│ ├─ ToolExecutionStartEvent
│ │ ├─ ToolExecutionUpdateEvent (streaming)
│ │ └─ ToolExecutionEndEvent
│ └─ TurnEndEvent
│
└─ AgentEndEvent (with final messages)
```
## Data Flow ## QUEUE PROCESSING ORDER
1. **Input**: User messages → Agent normalization → AgentLoop 1. **Initial steering messages** (if any)
2. **LLM Call**: Messages transformed → LLM stream → Assistant message 2. **Main loop**:
3. **Tool Execution**: Tool calls extracted → Prepared → Executed → Results
4. **State Update**: New messages appended to context
5. **Output**: AgentEndEvent with final messages
## Queue Processing Order
1. Initial steering messages (if any)
2. Main loop:
- Steering/follow-up messages (if any) - Steering/follow-up messages (if any)
- LLM call - LLM call
- Tool execution (if any) - Tool execution (if any)
- Turn end event - Turn end event
- Next turn preparation - Next turn preparation
- Check stop condition - Check stop condition
3. Follow-up messages (after loop exits) 3. **Follow-up messages** (after loop exits, only if no steering)
## DATA FLOW
```
Input:
User messages → Agent.normalizePromptInput() → AgentLoop
LLM Call:
AgentMessage[] → transform_context() → convert_to_llm() →
LLM.stream() → AssistantMessage
Tool Execution:
ToolCall[] → prepareToolCall() →
before_tool_call? → execute() → after_tool_call? →
ToolResultMessage[]
Output:
AgentEndEvent(messages) → Session.appendMessage() → User promise
```
## EXECUTION MODES
### Sequential (EXECUTION_SEQUENTIAL)
```
ToolCall1 → ToolCall2 → ToolCall3
│ │ │
▼ ▼ ▼
Result1 Result2 Result3
```
### Parallel (EXECUTION_PARALLEL)
```
ToolCall1 ─┐
ToolCall2──┼→ Execute all → Wait for all → Results
ToolCall3 ─┘
```