Long-running agent tasks

Persistent session, busy polling, output retrieval — for tasks that take minutes.

Some agent tasks (deep research, multi-step generation, report builds) run for minutes. The agent should keep working independently of your client; you should be able to disconnect, come back later, and grab the output.

Pattern

Create a persistent session (won't auto-destroy).
Send the message; the agent runs to completion server-side even if you disconnect.
Poll GET /v1/sessions/{id} for the busy flag (and any metadata your workflow writes).
When done, download outputs via the files API.

Code

import os, time, httpx

API = os.environ["POKEE_API"]
KEY = os.environ["POKEE_KEY"]
H   = {"Authorization": f"Bearer {KEY}", "Content-Type": "application/json"}

with httpx.Client(base_url=API, headers=H, timeout=httpx.Timeout(None)) as c:
    # 1. Persistent session — won't auto-destroy after idle
    sid = c.post("/v1/sessions",
                 json={"persistent": True, "ttl": 14400}).json()["id"]

    # 2. Kick off the long-running task. You can stream and consume,
    #    or fire-and-forget — the agent keeps running either way.
    with c.stream("POST", f"/v1/sessions/{sid}/messages",
                  json={"message": "Build a 10-page market research report on Q3 NVIDIA performance and write it to /opt/sandbox/workspace/report.md"}) as r:
        for line in r.iter_lines():
            if "message.completed" in line or "message.error" in line:
                break

    # 3. (Or, if you disconnected) poll until the agent finishes the turn.
    while True:
        s = c.get(f"/v1/sessions/{sid}").json()
        if not s["busy"]:
            break
        # The agent (or any tool it invokes) can write progress hints
        # into session.metadata. Read whatever keys your workflow uses.
        print(f"  metadata: {s['metadata']}")
        time.sleep(15)

    # 4. Download the result
    files = c.get(f"/v1/sessions/{sid}/files").json()
    report = next(f for f in files if f["name"] == "report.md")
    with c.stream("GET", f"/v1/sessions/{sid}/files/{report['name']}") as r, \
         open(report["name"], "wb") as out:
        for chunk in r.iter_bytes():
            out.write(chunk)

Why this works

persistent: true means the session survives long after a default ephemeral one would auto-destroy (5 min after the last response).
The agent keeps running even if you disconnect — the next call to /v1/sessions/{id} will see busy: true until the turn completes.
metadata is workflow-specific. Long-running agent flows can write progress hints there; watch for keys relevant to what you asked the agent to do.

Cleanup

Destroy when done:

curl -X DELETE "$POKEE_API/v1/sessions/$SID" \
  -H "Authorization: Bearer $POKEE_KEY"

Or batch-clean idle sessions older than an hour:

curl -X DELETE "$POKEE_API/v1/sessions?status=idle&older_than=1h" \
  -H "Authorization: Bearer $POKEE_KEY"

Pattern

Code

Why this works

Cleanup

On this page