Install & connect

Start with an explicitly selected real provider account. Install the current preview, connect a host, then use the tested example for your language. Apps keep their own authentication, data and approval decisions.

1. Obtain the packages#

For JavaScript and TypeScript:

npm install @agenticdriver/sdk@rc

The rc channel tracks the current release candidate; your lockfile records the version. The npm latest channel remains the earlier stable release. Python uses the reviewed wheel download while PyPI approval is pending. Go and Rust install commands appear with their examples below.

Check Compatibility for runtime requirements. Upgrade an execution host before its management clients and preserve existing accounts and grants; Upgrading explains the required order.

2. Connect your provider account#

On the execution machine, use a supported native CLI already signed into the account you intend to use. The qualified Codex adapter requires CLI 0.157.0; Claude Code 2.1.282 is also qualified. See provider setup for other adapters and their actual availability. Keep provider sign-in files on this execution machine.

In a fresh application directory, install the published npm package:

npm init -y
npm install @agenticdriver/sdk@rc
npx --no-install agenticdriver init --config ./driver/config.json \
  --provider codex --provider-id my-codex --account-id my-codex-account \
  --binary /absolute/path/to/codex \
  --account-directory /absolute/path/to/your/codex-home --management
npx --no-install agenticdriver serve --config ./driver/config.json

Replace the two native paths with your selected installation and signed-in account profile. init creates a private driver token and separate operator credential, and refuses to replace existing configuration. It does not sign in to a provider or run a model.

In a second terminal, inspect the actual account catalog:

npx --no-install agenticdriver status --config ./driver/config.json --refresh

Download the AgenticDriver brand brief as brand-brief.txt, choose an inexpensive model reported by your account, and run:

npx --no-install agenticdriver run --config ./driver/config.json \
  --provider my-codex --model YOUR_REPORTED_MODEL < brand-brief.txt

This submits a real model request and consumes that account's usage. Review its answer; seeing a catalog alone does not prove execution. Stop the foreground host with Ctrl+C when finished. See the host guide for service startup.

Applications keep their chosen authentication system. Before connecting real users or a remote application, configure scoped host access through the application-owned auth contract or the host's connection flow. See Deploy a host for remote setup. Keep provider API keys and native sign-in on the execution host; clients receive scoped driver credentials through the chosen connection or application auth flow. For a host on another computer, follow the real remote connection guide.

3. Connect a language client#

The following examples share these application-supplied settings:

Use the application's credential manager to supply and rotate the token file; never put credentials in URLs, source code or browser storage. Python, Go and Rust read a current token when constructing this one-shot client. Long-lived applications must obtain a fresh token before subsequent operations and preserve the outcome of uncertain requests. JavaScript can resolve credentials for every request. None of the clients replays model work automatically after expiry.

The Prometheus validation receipt records real requests using installed packages through an SSH connection. The examples run once with the selected provider/model and do not select an alternate account or billing route.

JavaScript and TypeScript#

Requires Node 22.13+. Install the package as above. Save the following as client.mjs and run node client.mjs. For a private CA, set NODE_EXTRA_CA_CERTS to its certificate path before starting Node. TypeScript imports the same AgenticClient; see its full guide.

import { readFile } from "node:fs/promises";
import { AgenticClient } from "@agenticdriver/sdk/client";

const client = new AgenticClient({
  url: process.env.AGENTICDRIVER_URL,
  // The application owns this private file and replaces it when tokens rotate.
  token: async () =>
    (await readFile(process.env.AGENTICDRIVER_TOKEN_FILE, "utf8")).trim(),
});
const result = await client.run({
  provider: process.env.AGENTICDRIVER_PROVIDER,
  model: process.env.AGENTICDRIVER_MODEL,
  input: await readFile(process.env.AGENTICDRIVER_INPUT_FILE, "utf8"),
});
console.log(result.text);

Download the example.

Python#

Requires Python 3.10+. Download the reviewed wheel from the 0.2.0-rc.2 release, verify its published checksum, and install it into the application's own environment:

python3 -m venv .venv
# Use .venv/Scripts/python.exe on Windows.
.venv/bin/python -m pip install /absolute/path/to/agenticdriver-0.2.0rc2-py3-none-any.whl
.venv/bin/python client.py

Save this as client.py. The synchronous client has no HTTP-library dependency. Install the wheel with [async] to use AsyncAgenticClient.

import os
from pathlib import Path
from agenticdriver import AgenticClient

