Quickstart

Create a minimal agent on the in-process runtime and run a single prompt. No Temporal or Restate server required. Requirements: Go 1.26+ and an API key for at least one LLM provider. Verify your Go version with go version.

Step 1 — Create a Go module

mkdir my-agent && cd my-agent
go mod init example.com/my-agent
go get github.com/agenticenv/agent-sdk-go@latest

Step 2 — Set your API key

export OPENAI_API_KEY=sk-your-key-here

For Anthropic or Gemini, see LLM Providers.

Step 3 — Write the agent

Create main.go:

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "github.com/agenticenv/agent-sdk-go/pkg/agent"
    "github.com/agenticenv/agent-sdk-go/pkg/llm"
    "github.com/agenticenv/agent-sdk-go/pkg/llm/openai"
)

func main() {
    ctx := context.Background()

    llmClient, err := openai.NewClient(
        llm.WithAPIKey(os.Getenv("OPENAI_API_KEY")),
        llm.WithModel("gpt-4o"),
    )
    if err != nil {
        log.Fatalf("create LLM client: %v", err)
    }

    a, err := agent.NewAgent(
        agent.WithName("quickstart-agent"),
        agent.WithSystemPrompt("You are a helpful assistant."),
        agent.WithLLMClient(llmClient),
    )
    if err != nil {
        log.Fatalf("create agent: %v", err)
    }
    defer a.Close()

    agentRun, err := a.Run(ctx, "Hello! What can you help me with?", nil)
    if err != nil {
        log.Fatalf("run agent: %v", err)
    }
    result, err := agentRun.Get(ctx)
    if err != nil {
        log.Fatalf("get result: %v", err)
    }

    fmt.Println("Agent:", result.AgentName)
    fmt.Println("Model:", result.Model)
    fmt.Println("Reply:", result.Content)
}

Step 4 — Run

go run .

Expected output includes the agent name, model, and assistant reply in result.Content.

What happened

Call	What it does
`openai.NewClient`	Creates an `interfaces.LLMClient` for OpenAI
`agent.NewAgent`	Builds the agent with your prompt and LLM client; uses in-process runtime by default
`a.Run`	Starts a run and returns an `AgentRun` handle; call `Get` for `*AgentRunResult`
`a.Close`	Stops any embedded Temporal worker or Restate SDK endpoint, closes the in-process durable-go engine, and flushes OTLP exporters

defer a.Close() is always required, on every runtime — it shuts down the embedded Temporal worker / Restate SDK endpoint and flushes OTLP exporters.Durability note — runtimes differ here: on Temporal/Restate, Close does not terminate in-flight runs — they continue on the server and resume when a worker or endpoint is available again. On the in-process (local) runtime, Close does cancel every in-flight run on the durable-go engine it owns (not just this agent’s run) and waits for that cancellation to be journaled — those runs become terminal, not resumable. A graceful shutdown (Close) is therefore not equivalent to a crash for local durability purposes; only an unclean process exit (kill -9, OOM) that skips Close leaves a run genuinely resumable on restart. See In-Process durability.

Switch to Temporal (optional)

Import pkg/agent/runtime/temporal and add temporal.WithTemporalConfig to run the same agent durably. A running Temporal cluster is required — see Temporal runtime.

a, err := agent.NewAgent(
    temporal.WithTemporalConfig(&temporal.TemporalConfig{
        Host:      "localhost",
        Port:      7233,
        Namespace: "default",
        TaskQueue: "my-app",
    }),
    agent.WithName("quickstart-agent"),
    agent.WithSystemPrompt("You are a helpful assistant."),
    agent.WithLLMClient(llmClient),
)

No other code changes. The agent loop now runs as a durable Temporal workflow. See Temporal runtime for connection options including Temporal Cloud.

Switch to Restate (optional)

Import pkg/agent/runtime/restate and add restate.WithRestateConfig to run the same agent durably. A running Restate server is required — see Restate runtime and restate-setup.md.

a, err := agent.NewAgent(
    restate.WithRestateConfig(&restate.RestateConfig{
        Ingress: restate.IngressConfig{
            URL: "http://localhost:8080",
        },
        Endpoint: restate.EndpointConfig{
            ListenAddress: ":9080",
            AdminURL:      "http://localhost:9070",
        },
    }),
    agent.WithName("quickstart-agent"),
    agent.WithSystemPrompt("You are a helpful assistant."),
    agent.WithLLMClient(llmClient),
)

No other code changes. The agent loop now runs as a durable Restate invocation with an embedded SDK endpoint. See Restate runtime for ingress, deployment URL, and Cloud options.

Use either Temporal or Restate — not both on the same agent.

Try the repository example

The same pattern is in the Simple Agent example. From the repository root:

export LLM_APIKEY=your-key
export LLM_PROVIDER=openai
export LLM_MODEL=gpt-4o
go run ./examples/simple_agent "Hello"

See Running Examples for environment variable details.

What’s next

LLM Providers

Configure OpenAI, Anthropic, Gemini, or a custom client

Run

AgentRun — Get, Done, Status, Cancel, non-blocking

Streaming

Stream partial tokens and lifecycle events

Overview

Getting Started

Runtimes

Features

Advanced

Observability

Testing & Evaluation

Production

Reference Apps

Step 1 — Create a Go module

Step 2 — Set your API key

Step 3 — Write the agent

Step 4 — Run

What happened

Switch to Temporal (optional)

Switch to Restate (optional)

Try the repository example

What’s next

LLM Providers

Run

Streaming

​Step 1 — Create a Go module

​Step 2 — Set your API key

​Step 3 — Write the agent

​Step 4 — Run

​What happened

​Switch to Temporal (optional)

​Switch to Restate (optional)

​Try the repository example

​What’s next

LLM Providers

Run

Streaming

Step 1 — Create a Go module

Step 2 — Set your API key

Step 3 — Write the agent

Step 4 — Run

What happened

Switch to Temporal (optional)

Switch to Restate (optional)

Try the repository example

What’s next