Go SDK使用指南

本指南提供了使用 Lybic Go SDK 与 Lybic 平台交互的示例。

快速开始

客户端初始化

Lybic Go SDK 提供了简单的客户端初始化方式。您可以使用默认配置或自定义设置来创建客户端。

基础初始化：

package main

import (
    "context"
    "fmt"
    "github.com/lybic/lybic-sdk-go"
)

func main() {
    ctx := context.Background()
    
    // 使用默认配置创建客户端
    // SDK 将从环境变量读取配置：
    // - LYBIC_ORG_ID: 组织 ID
    // - LYBIC_API_KEY: API 认证密钥
    // - LYBIC_ENDPOINT: API 端点 (默认: https://api.lybic.cn)
    client, err := lybic.NewClient(nil)
    if err != nil {
        fmt.Printf("创建客户端时出错: %v\n", err)
        return
    }
    
    // 使用客户端...
}

自定义配置：

config := lybic.NewConfig()
config.OrgId = "your-org-id"
config.ApiKey = "your-api-key"
config.Endpoint = "https://api.lybic.cn" // 可选，默认为 https://api.lybic.cn
config.Timeout = 30 // 可选，超时时间（秒），默认：10

client, err := lybic.NewClient(config)
if err != nil {
    fmt.Printf("创建客户端时出错: %v\n", err)
    return
}

带有额外请求头和自定义日志的配置：

config := &lybic.Config{
    OrgId:    "your-org-id",
    ApiKey:   "your-api-key",
    Endpoint: "https://api.lybic.cn",
    Timeout:  30,
    ExtraHeaders: map[string]string{
        "X-Custom-Header": "custom-value",
    },
    // 可选地提供自定义日志器
    // Logger: yourCustomLogger,
}

client, err := lybic.NewClient(config)
if err != nil {
    fmt.Printf("创建客户端时出错: %v\n", err)
    return
}

平台 API 示例

以下示例说明了如何通过 SDK 与 Lybic 平台的多种功能进行交互。

沙箱管理

沙箱是按需创建、独立隔离的云端环境，用于运行GUI智能体。

列出沙箱

检索所有可用沙箱的列表。

ctx := context.Background()
sandboxes, err := client.ListSandboxes(ctx)
if err != nil {
    fmt.Printf("列出沙箱时出错: %v", err)
    return
}
fmt.Printf("找到 %d 个沙箱。\n", len(sandboxes))
for _, sandbox := range sandboxes {
    fmt.Printf("- 沙箱 ID: %s, 名称: %s\n", sandbox.Id, sandbox.Name)
}

创建沙箱

创建新沙箱。并非所有参数都需要填写。标有 * 的参数是可选的。

_sandboxName := "Test Sandbox"
createDto := lybic.CreateSandboxDto{
    Name: &_sandboxName,
}

sandbox, err := client.CreateSandbox(ctx, createDto)
if err != nil {
    fmt.Printf("创建沙箱时出错: %v", err)
    return
}
fmt.Printf("已创建沙箱: %+v\n", sandbox)

获取沙箱详情

检索特定沙箱的详细信息。

sandbox, err := client.GetSandbox(ctx, "sandbox-id")
if err != nil {
    fmt.Printf("获取沙箱时出错: %v\n", err)
    return
}
fmt.Printf("沙箱信息: %+v\n", sandbox)

与沙箱交互

您可以执行鼠标点击或键盘输入等操作，并截取截图（预览）。

actionResult, err := client.ExecuteComputerUseAction(ctx, "sandbox-Id", lybic.ComputerUseActionDto{
    Action: lybic.ComputerUseActionDtoActionOneOf{
        ComputerUseActionDtoActionOneOfInterface: map[string]any{
            "type": "mouse:click",
            "x": map[string]any{
                "type":  "px",
                "value": 10,
            },
            "y": map[string]any{
                "type":  "px",
                "value": 10,
            },
            "button": 1,
        },
    },
})
if err != nil {
    fmt.Println("执行计算机使用操作时出错:", err.Error())
    return
}
fmt.Println("操作执行成功:", actionResult)

获取预览（截图）：

previewSandbox, err := client.PreviewSandbox(ctx, "sandbox-Id")
if err != nil {
    fmt.Printf("预览沙箱时出错: %v\n", err)
    return
}
fmt.Printf("已预览沙箱: %+v\n", previewSandbox)

延长沙箱

延长运行中沙箱的生命周期。

var _maxLife float32 = 86400 // 24 小时（秒）
err = client.ExtendSandbox(ctx, "sandbox_id", lybic.ExtendSandboxDto{
    MaxLifeSeconds: &_maxLife,
})
if err != nil {
    fmt.Printf("延长沙箱时出错: %v\n", err)
    return
}
fmt.Println("沙箱延长成功。")

