Week 1 Day 4：Agent Loop - 苏格拉底教学#

// internal/agent/runtime.go
package agent

import (
	"context"
	"encoding/json"
	"fmt"
	"log/slog"
	"time"

	"yourname/agent-runtime/internal/llm"
	"yourname/agent-runtime/internal/tools"
)

// ToolCallRecord 一条工具调用记录（用于审计和debug）
type ToolCallRecord struct {
	Iteration int             // 第几轮Loop
	ToolName  string          // 调用的工具名
	Arguments json.RawMessage // 原始参数
	Result    string          // 工具返回的Output
	Error     string          // 如果有错误
	Duration  time.Duration   // 执行耗时
}

// LoopState 记录一次Agent执行的完整状态
type LoopState struct {
	Iteration       int
	Messages        []llm.Message
	ToolCallHistory []ToolCallRecord
	StartTime       time.Time
	LastError       error
}

// AgentResponse Agent执行完毕的结果
type AgentResponse struct {
	Answer          string           // 最终答案（给用户）
	TotalIterations int              // 总共循环了几次
	ToolCallHistory []ToolCallRecord // 调用链（给审计系统）
	Duration        time.Duration    // 总耗时
}

// Runtime Agent的核心运行时
type Runtime struct {
	llmClient     llm.LLMClient
	toolRegistry  *tools.Registry
	maxIterations int
	systemPrompt  string
}

// NewRuntime 创建Agent运行时
func NewRuntime(client llm.LLMClient, registry *tools.Registry, opts ...Option) *Runtime {
	r := &Runtime{
		llmClient:     client,
		toolRegistry:  registry,
		maxIterations: 10, // 安全默认值
		systemPrompt:  defaultSystemPrompt,
	}
	for _, o := range opts {
		o(r)
	}
	return r
}

// Option 功能选项（对外扩展点）
type Option func(*Runtime)

func WithMaxIterations(n int) Option {
	return func(r *Runtime) { r.maxIterations = n }
}

func WithSystemPrompt(prompt string) Option {
	return func(r *Runtime) { r.systemPrompt = prompt }
}

const defaultSystemPrompt = `You are a helpful customer support agent.
You have access to tools to look up information and create tickets.
Use tools when you need real information. When you have a complete answer, respond directly without calling any tool.`

// internal/agent/runtime.go（续）

// Run 执行Agent Loop
// 这是整个系统最核心的方法，务必彻底理解每一行
func (r *Runtime) Run(ctx context.Context, userInput string) (*AgentResponse, error) {
	// 初始化 Loop State
	state := &LoopState{
		StartTime: time.Now(),
		Messages: []llm.Message{
			{Role: "system", Content: r.systemPrompt},
			{Role: "user", Content: userInput},
		},
	}

	slog.Info("agent.run.start",
		"user_input", userInput,
		"max_iterations", r.maxIterations,
	)

	// === 主循环 ===
	for state.Iteration < r.maxIterations {
		slog.Info("agent.loop.iteration",
			"iteration", state.Iteration,
			"message_count", len(state.Messages),
		)

		// Step 1：调用LLM
		llmResp, err := r.callLLM(ctx, state)
		if err != nil {
			// LLM调用本身失败（网络、认证等），不可恢复，直接终止
			return nil, fmt.Errorf("llm call failed at iteration %d: %w", state.Iteration, err)
		}

		// Step 2：检查是否有 ToolCall
		if len(llmResp.ToolCalls) == 0 {
			// 没有工具调用 → 这是最终答案
			slog.Info("agent.run.finished",
				"iterations", state.Iteration+1,
				"duration_ms", time.Since(state.StartTime).Milliseconds(),
			)
			return &AgentResponse{
				Answer:          llmResp.Content,
				TotalIterations: state.Iteration + 1,
				ToolCallHistory: state.ToolCallHistory,
				Duration:        time.Since(state.StartTime),
			}, nil
		}

		// Step 3：把LLM的助手消息加入历史
		// 注意：OpenAI规范要求 tool_calls 这轮的 assistant 消息先加入
		state.Messages = append(state.Messages, llm.Message{
			Role:      "assistant",
			Content:   llmResp.Content,
			ToolCalls: llmResp.ToolCalls,
		})

		// Step 4：执行所有 ToolCalls（可能有多个）
		r.processToolCalls(ctx, state, llmResp.ToolCalls)

		// Step 5：iteration计数
		state.Iteration++
	}

	// 超过最大迭代次数
	slog.Warn("agent.run.max_iterations_exceeded",
		"max", r.maxIterations,
		"duration_ms", time.Since(state.StartTime).Milliseconds(),
	)
	return nil, fmt.Errorf("agent exceeded max iterations (%d)", r.maxIterations)
}

