Go SDK Usage

Explore practical examples for interacting with the Lybic platform using the Go SDK.

This guide provides examples for using the Lybic Go SDK to interact with the Lybic platform.

Getting Started

Client Initialization

The Lybic Go SDK provides a simple way to initialize the client. You can create a client with default configuration or customize it with your settings.

Basic Initialization:

package main

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

func main() {
    ctx := context.Background()
    
    // Create a client with default configuration
    // The SDK will read from environment variables:
    // - LYBIC_ORG_ID: Organization ID
    // - LYBIC_API_KEY: API authentication key
    // - LYBIC_ENDPOINT: API endpoint (default: https://api.lybic.cn)
    client, err := lybic.NewClient(nil)
    if err != nil {
        fmt.Printf("Error creating client: %v\n", err)
        return
    }
    
    // Use the client...
}

Custom Configuration:

config := lybic.NewConfig()
config.OrgId = "your-org-id"
config.ApiKey = "your-api-key"
config.Endpoint = "https://api.lybic.cn" // Optional, defaults to https://api.lybic.cn
config.Timeout = 30 // Optional, timeout in seconds (default: 10)

client, err := lybic.NewClient(config)
if err != nil {
    fmt.Printf("Error creating client: %v\n", err)
    return
}

Configuration with Extra Headers and Custom Logger:

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",
    },
    // Optionally provide a custom logger
    // Logger: yourCustomLogger,
}

client, err := lybic.NewClient(config)
if err != nil {
    fmt.Printf("Error creating client: %v\n", err)
    return
}

Platform API Examples

Here are examples of how to use the SDK to interact with various Lybic platform features.

Sandbox Management

Sandboxes are on-demand, isolated environments for running your GUI-based agents.

List Sandboxes

Retrieve a list of all your available sandboxes.

ctx := context.Background()
sandboxes, err := client.ListSandboxes(ctx)
if err != nil {
    fmt.Printf("Error listing sandboxes: %v", err)
    return
}
fmt.Printf("Found %d sandboxes.\n", len(sandboxes))
for _, sandbox := range sandboxes {
    fmt.Printf("- Sandbox ID: %s, Name: %s\n", sandbox.Id, sandbox.Name)
}

Create a Sandbox

Create a new sandbox. Not all parameters need to be filled in. Parameters marked with * are optional.

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

sandbox, err := client.CreateSandbox(ctx, createDto)
if err != nil {
    fmt.Printf("Error creating sandbox: %v", err)
    return
}
fmt.Printf("Created sandbox: %+v\n", sandbox)

Get Sandbox Details

Retrieve detailed information for a specific sandbox.

sandbox, err := client.GetSandbox(ctx, "sandbox-id")
if err != nil {
    fmt.Printf("Error getting sandbox: %v\n", err)
    return
}
fmt.Printf("Sandbox info: %+v\n", sandbox)

Interact with a Sandbox

You can perform actions like mouse clicks or keyboard inputs, and take screenshots (previews).

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("Error executing computer use action:", err.Error())
    return
}
fmt.Println("Action executed successfully:", actionResult)

Get a Preview (Screenshot):

previewSandbox, err := client.PreviewSandbox(ctx, "sandbox-Id")
if err != nil {
    fmt.Printf("Error previewing sandbox: %v\n", err)
    return
}
fmt.Printf("Previewed sandbox: %+v\n", previewSandbox)

Extend a Sandbox

Extend the lifetime of a running sandbox.

var _maxLife float32 = 86400 // 24 hours in seconds
err = client.ExtendSandbox(ctx, "sandbox_id", lybic.ExtendSandboxDto{
    MaxLifeSeconds: &_maxLife,
})
if err != nil {
    fmt.Printf("Error extending sandbox: %v\n", err)
    return
}
fmt.Println("Sandbox extended successfully.")

Delete a Sandbox

Delete a sandbox when you are finished with it.

sandboxId := "your-sandbox-id"
err := client.DeleteSandbox(context.Background(), sandboxId)
if err != nil {
    fmt.Printf("Error deleting sandbox: %v", err)
    return
}
fmt.Println("Sandbox deleted successfully.")

Machine Image Management

Create snapshots of sandboxes and launch new sandboxes from saved images.

List Machine Images

Retrieve all available machine images.

images, err := client.ListMachineImages(ctx)
if err != nil {
    fmt.Println("Error listing machine images:", err)
    return
}
fmt.Printf("Available images: %+v\n", images)

Create a Machine Image

Create a new machine image from a running sandbox.

imageDto := lybic.CreateMachineImageDto{
    SandboxId: "sandbox-id",
    Name: "my-sandbox-snapshot",
}
image, err := client.CreateMachineImage(ctx, imageDto)
if err != nil {
    fmt.Println("Error creating machine image:", err)
    return
}
fmt.Printf("Created image: %s\n", image.Id)

Delete a Machine Image

Remove a machine image when no longer needed.

err := client.DeleteMachineImage(ctx, "image-id")
if err != nil {
    fmt.Println("Error deleting machine image:", err)
    return
}
fmt.Println("Machine image deleted successfully")