删除沙箱

当您完成使用后删除沙箱。

sandboxId := "your-sandbox-id"
err := client.DeleteSandbox(context.Background(), sandboxId)
if err != nil {
    fmt.Printf("删除沙箱时出错: %v", err)
    return
}
fmt.Println("沙箱删除成功。")

机器镜像管理

创建沙箱快照并从已保存的镜像启动新沙箱。

列出机器镜像

检索所有可用的机器镜像。

images, err := client.ListMachineImages(ctx)
if err != nil {
    fmt.Println("列出机器镜像时出错:", err)
    return
}
fmt.Printf("可用镜像: %+v\n", images)

创建机器镜像

从运行中的沙箱创建新的机器镜像。

imageDto := lybic.CreateMachineImageDto{
    SandboxId: "sandbox-id",
    Name: "my-sandbox-snapshot",
}
image, err := client.CreateMachineImage(ctx, imageDto)
if err != nil {
    fmt.Println("创建机器镜像时出错:", err)
    return
}
fmt.Printf("已创建镜像: %s\n", image.Id)

删除机器镜像

删除不再需要的机器镜像。

err := client.DeleteMachineImage(ctx, "image-id")
if err != nil {
    fmt.Println("删除机器镜像时出错:", err)
    return
}
fmt.Println("机器镜像删除成功")

沙箱文件和进程操作

在沙箱中传输文件和执行命令。

复制文件到/从沙箱：

copyDto := lybic.SandboxFileCopyRequestDto{
    Files: []lybic.SandboxFileCopyRequestDtoFiles{
      {
        Src: map[string]string{
            "type":"sandboxFileLocation",
            "path":"/home/agent/file1"
        },
        Dest: map[string]any{
            "type":"httpPutLocation",
            "url":"http://example.com/accept-put-singend-file-url/file",
            "headers":map[string]any{"x-api-key":"my-api-key"}
        },
      },
  },
}

result, err := client.CopyFilesWithSandbox(ctx, "sandbox-id", copyDto)
if err != nil {
    fmt.Println("复制文件时出错:", err)
    return
}
fmt.Printf("复制结果: %+v\n", result)

在沙箱中执行进程：

processDto := lybic.SandboxProcessRequestDto{
    Executable: "/bin/ls",
    Args:[]string{"-anh"}
}

result, err := client.ExecSandboxProcess(ctx, "sandbox-id", processDto)
if err != nil {
    fmt.Println("执行进程时出错:", err)
    return
}
fmt.Printf("进程输出: %s\n", result.Output)

沙箱状态和监控

监控沙箱状态和生命周期。

获取沙箱状态：

status, err := client.GetSandboxStatus(ctx, "sandbox-id")
if err != nil {
    fmt.Println("获取沙箱状态时出错:", err)
    return
}
// 状态可能是: PENDING, RUNNING, STOPPED, ERROR
fmt.Printf("沙箱状态: %s\n", status.Status)

项目管理

项目用于组织和管理你的资源。

列出项目

projects, err := client.ListProjects(ctx)
if err != nil {
    fmt.Println("列出项目时出错:", err)
    return
}
for _, project := range projects {
    fmt.Printf("项目 ID: %s, 名称: %s\n", project.Id, project.Name)
}

创建项目

projectDto := lybic.CreateProjectDto{
    Name: "My New AI Agent",
}
project, err := client.CreateProject(ctx, projectDto)
if err != nil {
    fmt.Println("创建项目时出错:", err)
	return
}
fmt.Println("项目创建成功:", project.Name)

删除项目

err = client.DeleteProject(ctx, "project-id")
if err != nil {
    fmt.Println("删除项目失败:", err)
    return
}
fmt.Println("项目删除成功")

组织统计信息

检索组织的当前使用统计信息。

stats, err := client.GetStats(ctx)
if err != nil {
    fmt.Println("获取统计信息时出错:", err)
    return
}
fmt.Printf("平台统计: %+v\n", stats)

使用 MCP 客户端

对于涉及工具调用能力的高级智能体开发，您需要使用模型上下文协议（MCP）客户端。

MCP 客户端初始化

您可以通过多种方式初始化 McpClient：

从现有客户端：

// 假设 'client' 是您已初始化的 lybic.Client
mcpClient, err := lybic.NewMcpClient(ctx, lybic.McpOption{
    UsingClient: client,
})
if err != nil {
    panic(err)
}
defer mcpClient.Close()

从配置对象：

config := &lybic.Config{
    OrgId:    "your-org-id",
    ApiKey:   "your-api-key",
}

