common/ragflow/agent.go

package ragflow

import (
	"context"
	"fmt"
)

// Agent AGENT 管理
// 参考: https://ragflow.com.cn/docs/dev/http_api_reference#agent-管理

// Agent Agent 结构体
type Agent struct {
	ID          string                 `json:"id"`          // Agent ID
	Title       string                 `json:"title"`       // Agent 标题
	Description string                 `json:"description"` // Agent 描述
	Avatar      string                 `json:"avatar"`      // 头像（Base64 编码）
	CanvasType  string                 `json:"canvas_type"` // 画布类型
	CreateDate  string                 `json:"create_date"` // 创建日期（格式化字符串）
	CreateTime  int64                  `json:"create_time"` // 创建时间（Unix 时间戳）
	UpdateDate  string                 `json:"update_date"` // 更新日期（格式化字符串）
	UpdateTime  int64                  `json:"update_time"` // 更新时间（Unix 时间戳）
	UserID      string                 `json:"user_id"`     // 用户 ID
	DSL         map[string]interface{} `json:"dsl"`         // Canvas DSL 对象，定义 Agent 的工作流
}

// CreateAgentReq 创建 Agent 请求
type CreateAgentReq struct {
	Title       string                 `json:"title"`                 // 必需
	Description string                 `json:"description,omitempty"` // 可选，默认为 None
	DSL         map[string]interface{} `json:"dsl"`                   // 必需，Canvas DSL 对象
}

// UpdateAgentReq 更新 Agent 请求
type UpdateAgentReq struct {
	Title       string                 `json:"title,omitempty"`
	Description string                 `json:"description,omitempty"`
	DSL         map[string]interface{} `json:"dsl,omitempty"`
}

// ListAgentsReq 列出 Agent 请求
type ListAgentsReq struct {
	Page     int    `json:"page,omitempty"`
	PageSize int    `json:"page_size,omitempty"`
	OrderBy  string `json:"orderby,omitempty"`
	Desc     bool   `json:"desc,omitempty"`
	Title    string `json:"title,omitempty"`
	ID       string `json:"id,omitempty"`
}

// ListAgentsRes 列出 Agent 响应
// 注意：API 不返回 total 字段，仅返回 data 数组
type ListAgentsRes struct {
	Code int      `json:"code"` // 状态码，0 表示成功
	Data []*Agent `json:"data"` // Agent 列表
}

// CreateAgent 创建 Agent
// POST /api/v1/agents
func (c *Client) CreateAgent(ctx context.Context, req *CreateAgentReq) error {
	var res CommonResponse
	if err := c.request(ctx, "POST", "/api/v1/agents", req, &res); err != nil {
		return fmt.Errorf("create agent failed: %w", err)
	}
	if !res.IsSuccess() {
		return fmt.Errorf("create agent failed: %s", res.Message)
	}
	return nil
}

// UpdateAgent 更新 Agent
// PUT /api/v1/agents/{agent_id}
func (c *Client) UpdateAgent(ctx context.Context, agentID string, req *UpdateAgentReq) error {
	path := fmt.Sprintf("/api/v1/agents/%s", agentID)
	var res CommonResponse
	if err := c.request(ctx, "PUT", path, req, &res); err != nil {
		return fmt.Errorf("update agent failed: %w", err)
	}
	if !res.IsSuccess() {
		return fmt.Errorf("update agent failed: %s", res.Message)
	}
	return nil
}

// DeleteAgent 删除 Agent
// DELETE /api/v1/agents/{agent_id}
func (c *Client) DeleteAgent(ctx context.Context, agentID string) error {
	path := fmt.Sprintf("/api/v1/agents/%s", agentID)
	var res CommonResponse
	// 官方文档要求传空对象，不是 nil
	if err := c.request(ctx, "DELETE", path, map[string]interface{}{}, &res); err != nil {
		return fmt.Errorf("delete agent failed: %w", err)
	}
	if !res.IsSuccess() {
		return fmt.Errorf("delete agent failed: %s", res.Message)
	}
	return nil
}

// ListAgents 列出 Agent
// GET /api/v1/agents
func (c *Client) ListAgents(ctx context.Context, req *ListAgentsReq) (*ListAgentsRes, error) {
	path := "/api/v1/agents"
	if req != nil {
		params := map[string]interface{}{}
		if req.Page > 0 {
			params["page"] = req.Page
		}
		if req.PageSize > 0 {
			params["page_size"] = req.PageSize
		}
		if req.OrderBy != "" {
			params["orderby"] = req.OrderBy
		}
		if req.Desc {
			params["desc"] = "true"
		} else {
			params["desc"] = "false"
		}
		if req.Title != "" {
			params["title"] = req.Title
		}
		if req.ID != "" {
			params["id"] = req.ID
		}

		query := buildQueryString(params)
		if query != "" {
			path += "?" + query
		}
	}

	var res ListAgentsRes
	if err := c.request(ctx, "GET", path, nil, &res); err != nil {
		return nil, fmt.Errorf("list agents failed: %w", err)
	}
	if res.Code != 0 {
		return nil, fmt.Errorf("list agents failed: code=%d", res.Code)
	}
	return &res, nil
}