Build

Sessions

One agent run, from prompt to change request.

A session is the unit of work in Ara. You give it a connected repository and a prompt. Ara starts a cloud agent, gives it a sandbox, and tracks the work until it finishes.

How a session runs

1

Create it

Send a prompt and a repo path. GitHub uses owner/name; GitLab projects can use nested paths. The API returns right away.

2

Follow it

Poll the session for status. Poll messages for the conversation and work log.

3

Steer it

Send another message while it runs, or cancel it if the work should stop.

4

Review it

A completed session may include a pull request or merge request URL, title, summary, cost, token usage, tags, and attachments.

Status

These labels are the exact public session status enum.

StatusMeaning
runningThe agent is still working.
exitThe session finished. Check pr_url and result_summary.
errorThe run failed before completion.
suspendedThe run stopped because it was cancelled or out of quota.

A few practical rules

  • Use an idempotency_key when retrying POST /sessions.
  • Use tags when you need reporting or filtering later.
  • Use attachments for files the agent should see.
  • Use a test repo while you are wiring up automation.
Create a session

Start a cloud agent against a connected repository.

List messages

Poll forward through the session transcript.