mcpClient, err := lybic.NewMcpClient(ctx, lybic.McpOption{
    UsingClientConfig: config,
})
if err != nil {
    panic(err)
}
defer mcpClient.Close()

使用特定的 MCP 服务器：

// 使用特定的 MCP 服务器而非默认的
doNotUseDefault := true
mcpServerId := "your-mcp-server-id"

mcpClient, err := lybic.NewMcpClient(ctx, lybic.McpOption{
    UsingClient:              client,
    DoNotUsingDefaultServer:  &doNotUseDefault,
    UsingSpecificMcpServerId: &mcpServerId,
})
if err != nil {
    panic(err)
}
defer mcpClient.Close()

调用工具

MCP 客户端的主要功能是调用工具，例如 computer-use 服务。

// 此示例假设您有一个与沙箱关联的 MCP 服务器。
args := map[string]any{
    "action": "doubleClick",
    "x":      120,
    "y":      240,
}
service := "computer-use"

result, err := mcpClient.CallTools(context.Background(), args, &service)
if err != nil {
    fmt.Printf("调用工具时出错: %v", err)
    return
}
fmt.Printf("工具调用结果: %+v\n", result)

MCP 服务器管理

您也可以管理 MCP 服务器本身。

列出 MCP 服务器

servers, err := mcpClient.ListMcpServers(ctx)
if err != nil {
    fmt.Println("列出 MCP 服务器时出错:", err)
    return
}
fmt.Println("MCP 服务器:")
for _, server := range servers {
    fmt.Printf("ID: %s, 名称: %s\n", server.Id, server.Name)
}

获取默认 MCP 服务器

defaultServer, err := mcpClient.GetDefaultMcpServer(ctx)
if err != nil {
    fmt.Println("获取默认 MCP 服务器时出错:", err)
    return
}
fmt.Printf("默认 MCP 服务器: %s\n", defaultServer.Id)

创建 MCP 服务器

m, err := mcpClient.CreateMcpServer(ctx, lybic.CreateMcpServerDto{
    Name: "MCP-server-01",
})
if err != nil {
    fmt.Println("创建 MCP 服务器时出错:", err)
    return
}
fmt.Println("已创建 MCP 服务器:")
fmt.Printf("ID: %s, 名称: %s\n", m.Id, m.Name)

删除 MCP 服务器

err := mcpClient.DeleteMcpServer(ctx, "mcp-server-id")
if err != nil {
    fmt.Println("删除 MCP 服务器时出错:", err)
    return
}
fmt.Println("MCP 服务器删除成功")

将 MCP 服务器与沙箱关联

err := mcpClient.SetMcpServerToSandbox(ctx, "mcp-server-id", 
    lybic.SetMcpServerToSandboxResponseDto{
        SandboxId: "sandbox-id",
    })
if err != nil {
    fmt.Println("将 MCP 服务器设置到沙箱时出错:", err)
    return
}
fmt.Println("MCP 服务器与沙箱关联成功")

获取可用工具

从 MCP 服务器检索可用工具列表。

tools, err := mcpClient.GetTools(ctx)
if err != nil {
    fmt.Println("获取工具时出错:", err)
    return
}
fmt.Println("可用工具:")
for _, tool := range tools {
    fmt.Printf("- %s: %s\n", tool.Name, tool.Description)
}

与沙箱的 Action 结构体进行交互

您可以执行鼠标点击或键盘输入等操作，并截图。以下示例演示如何使用 SDK 中提供的各种action(操作)。

执行鼠标点击操作：

// 在位置 (100, 200) 使用鼠标左键创建鼠标点击操作。
action := lybic.NewMouseClickAction(
    lybic.NewPixelLength(100),
    lybic.NewPixelLength(200),
    1, // 1 表示左键
)

actionResult, err := client.ExecuteComputerUseAction(ctx, "sandbox-Id", lybic.ComputerUseActionDto{
    Action: action,
})
if err != nil {
    fmt.Println("执行鼠标点击操作时出错:", err.Error())
    return
}
fmt.Println("操作执行成功:", actionResult)

执行鼠标双击操作：

// 在屏幕中心创建鼠标双击操作。
action := lybic.NewMouseDoubleClickAction(
    lybic.NewFractionalLength(1, 2), // 屏幕宽度的 1/2
    lybic.NewFractionalLength(1, 2), // 屏幕高度的 1/2
    1, // 1 表示左键
)

actionResult, err := client.ExecuteComputerUseAction(ctx, "sandbox-Id", lybic.ComputerUseActionDto{
    Action: action,
})
if err != nil {
    fmt.Println("执行鼠标双击操作时出错:", err.Error())
    return
}
fmt.Println("操作执行成功:", actionResult)

执行鼠标移动操作：