Sandbox File and Process Operations

Transfer files and execute commands within sandboxes.

Copy Files to/from Sandbox:

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("Error copying files:", err)
    return
}
fmt.Printf("Copy result: %+v\n", result)

Execute Process in Sandbox:

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

result, err := client.ExecSandboxProcess(ctx, "sandbox-id", processDto)
if err != nil {
    fmt.Println("Error executing process:", err)
    return
}
fmt.Printf("Process output: %s\n", result.Output)

Sandbox Status and Monitoring

Monitor sandbox status and lifecycle.

Get Sandbox Status:

status, err := client.GetSandboxStatus(ctx, "sandbox-id")
if err != nil {
    fmt.Println("Error getting sandbox status:", err)
    return
}
// Status can be: PENDING, RUNNING, STOPPED, ERROR
fmt.Printf("Sandbox status: %s\n", status.Status)

Project Management

Organize your work into projects.

List Projects

projects, err := client.ListProjects(ctx)
if err != nil {
    fmt.Println("Error listing projects:", err)
    return
}
for _, project := range projects {
    fmt.Printf("Project ID: %s, Name: %s\n", project.Id, project.Name)
}

Create a Project

projectDto := lybic.CreateProjectDto{
    Name: "My New AI Agent",
}
project, err := client.CreateProject(ctx, projectDto)
if err != nil {
    fmt.Println("Error creating project:", err)
	return
}
fmt.Println("Project created successfully:", project.Name)

Delete a Project

err = client.DeleteProject(ctx, "project-id")
if err != nil {
    fmt.Println("Failed to delete project:", err)
    return
}
fmt.Println("Project deleted successfully")

Organization Stats

Retrieve current usage statistics for your organization.

stats, err := client.GetStats(ctx)
if err != nil {
    fmt.Println("Error getting stats:", err)
    return
}
fmt.Printf("Platform Statistics: %+v\n", stats)

Using the MCP Client

For advanced agent development involving tool calling, you need to use the Model Context Protocol (MCP) client.

MCP Client Initialization

You can initialize the McpClient in multiple ways:

From Existing Client:

// Assuming 'client' is your initialized lybic.Client
mcpClient, err := lybic.NewMcpClient(ctx, lybic.McpOption{
    UsingClient: client,
})
if err != nil {
    panic(err)
}
defer mcpClient.Close()

From Configuration:

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()

Using a Specific MCP Server:

// Use a specific MCP server instead of the default one
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()

Calling Tools

The primary function of the MCP client is to call tools, such as the computer-use service.

// This example assumes you have an MCP server associated with a sandbox.
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("Error calling tool: %v", err)
    return
}
fmt.Printf("Tool call result: %+v\n", result)

MCP Server Management

You can also manage the MCP servers themselves.

List MCP Servers

servers, err := mcpClient.ListMcpServers(ctx)
if err != nil {
    fmt.Println("Error listing MCP servers:", err)
    return
}
fmt.Println("MCP Servers:")
for _, server := range servers {
    fmt.Printf("ID: %s, Name: %s\n", server.Id, server.Name)
}

Get Default MCP Server

defaultServer, err := mcpClient.GetDefaultMcpServer(ctx)
if err != nil {
    fmt.Println("Error getting default MCP server:", err)
    return
}
fmt.Printf("Default MCP Server: %s\n", defaultServer.Id)

Create an MCP Server

m, err := mcpClient.CreateMcpServer(ctx, lybic.CreateMcpServerDto{
    Name: "MCP-server-01",
})
if err != nil {
    fmt.Println("Error creating MCP server:", err)
    return
}
fmt.Println("Created MCP Server:")
fmt.Printf("ID: %s, Name: %s\n", m.Id, m.Name)

Delete an MCP Server

err := mcpClient.DeleteMcpServer(ctx, "mcp-server-id")
if err != nil {
    fmt.Println("Error deleting MCP server:", err)
    return
}
fmt.Println("MCP server deleted successfully")

Associate MCP Server with Sandbox

err := mcpClient.SetMcpServerToSandbox(ctx, "mcp-server-id", 
    lybic.SetMcpServerToSandboxResponseDto{
        SandboxId: "sandbox-id",
    })
if err != nil {
    fmt.Println("Error setting MCP server to sandbox:", err)
    return
}
fmt.Println("MCP server associated with sandbox successfully")

Get Available Tools

Retrieve the list of available tools from the MCP server.

tools, err := mcpClient.GetTools(ctx)
if err != nil {
    fmt.Println("Error getting tools:", err)
    return
}
fmt.Println("Available tools:")
for _, tool := range tools {
    fmt.Printf("- %s: %s\n", tool.Name, tool.Description)
}

Interact with a Sandbox action Struct

You can perform actions like mouse clicks or keyboard inputs, and take screenshots. The following examples demonstrate how to use various actions available in the SDK.

Execute a Mouse Click Action:

// Create a mouse click action at position (100, 200) with the left mouse button.
action := lybic.NewMouseClickAction(
    lybic.NewPixelLength(100),
    lybic.NewPixelLength(200),
    1, // 1 for left button
)

