第1周：Agent Runtime + Tools + API - 完整概览#

// main.go中的优雅关闭模式
sigChan := make(chan os.Signal, 1)
signal.Notify(sigChan, syscall.SIGINT, syscall.SIGTERM)
<-sigChan
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
httpServer.Shutdown(ctx)

// internal/llm/openai_client.go
type LLMClient interface {
	Generate(ctx context.Context, req GenerateRequest) (*GenerateResponse, error)
}

type GenerateRequest struct {
	Messages  []Message
	RequestID string  // trace用
	Model     string
}

type OpenAIClient struct {
	client *openai.Client
	model  string
}

func (c *OpenAIClient) Generate(ctx context.Context, req GenerateRequest) (*GenerateResponse, error) {
	// 重点：ctx里面已经有timeout信息
	// 所以OpenAI SDK会自动尊重这个timeout
	resp, err := c.client.CreateChatCompletion(ctx, openai.ChatCompletionRequest{
		Messages: convertMessages(req.Messages),
	})
	// ...
}

// internal/tools/registry.go
type ToolRegistry struct {
	tools map[string]*ToolDefinition
}

type ToolDefinition struct {
	Name        string                 `json:"name"`
	Description string                 `json:"description"`
	InputSchema map[string]interface{} `json:"input_schema"` // JSON schema
	RiskLevel   string                 `json:"risk_level"`   // low/medium/high
	Timeout     time.Duration          `json:"-"`
	Execute     func(ctx context.Context, input json.RawMessage) (interface{}, error)
}

// 使用示例
func (r *ToolRegistry) Register(def *ToolDefinition) {
	r.tools[def.Name] = def
}

func (r *ToolRegistry) Execute(ctx context.Context, name string, input json.RawMessage) (interface{}, error) {
	tool, ok := r.tools[name]
	if !ok {
		return nil, fmt.Errorf("tool not found: %s", name)
	}
	return tool.Execute(ctx, input)
}

// internal/agent/runtime.go
func (r *Runtime) Execute(ctx context.Context, userInput string) (*AgentResponse, error) {
	conversation := []Message{
		{Role: "user", Content: userInput},
	}

	for iteration := 0; iteration < r.maxIterations; iteration++ {
		// 1. 调LLM，让它判断是否需要工具
		response, err := r.llmClient.Generate(ctx, GenerateRequest{
			Messages:  conversation,
			RequestID: r.getRequestID(ctx),
		})
		if err != nil {
			return nil, fmt.Errorf("llm error: %w", err)
		}

		// 2. 检查是否有tool call
		if response.ToolCall == nil {
			// 没有工具调用，直接返回答案
			return &AgentResponse{
				Answer:     response.Content,
				ToolCalls:  []string{},
			}, nil
		}

		// 3. 执行工具
		toolResult, err := r.toolRegistry.Execute(ctx, response.ToolCall.Name, response.ToolCall.Input)
		if err != nil {
			// 工具调用失败，告诉LLM发生了什么
			conversation = append(conversation, Message{
				Role:    "assistant",
				Content: response.Content,
			})
			conversation = append(conversation, Message{
				Role:    "user",
				Content: fmt.Sprintf("Tool failed: %v. Try again.", err),
			})
			continue
		}

		// 4. 把结果送回LLM
		conversation = append(conversation, Message{
			Role:    "assistant",
			Content: response.Content,
		})
		conversation = append(conversation, Message{
			Role:    "user",
			Content: fmt.Sprintf("Tool result: %s", toolResult),
		})
	}

	return nil, fmt.Errorf("max iterations exceeded")
}

// internal/agent/output.go
type AgentAnswer struct {
	Answer           string   `json:"answer"`
	Confidence       string   `json:"confidence"`        // low/medium/high
	Sources          []string `json:"sources"`           // 信息来源
	ToolCalls        []string `json:"tool_calls"`        // 调用过的工具
	NeedsHumanReview bool     `json:"needs_human_review"` // 是否需要人工审核
}

// 验证规则
func (a *AgentAnswer) Validate() error {
	if !contains([]string{"low", "medium", "high"}, a.Confidence) {
		return fmt.Errorf("invalid confidence: %s", a.Confidence)
	}

	// 规则：sources为空时，confidence不能是high
	if len(a.Sources) == 0 && a.Confidence == "high" {
		return fmt.Errorf("cannot be high confidence without sources")
	}

	// 规则：写操作必须需要human review
	if contains(a.ToolCalls, "create_ticket") && !a.NeedsHumanReview {
		return fmt.Errorf("write operations must have NeedsHumanReview=true")
	}

	return nil
}

// internal/retry/retry.go
type Config struct {
	MaxRetries int
	InitialBackoff time.Duration
	MaxBackoff     time.Duration
}

func Do(ctx context.Context, cfg Config, fn func() error) error {
	backoff := cfg.InitialBackoff

	for attempt := 0; attempt < cfg.MaxRetries; attempt++ {
		// 检查是否已经超时
		select {
		case <-ctx.Done():
			return ctx.Err()
		default:
		}

		err := fn()
		if err == nil {
			return nil
		}

		// 某些错误不应该retry
		if !isRetryable(err) {
			return err
		}

		// 计算下次retry的等待时间
		if attempt < cfg.MaxRetries-1 {
			select {
			case <-time.After(backoff):
				backoff = time.Duration(float64(backoff) * 1.5)
				if backoff > cfg.MaxBackoff {
					backoff = cfg.MaxBackoff
				}
			case <-ctx.Done():
				return ctx.Err()
			}
		}
	}

	return fmt.Errorf("max retries exceeded")
}

// Idempotency key去重
func (r *ToolRegistry) ExecuteIdempotent(ctx context.Context, idempotencyKey string, name string, input json.RawMessage) (interface{}, error) {
	// 检查是否已经执行过
	if result, exists := r.cache.Get(idempotencyKey); exists {
		return result, nil
	}

	result, err := r.Execute(ctx, name, input)
	if err == nil {
		r.cache.Set(idempotencyKey, result)
	}
	return result, err
}