// 将鼠标移动到位置 (300, 400)。
action := lybic.NewMouseMoveAction(
    lybic.NewPixelLength(300),
    lybic.NewPixelLength(400),
)

actionResult, err := client.ExecuteComputerUseAction(ctx, "sandbox-Id", lybic.ComputerUseActionDto{
    Action: action,
})
if err != nil {
    fmt.Println("执行鼠标移动操作时出错:", err.Error())
    return
}
fmt.Println("操作执行成功:", actionResult)

执行鼠标滚动操作：

// 在位置 (300, 400) 垂直滚动 10 步。
action := lybic.NewMouseScrollAction(
    lybic.NewPixelLength(300), // x 位置
    lybic.NewPixelLength(400), // y 位置
    10,  // 垂直滚动步数
    0,   // 水平滚动步数
)

actionResult, err := client.ExecuteComputerUseAction(ctx, "sandbox-Id", lybic.ComputerUseActionDto{
    Action: action,
})
if err != nil {
    fmt.Println("执行鼠标滚动操作时出错:", err.Error())
    return
}
fmt.Println("操作执行成功:", actionResult)

执行鼠标拖动操作：

// 从 (100, 100) 拖动鼠标到 (500, 500)。
action := lybic.NewMouseDragAction(
    lybic.NewPixelLength(100),
    lybic.NewPixelLength(100),
    lybic.NewPixelLength(500),
    lybic.NewPixelLength(500),
)

actionResult, err := client.ExecuteComputerUseAction(ctx, "sandbox-Id", lybic.ComputerUseActionDto{
    Action: action,
})
if err != nil {
    fmt.Println("执行鼠标拖动操作时出错:", err.Error())
    return
}
fmt.Println("操作执行成功:", actionResult)

执行键盘输入操作：

// 创建键盘输入动作，输入 "Hello, Lybic!"。
action := lybic.NewKeyboardTypeAction("Hello, Lybic!", false)

actionResult, err := client.ExecuteComputerUseAction(ctx, "sandbox-Id", lybic.ComputerUseActionDto{
    Action: action,
})
if err != nil {
    fmt.Println("执行键盘输入操作时出错:", err.Error())
    return
}
fmt.Println("操作执行成功:", actionResult)

执行键盘快捷键操作：

// 按 Ctrl+C。
action := lybic.NewKeyboardHotkeyAction("ctrl+c")

actionResult, err := client.ExecuteComputerUseAction(ctx, "sandbox-Id", lybic.ComputerUseActionDto{
    Action: action,
})
if err != nil {
    fmt.Println("执行键盘快捷键操作时出错:", err.Error())
    return
}
fmt.Println("操作执行成功:", actionResult)

获取截图：

// 获取沙箱的截图。
action := lybic.NewScreenshotAction()

actionResult, err := client.ExecuteComputerUseAction(ctx, "sandbox-Id", lybic.ComputerUseActionDto{
    Action: action,
})
if err != nil {
    fmt.Println("获取截图时出错:", err.Error())
    return
}
// 截图数据将在 actionResult 中。
fmt.Println("截图获取成功:", actionResult)

获取预览（截图的便捷方法）：

// 这是一个对截图动作进行封装的辅助函数。
previewSandbox, err := client.PreviewSandbox(ctx, "sandbox-Id")
if err != nil {
    fmt.Printf("预览沙箱时出错: %v\n", err)
    return
}
fmt.Printf("已预览沙箱: %+v", previewSandbox)

执行等待操作：

// 等待 5 秒（5000 毫秒）。
action := lybic.NewWaitAction(5000)

actionResult, err := client.ExecuteComputerUseAction(ctx, "sandbox-Id", lybic.ComputerUseActionDto{
    Action: action,
})
if err != nil {
    fmt.Println("执行等待操作时出错:", err.Error())
    return
}
fmt.Println("等待操作完成成功:", actionResult)

标记任务完成：

// 发送任务成功完成。
action := lybic.NewFinishedAction()
// 可选地，您可以添加消息。
// action.Message = "任务完成！"

actionResult, err := client.ExecuteComputerUseAction(ctx, "sandbox-Id", lybic.ComputerUseActionDto{
    Action: action,
})
if err != nil {
    fmt.Println("标记任务完成时出错:", err.Error())
    return
}
fmt.Println("标记完成成功:", actionResult)

标记任务失败：

// 标记任务失败。
action := lybic.NewFailedAction()
// 可选地，您可以添加消息。
// action.Message = "出现了问题。"

actionResult, err := client.ExecuteComputerUseAction(ctx, "sandbox-Id", lybic.ComputerUseActionDto{
    Action: action,
})
if err != nil {
    fmt.Println("标记失败时出错:", err.Error())
    return
}
fmt.Println("标记失败成功:", actionResult)

本页内容