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

agent_client_protocol_schema/
plan.rs