// internal/agent/runtime.go（续）

// callLLM 封装LLM调用，把当前state转换成请求格式
func (r *Runtime) callLLM(ctx context.Context, state *LoopState) (*llm.GenerateResponse, error) {
	// 把registry的工具格式化给LLM
	openaiTools := r.toolRegistry.ToOpenAIFormat()

	req := llm.GenerateRequest{
		Messages:  state.Messages,
		Tools:     openaiTools,
		// 当有工具可用时，让LLM自己决定是否调用工具
		ToolChoice: "auto",
	}

	start := time.Now()
	resp, err := r.llmClient.Generate(ctx, req)
	duration := time.Since(start)

	if err != nil {
		slog.Error("agent.llm.error",
			"iteration", state.Iteration,
			"duration_ms", duration.Milliseconds(),
			"error", err,
		)
		return nil, err
	}

	slog.Info("agent.llm.ok",
		"iteration", state.Iteration,
		"duration_ms", duration.Milliseconds(),
		"tool_calls_count", len(resp.ToolCalls),
		"has_content", resp.Content != "",
	)
	return resp, nil
}

// internal/agent/runtime.go（续）

// processToolCalls 执行所有tool_calls，把结果作为tool消息加入对话
// 每个工具调用都独立执行，互不影响
func (r *Runtime) processToolCalls(ctx context.Context, state *LoopState, calls []llm.ToolCall) {
	for _, call := range calls {
		record := ToolCallRecord{
			Iteration: state.Iteration,
			ToolName:  call.Name,
			Arguments: call.Arguments,
		}
		start := time.Now()

		slog.Info("agent.tool.execute",
			"iteration", state.Iteration,
			"tool", call.Name,
			"args", string(call.Arguments),
		)

		// 执行工具（Registry.Execute内部已经有timeout和panic recovery）
		toolResult := r.toolRegistry.Execute(ctx, call.Name, call.Arguments)

		record.Duration = time.Since(start)

		// 构造要加入对话的消息内容
		var messageContent string
		if toolResult.Error != "" {
			// 工具执行失败：把错误告诉LLM，让它决定下一步
			messageContent = fmt.Sprintf("Tool execution failed: %s", toolResult.Error)
			record.Error = toolResult.Error
			slog.Warn("agent.tool.failed",
				"iteration", state.Iteration,
				"tool", call.Name,
				"error", toolResult.Error,
				"duration_ms", record.Duration.Milliseconds(),
			)
		} else {
			// 工具执行成功
			messageContent = toolResult.Output
			record.Result = toolResult.Output
			slog.Info("agent.tool.success",
				"iteration", state.Iteration,
				"tool", call.Name,
				"output_len", len(toolResult.Output),
				"duration_ms", record.Duration.Milliseconds(),
			)
		}

		// 把工具结果加入消息历史
		// OpenAI的规范：role=tool，需要带 tool_call_id
		state.Messages = append(state.Messages, llm.Message{
			Role:       "tool",
			Content:    messageContent,
			ToolCallID: call.ID, // 对应assistant消息里的call.id
		})

		// 记录到审计历史
		state.ToolCallHistory = append(state.ToolCallHistory, record)
	}
}

// internal/llm/types.go（在Day 2基础上扩展）
package llm

import "encoding/json"

// Message 对话消息（扩展版）
type Message struct {
	Role       string     `json:"role"`
	Content    string     `json:"content"`
	ToolCalls  []ToolCall `json:"tool_calls,omitempty"`  // assistant发出的工具调用
	ToolCallID string     `json:"tool_call_id,omitempty"` // tool消息回传时的ID
}

