> ## Documentation Index
> Fetch the complete documentation index at: https://developer.box.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage sessions and tasks

> Continue multi-turn conversations with the Box Agents API, get stored tasks, and list or delete sessions.

A session is a conversation with an agent. It holds every message you send in that conversation and every task the agent runs in response. The agent uses earlier messages in the session as context, so you can ask follow-up questions without repeating yourself.

| | Session | Task |
| - | - | - |
| What it is | A conversation with an agent | One run of the agent, started by one message |
| ID | `contextId` | The task's `id` |
| Created when | You send a message without a `contextId` | You send any message |
| Contains | One or more tasks | The task's status, artifacts, and message history |

Files the agent creates are saved in the session's own folder, unless you set [`outputDestination`](https://developer.box.com/ai/agents-api/send-requests#configure-the-response). Deleting a session deletes all of its tasks.

This page shows how to continue a conversation, get a stored task, and list or delete sessions.

## Continue a conversation

* Send your first message without a `contextId`. Box creates a session and returns its `contextId` on the task.
* Include that `contextId` on follow-up messages to continue the conversation.
* Don't send a `taskId` to continue a conversation. Box generates task IDs.
* A session runs one task at a time. If you send a message while the previous task is still working, Box refuses it with `409 CONFLICT` (JSON-RPC `-32012`) and doesn't create a task. Wait for the task to finish, or start a new session.

The JavaScript examples on this page use the `client` and `auth` objects from [Send your first request](https://developer.box.com/ai/agents-api/index.md#send-your-first-request).

### First message

```bash cURL theme={null}
RESPONSE=$(curl -sS -X POST "https://api.box.com/a2a/message:send" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "A2A-Version: 1.0" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "messageId": "m-1",
      "role": "ROLE_USER",
      "parts": [
        { "text": "Summarize this contract." },
        {
          "data": { "id": "1728901234567", "type": "file" },
          "mediaType": "application/vnd.box.source-reference+json"
        }
      ]
    }
  }')

CONTEXT_ID=$(echo "$RESPONSE" | jq -r '.task.contextId')
```

```javascript JavaScript theme={null}
const SOURCE_REF = 'application/vnd.box.source-reference+json';

const first = await client.sendMessage(
  SendMessageRequest.fromJSON({
    message: {
      messageId: 'm-1',
      role: 'ROLE_USER',
      parts: [
        { text: 'Summarize this contract.' },
        { data: { id: '1728901234567', type: 'file' }, mediaType: SOURCE_REF },
      ],
    },
  }),
  auth
);

const contextId = first.contextId;
```

The response includes the task ID and the session ID:

```json theme={null}
{
  "task": {
    "id": "3706d316-0832-421d-9ce6-5aa645598ce9",
    "contextId": "410109491801",
    "status": { "state": "TASK_STATE_COMPLETED", "timestamp": "2022-01-01T00:00:00Z" },
    "artifacts": []
  }
}
```

### Follow-up message

Reuse the `contextId`. The response returns the same `contextId` and a new task `id`.

```bash cURL theme={null}
curl -sS -X POST "https://api.box.com/a2a/message:send" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "A2A-Version: 1.0" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "messageId": "m-2",
      "role": "ROLE_USER",
      "contextId": "'"$CONTEXT_ID"'",
      "parts": [{ "text": "What is the termination notice period?" }]
    }
  }'
```

```javascript JavaScript theme={null}
const second = await client.sendMessage(
  SendMessageRequest.fromJSON({
    message: {
      messageId: 'm-2',
      role: 'ROLE_USER',
      contextId,
      parts: [{ text: 'What is the termination notice period?' }],
    },
  }),
  auth
);
```

## Get a task

`GET /tasks/{taskId}` returns a stored task, including its artifacts and history. While the task is working, the result can lag behind a live stream. After the task stops, the result includes everything the task produced. Use `historyLength` to limit how much conversation history Box returns.

```bash cURL theme={null}
curl -sS "https://api.box.com/a2a/tasks/$TASK_ID?historyLength=1" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "A2A-Version: 1.0" | jq
```

```javascript JavaScript theme={null}
const task = await client.getTask({ id: taskId }, auth);

// Limit how much conversation history Box returns.
const trimmed = await client.getTask({ id: taskId, historyLength: 1 }, auth);
```

## List and delete sessions

A2A has no operations for listing or deleting sessions, so Box provides them in the Box API at `/2.0/ai_sessions`. Both require the `ai.readwrite` scope. Session IDs are the same values as A2A `contextId` values.

```bash cURL theme={null}
curl -sS "https://api.box.com/2.0/ai_sessions?source=api&limit=100" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "box-version: 2026.0" | jq
```

```json theme={null}
{
  "entries": [
    {
      "type": "ai_session",
      "id": "410109491801",
      "name": "Q3 pipeline summary",
      "source": "api",
      "created_at": "2022-01-01T00:00:00Z",
      "updated_at": "2022-01-01T00:00:00Z",
      "created_by": { "type": "user", "id": "12345" },
      "updated_by": { "type": "user", "id": "12345" }
    }
  ],
  "limit": 100,
  "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii"
}
```

| Parameter | Required | Value |
| - | - | - |
| `source` | Yes | Must be `api`, which returns sessions created through the Agents API. Other values return `400`. |
| `limit` | No | Page size. Defaults to 100, which is also the maximum. |
| `marker` | No | The `next_marker` value from the previous page |

Sessions are sorted by last activity, most recent first.

To delete a session and all its tasks:

```bash cURL theme={null}
curl -sS -X DELETE "https://api.box.com/2.0/ai_sessions/$CONTEXT_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "box-version: 2026.0"
```

Deletion succeeds even while a task in the session is working, and it doesn't interrupt a client that's streaming that task. You can delete only sessions created through the Agents API. For any other session, the request returns `404`. Deleted sessions and files go to the user's trash.

**RELATED GUIDES**
