Using Agent Sessions

Beta

Agent Sessions is in private preview. The feature is enabled per workspace by the Orq.ai team and the API is not part of the public SDKs yet.

A session is a coding agent attached to a repository and running on an isolated computer. Create it once, then send as many messages as the task needs; each message becomes a run that continues the same conversation. For what a session is and how it is isolated, see the overview. Sessions live under Managed Agents > Factories > Sessions after selecting a factory. Members with the Developer or Admin role can create, pause, resume, and delete sessions; Researchers can view them.

Create a session

Click on the Sessions page to open New agent session.

Field	Description
Factory	The factory the session runs in. Selecting a factory prefills its defaults and restricts the agent, model, and computer choices to what the factory allows. Every workspace has a Default factory.
Name	Display label of the session, for example `fix-flaky-tests`.
Agent	Claude Code, Codex, Gemini CLI, opencode, orq, or pi.
Repository URL	HTTPS clone URL, for example `https://github.com/octocat/Hello-World`. Private repositories are cloned through a GitHub connection of the workspace when one covers the repository owner.
Branch or ref	Branch, tag, or commit to check out. Empty uses the repository default branch.
Computer	Isolation, for example `coding-session-runc` or `coding-session-gvisor`.
Model	Gateway model id, for example `anthropic/claude-sonnet-4-6`.
Git token (optional)	Personal access token for a private repository that no GitHub connection covers. Stored encrypted for the lifetime of the session and never returned.
Idle timeout (minutes)	Pauses the computer after this much inactivity; sending a message resumes it. Default 30.
Clone depth	Shallow clone depth. `0` clones the full history.
First prompt	Optional. Runs as soon as the computer is ready.

Click Create session. The status line walks through Creating computer, Computer ready, Cloning repository, and Repository cloned; with a warm computer pool the session is usually ready within seconds.

Chat with the agent

The session page is a conversation. Type a task in the composer and press ⌘ ↵ (or click send). Each message starts a run; only one run can be active per session, and Stop cancels it. While the run is active the transcript streams:

Text and thought from the agent as they stream.
Tool cards with kind, status, locations, arguments, and (when present) the inline diff or terminal output. Permission prompts appear on the tool card.
Plan updates as a checklist in the transcript.

Every message continues the previous conversation, also after the session was paused. Use the New conversation toggle next to the status line to start a fresh conversation on the same computer; the transcript marks the break with a divider.

Review changes

The Changes tab shows the computer’s working tree against the commit that was cloned: a file list with additions and deletions per file (added, modified, deleted, renamed, and untracked files) and a unified diff. Refresh it after a run; it is also refreshed automatically when a run finishes. A paused session has no diff to show; resume it from the tab to load one.

Open a pull request

Click Open pull request on the session page and provide a title, an optional Markdown description, and optionally a base branch (empty uses the repository default branch). Orq.ai then:

Commits the working tree on the computer using the title as the commit message, skipping files that look like secrets (for example .env, key files, anything under a secrets directory, or contents matching common token formats) and files larger than 5 MiB.
Pushes the commit to the branch orq/session-<session_id> on the repository’s origin, using the session’s GitHub token.
Creates the pull request through the workspace’s GitHub connection and links it on the session.

Subsequent calls push the latest state to the same branch and return the existing pull request. The link to the pull request is shown on the session page and in the sessions list. Creating pull requests requires a GitHub connection; a personal access token alone is not enough.

Pause, resume, and delete

Use the menu on the session page:

Pause removes the computer and keeps the workspace volume and the agent’s conversation. Sessions also pause automatically after the idle timeout.
Resume brings the computer back. Sending a message to a paused session resumes it automatically, so this is rarely needed.
Delete removes the computer and its volume and revokes the session’s API key. This cannot be undone; open a pull request first if the changes matter.

Sessions list

The Sessions page lists every session with its status, agent, repository and branch, last activity, and pull request link, and can be filtered by status, agent, and factory.

API

The REST API lives under /v2/agent-sessions and authenticates with a project API key (Authorization: Bearer). Endpoints are private during the preview: they are not in the public OpenAPI specification or SDKs and may change.

Create a session

curl -X POST https://my.orq.ai/v2/agent-sessions \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "fix-flaky-tests",
    "agent": "AGENT_SESSION_AGENT_CLAUDE",
    "repository": {
      "url": "https://github.com/octocat/Hello-World",
      "ref": "main"
    },
    "model": "anthropic/claude-sonnet-4-6",
    "idle_timeout_seconds": 1800
  }'

