> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orq.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Using Agent Sessions
> Create an agent session on a repository, chat with the agent, follow tool calls and diffs live, review the workspace changes, open a pull request, and drive sessions through the REST and Connect APIs.
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](/docs/ai-studio/ai-engineering/agent-sessions/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](/docs/ai-studio/ai-engineering/agent-sessions/factories-and-connections) 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](/docs/ai-studio/ai-engineering/agent-sessions/factories-and-connections#connections) 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:
1. 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.
2. Pushes the commit to the branch `orq/session-` on the repository's origin, using the session's GitHub token.
3. 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
```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
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)
```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:
```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:
```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](/docs/ai-studio/ai-engineering/agent-sessions/overview#lifecycle).
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. |