agent_client_protocol_schema/
plan.rs

1//! Execution plans for complex tasks that require multiple steps.
2//!
3//! Plans are strategies that agents share with clients through session updates,
4//! providing real-time visibility into their thinking and progress.
5//!
6//! See: [Agent Plan](https://agentclientprotocol.com/protocol/agent-plan)
7
8use schemars::JsonSchema;
9use serde::{Deserialize, Serialize};
10use serde_with::{DefaultOnError, VecSkipError, serde_as, skip_serializing_none};
11
12use crate::{IntoOption, Meta, SkipListener};
13
14/// An execution plan for accomplishing complex tasks.
15///
16/// Plans consist of multiple entries representing individual tasks or goals.
17/// Agents report plans to clients to provide visibility into their execution strategy.
18/// Plans can evolve during execution as the agent discovers new requirements or completes tasks.
19///
20/// See protocol docs: [Agent Plan](https://agentclientprotocol.com/protocol/agent-plan)
21#[serde_as]
22#[skip_serializing_none]
23#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)]
24#[serde(rename_all = "camelCase")]
25#[non_exhaustive]
26pub struct Plan {
27    /// The list of tasks to be accomplished.
28    ///
29    /// When updating a plan, the agent must send a complete list of all entries
30    /// with their current status. The client replaces the entire plan with each update.
31    #[serde_as(deserialize_as = "DefaultOnError<VecSkipError<_, SkipListener>>")]
32    pub entries: Vec<PlanEntry>,
33    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
34    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
35    /// these keys.
36    ///
37    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)
38    #[serde(rename = "_meta")]
39    pub meta: Option<Meta>,
40}
41
42impl Plan {
43    #[must_use]
44    pub fn new(entries: Vec<PlanEntry>) -> Self {
45        Self {
46            entries,
47            meta: None,
48        }
49    }
50
51    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
52    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
53    /// these keys.
54    ///
55    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)
56    #[must_use]
57    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
58        self.meta = meta.into_option();
59        self
60    }
61}
62
63/// A single entry in the execution plan.
64///
65/// Represents a task or goal that the assistant intends to accomplish
66/// as part of fulfilling the user's request.
67/// See protocol docs: [Plan Entries](https://agentclientprotocol.com/protocol/agent-plan#plan-entries)
68#[skip_serializing_none]
69#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)]
70#[serde(rename_all = "camelCase")]
71#[non_exhaustive]
72pub struct PlanEntry {
73    /// Human-readable description of what this task aims to accomplish.
74    pub content: String,
75    /// The relative importance of this task.
76    /// Used to indicate which tasks are most critical to the overall goal.
77    pub priority: PlanEntryPriority,
78    /// Current execution status of this task.
79    pub status: PlanEntryStatus,
80    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
81    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
82    /// these keys.
83    ///
84    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)
85    #[serde(rename = "_meta")]
86    pub meta: Option<Meta>,
87}
88
89impl PlanEntry {
90    #[must_use]
91    pub fn new(
92        content: impl Into<String>,
93        priority: PlanEntryPriority,
94        status: PlanEntryStatus,
95    ) -> Self {
96        Self {
97            content: content.into(),
98            priority,
99            status,
100            meta: None,
101        }
102    }
103
104    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
105    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
106    /// these keys.
107    ///
108    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)
109    #[must_use]
110    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
111        self.meta = meta.into_option();
112        self
113    }
114}
115
116/// Priority levels for plan entries.
117///
118/// Used to indicate the relative importance or urgency of different
119/// tasks in the execution plan.
120/// See protocol docs: [Plan Entries](https://agentclientprotocol.com/protocol/agent-plan#plan-entries)
121#[derive(Deserialize, Serialize, JsonSchema, Debug, Clone, PartialEq, Eq)]
122#[serde(rename_all = "snake_case")]
123#[non_exhaustive]
124pub enum PlanEntryPriority {
125    /// High priority task - critical to the overall goal.
126    High,
127    /// Medium priority task - important but not critical.
128    Medium,
129    /// Low priority task - nice to have but not essential.
130    Low,
131}
132
133/// Status of a plan entry in the execution flow.
134///
135/// Tracks the lifecycle of each task from planning through completion.
136/// See protocol docs: [Plan Entries](https://agentclientprotocol.com/protocol/agent-plan#plan-entries)
137#[derive(Deserialize, Serialize, JsonSchema, Debug, Clone, PartialEq, Eq)]
138#[serde(rename_all = "snake_case")]
139#[non_exhaustive]
140pub enum PlanEntryStatus {
141    /// The task has not started yet.
142    Pending,
143    /// The task is currently being worked on.
144    InProgress,
145    /// The task has been successfully completed.
146    Completed,
147}
agent_client_protocol_schema/plan.rs

agent_client_protocol_schema/
plan.rs
