> ## Documentation Index
> Fetch the complete documentation index at: https://arize-ax.mintlify.site/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Sessions

> Create, message, follow, and inspect managed agent sessions with the ag CLI

A **session** is one managed agent run: a sandbox job you create with a prompt, optionally message while it runs, and follow to completion. A session can start from a [preset](/docs/api-clients/ag/presets) and attach [skills](/docs/api-clients/ag/skills). Sessions correspond to one-off runs in the [Managed agents](/docs/ax/agents/build-your-own-agent) UI; recurring runs are [automations](/docs/api-clients/ag/automations).

`ag session`, `ag sessions`, and `ag jobs` are the same command.

## `ag session list`

List recent sessions in a space.

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
ag session list [--space <id>] [--limit <n>] [--columns <list>] [--output <fmt>]
```

| Option | Description |
| - | - |
| `--space` | Space ID (falls back to the saved context) |
| `--limit` | Maximum sessions to list (default: 10) |
| `--columns` | Comma-separated columns for text output (default: `id,status,preset,provider,prompt,created_at`). Available: `id`, `name`, `status`, `preset`, `agent`, `provider`, `prompt`, `created_at`, `updated_at`, `repo`, `sandbox_uuid`, `pr_count` |

**Examples:**

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
ag session list
ag session list --limit 25 --columns id,status,repo,pr_count,created_at
ag session list --output json
```

## `ag session show`

Print a session's metadata, its sandboxes, and its raw events.

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
ag session show <session-id> [--output <fmt>]
```

**Example:**

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
ag session show <session-id> --output json
```

## `ag session create`

Start a new session. `--prompt` is required. Everything else is optional: start from a preset, attach skills, override the repository, or pick a different provider.

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
ag session create --prompt <text> [--space <id>] [--preset <id-or-name>] [--skill <name-or-id>]... [--repo <name-or-url>] [--provider-id <id>] [--claude-agent-id <id>] [--claude-env-id <id>] [--follow]
```

| Option | Description |
| - | - |
| `--prompt` | Initial prompt for the agent (required) |
| `--space` | Space ID (falls back to the saved context) |
| `--preset` | Preset ID or unique preset name. `--agent` is a deprecated alias. |
| `--skill` | Skill name or ID. Repeat the flag or pass a comma-separated list. `--integration` is a deprecated alias. |
| `--repo` | Repository name or URL, overriding the preset's repo |
| `--provider-id` | Sandbox provider ID override |
| `--claude-agent-id` | Claude managed agent ID override |
| `--claude-env-id` | Claude managed environment ID override |
| `--follow`, `-f` | Stream the transcript after the session starts |

**Examples:**

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
# Start from a preset and follow the transcript
ag session create --prompt "Fix the failing tests" --preset oncall-preset --follow

# Smoke test with no preset
ag session create --prompt "hello" --follow

# Attach a skill and override the repo
ag session create \
  --prompt "Investigate the latest 5xx traces" \
  --preset oncall-preset \
  --skill github-default \
  --repo github.com/org/repo \
  --follow
```

## `ag session send`

Send a follow-up message to a running session.

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
ag session send <session-id> --message <text>
```

| Option | Description |
| - | - |
| `--message` | Follow-up message for the agent (required) |

**Example:**

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
ag session send <session-id> --message "Continue from the latest feedback"
```

## `ag session events`

Print a session's transcript, or poll it until you stop. The default view shows each event's `type` and `content`. Use `--raw` or `--output json` for the full job events.

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
ag session events <session-id> [--limit <n>] [--follow] [--raw] [--output <fmt>]
```

| Option | Description |
| - | - |
| `--limit` | Maximum events to include (default: 100) |
| `--follow`, `-f` | Poll for new events every 5 seconds |
| `--raw` | Print raw job events instead of the transcript view |

**Examples:**

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
ag session events <session-id>
ag session events <session-id> --follow
ag session events <session-id> --raw --output json
```

## `ag session artifacts`

List the artifacts a session produced, such as pull requests.

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
ag session artifacts <session-id> [--output <fmt>]
```

## `ag session delete`

Delete a session.

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
ag session delete <session-id>
```

## `ag resume`

Open the interactive TUI on a session's live transcript. Useful after you closed the terminal that was following it.

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
ag resume <session-id>
```

**Example:**

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
ag session list
ag resume <session-id>
```