claude_api/managed_agents/
mod.rs

1//! Anthropic Managed Agents API (preview).
2//!
3//! Managed Agents lets you provision long-running agent sessions backed by
4//! Anthropic-managed compute environments, persistent memory stores, and
5//! credential vaults. Each session references a versioned agent and an
6//! environment, drives a [stream of events](crate::managed_agents::events),
7//! and may produce outputs as files.
8//!
9//! # Beta status
10//!
11//! All requests in this module require the `managed-agents-2026-04-01`
12//! beta header, which the SDK adds automatically. Outcomes additionally
13//! require `managed-agents-2026-04-01-research-preview`.
14//!
15//! **The API surface is in preview and will change.** Field names,
16//! request shapes, and resource relationships are not yet stable. We
17//! follow the broader claude-api forward-compatibility contract: every
18//! union deserializes into `Other(Value)` when the wire `type` tag is
19//! unknown, so brand-new variants don't break the build. New `Known`
20//! variants are minor bumps that may require sweeping `Other` matches.
21//!
22//! Gated on the `managed-agents-preview` feature.
23//!
24//! # Layout
25//!
26//! - [`sessions`] -- create, retrieve, list, archive, delete sessions;
27//!   send and stream events.
28//! - [`vaults`] -- credential vaults for MCP authentication.
29//! - [`memory_stores`] -- persistent memory across sessions.
30//! - [`agents`] -- agent definitions (create only in this version; full
31//!   CRUD lands once docs are available).
32//!
33//! # Create a session and send a message
34//!
35//! ```no_run
36//! use claude_api::{Client,
37//!     managed_agents::sessions::{AgentRef, CreateSessionRequest},
38//!     managed_agents::events::OutgoingUserEvent};
39//! # async fn run() -> Result<(), claude_api::Error> {
40//! let client = Client::new(std::env::var("ANTHROPIC_API_KEY").unwrap());
41//! let ma = client.managed_agents();
42//! let session = ma.sessions().create(
43//!     CreateSessionRequest::builder()
44//!         .agent(AgentRef::latest("agt_..."))
45//!         .build()?,
46//! ).await?;
47//! let sessions = ma.sessions();
48//! sessions.events(session.id)
49//!     .send(&[OutgoingUserEvent::message("Hello!")])
50//!     .await?;
51//! # Ok(())
52//! # }
53//! ```
54
55#![cfg(feature = "managed-agents-preview")]
56#![cfg_attr(docsrs, doc(cfg(feature = "managed-agents-preview")))]
57
58use crate::client::Client;
59
60pub mod agents;
61pub mod environments;
62pub mod events;
63pub mod memory_stores;
64pub mod resources;
65pub mod sessions;
66pub mod threads;
67pub mod vaults;
68
69/// Top-level namespace handle for the Managed Agents API.
70///
71/// Obtained via [`Client::managed_agents`].
72pub struct ManagedAgents<'a> {
73    client: &'a Client,
74}
75
76impl<'a> ManagedAgents<'a> {
77    pub(crate) fn new(client: &'a Client) -> Self {
78        Self { client }
79    }
80
81    /// Sessions sub-namespace.
82    #[must_use]
83    pub fn sessions(&self) -> sessions::Sessions<'a> {
84        sessions::Sessions::new(self.client)
85    }
86
87    /// Vaults sub-namespace (per-user MCP credential vaults).
88    #[must_use]
89    pub fn vaults(&self) -> vaults::Vaults<'a> {
90        vaults::Vaults::new(self.client)
91    }
92
93    /// Memory stores sub-namespace (persistent memory across sessions).
94    #[must_use]
95    pub fn memory_stores(&self) -> memory_stores::MemoryStores<'a> {
96        memory_stores::MemoryStores::new(self.client)
97    }
98
99    /// Agents sub-namespace (currently `create` only).
100    #[must_use]
101    pub fn agents(&self) -> agents::Agents<'a> {
102        agents::Agents::new(self.client)
103    }
104
105    /// Environments sub-namespace (full CRUD + archive).
106    #[must_use]
107    pub fn environments(&self) -> environments::Environments<'a> {
108        environments::Environments::new(self.client)
109    }
110}
111
112/// Beta header value required on every Managed Agents API request.
113pub(crate) const MANAGED_AGENTS_BETA: &str = "managed-agents-2026-04-01";
114
115/// Additional beta header value required for research-preview features
116/// like outcomes. Add **alongside** [`MANAGED_AGENTS_BETA`]. Opt in
117/// via [`Sessions::with_research_preview`](sessions::Sessions::with_research_preview).
118pub(crate) const MANAGED_AGENTS_RESEARCH_PREVIEW_BETA: &str =
119    "managed-agents-2026-04-01-research-preview";
120
121/// Pick the right beta-header slice for a Managed Agents request.
122///
123/// Returns the base header on its own, or both headers when the
124/// caller has opted into research-preview features (outcomes via
125/// `user.define_outcome` events, span outcome events, and the
126/// `Session.outcome_evaluations` field).
127pub(crate) const fn betas(research_preview: bool) -> &'static [&'static str] {
128    if research_preview {
129        &[MANAGED_AGENTS_BETA, MANAGED_AGENTS_RESEARCH_PREVIEW_BETA]
130    } else {
131        &[MANAGED_AGENTS_BETA]
132    }
133}
claude_api/managed_agents/mod.rs

claude_api/managed_agents/
mod.rs
