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.
The agent owns the inserted user message. Match it to this submission
by the response’s message_id, never by content or arrival order: the
content the agent reports for it can differ from prompt.
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 the prompts the
agent has received and 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. While the agent recognizes the key,
it inserts at most one user message for it in a session and answers a
retry with the messageId of the message it already inserted, without
starting the work again. To retry, call this again with the same key
and the same prompt. Each attempt is its own request.
A retry is not always safe. On a new connection, resume the session
before you retry. A successful session/resume does not tell you
whether the prompt was inserted or whether the agent kept the key, and
a retry with a forgotten key is a new submission. If a duplicate would
matter and you cannot rule one out, do not resend the prompt
automatically. Tell the user that it might already have run and let
them decide.
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. For a message it does not retain, it recognizes the key while the session stays active on a connection.
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
idle update is required when nothing was running. The agent sends that
update before it starts new foreground work in the session, and it does
not reject a prompt because cancellation is in progress. cancelled is
only reported for work the client cancelled, through this notification
or by closing the session, and for a child session whose parent
cancelled its work. The client should immediately mark unfinished tool
calls for the active work as cancelled.
Keep accepting updates after sending this notification. Updates for
listed background work can arrive after the idle update. To stop a
listed tool call or terminal, send tool_call/cancel or
terminal/cancel while the item advertises capabilities.cancel.
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.
§Errors
Returns an error if the cancellation notification cannot be encoded or queued. Success does not mean the agent has finished cancelling.
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 options of a child session are read-only, so do not call this for
one.
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). After the close response the agent
sends no notifications or requests for the session. It still answers
session/prompt requests that were pending.
A child session cannot be closed on its own. Close its root session instead.
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.