// ToolCall LLM发出的工具调用请求
type ToolCall struct {
	ID        string          `json:"id"`       // OpenAI分配的唯一ID
	Name      string          `json:"name"`     // 工具名称
	Arguments json.RawMessage `json:"arguments"` // JSON格式的参数
}

// GenerateRequest 发给LLM的请求（扩展版）
type GenerateRequest struct {
	Messages   []Message        `json:"messages"`
	Tools      []map[string]any `json:"tools,omitempty"`
	ToolChoice string           `json:"tool_choice,omitempty"` // "auto" | "none" | "required"
	RequestID  string           `json:"-"`
	Model      string           `json:"-"`
}

// GenerateResponse LLM返回的响应
type GenerateResponse struct {
	Content   string     // 文本内容（如果是final answer）
	ToolCalls []ToolCall // 工具调用列表（如果LLM决定调用工具）
}

// internal/server/handler.go（更新版）
package server

import (
	"encoding/json"
	"log/slog"
	"net/http"

	"yourname/agent-runtime/internal/agent"
)

type ChatRequest struct {
	Message   string `json:"message"`
	RequestID string `json:"request_id,omitempty"`
}

type ChatResponse struct {
	Answer          string                   `json:"answer"`
	TotalIterations int                      `json:"total_iterations"`
	ToolCallHistory []agent.ToolCallRecord   `json:"tool_call_history,omitempty"`
	DurationMs      int64                    `json:"duration_ms"`
}

func (s *Server) ChatHandler(w http.ResponseWriter, r *http.Request) {
	var req ChatRequest
	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
		http.Error(w, "invalid request body", http.StatusBadRequest)
		return
	}
	if req.Message == "" {
		http.Error(w, "message is required", http.StatusBadRequest)
		return
	}

	// 执行Agent Loop
	agentResp, err := s.agentRuntime.Run(r.Context(), req.Message)
	if err != nil {
		slog.Error("agent.run.error", "error", err, "request_id", req.RequestID)
		http.Error(w, "agent failed: "+err.Error(), http.StatusInternalServerError)
		return
	}

	resp := ChatResponse{
		Answer:          agentResp.Answer,
		TotalIterations: agentResp.TotalIterations,
		ToolCallHistory: agentResp.ToolCallHistory,
		DurationMs:      agentResp.Duration.Milliseconds(),
	}

	w.Header().Set("Content-Type", "application/json")
	json.NewEncoder(w).Encode(resp)
}

// cmd/api/main.go（核心部分）
package main

import (
	"yourname/agent-runtime/internal/agent"
	"yourname/agent-runtime/internal/llm"
	"yourname/agent-runtime/internal/tools"
	"yourname/agent-runtime/internal/tools/builtin"
)

func setupAgentRuntime(cfg *config.Config) *agent.Runtime {
	// 1. LLM Client（Day 2实现）
	llmClient := llm.NewOpenAIClient(cfg.OpenAIKey, cfg.ModelName)

	// 2. Tool Registry（Day 3实现）
	registry := tools.NewRegistry()
	_ = registry.Register(builtin.NewSearchKB())
	_ = registry.Register(builtin.NewCreateTicket())
	_ = registry.Register(builtin.NewGetUserInfo())

	// 3. Agent Runtime（Day 4实现）
	runtime := agent.NewRuntime(
		llmClient,
		registry,
		agent.WithMaxIterations(10),
	)

	return runtime
}

// 不要误解：iteration=10不是"好的Agent"的标志
// 好的Agent应该在3-5轮内完成任务
// iteration=10说明任务很复杂或者Agent陷入了问题

// 生产环境建议：监控平均iteration次数
// 如果平均>5，说明prompt或工具设计有问题

// Run的ctx必须贯穿所有子调用
// 如果用户HTTP请求超时，ctx会被cancel
// callLLM里的LLM调用会中断
// processToolCalls里的工具调用也会中断
// Agent不会继续循环浪费资源

