Containers Chat API: Sample Flows

This article presents possible use cases and corresponding sample flows that you can support. It provides a useful starting point as you plan your implementation.

Send a message and track the assistant's response

When a user asks the coding agent to change their project, your app sends the request as a message and then shows the agent's progress until the response is ready. The API doesn't push updates, so your app polls for the current state of the conversation.

To send a message and track the assistant's response:

1. Call Create Conversation with the project's ID in conversation.projectId. Save the returned conversation.id.

2. Call Send Message with the conversation ID, the user's request in parts, and a unique idempotencyKey. Save the returned message.id. This is the user message ID.

3. Call Query Messages with the conversation ID. Find the assistant message whose inReplyToId matches the user message ID. Its status is WORKING, and its tasks list shows the agent's current work items.

4. Continue to call Query Messages at regular intervals, and update the task checklist in your app, until the assistant message's status changes to DONE or ERROR.

5. Show the assistant message's parts to the user. When the status is DONE, parts holds the agent's response. When the status is ERROR, parts holds the reason for the failure.

6. Show the questions in followUpQuestionOptions as suggested next requests. When the user selects one, call Send Message again with a new idempotencyKey.

Answer a clarifying questionnaire

Sometimes the coding agent needs more information before it can continue. In this case, the assistant message is completed with type set to QUESTIONNAIRE instead of TEXT. Your app shows the questions, collects the user's answers, and sends them back to the agent.

To answer a clarifying questionnaire:

1. Call Query Messages with the conversation ID. Find the assistant message with DONE status and type set to QUESTIONNAIRE. Save its id. This is the questionnaire message ID.

2. Show the questions in questionnairePayload.questions to the user. For each question, show its options. Let the user select more than one option when multiSelect is true, and let the user type their own answer.

3. Call Send Message with these values:

   • type: QUESTIONNAIRE_RESPONSE.

   • questionnaireResponsePayload.questionnaireMessageId: The questionnaire message ID.

   • questionnaireResponsePayload.answers: The user's answers, keyed by each question's id. For example:

     Copy

   • idempotencyKey: A new unique key.

4. Call Query Messages at regular intervals to track the new assistant message that replies to the user's answers, the same as in Send a message and track the assistant's response.