Sessions

One agent working on a task.

Run a session

holo run and run_session / runSession create the session, block until it ends, and return the answer.

CLI

holo run "Open Hacker News and list the top 3 stories with their URLs." \
  --agent h/web-surfer-flash

Long sessions compact their history automatically.

Get the result

Way	Use when	You get back
client.run_session(...) / runSession	One call: create, block, read	The final result: status, answer, outcome, error_code
client.start_session(...), then session.stream() or session.wait_for_completion() (Watch and steer)	Read or steer while it runs	Each event as it arrives, or the same final result
Webhooks	Batches and queued sessions, without polling	session.completed and the other status events

Over raw HTTP, the create call returns at once with the id, which every follow-up call (message, pause, cancel) uses. Long-poll changes by its polling rules, or read latest_answer with Retrieve a session once the session is terminal.

curl -X POST https://agp.eu.hcompany.ai/api/v2/sessions \
  -H "Authorization: Bearer $HAI_API_KEY" -H "Content-Type: application/json" \
  -d '{"agent": "h/web-surfer-flash", "messages": "Open Hacker News and list the top 3 stories with their URLs."}' | jq -r .id

Session states

The session object carries the current state.

Status	Meaning	Terminal
queued	Waiting for a free slot (see Queued sessions).	No
pending	Created, agent is launching.	No
running	Agent is working on the task.	No
paused	Paused via the API. State is preserved.	No
idle	Interactive agent finished a task and waits for your next message.	No
awaiting_tool_results	Blocked on custom tool calls your code must answer.	No
completed	The agent answered. Its outcome says whether the task succeeded.	Yes
timed_out	Never started: it waited 24 hours in the queue.	Yes
interrupted	Cancelled, or ended while idle to make room at your limit.	Yes
failed	An unrecoverable error occurred. error_code says why.	Yes

A message or a forced answer restarts a finished session at pending, billed again.

Customize a catalog agent for one session

overrides replaces fields of a catalog agent for one session, keyed by path. For example, send a web surfer to a chosen start page:

CLI

holo run "Summarize the top discussion right now" \
  --agent h/web-surfer-flash \
  --override 'agent.environments[kind=web].start_url=https://news.ycombinator.com'

Find past sessions

GET /api/v2/sessions pages through your sessions, newest first. Combine filters, for example ?status=running&status=queued&agent=web-price-finder. The SDKs expose it as client.sessions.list_sessions(...) / listSessions.