【AI云原生】16、Go语言实战：从零构建可定制API Agent

一、引言：API Agent的价值与技术选型

在云原生与AI融合的趋势下，可定制API Agent已成为连接自然语言交互与企业服务的核心枢纽。它能够像人类操作员一样理解用户意图、调用合适的API工具、编排复杂工作流，并最终返回直观结果。相较于Python等语言，Go语言凭借其并发性能优异、部署轻量、类型安全等特性，成为构建高性能API Agent的理想选择。

本文将系统整合"用Go语言手写可定制API Agent"的上下篇内容，从核心架构设计到生产级功能实现，完整呈现一个可直接运行的API Agent系统。通过本文，读者将掌握工具注册、意图解析、工作流引擎、HTTP调用等关键模块的实现，并理解如何应对参数错误自修复、轮次控制等实战挑战。

二、核心架构设计：模块化与分层解耦

可定制API Agent的核心优势在于分层解耦的架构设计，通过将复杂系统拆分为独立模块，实现"功能复用、灵活扩展、便于维护"的目标。其整体架构如图1所示：

2.1 核心模块说明

1. API网关：负责请求验证、路由分发、流量控制，是Agent与外部交互的入口。
2. 意图解析器：将用户自然语言输入转换为结构化指令（工具名称+参数），核心依赖LLM或规则引擎。
3. 工具注册中心：管理所有API工具的元数据（端点、方法、参数、认证信息等），支持动态注册与查询。
4. 工作流引擎：处理多工具调用的依赖关系，支持顺序执行、条件分支等复杂逻辑，并维护上下文状态。
5. 响应生成器：将API调用的结构化结果转换为自然语言，确保输出符合用户理解习惯。

三、核心模块实现（上篇）：基础框架搭建

3.1 数据结构定义

首先定义系统核心数据结构，包括API工具、工作流、认证配置等：

package main

import (
	"encoding/json"
	"fmt"
	"log"
	"net/http"
	"regexp"
	"strings"
	"sync"
	"time"
)

// ToolRequest 工具调用请求结构
type ToolRequest struct {
   
   
	ToolName string                 `json:"tool_name"`
	Params   map[string]interface{
   
   } `json:"params"`
}

// APITool API工具定义
type APITool struct {
   
   
	Name        string                 `json:"name"`        // 工具名称（唯一标识）
	Description string                 `json:"description"` // 功能描述
	Endpoint    string                 `json:"endpoint"`    // API端点URL
	Method      string                 `json:"method"`      // HTTP方法（GET/POST等）
	Parameters  map[string]interface{
   
   } `json:"parameters"`  // 参数定义
	Auth        AuthConfig             `json:"auth"`        // 认证配置
}

// AuthConfig 认证配置
type AuthConfig struct {
   
   
	Type   string `json:"type"`   // 认证类型：none, api_key, oauth2
	APIKey string `json:"api_key"` // API密钥（仅当type=api_key时使用）
}

// WorkflowNode 工作流节点
type WorkflowNode struct {
   
   
	ToolName    string            `json:"tool_name"`    // 调用的工具名称
	InputParams map[string]string `json:"input_params"` // 参数映射：{"api_param": "workflow_var"}
	OutputKey   string            `json:"output_key"`   // 输出存储的变量名
}

// Workflow 工作流定义
type Workflow struct {
   
   
	ID    string         `json:"id"`    // 工作流唯一标识
	Nodes []WorkflowNode `json:"nodes"` // 节点列表（按执行顺序）
}

// APIAgent API Agent核心结构
type APIAgent struct {
   
   
	registry      *ToolRegistry   // 工具注册中心
	workflows     map[string]Workflow // 工作流存储
	intentParser  *IntentParser   // 意图解析器
	workflowCache map[string]Workflow // 工作流缓存（加速查询）
}

3.2 工具注册中心：管理API工具元数据

工具注册中心是Agent的"工具库"，负责管理所有可用API工具的元数据，支持动态注册、查询与列表获取：

// ToolRegistry 工具注册中心
type ToolRegistry struct {
   
   
	tools map[string]APITool // 工具存储：key=工具名称
	mu    sync.RWMutex       // 读写锁（保证并发安全）
}

// NewToolRegistry 创建新工具注册中心
func NewToolRegistry() *ToolRegistry {
   
   
	return &ToolRegistry{
   
   
		tools: make(map[string]APITool),
	}
}

// Register 注册API工具
func (r *ToolRegistry) Register(tool APITool) error {
   
   
	r.mu.Lock()
	defer r.mu.Unlock()

	// 检查工具是否已存在
	if _, exists := r.tools[tool.Name]; exists {
   
   
		return fmt.Errorf("tool '%s' already registered", tool.Name)
	}

	// 验证必要字段
	if tool.Name == "" || tool.Endpoint