Core routes, exact shapes.

# cURL
: "${DRIFTSTACK_API_KEY:?Set DRIFTSTACK_API_KEY}"
: "${DRIFTSTACK_PROXY_ID:?Set DRIFTSTACK_PROXY_ID}"
API="https://api.driftstack.dev/v1/agent-sessions"
AUTH="authorization: Bearer $DRIFTSTACK_API_KEY"

AGENT_ID=$(curl --fail-with-body -sS -X POST "$API" \
  -H "$AUTH" -H "content-type: application/json" \
  -d "$(jq -n --arg proxy "$DRIFTSTACK_PROXY_ID" '{mode: "ai", proxy_id: $proxy}')" \
  | jq -r .id)
# status is "active" from the start: wait up to two minutes for ready.
for _ in $(seq 60); do
  STATE=$(curl --fail-with-body -sS -H "$AUTH" "$API/$AGENT_ID") || { echo "$STATE" >&2; exit 1; }
  [ "$(echo "$STATE" | jq -r .status)" = closed ] && { echo "the session did not start" >&2; exit 1; }
  [ "$(echo "$STATE" | jq -r .ready)" = true ] && break
  sleep 2
done
echo "$AGENT_ID"

// TypeScript
import { Driftstack } from "@driftstack/sdk";

const apiKey = process.env.DRIFTSTACK_API_KEY;
const proxyId = process.env.DRIFTSTACK_PROXY_ID;
if (!apiKey || !proxyId) throw new Error("Set DRIFTSTACK_API_KEY and DRIFTSTACK_PROXY_ID");
const client = new Driftstack({ apiKey });

const agent = await client.agentSessions.create({ mode: "ai", proxy_id: proxyId });
// status is "active" from the start: wait up to two minutes for ready.
for (let i = 0; i < 60; i++) {
  const s = await client.agentSessions.get(agent.id);
  if (s.status === "closed") throw new Error("The session did not start: " + s.closed_reason);
  if (s.ready !== false) break;
  await new Promise((resolve) => setTimeout(resolve, 2_000));
}
console.log(agent.id);

# Python
import os
import time

from driftstack import Driftstack

client = Driftstack(api_key=os.environ["DRIFTSTACK_API_KEY"])
agent = client.agent_sessions.create(
    {"mode": "ai", "proxy_id": os.environ["DRIFTSTACK_PROXY_ID"]}
)
# status is "active" from the start: wait up to two minutes for ready.
for _ in range(60):
    s = client.agent_sessions.get(agent["id"])
    if s["status"] == "closed":
        raise RuntimeError(f"The session did not start: {s['closed_reason']}")
    if s.get("ready") is not False:
        break
    time.sleep(2)
print(agent["id"])

// Go
package main

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

    driftstack "github.com/driftstackdev/driftstack-go"
)

func main() {
    apiKey, proxyID := os.Getenv("DRIFTSTACK_API_KEY"), os.Getenv("DRIFTSTACK_PROXY_ID")
    if apiKey == "" || proxyID == "" { log.Fatal("set DRIFTSTACK_API_KEY and DRIFTSTACK_PROXY_ID") }
    client := driftstack.New(apiKey)
    defer client.Close()
    ctx := context.Background()
    agent, err := client.AgentSessions.Create(ctx, &driftstack.CreateAgentSessionRequest{
        Mode:    "ai",
        ProxyID: proxyID,
    }, nil)
    if err != nil { log.Fatal(err) }
    // Status is "active" from the start: wait up to two minutes for IsReady.
    for i := 0; i < 60; i++ {
        s, err := client.AgentSessions.Get(ctx, agent.ID)
        if err != nil { log.Fatal(err) }
        if s.Status == "closed" {
            reason := "unknown"
            if s.ClosedReason != nil { reason = *s.ClosedReason }
            log.Fatal("The session did not start: " + reason)
        }
        if s.IsReady() { break }
        time.Sleep(2 * time.Second)
    }
    fmt.Println(agent.ID)
}

# cURL
: "${DRIFTSTACK_API_KEY:?Set DRIFTSTACK_API_KEY}"
: "${DRIFTSTACK_AGENT_SESSION_ID:?Set DRIFTSTACK_AGENT_SESSION_ID}"
curl --fail-with-body -sS --max-time 3000 -X POST \
  "https://api.driftstack.dev/v1/agent-sessions/$DRIFTSTACK_AGENT_SESSION_ID/message" \
  -H "authorization: Bearer $DRIFTSTACK_API_KEY" \
  -H "content-type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"user_message":"Open https://example.com and tell me the page title."}' \
  | jq '{kind, answer}'

