Aufgaben-API-Referenz
Starte einen gehosteten Agentenlauf in einer Session und polle ihn bis zum Endzustand: Anfrageoptionen, TaskRun-Felder und das separate Reviewer-Urteil.
Zuletzt aktualisiert:
Eine Aufgabe übergibt den ganzen Loop an Browserberg: Du nennst ein Ziel, der gehostete Agent plant Schritte in deiner Session, und ein separater Reviewer entscheidet, ob das Ziel erreicht wurde. Die Task-Endpunkte unten erwarten den üblichen, im Dashboard erzeugten API-Schlüssel hinter Bearer im Authorization-Header.
/v1/sessions/:id/tasks
Startet einen Task-Lauf in der Session und antwortet sofort mit 202; polle den Lauf bis zum Ende.
Task-Request
| Name | Typ | Beschreibung |
|---|---|---|
task
erforderlich
|
string | Das Ziel, bis zu 4000 Zeichen. |
startUrl
|
string | Die Seite, auf der die Aufgabe beginnt. Die API ÖFFNET sie vor dem Lauf (seit 1.4) und verankert den Ziel-Guard an ihrer Site; eine Seite, die sich nicht öffnen lässt, antwortet mit `422 navigation_failed`, und es entsteht keine Aufgabe. Mit `pinToStartSite` kann der Agent diese Site nicht verlassen. |
variables
|
object | Werte, auf die der Aufgabentext verweisen darf. |
maxSteps
|
integer |
Schrittbudget, höchstens 100.
Standard: 25
|
maxFailures
|
integer | Wie viele gescheiterte Schritte der Lauf duldet, bevor er aufgibt. |
pinToStartSite
|
boolean | Entfernt Navigation vollständig aus dem Aktionsschema des Modells, damit eine Seite den Agenten nicht vom Startportal weglenken kann. |
readOnly
|
boolean | Beschränkt den Lauf auf nicht verändernde Aktionen. |
timeoutSeconds
|
integer | Obergrenze für die Gesamtlaufzeit. |
/v1/tasks/:id
Liefert den TaskRun, live während des Laufs und endgültig im Endzustand.
TaskRun-Felder
| Name | Typ | Beschreibung |
|---|---|---|
status
|
string | `running` während des Laufs; Endwerte sind `completed`, `terminated`, `failed` und `canceled`. |
endedBy
|
string | Warum der Lauf endete, feiner als `status`: `verified` (completed), `gave_up` (der Agent sagte, er kann nicht) oder `not_offered` (der Prüfer stimmt zu, dass die Seite so etwas nicht bietet) bei terminated, und `budget`, `timeout`, `canceled`, `error` bei failed. Offene Aufzählung; fehlt, solange der Lauf läuft, und bei Servern vor 1.4. |
answer
|
string | Die Antwort des Agenten auf das Ziel, sofern es eine gibt. |
data
|
array | Alles, was extract unterwegs zurückgegeben hat. |
steps
|
array | Die Denkspur: `{step, evaluation, memory, nextGoal, actions}` je Schritt. |
verification
|
object | `{isComplete, isTerminate, thoughts}` aus einem separaten Reviewer-Aufruf gegen eine frisch gelesene Seite — der Agent bescheinigt seinen Erfolg nie selbst. |
notes
|
array | Formlose Anmerkungen, die der Lauf hinterlassen hat. |
/v1/tasks
Listet deine Task-Läufe auf.
/v1/tasks/:id
Bricht eine laufende Aufgabe ab; der Lauf endet mit Status `canceled`.
Drei Arten zu enden
completed heißt: Der Reviewer hat das Ziel gegen die frisch gelesene Seite bestätigt. terminated ist ein Schluss: Agent oder Reviewer haben entschieden, dass die Aufgabe enden soll — ein Portal, das sich verweigert, eine Vorbedingung, die sich als falsch erweist. failed ist ein Unvermögen: Der Lauf kam innerhalb seiner Budgets nicht weiter. Die Unterscheidung zählt, denn ein terminierter Lauf trägt oft eine brauchbare Antwort, ein gescheiterter meist nicht. Eine Organisation führt standardmäßig höchstens 5 Aufgaben gleichzeitig aus.