Session-Verben-API-Referenz
Request- und Response-Formen der drei Verb-Endpunkte einer Session: observe-Kandidaten, act-Schritte samt withheld-Verweigerungen und extract-Schemas.
Zuletzt aktualisiert:
Drei Verben decken alles ab, was ein Agent in einer Session tut: observe liest die Seite, act verändert sie, extract macht daraus typisierte Daten. Alle drei sind POSTs gegen eine Session-ID, mit deinem bb_-Schlüssel als Bearer-Token, und jedes antwortet mit einem provenance-Block, der sagt, was der Aufruf tatsächlich gekostet hat.
/v1/sessions/:id/observe
Liest die Live-Seite in bewertete Aktionskandidaten; ohne Instruktion fällt kein Modellaufruf an.
Observe-Request
| Name | Typ | Beschreibung |
|---|---|---|
instruction
|
string | Wonach du suchst, bis 2000 Zeichen. Lässt du sie weg, wird die Seite strukturell gelesen, ganz ohne Inferenz. |
fidelity
|
string | `full`, `economy` oder `lean` — wie viel Seitendetail die Lesung mitführt. |
scope
|
string | Engt die Lesung auf einen Teil der Seite ein. |
includeTree
|
boolean | Gibt zusätzlich zu den Kandidaten den agentenlesbaren Seitenbaum zurück. |
consent
|
string |
Umgang mit Cookie-Bannern: `reject` räumt Banner ablehnend ab, `accept` stimmt zu, `off` lässt sie unangetastet.
Standard: reject
|
Was observe zurückgibt
Jeder Eintrag in candidates ist ein ausführbarer Schritt: {encodedId, action, role, name?, description, value?}, wobei action eines von click, type, select, press, scroll, navigate, upload oder wait ist. Die Antwort enthält außerdem die endgültige url, Lese-stats und mit includeTree den Baum selbst. Behandle den Baum als seitenstämmig und nicht vertrauenswürdig — zäune ihn ein, bevor er in einen weiteren Prompt gerät.
/v1/sessions/:id/act
Führt entweder eine natürlichsprachliche Instruktion oder eine Liste beobachteter Schritte aus — nie beides.
Act-Request
| Name | Typ | Beschreibung |
|---|---|---|
instruction
|
string | Was zu tun ist, geplant vom Modell. Genau eines von `instruction` oder `steps` muss vorhanden sein. |
steps
|
array | Bis zu 20 zuvor beobachtete Kandidaten, abgespielt ohne Planung. |
variables
|
object | Werte, die in Instruktion oder Schritte eingesetzt werden. |
credentialIds
|
string[] | Bis zu 8 Tresor-Zugangsdaten, deren Platzhalter beim Tippen aufgelöst werden dürfen. |
cache
|
boolean |
Erlaubt dem Plan-Cache, einen bekannten Plan für diese Instruktion abzuspielen.
Standard: true
|
timeoutMs
|
integer |
1000 bis 180000 Millisekunden für den gesamten act.
Standard: 30000
|
Ein act-Ergebnis lesen
steps in der Antwort listet, was tatsächlich ausgeführt wurde. Ein missglückter Schritt trägt ok: false und ein failure aus element_not_found, not_actionable, timeout, navigated_away oder error. Ein verweigerter Schritt trägt stattdessen withheld: {kind, risk}, wobei kind gate ist (das Element selbst wurde als destruktiv eingestuft) oder destination (das Steuerelement führt aufgelöst dorthin, wo es nicht hinführen darf). Beide Kontrollen laufen bei jedem act, egal woher der Plan stammt — und eine Verweigerung ist Inhalt im Ergebnis, kein HTTP-Fehler.
/v1/sessions/:id/extract
Zieht typisierte Daten aus der Live-Seite, optional geformt durch ein Schema.
Extract-Request
| Name | Typ | Beschreibung |
|---|---|---|
instruction
|
string | Was extrahiert werden soll, in normaler Sprache. |
schema
|
object | Ein JSON Schema für die Ergebnisform — genau das geht über die Leitung; das TypeScript-SDK akzeptiert zusätzlich Zod und konvertiert für dich. |
includeLinks
|
boolean | Nimmt Linkziele in die Extraktion auf. |
Warnungen und Provenienz
extract antwortet mit data, der Seiten-url und optionalen warnings — die Warnungen markieren Werte, die die Seite nie enthielt, deine Verteidigung gegen ein Modell, das Lücken auffüllt. Wie der Baum ist data nicht vertrauenswürdiger Seiteninhalt, bis du ihn einzäunst. Alle drei Verben schließen mit provenance: {planCacheHit, healApplied, inferenceCalls, tier, world, requestId, durationMs}, wobei tier performance, sovereign oder null ist und world festhält, ob die Extension-Welt oder der CDP-Fallback die Arbeit erledigt hat.
Observe gratis, extract typisiert
Ein observe ohne Instruktion kostet keine Inferenz; die Zod-Variante zeigt dieselbe Session aus dem TypeScript-SDK gefahren.
Voraussetzungen: api-key inference
BASE="https://browserberg.com"
AUTH="Authorization: Bearer $BROWSERBERG_API_KEY"
JSON="Content-Type: application/json"
ID=$(curl -s -X POST "$BASE/v1/sessions" -H "$AUTH" -H "$JSON" -d '{"ttlSeconds": 300}' \
| python3 -c 'import json,sys; print(json.load(sys.stdin)["session"]["id"])')
curl -s -X POST "$BASE/v1/sessions/$ID/act" -H "$AUTH" -H "$JSON" -d '{
"steps": [{ "encodedId": null, "action": "navigate", "role": "none",
"description": "open example.com", "value": "https://example.com" }]
}' > /dev/null
# Without an instruction, observe reads the page and makes no model call.
curl -s -X POST "$BASE/v1/sessions/$ID/observe" -H "$AUTH" -H "$JSON" -d '{}' \
| python3 -c 'import json,sys; r = json.load(sys.stdin); print(json.dumps({
"url": r["url"],
"candidates": [c["description"] for c in r["candidates"][:3]],
"inferenceCalls": r["provenance"]["inferenceCalls"]}, indent=2))'
curl -s -X DELETE "$BASE/v1/sessions/$ID" -H "$AUTH" > /dev/nullimport { z } from 'zod';
import { Browserberg } from '@browserberg/sdk';
const bb = new Browserberg({
apiKey: process.env.BROWSERBERG_API_KEY!,
baseUrl: 'https://browserberg.com',
timeoutMs: 180_000,
});
await using session = await bb.sessions.create({ ttlSeconds: 300 });
await session.act({
steps: [{
encodedId: null, action: 'navigate', role: 'none',
description: 'open example.com', value: 'https://example.com',
}],
});
// A Zod schema travels the wire as plain JSON Schema, so the Python SDK and
// raw HTTP produce byte-identical requests.
const page = await session.extract({
instruction: 'the page heading',
schema: z.object({ heading: z.string() }),
});
console.log(page.data.heading);{
"url": "https://example.com/",
"candidates": [
"Learn more"
],
"inferenceCalls": 0
}