Skip to content

Commit 82b5a5f

Browse files
nerzhulartnerzhulart
committed
Per-request cancellation mechanism
1 parent 43b8fba commit 82b5a5f

File tree

5 files changed

+164
-0
lines changed

5 files changed

+164
-0
lines changed

‎docs/docs.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,7 @@
6767
"protocol/slash-commands",
6868
"protocol/extensibility",
6969
"protocol/transports",
70+
"protocol/cancellation",
7071
"protocol/schema"
7172
]
7273
},

‎docs/protocol/cancellation.mdx‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
---
2+
title: "Cancellation"
3+
description: "Mechanisms for request cancellation"
4+
---
5+
6+
ACP uses JSON-RPC 2.0 for making requests and getting responses.
7+
8+
The JSON-RPC specification doesn't define any standard mechanism for request cancellation and keeps it up to the implementation.
9+
10+
- The agent and the client **MUST** implement [$/cancelRequest](./schema#%24%2Fcancelrequest) notification method to support per-request cancellation.
11+
12+
- When a cancellation request is received from the remote side, the corresponding request activity and all nested activities (including outgoing requests) **MUST** be cancelled, then one of the responses **MUST** be sent back:
13+
- an error response with the Cancelled [error code `-32800`](./schema#param-code)
14+
- a valid response with the appropriate data (e.g., a partial result or a valid result with the Cancelled marker)
15+
16+
- The calling side **MAY** implement graceful cancellation processing by waiting for the cancelled response (error code `-32800`) from the remote side.
17+
18+
- The request **MAY** be also cancelled from inside the request handler activity (e.g. when a heavy action is being performed in IDE by a request and the user cancels it explicitly). In this case the response with the [error code `-32800`](./schema#param-code) and the appropriate message **MUST** be sent back and the cancellation **SHOULD** be propagated on the calling side.
19+
20+
- Cancellation **MAY** also be done explicitly on a per-feature basis to cover the bigger scope of things to cancel (e.g., cancellation of a [prompt turn](./prompt-turn#cancellation))

‎docs/protocol/schema.mdx‎

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,135 @@ title: "Schema"
33
description: "Schema definitions for the Agent Client Protocol"
44
---
55

6+
## JSON RPC
7+
8+
The Agent Client Protocol uses JSON RPC 2.0 for communication.
9+
10+
### <span class="font-mono">JsonRpcRequest</span>
11+
12+
A JSON-RPC request is represented by sending a request object to the remote side.
13+
14+
**Type:** Object
15+
16+
**Properties:**
17+
18+
<ResponseField name="id" type={"integer | string"} required>
19+
An identifier established by the calling side. The id must be a integer or
20+
string.
21+
</ResponseField>
22+
<ResponseField name="method" type={"string"} required>
23+
The name of the method to be invoked (e.g., "initialize", "session/new",
24+
"session/prompt").
25+
</ResponseField>
26+
<ResponseField name="params" type={"object"}>
27+
A structured value that holds the parameter values to be used during the
28+
invocation of the method.
29+
</ResponseField>
30+
<ResponseField name="jsonrpc" type={"string"} required>
31+
The version of the JSON-RPC protocol. Must be exactly "2.0".
32+
</ResponseField>
33+
34+
### <span class="font-mono">JsonRpcResponse</span>
35+
36+
When a JSON-RPC call is made, the server replies with a response.
37+
38+
**Type:** Object
39+
40+
**Properties:**
41+
42+
<ResponseField name="id" type={"integer | string"} required>
43+
This member is required. It must be the same as the value of the id member in
44+
the request object.
45+
</ResponseField>
46+
<ResponseField name="result" type={"any"}>
47+
This member is required on success. This member must not exist if there was an
48+
error invoking the method. The value is determined by the method invoked on
49+
the server.
50+
</ResponseField>
51+
<ResponseField name="error" type={<a href="#jsonrpcerror">Error</a>}>
52+
This member is required on error. This member must not exist if there was no
53+
error triggered during invocation.
54+
</ResponseField>
55+
<ResponseField name="jsonrpc" type={"string"} required>
56+
The version of the JSON-RPC protocol. Must be exactly "2.0".
57+
</ResponseField>
58+
59+
### <span class="font-mono">JsonRpcError</span>
60+
61+
When a JSON-RPC call encounters an error, the response contains the error member with a value that is an object.
62+
63+
**Type:** Object
64+
65+
**Properties:**
66+
67+
<ResponseField name="code" type={"integer"} required>
68+
A number that indicates the error type that occurred.
69+
70+
Standard error codes:
71+
72+
- `-32700`: Parse error - Invalid JSON was received
73+
- `-32600`: Invalid request - The JSON sent is not a valid request object
74+
- `-32601`: Method not found - The method does not exist or is not available
75+
- `-32602`: Invalid params - Invalid method parameter(s)
76+
- `-32603`: Internal error - Internal JSON-RPC error
77+
- `-32800`: Cancelled - The request was cancelled
78+
79+
</ResponseField>
80+
<ResponseField name="message" type={"string"} required>
81+
A short description of the error.
82+
</ResponseField>
83+
<ResponseField name="data" type={"any"}>
84+
A primitive or structured value that contains additional information about the error. This may be omitted.
85+
</ResponseField>
86+
87+
### <span class="font-mono">Notification</span>
88+
89+
A notification is a request object without an "id" member. Notifications express a lack of interest in the corresponding response and as such no response needs to be returned.
90+
91+
**Type:** Object
92+
93+
**Properties:**
94+
95+
<ResponseField name="method" type={"string"} required>
96+
The name of the method to be invoked (e.g., "session/cancel",
97+
"session/update").
98+
</ResponseField>
99+
<ResponseField name="params" type={"object"}>
100+
A structured value that holds the parameter values to be used during the
101+
invocation of the method.
102+
</ResponseField>
103+
<ResponseField name="jsonrpc" type={"string"} required>
104+
The version of the JSON-RPC protocol. MUST be exactly "2.0".
105+
</ResponseField>
106+
107+
### <span class="font-mono">$/cancelRequest</span>
108+
109+
Cancels a previously sent request by its ID.
110+
111+
This is a standard JSON-RPC notification that can be sent by either party to signal
112+
that they are no longer interested in the response to a previously sent request.
113+
114+
#### <span class="font-mono">CancelNotification</span>
115+
116+
Notification parameters for cancelling a request.
117+
118+
**Type:** Object
119+
120+
**Properties:**
121+
122+
<ResponseField name="id" type={"integer | string"} required>
123+
The ID of the request to cancel. Must match the id from a previously sent
124+
request.
125+
</ResponseField>
126+
<ResponseField name="method" type={"string"} required>
127+
The name of the method to be invoked (e.g., "session/cancel",
128+
"session/update").
129+
</ResponseField>
130+
<ResponseField name="params" type={"object"}>
131+
A structured value that holds the parameter values to be used during the
132+
invocation of the method.
133+
</ResponseField>
134+
6135
## Agent
7136

8137
Defines the interface that all ACP-compliant agents must implement.

‎schema/meta.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,7 @@
11
{
2+
"jsonRpcMethods": {
3+
"cancel_request": "$/cancelRequest"
4+
},
25
"agentMethods": {
36
"authenticate": "authenticate",
47
"initialize": "initialize",

‎schema/schema.json‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,16 @@
11
{
22
"$defs": {
3+
"CancelNotification": {
4+
"description": "Parameter type for JsonRPC cancellation method `$/cancelRequest`.\n\nA request that got canceled still needs send a response with cancellation signal back. It can not be left open / hanging.",
5+
"properties": {
6+
"id": {
7+
"description": "ID of JsonRPC request to cancel",
8+
"type": "integer"
9+
}
10+
},
11+
"type": "object",
12+
"x-method": "$/cancelRequest"
13+
},
314
"AgentCapabilities": {
415
"description": "Capabilities supported by the agent.\n\nAdvertised during initialization to inform the client about\navailable features and content types.\n\nSee protocol docs: [Agent Capabilities](https://agentclientprotocol.com/protocol/initialization#agent-capabilities)",
516
"properties": {

0 commit comments

Comments
 (0)