actionResult, err := client.ExecuteComputerUseAction(ctx, "sandbox-Id", lybic.ComputerUseActionDto{
    Action: action,
})
if err != nil {
    fmt.Println("Error executing mouse click action:", err.Error())
    return
}
fmt.Println("Action executed successfully:", actionResult)

Execute a Mouse Double-Click Action:

// Create a mouse double-click action at the center of the screen.
action := lybic.NewMouseDoubleClickAction(
    lybic.NewFractionalLength(1, 2), // 1/2 of screen width
    lybic.NewFractionalLength(1, 2), // 1/2 of screen height
    1, // 1 for left button
)

actionResult, err := client.ExecuteComputerUseAction(ctx, "sandbox-Id", lybic.ComputerUseActionDto{
    Action: action,
})
if err != nil {
    fmt.Println("Error executing mouse double-click action:", err.Error())
    return
}
fmt.Println("Action executed successfully:", actionResult)

Execute a Mouse Move Action:

// Move the mouse to position (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("Error executing mouse move action:", err.Error())
    return
}
fmt.Println("Action executed successfully:", actionResult)

Execute a Mouse Scroll Action:

// Scroll vertically by 10 steps at position (300, 400).
action := lybic.NewMouseScrollAction(
    lybic.NewPixelLength(300), // x position
    lybic.NewPixelLength(400), // y position
    10,  // vertical scroll steps
    0,   // horizontal scroll steps
)

actionResult, err := client.ExecuteComputerUseAction(ctx, "sandbox-Id", lybic.ComputerUseActionDto{
    Action: action,
})
if err != nil {
    fmt.Println("Error executing mouse scroll action:", err.Error())
    return
}
fmt.Println("Action executed successfully:", actionResult)

Execute a Mouse Drag Action:

// Drag the mouse from (100, 100) to (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("Error executing mouse drag action:", err.Error())
    return
}
fmt.Println("Action executed successfully:", actionResult)

Execute a Keyboard Type Action:

// Create a keyboard type action to type "Hello, Lybic!".
action := lybic.NewKeyboardTypeAction("Hello, Lybic!", false)

actionResult, err := client.ExecuteComputerUseAction(ctx, "sandbox-Id", lybic.ComputerUseActionDto{
    Action: action,
})
if err != nil {
    fmt.Println("Error executing keyboard type action:", err.Error())
    return
}
fmt.Println("Action executed successfully:", actionResult)

Execute a Keyboard Hotkey Action:

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

actionResult, err := client.ExecuteComputerUseAction(ctx, "sandbox-Id", lybic.ComputerUseActionDto{
    Action: action,
})
if err != nil {
    fmt.Println("Error executing keyboard hotkey action:", err.Error())
    return
}
fmt.Println("Action executed successfully:", actionResult)

Take a Screenshot:

// Take a screenshot of the sandbox.
action := lybic.NewScreenshotAction()

actionResult, err := client.ExecuteComputerUseAction(ctx, "sandbox-Id", lybic.ComputerUseActionDto{
    Action: action,
})
if err != nil {
    fmt.Println("Error taking screenshot:", err.Error())
    return
}
// The screenshot data will be in actionResult.
fmt.Println("Screenshot taken successfully:", actionResult)

Get a Preview (Convenience Method for Screenshot):

// This is a helper function that wraps the screenshot action.
previewSandbox, err := client.PreviewSandbox(ctx, "sandbox-Id")
if err != nil {
    fmt.Printf("Error previewing sandbox: %v\n", err)
    return
}
fmt.Printf("Previewed sandbox: %+v", previewSandbox)

Execute a Wait Action:

// Wait for 5 seconds (5000 milliseconds).
action := lybic.NewWaitAction(5000)

actionResult, err := client.ExecuteComputerUseAction(ctx, "sandbox-Id", lybic.ComputerUseActionDto{
    Action: action,
})
if err != nil {
    fmt.Println("Error executing wait action:", err.Error())
    return
}
fmt.Println("Wait action completed successfully:", actionResult)

Signal Task Finished:

// Signal that the task is finished successfully.
action := lybic.NewFinishedAction()
// Optionally, you can add a message.
// action.Message = "Task completed with flying colors!"

actionResult, err := client.ExecuteComputerUseAction(ctx, "sandbox-Id", lybic.ComputerUseActionDto{
    Action: action,
})
if err != nil {
    fmt.Println("Error sending finished signal:", err.Error())
    return
}
fmt.Println("Finished signal sent successfully:", actionResult)

Signal Task Failed:

// Signal that the task has failed.
action := lybic.NewFailedAction()
// Optionally, you can add a message.
// action.Message = "Something went wrong."

actionResult, err := client.ExecuteComputerUseAction(ctx, "sandbox-Id", lybic.ComputerUseActionDto{
    Action: action,
})
if err != nil {
    fmt.Println("Error sending failed signal:", err.Error())
    return
}
fmt.Println("Failed signal sent successfully:", actionResult)

On this page