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

agent_client_protocol_schema/
plan.rs
