Client

AgentClient submits, streams and cancels turns through the server’s HTTP routes.

from pyrula.agents import AgentClient

client = AgentClient(
    "https://agents.example.com",
    headers={"Authorization": "Bearer ..."},   # sent on every call
    prefix="/agents",                           # default
    timeout=30.0,                               # per request, default; streams have no total cap
)

handle = await client.submit("support", message="where is my order?", metadata={"source": "web"})
async for event in client.stream("support", handle.turn_id):
    print(event.kind, event.payload)

events = await client.run("support", message="where is my order?")   # submit, drain to the end

info = await client.status("support", handle.turn_id)
await client.cancel("support", handle.turn_id, reason="user left")      # stops at next step boundary
await client.terminate("support", handle.turn_id)                       # ends now; no worker needed

run follows continue_as_new chains and returns every event. Keyword arguments to submit / run other than metadata, idempotency_key and headers are the agent’s parameters.

idempotency_key on submit and run makes a retried submission return the existing turn.

Reconnect

Pass last_event_id and the server resumes after it. If that id has fallen out of the live window the stream emits stream:overflow; stream_with_replay_fallback switches to replay (the full stored event list) for you:

async for event in client.stream_with_replay_fallback("support", turn_id, last_event_id=seen):
    ...

stream(..., idle_timeout_seconds=...) gives up on a stream that goes silent.