sdk-reference.md

SDK Reference

Lists exported types, functions, methods and key notes by package. For brevity, only externally available members and necessary comments are listed.

Package import prefix: github.com/TencentCloudAgentRuntime/ags-go-sdk

Table of Contents

• connection
• constant
• sandbox/core
• sandbox/code
• tool/code
• tool/command
• tool/filesystem

---

connection

Import: github.com/TencentCloudAgentRuntime/ags-go-sdk/connection

Types

type Config struct {
	Domain      string
	AccessToken string
	Headers     http.Header
	Proxy       *url.URL
}

Constructor

func NewConfig() *Config

Notes

• Used for connection information of various tool clients.
• Domain is in the format "<sandboxId>.<region>.tencentags.com" (generated by sandbox/core).
• Domain in tool/code and other Clients includes the corresponding port, in the format "{port}-{sandboxId}.{region}.tencentags.com"
• AccessToken is issued internally by core.Create/Connect.

---

constant

Import: github.com/TencentCloudAgentRuntime/ags-go-sdk/constant

Constants

const (
	AgentSandboxInternalEndpoint = "ags.internal.tencentcloudapi.com"
	EnvdPort                     = 49983
	CodePort                     = 49999
)

---

sandbox/core

Import: github.com/TencentCloudAgentRuntime/ags-go-sdk/sandbox/core

Types

type Core struct {
	SandboxId        string
	ConnectionConfig *connection.Config
	// Internal fields: client
}

Methods

func NewCore(client *ags.Client, sandboxId string, cfg *connection.Config) *Core

Creates a new Core instance.

func (c *Core) GetHost(port int) string

Generates a domain in the format "{port}-{sandboxId}.{region}.tencentags.com".

func (c *Core) Kill(ctx context.Context) error

Terminates the sandbox instance.

func (c *Core) SetTimeoutSeconds(ctx context.Context, seconds int) error

Sets the sandbox timeout in seconds.

func (c *Core) GetInfo(ctx context.Context) (*ags.SandboxInstance, error)

Gets detailed sandbox information.

Top-level Functions (Operations)

func Create(ctx context.Context, toolName string, opts ...CreateOption) (*Core, error)

Creates a new sandbox and returns a Core instance.

func Connect(ctx context.Context, sandboxId string, opts ...ConnectOption) (*Core, error)

Connects to an existing sandbox and returns a Core instance.

func List(ctx context.Context, opts ...ListOption) ([]*ags.SandboxInstance, error)

Lists all sandbox instances.

func Kill(ctx context.Context, sandboxId string, opts ...KillOption) error

Destroys the specified sandbox.

Options (Option Interfaces)

type ClientOption interface {
	CreateOption
	ConnectOption
	ListOption
	KillOption
}

func WithClient(client *ags.Client) ClientOption

Sets the AGS client instance. This option takes precedence over WithCredential and WithRegion.

func WithCredential(cred common.CredentialIface) ClientOption

Sets Tencent Cloud credentials. Must be used with WithRegion to create a new AGS client.

func WithRegion(region string) ClientOption

Sets the Tencent Cloud region. Must be used with WithCredential to create a new AGS client. Default region is ap-guangzhou.

Notes

• When WithClient is not specified, both WithCredential and WithRegion must be provided to create an AGS Client.
• The Core returned by Create has built-in ConnectionConfig, which can be used to initialize various tool clients.

---

sandbox/code

Import: github.com/TencentCloudAgentRuntime/ags-go-sdk/sandbox/code

Types

type Sandbox struct {
	*core.Core
	Files    *filesystem.Client
	Commands *command.Client
	Code     *code.Client
}

Code sandbox instance, embeds core.Core and provides three tool clients.

Operations

func Create(ctx context.Context, toolName string, opts ...CreateOption) (*Sandbox, error)

Creates a sandbox and initializes Files/Commands/Code three clients.

func Connect(ctx context.Context, sandboxId string, opts ...ConnectOption) (*Sandbox, error)

Connects to an existing sandbox and initializes three clients.