// TypeScript
import { randomUUID } from "node:crypto";
import { Driftstack } from "@driftstack/sdk";

const apiKey = process.env.DRIFTSTACK_API_KEY;
const agentId = process.env.DRIFTSTACK_AGENT_SESSION_ID;
if (!apiKey || !agentId) throw new Error("Set DRIFTSTACK_API_KEY and DRIFTSTACK_AGENT_SESSION_ID");
const client = new Driftstack({ apiKey });

const reply = await client.agentSessions.message(
  agentId,
  "Open https://example.com and tell me the page title.",
  { idempotencyKey: randomUUID() },
);
if (reply.kind === "plan-executed") console.log(reply.answer ?? reply.results);
else console.log(reply.kind, reply);

# Python
import os
import uuid

from driftstack import Driftstack

client = Driftstack(api_key=os.environ["DRIFTSTACK_API_KEY"])
reply = client.agent_sessions.message(
    os.environ["DRIFTSTACK_AGENT_SESSION_ID"],
    "Open https://example.com and tell me the page title.",
    idempotency_key=str(uuid.uuid4()),
)
if reply["kind"] == "plan-executed":
    print(reply.get("answer", reply["results"]))
else:
    print(reply["kind"], reply)

// Go
package main

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

    driftstack "github.com/driftstackdev/driftstack-go"
)

func main() {
    apiKey, agentID := os.Getenv("DRIFTSTACK_API_KEY"), os.Getenv("DRIFTSTACK_AGENT_SESSION_ID")
    if apiKey == "" || agentID == "" { log.Fatal("set DRIFTSTACK_API_KEY and DRIFTSTACK_AGENT_SESSION_ID") }
    client := driftstack.New(apiKey)
    defer client.Close()
    reply, err := client.AgentSessions.Message(context.Background(), agentID,
        "Open https://example.com and tell me the page title.",
        &driftstack.MessageOptions{IdempotencyKey: "task-" + time.Now().Format(time.RFC3339Nano)})
    if err != nil { log.Fatal(err) }
    if reply.Kind == "plan-executed" {
        fmt.Println(reply.Answer)
    } else {
        fmt.Println(reply.Kind)
    }
}

# cURL
: "${DRIFTSTACK_API_KEY:?Set DRIFTSTACK_API_KEY}"
: "${DRIFTSTACK_AGENT_SESSION_ID:?Set DRIFTSTACK_AGENT_SESSION_ID}"
curl --fail-with-body -sS -X DELETE \
  "https://api.driftstack.dev/v1/agent-sessions/$DRIFTSTACK_AGENT_SESSION_ID" \
  -H "authorization: Bearer $DRIFTSTACK_API_KEY"

// TypeScript
import { Driftstack } from "@driftstack/sdk";

const apiKey = process.env.DRIFTSTACK_API_KEY;
const agentId = process.env.DRIFTSTACK_AGENT_SESSION_ID;
if (!apiKey || !agentId) throw new Error("Set DRIFTSTACK_API_KEY and DRIFTSTACK_AGENT_SESSION_ID");
const client = new Driftstack({ apiKey });
await client.agentSessions.close(agentId);

# Python
import os

from driftstack import Driftstack

client = Driftstack(api_key=os.environ["DRIFTSTACK_API_KEY"])
client.agent_sessions.close(os.environ["DRIFTSTACK_AGENT_SESSION_ID"])

// Go
package main

import (
    "context"
    "log"
    "os"

    driftstack "github.com/driftstackdev/driftstack-go"
)

func main() {
    apiKey, agentID := os.Getenv("DRIFTSTACK_API_KEY"), os.Getenv("DRIFTSTACK_AGENT_SESSION_ID")
    if apiKey == "" || agentID == "" { log.Fatal("set DRIFTSTACK_API_KEY and DRIFTSTACK_AGENT_SESSION_ID") }
    client := driftstack.New(apiKey)
    defer client.Close()
    if err := client.AgentSessions.Close(context.Background(), agentID); err != nil { log.Fatal(err) }
}