Run

Use Agent.Run when you want a final result without live token deltas. It returns an AgentRun handle immediately; the work continues in the background until you wait with Get or Done.

AgentRun methods

Method	Purpose
`ID()`	Stable run id — available immediately; persist before waiting when crash-durability matters
`Status(ctx)`	Current lifecycle status (`running`, `completed`, `failed`, `cancelled`, …)
`Cancel(ctx)`	Request cancellation of the agent run (not the same as cancelling a `Get` context)
`Done()`	Channel closed when the run finishes (success or failure)
`Get(ctx)`	Block until finished; return the result. Cancelling `ctx` only unblocks `Get` — use `Cancel` to stop the run

Wait for the result

Call Get right after Run — it waits until the agent finishes:

agentRun, err := a.Run(ctx, "Hello! What can you help me with?", nil)
if err != nil {
    return err
}
result, err := agentRun.Get(ctx)
if err != nil {
    return err
}
fmt.Println(result.Content)

Full walkthrough: Quickstart. Runnable example: Simple Agent.

Non-blocking Run

Wait on Done() (or multiplex with other work), poll Status, optionally Cancel, then Get:

agentRun, err := a.Run(ctx, "Summarize this document", nil)
if err != nil {
    return err
}
_ = agentRun.ID() // persist before waiting when crash-durability matters

polls := 0
for {
    select {
    case <-agentRun.Done():
        result, err := agentRun.Get(ctx)
        if err != nil {
            return err
        }
        fmt.Println(result.Content)
        return nil
    case <-time.After(5 * time.Second):
        polls++
        st, _ := agentRun.Status(ctx)
        fmt.Println("still running, status:", st)
        if polls >= 2 {
            _ = agentRun.Cancel(ctx) // then Done closes and Get returns
        }
    }
}

Cancelling the Get context only unblocks the waiter — use AgentRun.Cancel to cancel the agent run itself. Full example with approvals: Non-blocking Run.

Reconnect with GetAgentRun

On a durable runtime (Temporal or Restate), persist agentRun.ID() before waiting. After a process crash, reconnect and wait again — the run keeps executing server-side:

run, err := a.GetAgentRun(ctx, savedRunID)
if err != nil {
    if errors.Is(err, agent.ErrRunAlreadyCompleted) {
        // Run finished while disconnected — load outcome from
        // conversation/memory, or start a new run.
        return nil
    }
    return err // including ErrRunNotFound
}
result, err := run.Get(ctx) // or <-run.Done() then Get

Cancelling the GetAgentRun or Get context does not cancel the durable run — use AgentRun.Cancel for that. After reconnect, WithTimeout (if set) starts fresh — it is not the remaining time from the original Run. Full cancel/timeout rules: Timeouts & Modes. LocalRuntime cannot reconnect after a crash (ErrRunNotFound). Full protocol: Durable Execution.

Approvals on Run

Use WithApprovalHandler for interactive tool approval during Run (same as a blocking Run + Get). Stream-based approval uses CUSTOM events on AgentStream — see Approvals.

Examples

Simple Agent

Blocking Run + Get

Non-blocking Run

Status, Cancel, Done, Get, and approvals

Streaming

AgentStream, Events, and live tokens

Overview

Getting Started

Runtimes

Features

Advanced

Observability

Testing & Evaluation

Production

Reference Apps

AgentRun methods

Wait for the result

Non-blocking Run

Reconnect with GetAgentRun

Approvals on Run

Examples

Simple Agent

Non-blocking Run

Streaming

​AgentRun methods

​Wait for the result

​Non-blocking Run

​Reconnect with GetAgentRun

​Approvals on Run

​Examples

Simple Agent

Non-blocking Run

Streaming

AgentRun methods

Wait for the result

Non-blocking Run

Reconnect with GetAgentRun

Approvals on Run

Examples