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

# Agent Plan

> How Agents communicate their execution plans

Plans are execution strategies for complex tasks that require multiple steps.

Agents may share plans with Clients through [`session/update`](/protocol/v2/draft/prompt-lifecycle#3-agent-reports-output) notifications, providing real-time visibility into their thinking and progress.

`plan_update` carries a `plan` object with a `type` discriminator, and every plan format includes a required `planId` so Clients can track multiple plans independently.

The stable plan content type is `items`. The draft unstable schema also includes additional plan operations while the Plan Operations RFD is in progress.

## Creating Plans

When the language model creates an execution plan, the Agent **SHOULD** report it to the Client with `plan_update`.

### Item-Based Plans

```json theme={null}
{
  "jsonrpc": "2.0",
  "method": "session/update",
  "params": {
    "sessionId": "sess_abc123def456",
    "update": {
      "sessionUpdate": "plan_update",
      "plan": {
        "type": "items",
        "planId": "plan-1",
        "entries": [
          {
            "content": "Analyze the existing codebase structure",
            "priority": "high",
            "status": "pending"
          },
          {
            "content": "Identify components that need refactoring",
            "priority": "high",
            "status": "pending"
          },
          {
            "content": "Create unit tests for critical functions",
            "priority": "medium",
            "status": "pending"
          }
        ]
      }
    }
  }
}
```

<ParamField path="plan.type" type="string" required>
  The plan content type.
</ParamField>

<ParamField path="plan.planId" type="PlanId" required>
  A unique identifier for this plan within the session.
</ParamField>

<ParamField path="plan.entries" type="PlanEntry[]" required>
  An array of [plan entries](#plan-entries) representing the tasks to be
  accomplished.
</ParamField>

## Unstable Plan Operations

The draft unstable schema includes markdown plans, file-backed plans, and explicit plan removal. These operations are not part of the stable schema yet.

Clients using the draft unstable schema **MUST** tolerate these variants. Tolerating a variant means the Client can deserialize and validate it, then render it, preserve it for replay or proxying, or ignore it.

No Client capability is required in v2. Clients using only the baseline schema
accept unfamiliar plan representations through the unknown plan-content fallback
and unfamiliar removal updates through the unknown session-update fallback.
Agents cannot assume that these plans will be rendered. See [Experimental
Features and Negotiation](/protocol/v2/draft/extensibility#experimental-features-and-negotiation).

### Markdown Plans

```json theme={null}
{
  "jsonrpc": "2.0",
  "method": "session/update",
  "params": {
    "sessionId": "sess_abc123def456",
    "update": {
      "sessionUpdate": "plan_update",
      "plan": {
        "type": "markdown",
        "planId": "implementation-plan",
        "content": "## Steps\n- [ ] Refactor module\n- [ ] Add tests"
      }
    }
  }
}
```

### File Plans

```json theme={null}
{
  "jsonrpc": "2.0",
  "method": "session/update",
  "params": {
    "sessionId": "sess_abc123def456",
    "update": {
      "sessionUpdate": "plan_update",
      "plan": {
        "type": "file",
        "planId": "design-doc",
        "uri": "file:///tmp/plan.md"
      }
    }
  }
}
```

Plan file URIs **MUST** be absolute.

## Removing Plans

Agents can remove a plan by sending `plan_removed` with the plan ID:

```json theme={null}
{
  "jsonrpc": "2.0",
  "method": "session/update",
  "params": {
    "sessionId": "sess_abc123def456",
    "update": {
      "sessionUpdate": "plan_removed",
      "planId": "plan-1"
    }
  }
}
```

## Extensibility

`plan.type` values can be custom or future variants when Clients can preserve or display them generically. Custom plan content types **MUST** begin with `_`; unknown non-underscore plan content types are reserved for future ACP variants.

Every plan content variant, including custom or future variants, **MUST** carry a `planId`.

## Plan Entries

Each plan entry represents a specific task or goal within the overall execution strategy:

<ParamField path="content" type="string" required>
  A human-readable description of what this task aims to accomplish
</ParamField>

<ParamField path="priority" type="PlanEntryPriority" required>
  The relative importance of this task.

  * `high`
  * `medium`
  * `low`

  Custom or future priority values can be used for display hints. Custom priorities **MUST** begin with `_`; unknown non-underscore priorities are reserved for future ACP variants.
</ParamField>

<ParamField path="status" type="PlanEntryStatus" required>
  The current [execution status](#status) of this task

  * `pending`
  * `in_progress`
  * `completed`
  * `cancelled`

  Custom or future status values can be used when Clients can preserve or display a generic plan-entry state. Custom statuses **MUST** begin with `_`; unknown non-underscore statuses are reserved for future ACP variants.
</ParamField>

## Updating Plans

As the Agent progresses through the plan, it **SHOULD** report updates by sending more `session/update` notifications with the same `sessionUpdate: "plan_update"` structure and `planId`.

For item-based plans, the Agent **MUST** send a complete list of all plan entries in each update and their current status. The Client **MUST** replace the current contents of that plan completely.

### Dynamic Planning

Plans can evolve during execution. The Agent **MAY** add, remove, or modify plan entries as it discovers new requirements or completes tasks, allowing it to adapt based on what it learns.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.