Skip to main content

Plan block

Fields​

FieldTypeDescriptionRequired?
typeStringThe type of block. For this block, type will always be plan.Required
titleStringTitle of the plan in plain text.Required
tasksArrayA sequence of task card blocks, maximum of 50 tasks. Each one contains task-like objects without a type, and each task_id in a plan must be unique.Required
block_idStringA unique identifier for a block. If not specified, one will be generated. Maximum length for this field is 255 characters. block_id should be unique for each message and each iteration of a message. If a message is updated, use a new block_id.Optional

Usage info​

A plan block groups related task cards under a single title, so users can follow a multi-step process as one list. Each task shows its own title, status, and optional details and output.

Use a plan when your agent is working through several steps that belong together. For a single action, use a task card block on its own. When streaming a response, set task_display_mode to plan in chat.startStream to show task updates as a plan, and send plan_update chunks to change the plan's title as work progresses.

Examples​

{
  "blocks": [
    {
      "type": "plan",
      "title": "Thinking completed",
      "tasks": [
        {
          "task_id": "call_001",
          "title": "Fetched user profile information",
          "status": "in_progress",
          "details": {
            "type": "rich_text",
            "block_id": "viMWO",
            "elements": [
              {
                "type": "rich_text_section",
                "elements": [
                  {
                    "type": "text",
                    "text": "Searched database..."
                  }
                ]
              }
            ]
          },
          "output": {
            "type": "rich_text",
            "block_id": "viMWO",
            "elements": [
              {
                "type": "rich_text_section",
                "elements": [
                  {
                    "type": "text",
                    "text": "Profile data loaded"
                  }
                ]
              }
            ]
          }
        },
        {
          "task_id": "call_002",
          "title": "Checked user permissions",
          "status": "in_progress"
        },
        {
          "task_id": "call_003",
          "title": "Generated comprehensive user report",
          "status": "complete",
          "output": {
            "type": "rich_text",
            "block_id": "crsk",
            "elements": [
              {
                "type": "rich_text_section",
                "elements": [
                  {
                    "type": "text",
                    "text": "15 data points compiled"
                  }
                ]
              }
            ]
          }
        }
      ]
    }
  ]
}