Go SDK

The Go wrapper gives you typed event structs, `context.Context` support, and a straightforward split between the low-level SDK and the higher-level agent API.

Install

go get

go get github.com/autohandai/agent-sdk-go

Low-level SDK

Use `NewSDK` when you want to own startup, shutdown, and every request explicitly.

Go

package main

import (
    "context"
    "fmt"
    "log"

    autohand "github.com/autohandai/agent-sdk-go"
)

func main() {
    ctx := context.Background()
    sdk := autohand.NewSDK(&autohand.Config{CWD: ".", Debug: true})

    if err := sdk.Start(ctx); err != nil {
        log.Fatal(err)
    }
    defer sdk.Close()

    events, err := sdk.StreamPrompt(ctx, &autohand.PromptParams{
        Message: "Explain what main.go is responsible for.",
    })
    if err != nil {
        log.Fatal(err)
    }

    for event := range events {
        if e, ok := event.(autohand.MessageUpdateEvent); ok {
            fmt.Print(e.Delta)
        }
    }
}

High-level agent API

Use `NewAgent` when you want a reusable session with less transport code in your app.

Go

ctx := context.Background()
agent, err := autohand.NewAgent(ctx, &autohand.Config{
    CWD: ".",
    PermissionMode: autohand.PermissionInteractive,
})
if err != nil {
    log.Fatal(err)
}
defer agent.Close()

result, err := agent.Run(ctx, "Review the repository for release risks.", nil)
if err != nil {
    log.Fatal(err)
}

fmt.Println(result.Text)

Permission responses

Go

for event := range events {
    switch e := event.(type) {
    case autohand.PermissionRequestEvent:
        if err := sdk.PermissionResponse(ctx, e.RequestID, true, autohand.ScopeOnce); err != nil {
            log.Fatal(err)
        }
    case autohand.MessageUpdateEvent:
        fmt.Print(e.Delta)
    }
}

Important event types

  • `MessageUpdateEvent` and `MessageEndEvent` for assistant output.
  • `ToolStartEvent`, `ToolUpdateEvent`, and `ToolEndEvent` for tool execution.
  • `PermissionRequestEvent` for approval pauses.
  • `ErrorEvent` for runtime or transport failures.

Notes

  • The Go SDK still uses the CLI config file for provider settings.
  • The typed event surface is a good fit for terminal UIs and long-running background jobs.
  • Use the higher-level agent API for simple app code, and the low-level SDK if you need direct runtime toggles like permission mode changes.

Next steps

  • Open [Go API](/docs/agent-sdk/go-api.html) for the reference surface.
  • Open [Handle approvals and user input](/docs/agent-sdk/io/approvals.html) for the approval loop.