pub struct ActiveSession<Link>{ /* private fields */ }unstable_protocol_v2 only.Expand description
Cloneable command handle for a draft protocol v2 session.
Inbound protocol traffic is intentionally not owned by this value. Receive
authoritative v2::schema::UpdateSessionNotification values and interactive
requests such as v2::schema::RequestPermissionRequest through typed handlers
installed on v2::Builder.
Implementations§
Source§impl<Link> ActiveSession<Link>
impl<Link> ActiveSession<Link>
Sourcepub fn session_id(&self) -> &SessionId
pub fn session_id(&self) -> &SessionId
Access the session ID.
Sourcepub fn connection(&self) -> &ConnectionTo<Link>
pub fn connection(&self) -> &ConnectionTo<Link>
Access the underlying connection.
Sourcepub fn send_prompt(
&self,
prompt: impl ToString,
) -> SentRequest<PromptResponse, V2>
pub fn send_prompt( &self, prompt: impl ToString, ) -> SentRequest<PromptResponse, V2>
Submit a text prompt and return its independent acceptance request.
A successful response only acknowledges that the agent accepted the
prompt. The accepted user message, output, state changes, and completion
arrive independently through v2::schema::UpdateSessionNotification.
Sourcepub fn send_prompt_blocks(
&self,
prompt: Vec<ContentBlock>,
) -> SentRequest<PromptResponse, V2>
pub fn send_prompt_blocks( &self, prompt: Vec<ContentBlock>, ) -> SentRequest<PromptResponse, V2>
Submit arbitrary prompt content and return its acceptance request.
prompt must not be empty; an agent may reject [] with -32602.
The SDK does not track foreground state or gate prompt submission locally. A prompt may be sent in any state, including while foreground work is active: the agent either inserts it right away or holds it and inserts held prompts in received order, and it must not reject a prompt only because work is active. A held prompt’s response stays pending until it is inserted.
Self::cancel_active_work and Self::close drop every prompt the
agent has not inserted, and the agent answers each with -32800.
Cancelling the returned SentRequest sends $/cancel_request, which
is best effort: an agent that honors it answers -32800 and does not
insert the message, and otherwise the prompt is inserted as usual and
the response carries its messageId. An inserted prompt cannot be
withdrawn. Stop the work it started with Self::cancel_active_work.
A prompt sent this way has no idempotency key, so sending it again
after a lost response can insert a second user message. Use
Self::send_prompt_blocks_with_key for a prompt you may need to
retry.
Sourcepub fn send_prompt_blocks_with_key(
&self,
prompt: Vec<ContentBlock>,
idempotency_key: IdempotencyKey,
) -> SentRequest<PromptResponse, V2>
pub fn send_prompt_blocks_with_key( &self, prompt: Vec<ContentBlock>, idempotency_key: IdempotencyKey, ) -> SentRequest<PromptResponse, V2>
Submit prompt content with an idempotency key and return its acceptance request.
The key identifies one submission. The agent inserts at most one user
message for a key in a session and answers a retry with the messageId
of the message it already inserted, without starting the work again.
To retry after a lost response, for example on a new connection after
session/resume, call this again with the same key and the same
prompt. Each attempt is its own request.
Create the key when the user submits the input, with
v2::schema::IdempotencyKey::generate
or another random value, and store it with the pending input. Use a
new key for a new submission, including when the user sends the same
text again on purpose. Do not derive the key from the content, and do
not send the same key with a different prompt.
An error response means the message was not inserted and leaves the key unused, so the same prompt can be sent again with the same key. The agent recognizes a key for as long as it retains the message.
See https://agentclientprotocol.com/protocol/v2/prompt-lifecycle#retrying-a-prompt.
Sourcepub fn cancel_active_work(&self) -> Result<(), Error>
pub fn cancel_active_work(&self) -> Result<(), Error>
Ask the agent to cancel the session’s current foreground work.
This is independent from cancelling a prompt’s SentRequest.
session/cancel covers the session’s foreground work and prompts
received before it that the agent has not yet inserted; those prompt
requests fail with -32800 (request cancelled). A prompt sent after
this notification is not cancelled by it. A prompt whose user message was already
inserted still succeeds with its messageId. Work in the latest
background list is not covered and keeps running.
If foreground work was active, cancellation completes when the agent
reports an idle state update with v2::schema::StopReason::Cancelled; no
completion update is required when nothing was running. cancelled is only
reported for work the client cancelled, through this notification or
by closing the session. The client should immediately mark unfinished
tool calls for the active work as cancelled.
The agent stops waiting for pending
v2::schema::RequestPermissionRequests
of the cancelled work and must cancel each of them with
$/cancel_request. The agent decides which requests belong to that
work, so do not answer every pending permission request when you send
this notification. When $/cancel_request arrives for a permission
request you have not answered, dismiss the prompt and answer with the
cancelled outcome. A client may also answer a request it knows belongs
to the cancelled work that way without waiting for $/cancel_request.
See https://agentclientprotocol.com/protocol/v2/prompt-lifecycle#cancellation.
Sourcepub fn set_config_option(
&self,
config_id: impl Into<SessionConfigId>,
value: impl Into<SessionConfigOptionValue>,
) -> SentRequest<SetSessionConfigOptionResponse, V2>
pub fn set_config_option( &self, config_id: impl Into<SessionConfigId>, value: impl Into<SessionConfigOptionValue>, ) -> SentRequest<SetSessionConfigOptionResponse, V2>
Set a session configuration option.
Only send a config_id the agent advertised for this session, with a
value from that option. The agent rejects an unknown config_id or an
invalid value with -32602 and leaves the configuration unchanged.
The response contains the complete option set as of the response and
may report a different currentValue than requested; currentValue
is always the value the agent is using. Apply responses and
config_option_update notifications in the order received, each
replacing the whole list. A duplicate config_option_update
notification for the same change may arrive before the response. The
response is not cached on this command handle.
See https://agentclientprotocol.com/protocol/v2/session-config-options.
Sourcepub fn close(&self) -> SentRequest<CloseSessionResponse, V2>
pub fn close(&self) -> SentRequest<CloseSessionResponse, V2>
Close the remote session and release its resources.
The agent cancels the session’s ongoing work as if session/cancel had
been sent. When that cancels active foreground work, the agent sends the
work’s final updates and an idle state update with stop reason
cancelled before it responds to session/close. A pending prompt
whose user message closing kept from being inserted fails with -32800
(request cancelled); one already inserted still succeeds with its
message ID. Prompt responses need not precede the close response.
Before it responds, the agent cancels every pending permission request
and elicitation in the session with $/cancel_request.
Existing clones of this local command handle are not invalidated, but
the session is no longer active: the agent rejects later commands for it
with -32002 (resource not found).
Closing is idempotent. An agent should answer a close of an unknown or
already-closed session with success, and an older agent may answer
-32002 instead, so this helper resolves a -32002 response as a
successful, empty v2::schema::CloseSessionResponse. Other errors are
returned unchanged.
See https://agentclientprotocol.com/protocol/v2/session-setup#closing-active-sessions.