Conversational Tasks

Conversational Tasks

Conversational tasks let you keep the same task alive across multiple user messages. Instead of dispatching a one-shot job and waiting for a final result, you create a conversation for an agent, receive the first message ID immediately, then keep sending follow-up messages on that same task ID.

Use this mode when you want a chat-style workflow with access to the same files, runtime, and task state between turns. Conversation mode is available through the Pi runtime. When you want the agent to take over and finish on its own, switch the task to autonomous mode.

Create a conversation

Create conversations through the agent's conversation endpoint. The response includes both the task and the first queued user message, so clients can correlate the initial turn without listing the transcript.

curl -X POST https://agentcontainer.co/api/v1/agents/agt_standard_coding/conversations \
  -H "Authorization: Bearer ac_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Help me update a TypeScript app safely.",
    "message": "Start by reviewing the routing layer and tell me what looks risky."
  }'

The response shape is different from autonomous task creation because it returns the newly created task and the first generated message resource.

{
  "task": {
    "id": "tsk_abc123",
    "mode": "conversation",
    "status": "pending",
    "agentId": "agt_standard_coding",
    "createdAt": "2026-03-26T12:00:00Z"
  },
  "message": {
    "id": "msg_abc123",
    "role": "user",
    "content": "Start by reviewing the routing layer and tell me what looks risky.",
    "status": "queued",
    "createdAt": "2026-03-26T12:00:00Z"
  }
}

The task in the response moves through conversational states like awaiting_input between turns.

The task object also includes sessionTtlSeconds, which is the idle-session timeout for conversation mode. Once the task reaches awaiting_input, that many seconds can pass without a new message before the session expires.

Send follow-up messages

Use the conversation's /messages sub-resource to continue the conversation. The same task ID is used for the entire lifecycle.

curl -X POST https://agentcontainer.co/api/v1/conversations/tsk_abc123/messages \
  -H "Authorization: Bearer ac_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Now make the smallest safe patch and explain what changed."
  }'

To render the transcript, read /api/v1/conversations/:taskId/messages. This is the canonical paginated conversation history, including the assistant's final reply when the task finishes. It supports limit, cursor, and order. The default order=asc starts at the oldest messages and paginates toward newer history. Use order=desc to start at the latest page and paginate older history; each response page still returns messages oldest first for rendering.

Watch progress

You have two options:

• Poll /api/v1/tasks/:taskId and /api/v1/conversations/:taskId/messages if you want the simplest integration.
• Use /api/v1/conversations/:taskId/events?stream=true if you want a live event stream for task and message updates. The stream is for live updates, not complete transcript replay.

GET /api/v1/conversations/tsk_abc123/events?stream=true
Authorization: Bearer YOUR_API_KEY

The event stream is useful for chat UIs. If you just need the latest state, polling is usually enough. Browser EventSource clients cannot set headers, so pass the API key as a query parameter instead: /api/v1/conversations/:taskId/events?stream=true&apiKey=YOUR_API_KEY.

Status model

Conversational tasks use the same task resource as autonomous tasks, but with a few extra states:

• running — the current turn is executing
• awaiting_input — the task is waiting for the next user message
• finished — the task is done and output files, if any, are available
• expired — the session sat idle past its TTL

You can also switch a task into autonomous mode through /api/v1/conversations/:taskId/autonomous when the user has given enough context and you want the agent to finish independently.

Next steps

For the complete request and response shapes, see the API Reference. For the broader task lifecycle, file uploads, and output handling, see Tasks & Output.