Watch and steer

Follow a session live and redirect the agent while it works.

Agent View

Every session shows up in Agent View on the H Platform, and its agent_view_url links straight there. Watch it live, or replay it after. Agent View reads the same events stream as your code.

Watch a session

A blocking call (run_session / runSession) returns only at the end. To read or intervene while it works, start the session and keep its handle. Then stream its events, or block until it settles:

CLI

holo sessions watch "$SESSION_ID"   # stream events until the session settles

Stream events as they arrive

The SDK handle’s stream() runs the changes long-poll loop for you and yields each event in order.

• It stops when the session settles: a terminal state, or idle. Pass until="terminal" to keep it open across the idle turns of an interactive session.
• With custom tools, it answers their calls: after each batch of events, it runs the calls the agent is waiting on and posts the results. It uses the tools the handle was started with, or the tools you pass.
• Without tools it is read-only, so another process can answer the calls while you watch.

Python

for event in session.stream(tools=[get_order_status]):  # also answers tool calls
    print(event.type)

A handle’s stream and wait_for_completion share its tools and run each call once between them. Loops on separate handles or processes don’t coordinate: give tools to one of them only, or a call can run twice.

Get the files the agent sends

The agent sends each file once it is final, mid-run, as an AttachmentEvent with origin: "agent". Download it by its file_id:

Python

for event in session.stream():
    if event.type == "AttachmentEvent" and event.data.origin == "agent":
        with open(event.data.name, "wb") as out:
            for chunk in client.session_files.download_file(event.data.file_id):
                out.write(chunk)

file_id is set on hosted sessions; in local mode, download by url. Files the agent leaves in a cloud browser’s ~/Downloads without sending stay reachable through list files and read file while the browser runs.

Read the raw state

Read	Returns	Use it to
status	Current state, step count, token usage	Poll as a cheap health check
changes	New events past an index, plus the final answer, long-polled	Follow an active session by its polling rules
events	The full, paginated record	Replay or audit after the fact

CLI

holo sessions status "$SESSION_ID"

Steer a running agent

A real session, redirected mid-task with one message:

While the session runs, you can:

Action	Effect
Send a message	Adds context or redirects the agent. The agent picks it up on the next step. Wakes an idle session and auto-resumes a paused one.
Pause / Resume	Halts the agent with its state preserved, then continues.
Force an answer	The agent stops exploring and answers from what it has.
Cancel	Stops the agent. It ends interrupted.

CLI

holo sessions send "$SESSION_ID" "Only consider results from the last 24 hours"
holo sessions cancel "$SESSION_ID" --yes

Hold an interactive conversation

By default a session ends when the agent answers. Set idle_timeout_s at create time to keep it open: after each answer it goes idle and waits that long for your next message, keeping its context and environment across turns. It terminates once a turn goes unanswered for idle_timeout_s.

Python

session = client.start_session(
    agent="h/web-surfer-flash",
    idle_timeout_s=600,
    messages=[{"type": "user_message", "message": "Find the top story on Hacker News"}],
)
print(session.wait_for_completion().answer)
session.send_message({"type": "user_message", "message": "Now open its comments and summarize the discussion"})