Skip to content

Go SDK

Set up your agent

Give your coding agent a Steel browser and the Steel skills, so that it browses and writes Steel code the right way. Learn more

Install the Steel CLI. It signs you in and installs the skills for your coding agents.

curl -fsS https://setup.steel.dev | sh

Or send this prompt to your coding agent, and it does the same:

Read https://setup.steel.dev/install.md and follow it to set up Steel for this coding client.
Then continue my requested task using the installed Steel skill.

Set up your agent →

The Steel SDK for Go is the module github.com/steel-dev/sdk/go, imported as steel. It gives your code methods for the endpoints of the Steel API, and it retries failed requests and pages through lists for you. The API reference shows the call for each endpoint.

Install

Each Go program in these docs is the main.go of a module. Create the module, then add the SDK:

go mod init example
go get github.com/steel-dev/sdk/go

The SDK needs Go 1.22 or later. Import it as steel:

import (
	"github.com/steel-dev/sdk/go"
)

Create a client

steel.NewClient() reads your API key from the STEEL_API_KEY environment variable. To change the key or another setting, pass options from the option package.

import (
	"os"

	"github.com/steel-dev/sdk/go"
	"github.com/steel-dev/sdk/go/option"
)

client := steel.NewClient(
	option.WithSteelAPIKey(os.Getenv("STEEL_API_KEY")),
)
OptionDefaultMeaning
option.WithSteelAPIKeySTEEL_API_KEYThe API key.
option.WithBaseURLSTEEL_BASE_URL, then https://api.steel.devThe URL of the API. Change it to use a self-hosted Steel Browser.
option.WithMaxRetries2How many times the SDK retries a request that failed.
option.WithRequestTimeoutnoneHow long each attempt of a request can take.
option.WithHeadernoneA header to send with the request.
option.WithHTTPClientan http.Client that waits at most 10 minutes for response headersThe HTTP client that sends the requests.
option.WithMiddlewarenoneA function that runs around each request, for example to log it.

The STEEL_CUSTOM_HEADERS environment variable adds headers to every request. Write one Name: value pair on each line.

You can pass the same options to a single method call. An option on a call overrides the option on the client.

Create a session

This program creates a session, prints its ID, and releases it. A session runs until you release it or until it times out, so release it in a defer.

main.go
package main

import (
	"context"
	"fmt"
	"log"

	"github.com/steel-dev/sdk/go"
)

func main() {
	if err := run(context.Background()); err != nil {
		log.Fatal(err)
	}
}

func run(ctx context.Context) error {
	client := steel.NewClient()
	session, err := client.Sessions.New(ctx, steel.SessionNewParams{})
	if err != nil {
		return err
	}
	defer func() {
		if _, err := client.Sessions.Release(ctx, session.ID); err != nil {
			log.Print(err)
		}
	}()

	fmt.Println(session.ID)
	return nil
}

Run the program:

go run .

The program prints the session's ID.

ee60f12b-35e5-49f1-9eb4-6a86766a190a

To drive the session's browser, connect a CDP (Chrome DevTools Protocol) client to session.WebsocketURL. The URL holds a token for the session, so the client needs no API key.

Wrap each request field in steel.F. The wrapper marks the field as set, so the SDK can tell a set field from a zero value. The SDK does not send a field without the wrapper. Use steel.Null[T]() to send null.

params := steel.SessionListParams{
	Status: steel.F(steel.SessionListParamsStatusLive),
}

Session configuration lists every option of a new session.

Retries and timeouts

The SDK retries a request twice, with a short exponential backoff, after one of these failures:

  • a connection error
  • 408 Request Timeout
  • 409 Conflict
  • 429 Too Many Requests
  • a status of 500 or higher

A response with the x-should-retry header overrides this rule.

A request has no time limit by default. Set one for the whole call, retries included, with the context. Set one for each attempt with option.WithRequestTimeout.

import (
	"time"

	"github.com/steel-dev/sdk/go/option"
)

ctx, cancel := context.WithTimeout(ctx, 5*time.Minute)
defer cancel()

session, err := client.Sessions.New(
	ctx,
	steel.SessionNewParams{},
	option.WithRequestTimeout(20*time.Second),
	option.WithMaxRetries(5),
)

Handle errors

Every method returns an error as its last value. When the API returns a status outside 2xx, the error is a *steel.Error. It holds StatusCode, the *http.Request, the *http.Response and the response's JSON body. Use errors.As to read it:

import "errors"

_, err := client.Sessions.New(ctx, steel.SessionNewParams{})
if err != nil {
	var apierr *steel.Error
	if errors.As(err, &apierr) {
		fmt.Println(apierr.StatusCode)
		fmt.Println(string(apierr.DumpResponse(true)))
	}
	return err
}

For other failures, the method returns the underlying error. When the network fails, for example, you get a *url.Error.

Errors lists the error codes and messages of the API.

Pagination

client.Sessions.List returns its results in pages. ListAutoPaging reads every item and fetches the next page when it needs it:

iter := client.Sessions.ListAutoPaging(ctx, steel.SessionListParams{
	Status: steel.F(steel.SessionListParamsStatusLive),
})
for iter.Next() {
	session := iter.Current()
	fmt.Println(session.ID, "started at", session.CreatedAt)
}
if err := iter.Err(); err != nil {
	return err
}

To read one page at a time, call List, then GetNextPage() on each page:

page, err := client.Sessions.List(ctx, steel.SessionListParams{})
for page != nil {
	for _, session := range page.Sessions {
		fmt.Println(session.ID)
	}
	page, err = page.GetNextPage()
}
if err != nil {
	return err
}

Methods

The Go SDK has the methods of the other SDKs, with Go names. Groups of methods are fields of the client, such as client.Sessions and client.Profiles. create is New and retrieve is Get, so sessions.create is client.Sessions.New. Each method takes a context.Context, then the path parameters, then a params struct.

The API reference documents each endpoint and its parameters. The SDK's own list of methods is api.md, and the types are on pkg.go.dev.