# Use the private scoped credential issued by the selected AgenticDriver host.
token = Path(os.environ["AGENTICDRIVER_TOKEN_FILE"]).read_text(encoding="utf8").strip()
with AgenticClient(
    os.environ["AGENTICDRIVER_URL"], token,
    ca_file=os.environ.get("AGENTICDRIVER_CA"),
) as client:
    result = client.run(
        provider=os.environ["AGENTICDRIVER_PROVIDER"],
        model=os.environ["AGENTICDRIVER_MODEL"],
        input=Path(os.environ["AGENTICDRIVER_INPUT_FILE"]).read_text(encoding="utf8"),
    )
    print(result["text"])

Download the example · Python streaming, async and cancellation.

Go#

Requires Go 1.22+. Install the published version:

go mod init example.test/my-driver-client
go get github.com/agenticdriver/agenticdriver/clients/go@v0.2.0-rc.2
go run .

This public version installs through the ordinary Go module proxy and checksum database without GitHub credentials. CI also verifies a locally packed Go module archive without replace directives. Save the following as main.go. Ctrl+C cancels its context without imposing a run deadline.

package main

import (
	"context"
	"crypto/tls"
	"crypto/x509"
	"fmt"
	"net/http"
	"os"
	"os/signal"
	"strings"

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

func must(err error) {
	if err != nil {
		panic(err)
	}
}
func main() {
	ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt)
	defer cancel()
	token, err := os.ReadFile(os.Getenv("AGENTICDRIVER_TOKEN_FILE"))
	must(err)
	prompt, err := os.ReadFile(os.Getenv("AGENTICDRIVER_INPUT_FILE"))
	must(err)
	transport := http.DefaultTransport.(*http.Transport).Clone()
	defer transport.CloseIdleConnections()
	if path := os.Getenv("AGENTICDRIVER_CA"); path != "" {
		cert, err := os.ReadFile(path)
		must(err)
		roots := x509.NewCertPool()
		if !roots.AppendCertsFromPEM(cert) {
			panic("Invalid application CA certificate")
		}
		transport.TLSClientConfig = &tls.Config{RootCAs: roots, MinVersion: tls.VersionTLS12}
	}
	client, err := sdk.NewWithTransport(os.Getenv("AGENTICDRIVER_URL"), strings.TrimSpace(string(token)), transport)
	must(err)
	result, err := client.Run(ctx, sdk.Request{
		Provider: os.Getenv("AGENTICDRIVER_PROVIDER"), Model: os.Getenv("AGENTICDRIVER_MODEL"),
		Input: string(prompt),
	})
	must(err)
	fmt.Println(result.Text)
}

Download the example · Go transport and cancellation.

Rust#

Requires Rust 1.89+. Use the published crate:

[dependencies]
agenticdriver = "=0.2.0-rc.2"

Save the following as src/main.rs in a cargo new application and run cargo run. This uses the default blocking feature. The separate async client supports cancellation by dropping its stream/future; see the full guide for runtime ownership and feature selection.

use agenticdriver::{AgenticClient, RunRequest};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let token = std::fs::read_to_string(std::env::var("AGENTICDRIVER_TOKEN_FILE")?)?;
    let ca = std::env::var("AGENTICDRIVER_CA")
        .ok()
        .map(std::fs::read)
        .transpose()?;
    let client = AgenticClient::with_ca_pem(
        &std::env::var("AGENTICDRIVER_URL")?,
        token.trim(),
        ca.as_deref(),
    )?;
    let result = client.run(&RunRequest::new(
        std::env::var("AGENTICDRIVER_PROVIDER")?,
        std::env::var("AGENTICDRIVER_MODEL")?,
        std::fs::read_to_string(std::env::var("AGENTICDRIVER_INPUT_FILE")?)?,
    ))?;
    println!("{}", result.text);
    Ok(())
}

Download the example · Rust async, features and cancellation.

4. Validate the application workflow#

Provider instances belong to the host and have explicit account bindings. Refresh discovery, inspect the instance's health and capabilities, and select a model available to that account. A saved native sign-in does not prove model access or safe SDK integration. The provider guide distinguishes implemented adapters, recorded real checks and observed native blockers.

There is no default total run deadline or inactivity timeout. Add a positive idleTimeoutMs only if your application wants to cancel stalled work; genuine model/tool progress resets it. Streaming and cancellation are in each language guide. A cancelled request may already have produced effects, so reconcile its recorded outcome before retrying. See inactivity and idempotency.

Next, run the three installed application recipes, add selected-context retrieval, and connect the existing Usagestat backend for accounting.