func List(ctx context.Context, opts ...ListOption) ([]*ags.SandboxInstance, error)

Lists all sandbox instances.

func Kill(ctx context.Context, sandboxId string, opts ...KillOption) error

Destroys the specified sandbox.

Options

type ClientOption interface {
	CreateOption
	ConnectOption
	ListOption
	KillOption
}

func WithClient(client *ags.Client) ClientOption
func WithCredential(cred common.CredentialIface) ClientOption
func WithRegion(region string) ClientOption

Options are similar to those in sandbox/core, passed through to underlying core operations.

---

tool/code (Remote Code Execution)

Import: github.com/TencentCloudAgentRuntime/ags-go-sdk/tool/code

Client

type Client struct {
	// Internal fields: config, httpClient
}

func New(cfg *connection.Config) *Client

Creates a new code execution client.

Methods

func (c *Client) RunCode(ctx context.Context, code string, config *RunCodeConfig, onOutput *OnOutputConfig) (*Execution, error)

Executes code and returns execution results.

• If config sets both Language and ContextId, an error will be returned.
• Default Language=python (when neither Language nor ContextId is specified).
• onOutput is optional: real-time output callback (stdout/stderr), does not affect the final aggregated result.

func (c *Client) CreateCodeContext(ctx context.Context, config *CreateCodeContextConfig) (*CodeContext, error)

Creates a code execution context.

Configuration Types

type RunCodeConfig struct {
	Language  string
	ContextId string
	Envs      map[string]string
}

Code execution configuration.

type OnOutputConfig struct {
	OnStdout func(string)
	OnStderr func(string)
}

Output callback configuration:

• OnStdout: Receives real-time stdout text
• OnStderr: Receives real-time stderr text
• If nil is passed or any callback is nil, the corresponding callback will not be called; the final Execution.Logs still retains aggregated logs

type CreateCodeContextConfig struct {
	Cwd      string
	Language string
}

Context creation configuration. Default Cwd="/home/user", Language="python".

Result Types

type Execution struct {
	Results        []Result
	Logs           Logs
	Error          *ExecutionError
	ExecutionCount *int
}

Code execution result summary.

type Result struct {
	Text         *string
	Html         *string
	Markdown     *string
	Svg          *string
	Png          *string
	Jpeg         *string
	Pdf          *string
	Latex        *string
	Javascript   *string
	Json         map[string]any
	Data         map[string]any
	Chart        map[string]any
	IsMainResult bool
	Extra        map[string]any
}

Single execution result, supports multiple formats.

type Logs struct {
	Stdout []string
	Stderr []string
}

Standard output and standard error logs.

type ExecutionError struct {
	Name      string
	Value     string
	Traceback string
}

Execution error information.

type CodeContext struct {
	Id       string
	Language string
	Cwd      string
}

Code context information.

---

tool/command (Command/Process)

Import: github.com/TencentCloudAgentRuntime/ags-go-sdk/tool/command

Client

type Client struct {
	// Internal fields: config, httpClient, rpcClient
}

func New(cfg *connection.Config) (*Client, error)

Creates a new command execution client.

Methods

func (c *Client) Run(ctx context.Context, cmd string, config *ProcessConfig, onOutput *OnOutputConfig) (*Result, error)

Convenient foreground command execution, aggregates stdout/stderr and exit code.

func (c *Client) Start(ctx context.Context, cmd string, config *ProcessConfig, onOutput *OnOutputConfig) (*Handle, error)

Background command execution, returns Handle.

func (c *Client) Connect(ctx context.Context, pid uint32, onOutput *OnOutputConfig) (*Handle, error)

Connects to an existing process.

func (c *Client) List(ctx context.Context) ([]ProcessInfo, error)

Lists currently running processes.

Configuration Types

type ProcessConfig struct {
	User string
	Args []string
	Envs map[string]string
	Cwd  *string
}

Process configuration. User defaults to "user", only allows "user" or "root".

type OnOutputConfig struct {
	OnStdout func([]byte)
	OnStderr func([]byte)
}

Output callback configuration.