func (r *Runtime) Run(ctx context.Context, ...) {
    for {
        llmResp, err := r.callLLM(ctx, state)   // ctx传入
        r.processToolCalls(ctx, state, ...)        // ctx传入
    }
}

// internal/agent/runtime_test.go
func TestRun_DirectAnswer_NoToolCalls(t *testing.T) {
    // mock LLMClient 返回没有tool_calls的response
    // 验证：iteration=1，answer非空，ToolCallHistory为空
}

func TestRun_SingleToolCall_ThenAnswer(t *testing.T) {
    // mock LLMClient 第1次返回tool_call，第2次返回final answer
    // 验证：iteration=2，ToolCallHistory长度=1
}

func TestRun_MaxIterationsExceeded(t *testing.T) {
    // mock LLMClient 永远返回tool_call
    // 验证：返回error，包含"max iterations"
}

func TestRun_ToolError_ContinuesLoop(t *testing.T) {
    // Registry返回tool error
    // 验证：error被加入messages，loop继续，不提前终止
}

// 简单实现
toolCallCount := map[string]int{}
for _, r := range state.ToolCallHistory {
    toolCallCount[r.ToolName]++
}
if toolCallCount[call.Name] >= 3 {
    state.Messages = append(state.Messages, llm.Message{
        Role:    "user",
        Content: fmt.Sprintf("Warning: You have already called '%s' %d times. Please provide your final answer now.", call.Name, toolCallCount[call.Name]),
    })
}

// 这样是安全的（两个请求用同一个runtime）
go runtime.Run(ctx1, "用户A的问题")
go runtime.Run(ctx2, "用户B的问题")

var rawCheck map[string]any
if err := json.Unmarshal(call.Arguments, &rawCheck); err != nil {
    // 直接加错误消息，跳过工具执行
    state.Messages = append(state.Messages, llm.Message{
        Role:    "tool",
        Content: "Error: invalid JSON arguments for " + call.Name,
        ToolCallID: call.ID,
    })
    continue
}

if strings.TrimSpace(agentResp.Answer) == "" {
    agentResp.Answer = "I was unable to find a complete answer. Please try rephrasing your question."
}

// algo/reverse_linked_list.go
package algo

type ListNode struct {
    Val  int
    Next *ListNode
}

// 迭代法：O(n) / O(1)
func reverseList(head *ListNode) *ListNode {
    var prev *ListNode
    curr := head
    for curr != nil {
        next := curr.Next // 保存下一个节点（关键！否则断链）
        curr.Next = prev  // 反转指针
        prev = curr       // prev前进
        curr = next       // curr前进
    }
    return prev
}

// 递归法（理解递归思维）
func reverseListRecursive(head *ListNode) *ListNode {
    if head == nil || head.Next == nil {
        return head
    }
    // 递归到尾部
    newHead := reverseListRecursive(head.Next)
    // 反转指针
    head.Next.Next = head
    head.Next = nil
    return newHead
}

// algo/linked_list_cycle.go
package algo

// Floyd龟兔算法：O(n) / O(1)
func hasCycle(head *ListNode) bool {
    slow, fast := head, head
    for fast != nil && fast.Next != nil {
        slow = slow.Next        // 慢指针：一次走1步
        fast = fast.Next.Next   // 快指针：一次走2步
        if slow == fast {        // 相遇 → 有环
            return true
        }
    }
    return false // fast走到nil → 无环
}

// algo/merge_sorted_lists.go
package algo

// 迭代法：O(m+n) / O(1)
func mergeTwoLists(list1 *ListNode, list2 *ListNode) *ListNode {
    // dummy哨兵节点：避免处理head为空的特殊情况
    dummy := &ListNode{}
    curr := dummy

    for list1 != nil && list2 != nil {
        if list1.Val <= list2.Val {
            curr.Next = list1
            list1 = list1.Next
        } else {
            curr.Next = list2
            list2 = list2.Next
        }
        curr = curr.Next
    }

    // 把剩余部分直接接上
    if list1 != nil {
        curr.Next = list1
    } else {
        curr.Next = list2
    }

    return dummy.Next
}