The response contains the session with its id, status (AGENT_SESSION_STATUS_CREATING at first), factory_id, and repository. Optional fields: factory_id (defaults to the workspace’s default factory), computer_template, git_token, clone_depth, idempotency_key (a repeat with the same key returns the existing session), and project_id (only for workspace-wide callers; a project API key pins the project).

Request field	Description
`display_name`	Required. 1 to 100 characters.
`agent`	`AGENT_SESSION_AGENT_CLAUDE`, `AGENT_SESSION_AGENT_CODEX`, `AGENT_SESSION_AGENT_OPENCODE`, `AGENT_SESSION_AGENT_ORQ`, or `AGENT_SESSION_AGENT_PI`. Unset uses the factory default.
`repository.url`	Required. HTTPS URL without embedded credentials.
`repository.ref`	Branch, tag, or commit. Empty uses the default branch.
`model`	Gateway model id. Unset uses the factory default, then the runtime default.
`computer_template`	Computer template name. Unset uses the factory default, then `coding-session-runc`.
`idle_timeout_seconds`	Minimum 60. Unset uses the factory default, then 1800.

Send a message (start a run)

curl -X POST https://my.orq.ai/v2/agent-sessions/$SESSION_ID/runs \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Add a CI status badge to the README and open the change for review."
  }'

The call returns the run (id, status, continued). If the session is paused it is resumed first, so the call can take a few seconds. Optional fields: agent and model (override for this run), new_conversation (start a fresh conversation), and idempotency_key. Only one run can be active per session.

Read events

Run events (agent output) and session events (lifecycle) are paged by sequence number. Run events:

curl "https://my.orq.ai/v2/agent-sessions/$SESSION_ID/runs/$RUN_ID/events?after_seq=0&limit=200" \
  -H "Authorization: Bearer $ORQ_API_KEY"

Session events:

curl "https://my.orq.ai/v2/agent-sessions/$SESSION_ID/events?after_seq=0" \
  -H "Authorization: Bearer $ORQ_API_KEY"

Each event has seq (a string-encoded integer), type, ts, and data; run events also carry raw, the agent’s native JSON line. Page with after_seq set to the last seq received until has_more is false. Run event types include run.started, acp.session_update (the ACP session/update payload in data), tool.approval_requested, message.complete, run.completed, and run.failed; session event types are listed in the overview.

Live streaming is available over Connect or gRPC only: StreamAgentSessionRunEvents and StreamAgentSessionEvents on orq.platform.v1.AgentSessionsService (both take after_seq to resume). REST clients poll the list endpoints above.

Other endpoints

Method and path	Purpose
`GET /v2/agent-sessions`	List sessions; filter with `project_id` and `factory_id`, page with `limit`, `starting_after`, `ending_before`.
`GET /v2/agent-sessions/{session_id}`	Get a session.
`POST /v2/agent-sessions/{session_id}:pause`	Pause a ready session.
`POST /v2/agent-sessions/{session_id}:resume`	Resume a paused session.
`DELETE /v2/agent-sessions/{session_id}`	Delete a session.
`GET /v2/agent-sessions/{session_id}/runs`	List runs.
`GET /v2/agent-sessions/{session_id}/runs/{run_id}`	Get a run.
`POST /v2/agent-sessions/{session_id}/runs/{run_id}:cancel`	Cancel a run.
`GET /v2/agent-sessions/{session_id}/workspace-diff`	Working tree diff against the clone commit.
`POST /v2/agent-sessions/{session_id}/pull-requests`	Open a pull request: `title` (required), `body`, `base_branch`.
`GET /v2/computer-templates`	Computer templates available in this environment.

Overview

Managed Agents

Context Management

Test & Evaluate

Playground

Create a session

Chat with the agent

Review changes

Open a pull request

Pause, resume, and delete

Sessions list

API

Create a session

Send a message (start a run)

Read events

Other endpoints

​Create a session

​Chat with the agent

​Review changes

​Open a pull request

​Pause, resume, and delete

​Sessions list

​API

​Create a session

​Send a message (start a run)

​Read events

​Other endpoints

Create a session

Chat with the agent

Review changes

Open a pull request

Pause, resume, and delete

Sessions list

API

Create a session

Send a message (start a run)

Read events

Other endpoints