Skip to main content
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. Files the agent creates are saved in the session’s own folder, unless you set outputDestination. 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.

First message

The response includes the task ID and the session ID:

Follow-up message

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

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.

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.
cURL
Sessions are sorted by last activity, most recent first. To delete a session and all its tasks:
cURL
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.
Last modified on November 17, 2026