Result Types

type ProcessInfo struct {
	Pid  uint32
	Tag  *string
	Cmd  string
	Args []string
	Envs map[string]string
	Cwd  *string
}

Process information.

type ProcessResult struct {
	ExitCode int32
	Error    *string
}

Process execution result.

type Result struct {
	ExitCode int32
	Stdout   []byte
	Stderr   []byte
	Error    *string
}

Aggregated foreground execution result.

Handle

type Handle struct {
	Pid uint32
	// Internal fields: cancel, stream, client, onStdout, onStderr
}

Process handle for controlling and monitoring processes.

Methods

func (h *Handle) Wait(ctx context.Context) (*ProcessResult, error)

Waits for the process to end and returns the result.

func (h *Handle) Kill(ctx context.Context) error

Sends SIGKILL signal to terminate the process.

func (h *Handle) Disconnect(ctx context.Context) error

Disconnects without terminating the process.

func (h *Handle) SendInput(ctx context.Context, pid uint32, stdin []byte) error

Sends input to the process.

func (h *Handle) SendSignal(ctx context.Context, pid uint32, sig process.Signal) error

Sends a signal to the process. Signal values e.g.: 15 (SIGTERM), 9 (SIGKILL).

---

tool/filesystem (Filesystem)

Import: github.com/TencentCloudAgentRuntime/ags-go-sdk/tool/filesystem

Client

type Client struct {
	// Internal fields: config, httpClient, rpcClient
}

func New(cfg *connection.Config) (*Client, error)

Creates a new filesystem client.

Methods

func (c *Client) Read(ctx context.Context, path string, config *ReadConfig) (io.Reader, error)

Reads file content.

func (c *Client) Write(ctx context.Context, path string, data io.Reader, config *WriteConfig) (*WriteInfo, error)

Writes to a file.

func (c *Client) List(ctx context.Context, path string, config *ListConfig) ([]EntryInfo, error)

Lists directory contents.

func (c *Client) Exists(ctx context.Context, path string, config *ExistsConfig) (bool, error)

Checks if a file or directory exists.

func (c *Client) GetInfo(ctx context.Context, path string, config *GetInfoConfig) (*EntryInfo, error)

Gets detailed file or directory information.

func (c *Client) Remove(ctx context.Context, path string, config *RemoveConfig) error

Removes a file or directory.

func (c *Client) Rename(ctx context.Context, oldPath, newPath string, config *RenameConfig) error

Renames or moves a file/directory.

func (c *Client) MakeDir(ctx context.Context, path string, config *MakeDirConfig) (bool, error)

Creates a directory. Returns true if creation was successful.

Types

type FileType string

const (
	File FileType = "file"
	Dir  FileType = "dir"
)

File type constants.

type WriteInfo struct {
	Name string
	Type *FileType
	Path string
}

Basic information returned by write operations.

type EntryInfo struct {
	WriteInfo
	Size          int64
	Mode          int
	Permissions   string
	Owner         string
	Group         string
	ModifiedTime  time.Time
	SymlinkTarget *string
}

Detailed file or directory information.

Event Types (Reserved)

type FilesystemEventType string

const (
	EventCreate FilesystemEventType = "create"
	EventWrite  FilesystemEventType = "write"
	EventRemove FilesystemEventType = "remove"
	EventRename FilesystemEventType = "rename"
	EventChmod  FilesystemEventType = "chmod"
)

Filesystem event types (currently reserved functionality).

Configuration Types

All filesystem operation configuration types:

type ReadConfig struct{ User string }
type WriteConfig struct{ User string }
type ListConfig struct{ Depth int; User string }
type ExistsConfig struct{ User string }
type GetInfoConfig struct{ User string }
type RemoveConfig struct{ User string }
type RenameConfig struct{ User string }
type MakeDirConfig struct{ User string }

Notes

• All *Config.User only allows "user" or "root"; defaults to "user" when empty.
• Read/Write use HTTP /files endpoint; others use RPC interface.
• ListConfig.Depth specifies recursion depth, default is 1.