> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agenticenv.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Create your first agent and run it in under 5 minutes

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

```bash theme={null}
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

```bash theme={null}
export OPENAI_API_KEY=sk-your-key-here
```

For Anthropic or Gemini, see [LLM Providers](/getting-started/llm-providers).

## Step 3 — Write the agent

Create `main.go`:

```go theme={null}
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

```bash theme={null}
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`](/getting-started/llm-providers) 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`](/getting-started/run) handle; call `Get` for [`*AgentRunResult`](/features/token-usage) |
| `a.Close` | Stops any embedded Temporal worker or Restate SDK endpoint, closes the in-process durable-go engine, and flushes OTLP exporters |

<Warning>
  `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](/runtimes/in-process#durability).
</Warning>

## 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](/runtimes/temporal).

```go theme={null}
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](/runtimes/temporal) 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](/runtimes/restate) and [restate-setup.md](https://github.com/agenticenv/agent-sdk-go/blob/main/restate-setup.md).

```go theme={null}
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](/runtimes/restate) for ingress, deployment URL, and Cloud options.

<Warning>
  Use **either** Temporal **or** Restate — not both on the same agent.
</Warning>

## Try the repository example

The same pattern is in the [Simple Agent](/examples/simple-agent) example. From the repository root:

```bash theme={null}
export LLM_APIKEY=your-key
export LLM_PROVIDER=openai
export LLM_MODEL=gpt-4o
go run ./examples/simple_agent "Hello"
```

See [Running Examples](/examples/running-examples) for environment variable details.

## What's next

<CardGroup cols={2}>
  <Card title="LLM Providers" icon="brain" href="/getting-started/llm-providers" horizontal>
    Configure OpenAI, Anthropic, Gemini, or a custom client
  </Card>

  <Card title="Run" icon="play" href="/getting-started/run" horizontal>
    AgentRun — Get, Done, Status, Cancel, non-blocking
  </Card>

  <Card title="Streaming" icon="wave-square" href="/getting-started/streaming" horizontal>
    Stream partial tokens and lifecycle events
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.