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

# Start and follow agent runs from a Go service

> Start a Reliant workflow from Go code, follow it to a pass or fail verdict, put its question to a person, and fire an automation, with the Go SDK.

By the end of this guide, a small Go program starts a Reliant workflow, streams its progress, asks a person the question the run is waiting on, and exits 0 or 1 with the run's verdict. It then fires an automation the same way. The [Go SDK](https://docs.reliantlabs.io/sdk/go.md) is the client the `reliant` command's own run supervision is built on, so anything it shows in the terminal your service can act on.

## Before you begin

* The `reliant` CLI, v1.21 or later, signed in ([Sign in and tokens](https://docs.reliantlabs.io/cli/sign-in.md)), on a computer with a browser to approve a token.
* Go 1.27 or newer.
* A Reliant project on a connected [machine](https://docs.reliantlabs.io/machines/overview.md). The workflow below needs no model, so it runs in any organization.

**1. Add a workflow that asks a question**

In the project, add a workflow that asks whether a release may ship and ends passed or failed on the answer:

```yaml .reliant/workflows/release-check.yaml theme={null}
name: release-check
description: Ask a person whether a release may ship, and end the run passed or failed on the answer
inputs:
  version:
    type: string
    required: true
    description: The release being checked
entry: [ask]
nodes:
  - id: ask
    type: ask_question
    args:
      metadata: '{"type":"ask_user","questions":[{"question":"Ship this release?","options":[{"label":"Ship","description":"Mark the release as cleared"},{"label":"Hold","description":"Stop the release"}]}]}'
  - id: shipped
    type: save_message
    outcome: success
    args:
      role: assistant
      content: "Release {{ inputs.version }} cleared to ship."
  - id: held
    type: save_message
    outcome: failure
    args:
      role: assistant
      display_style: warning
      content: "Release {{ inputs.version }} held: {{ nodes.ask.response }}"
edges:
  - from: ask
    cases:
      - to: shipped
        condition: nodes.ask.response == 'Ship'
    default: held
```

Run it once from the terminal to check it and let the machine sync it:

```bash terminal theme={null}
reliant workflow validate
reliant workflow run release-check --project-id <project-id> --input version=v0.0.1 --follow --exit-on-gate
```

It stops at the question; answer it with `reliant workflow answer <execution-id> --select Hold`, or in the app.

A run you start from code without a session is hosted in the project you used most recently, and a saved workflow's name is looked up there. Running it from this project makes it that project. To run in a chosen conversation instead, pass its `SessionID`.

**2. Create a token**

```bash terminal theme={null}
reliant auth token create --name release-bot
```

You approve it in the browser, or with a device code. It prints an `rlat_` token once, acting as you for 90 days. Following a run and answering its questions need the whole API (`reliant:api`), which this token has. A service that only starts runs and checks them with `Runs.Get` can take a narrower one, `--scope runs:start` ([Scopes](https://docs.reliantlabs.io/sdk/overview.md#scopes)).

**3. Write the program**

```bash terminal theme={null}
go mod init example.com/releasebot
go get github.com/reliant-labs/reliant/sdk/go@main
```

```go main.go theme={null}
// releasebot starts the release-check workflow, puts its question to the
// person at the terminal, and exits with the run's verdict.
package main

import (
	"bufio"
	"context"
	"fmt"
	"log"
	"os"
	"strings"
	"time"

	"github.com/reliant-labs/reliant/sdk/go/reliant"
)

func main() {
	ctx := context.Background()
	c, err := reliant.FromEnv()
	if err != nil {
		log.Fatal(err)
	}

	run, err := c.Runs.Start(ctx, reliant.StartRun{
		Workflow: "release-check",
		Message:  "Check release v1.4.0",
		Inputs:   map[string]any{"version": "v1.4.0"},
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("started run", run.GetId())

	for tail := false; ; tail = true {
		f, err := c.Runs.Follow(ctx, run.GetId(), reliant.FollowOptions{
			StopOnGate: true,
			Tail:       tail, // after an answer, only what happens next
			Timeout:    30 * time.Minute,
		})
		if err != nil {
			log.Fatal(err)
		}
		for ev := range f.Events() {
			fmt.Println(" ", ev.Event, ev.NodeID)
		}
		res, err := f.Wait()
		if err != nil {
			log.Fatal(err)
		}
		if !res.StoppedOnGate {
			fmt.Printf("status=%s outcome=%s succeeded=%v\n", res.Status, res.Outcome, res.Succeeded)
			os.Exit(res.ExitCode)
		}
		if err := answerQuestions(ctx, c, run.GetId()); err != nil {
			log.Fatal(err)
		}
	}
}

// answerQuestions asks the person at the terminal each open question and
// sends exactly what they typed. It never picks an option for them.
func answerQuestions(ctx context.Context, c *reliant.Client, runID string) error {
	gates, err := c.Gates.Pending(ctx, runID)
	if err != nil {
		return err
	}
	in := bufio.NewReader(os.Stdin)
	for _, g := range gates {
		if g.Kind != reliant.GateQuestion {
			fmt.Printf("approval %q is waiting for a person in the app\n", g.Title)
			continue
		}
		var answers []reliant.Answer
		for _, p := range g.Prompts {
			fmt.Printf("%s %v: ", p.Question, p.Options)
			line, err := in.ReadString('\n')
			if err != nil {
				return err
			}
			answers = append(answers, reliant.Answer{
				Question: p.Question,
				Selected: []string{strings.TrimSpace(line)},
			})
		}
		if err := c.Gates.Answer(ctx, g.ID, answers); err != nil {
			return err
		}
	}
	return nil
}
```

`Runs.Start` returns as soon as the run is dispatched. `StopOnGate` ends each follow when the run opens a question, and `Gates.Pending` returns its prompts. The answer is exactly what the person typed: the SDK never picks an option for you, and has no call that decides an approval.

**4. Run it and read the verdict**

```bash terminal theme={null}
RELIANT_TOKEN=rlat_... go run .
```

```text theme={null}
started run 6994c418-2c47-4c48-9612-01c2254d7e8c
  workflow_started
  node_started ask
  question ask
Ship this release? [Ship Hold]: Ship
  node_started shipped
  node_completed shipped
  workflow_completed
status=completed outcome=success succeeded=true
```

It exits `0`. Answer `Hold` instead and the run still completes, but at a node that declares failure:

```text theme={null}
status=completed outcome=failure succeeded=false
```

and it exits `1`. Always branch on `Succeeded`, which combines status and outcome; `status` alone would call this run a success.

**5. Fire an automation**

`Triggers.Fire` runs a saved automation now, by name or ID. Firing is asynchronous, so look for its event, then follow the session it launched. Take the loop from [Fire a trigger](https://docs.reliantlabs.io/sdk/go.md#fire-a-trigger); here it fires a disabled nightly schedule of the same workflow:

```text theme={null}
launched session bc0a2f1f-7d45-540c-9adc-dfdda0666a7f
status=completed outcome=failure succeeded=false
```

The run failed because an automation's run has nobody to ask: its question resolves at once with no answer, so it ends at `held`. Workflows you fire this way should not depend on a person ([Unattended by design](https://docs.reliantlabs.io/automations/overview.md#unattended-by-design)).

**6. Revoke the token when you are done**

```bash terminal theme={null}
reliant auth token revoke release-bot
```

## What this does not do

* **It can't approve.** `Gates.Pending` reports an approval so you can page someone, but deciding it takes a person in the app ([Who can decide an approval](https://docs.reliantlabs.io/automations/overview.md#who-can-decide-an-approval)).
* **It can't enable, create or edit automations.** The SDK reads and fires triggers only.
* **No narrow token for following.** `runs:start` and `runs:read` cover starting and reading runs; `Follow`, `Gates` and `Triggers.Fire` need `reliant:api`.

## Troubleshooting

> [accordion] runs.start …: at least one user message or attachment is required
>
> Set `Message` on `StartRun`, even for a workflow that reads only its inputs.

> [accordion] PermissionDenied (scope\_missing)
>
> The token was created with `--scope` and lacks what this call needs (`ErrPermissionDenied`). Create it again without `--scope`, under the same `--name` to replace it.

> [accordion] The workflow is not found, or the run is in another project
>
> The headless run went to your most recently used project. Run the workflow once from its project, or pass `SessionID`.

## Next steps

> [card] [Stream a run in TypeScript](https://docs.reliantlabs.io/guides/workflows/stream-run-events-typescript.md)
>
> Show the same run live in a frontend, with resume.

> [card] [Run a workflow from GitHub Actions](https://docs.reliantlabs.io/guides/workflows/run-workflow-from-github-actions.md)
>
> The same start-and-follow from CI, with the CLI.

> [card] [Go SDK reference](https://docs.reliantlabs.io/sdk/go.md)
>
> Every call: listing runs, steering, webhooks and errors.

> [card] [Require human approval](https://docs.reliantlabs.io/guides/workflows/require-human-approval.md)
>
> Approvals and questions inside a workflow.


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