Go

Connect a Go 1.22+ application to its local or remote AgenticDriver host. This module has no external Go dependencies. Provider credentials and native agent processes stay on the host. The client uses an application-scoped driver bearer token and explicit provider/model selection.

Optional detached jobs use SubmitJob, ReadJob, CancelJob and JobEvents with typed requests/results. Cancelling the HTTP context does not cancel accepted background work; call CancelJob explicitly. Reconnect using JobEventPage.NextCursor; pages never automatically execute tool actions.

Install the current published preview:

go get github.com/agenticdriver/agenticdriver/clients/go@v0.2.0-rc.2

Your application's go.mod and go.sum record the dependency. No sibling checkout or replace directive is needed. The repository is public. Installation uses the public Go module proxy and checksum database without GitHub credentials or a GOPRIVATE setting. The installation check below uses a fresh module cache and does not change your global Go configuration.

package main

import (
    "context"
    "errors"
    "fmt"
    "os"
    "os/signal"

    "github.com/agenticdriver/agenticdriver/clients/go"
)

func main() {
    ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt)
    defer stop()
    client, err := agenticdriver.New(os.Getenv("AGENTICDRIVER_URL"), os.Getenv("AGENTICDRIVER_TOKEN"))
    if err != nil { panic(err) }
    providers, err := client.RefreshProviders(ctx)
    if err != nil { panic(err) }
    fmt.Printf("Authorized provider instances: %d\n", len(providers))
    request := agenticdriver.Request{
        Provider: os.Getenv("AGENTICDRIVER_PROVIDER"),
        Model: os.Getenv("AGENTICDRIVER_MODEL"),
        Input: "Summarize the selected evidence.",
    }
    err = client.Stream(ctx, request, func(event agenticdriver.Event) error {
        switch event.Type {
        case "text.delta": fmt.Print(event.Text)
        case "run.progress": fmt.Printf("Progress: %s\n", event.Phase)
        case "run.completed": fmt.Printf("\nRun: %s\n", event.Result.RunID)
        }
        return nil // Return an application error to stop consuming and cancel the run.
    })
    if err != nil {
        var driverError *agenticdriver.Error
        if errors.As(err, &driverError) {
            fmt.Printf("%s: %s\n", driverError.Code, driverError.Message)
            // Outcome == "uncertain" requires reconciliation before replacing work.
            // Retryable is advisory; the client never replays a run automatically.
        } else if errors.Is(err, context.Canceled) {
            fmt.Println("Cancelled")
        } else { panic(err) }
    }
}

Run(ctx, request) returns a typed Result; Stream exposes typed model, step, progress, tool, usage, error and result fields plus each validated event's Raw JSON. Check the event type before reading its associated fields. Pointer token counters distinguish a reported zero from an unknown measurement. Callback errors return unchanged. The callback runs synchronously, so applications control buffering/backpressure and must return promptly when they want cancellation to finish; the SDK cannot interrupt arbitrary application code.

A stream owns its response body and derived cancellation context. Terminal success, malformed frames, transport failures, context cancellation and callback termination close that body. A nil callback is rejected before HTTP with INVALID_CALLBACK. SSE supports UTF-8, BOM, LF/CR/CRLF, multiline data and any network-read boundaries, including bytes returned together with EOF. EOF without a terminal event remains an error; it never turns an incomplete answer into success. There is no reconnection or implicit replay.

SearchContext, IndexContext, IngestContext and DeleteContext expose the shared retrieval/ingestion contract. Their inputs include corpus and exact source/revision; manifests preserve extraction coverage and source provenance. Canonical data, access control and citation validity remain application-owned.

HTTPS is required away from loopback, and redirects never forward credentials. For a custom CA, mTLS or proxy policy, configure a verified http.Transport and pass it to NewWithTransport. The caller owns that transport and any CloseIdleConnections lifecycle. Do not disable TLS verification. No HTTP-client execution timeout is installed. Caller context deadlines are explicit application choices; runs can separately opt in to host-enforced IdleTimeoutMs based on real model/tool/context progress. Discovery has a bounded ten-second I/O timeout. A background context gives an execution request no default deadline.

npm run test:clients builds and installs the actual language packages, compiles examples and runs pure contracts. It does not simulate connections or model answers. Use real connection checks for provider execution.

Interactive approvals#

Set Request.Approvals to &ApprovalPolicy{Mode: "interactive", IdlePolicy: "pause"} and consume Stream. Event.Approval contains the reviewed call; submit DecideApproval(ctx, ApprovalDecision{ApprovalID: approval.ApprovalID, RunID: approval.RunID, Call: approval.Call, Decision: "approve"}) using the same authenticated subject with a separate approval grant. Decisions may also be deny or cancel; inspect Event.Resolution and the terminal run outcome.

The host must enable this feature and grant approveTools. run rejects interactive mode because it cannot deliver review requests. There is no default approval expiry; choose expiresAfterMs / the typed equivalent when needed. Decisions are single-use and are never retried automatically. A receipt does not confirm a tool effect. See the approval contract.

Functions in your application#

Set Request.ApplicationTools to your []ApplicationToolDefinition and select the same names in Tools. In Stream, dispatch only tool.execution.requested: event.Execution contains the call arguments and Identity() for replies. Use ReportToolProgress(ctx, identity) after real work and CompleteTool(ctx, ToolExecutionResult{ToolExecutionIdentity: identity, Output: jsonBytes}) to submit the JSON result once. Output is json.RawMessage; encode a JSON null as json.RawMessage("null"). On callback failure set only Error: "APPLICATION_TOOL_FAILED", without private exception text.

Host opt-in and named token grants are required; review defaults to required. Pass the stream's context to your application function so cancellation propagates through its I/O. Cancelled runs invalidate pending tickets but cannot undo effects. No default inactivity deadline or automatic retries apply. See the full contract.

Conversation sessions#

Create/read/delete methods and typed session models support explicit conversation continuation. Pass only the returned session ID and revision on each run, then use the next revision from the successful result. Provider/account/model changes require an explicitly created conversation with exported visible history. Host opt-in, account binding and per-operation token grants are required. Idle retention pauses during active work; no default execution deadline is introduced. See the session contract and binding examples.

Provider settings component#

The provider and connection panel supplies provider/model settings, remote management and local/remote setup through the existing SDK client. TypeScript, Python, Go and Rust packages share the same embeddable browser component and provide native backend bindings. These additions are available on sdk-roadmap and are not in the published 0.1.0 packages.