Skip to main content
Launching a session is just the start. While the agent works you can watch what it is doing, step in to redirect or stop it, and keep the session open for a back-and-forth. All of it is addressed to the session’s id, and all of it works the same whether the agent runs alone or delegates to subagents. This guide ties together the read endpoints and the control endpoints into one mental model. Each links to its reference page for the full request and response shape. In the Python and TypeScript SDKs, starting a session returns immediately with a lightweight handle bound to its id; the snippets below read and steer through that handle. Every operation is equally available as a direct client call keyed by id, and as a raw HTTP request, as each reference page shows.
Prefer a UI? Every session is visible in the H Platform; see Agent View for the live and replay flows.

​
Watch a run

There are three ways to read a session, from cheapest to most complete. Pick by what you need, not by habit.
  • Liveness, with status. A small snapshot: current state, step count, and token usage. Poll it on an interval to drive a progress indicator or to detect a terminal state.
  • The answer and live updates, with changes. Long-poll from an event index and the call blocks until something new happens, then returns the new events and the final answer when it lands. This is how you read the result without hammering status.
  • Full history, with events. The complete, paginated record of everything the agent observed and did. Use it to replay or audit a run after the fact.
Rule of thumb: long-poll changes while a run is active, poll status for a lightweight health check, and page through events when you need the whole trajectory. 
# start_session(...) returns a handle you can read and steer;
# run_session(...) instead blocks until the agent finishes.
session = client.start_session(
    agent="h/web-surfer-holo3-1-35b",
    messages=[{"type": "user_message", "message": "Find the top story on Hacker News"}],
)

session.status()               # cheap liveness snapshot
session.changes(from_index=0)  # new events + final answer, long-polled
session.get()                  # the full Session resource

result = session.wait_for_completion()  # block until terminal, then read the answer
print(result.status, result.answer)

​
Steer a running agent

As long as the session is not in a terminal state, you can intervene:
  • Send a message to add context or redirect the agent mid-run. The message is picked up on the next step; a message to an idle session also wakes it. See Send a message.
  • Pause and resume to halt the agent with its state preserved (for review or cost control), then continue. Sending a message auto-resumes a paused session. See Pause and Resume.
  • Force an answer to tell the agent to stop exploring and commit to a final answer from what it has so far. See Force an answer.
  • Cancel to stop the session for good; it ends in interrupted. See Cancel.
A blocking run-and-wait call never surfaces the session mid-run. Start the session and keep its handle when you need to read or intervene while it works.
Sending a steering message is the most common intervention: 
curl -X POST "https://agp.eu.hcompany.ai/api/v2/sessions/$SESSION_ID/messages" \
  -H "Authorization: Bearer $H_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "user_message", "message": "Only consider results from the last 24 hours"}'
The other interventions follow the same shape: 
session.pause()         # halt, state preserved
session.resume()        # continue where it left off
session.force_answer()  # stop exploring and commit to a final answer
session.cancel()        # stop for good; ends in `interrupted`

​
Hold an interactive conversation

By default a session ends as soon as the agent answers. Set idle_timeout_s when you create it to keep it open: after each answer the session enters idle and waits that long for your next message before terminating. One session becomes a multi-turn conversation that keeps its full context and environment state across turns. 
# Open an interactive session that stays alive for 10 minutes between turns.
SESSION_ID=$(curl -sX POST https://agp.eu.hcompany.ai/api/v2/sessions \
  -H "Authorization: Bearer $H_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "agent": "h/web-surfer-holo3-1-35b",
    "idle_timeout_s": 600,
    "messages": [{"type": "user_message", "message": "Find the top story on Hacker News"}]
  }' | jq -r .id)

# After it answers and goes idle, ask a follow-up in the same context.
curl -X POST "https://agp.eu.hcompany.ai/api/v2/sessions/$SESSION_ID/messages" \
  -H "Authorization: Bearer $H_API_KEY" -H "Content-Type: application/json" \
  -d '{"type": "user_message", "message": "Now open its comments and summarize the discussion"}'
Watch the session’s status flip to idle between turns; it terminates once a turn goes unanswered for idle_timeout_s.