Skip to content

Commit 3af7d1f

Browse files
nerzhulartnerzhulart
committed
Per-request cancellation mechanism
1 parent 43b8fba commit 3af7d1f

File tree

5 files changed

+152
-0
lines changed

5 files changed

+152
-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: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
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+
14+
* an error response with the Cancelled [error code `-32800`](./schema#param-code)
15+
* a valid response with the appropriate data (e.g., a partial result or a valid result with the Cancelled marker)
16+
17+
- The calling side **MAY** implement graceful cancellation processing by waiting for the cancelled response (error code `-32800`) from the remote side.
18+
19+
- 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.
20+
21+
- 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: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,122 @@ 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 string.
20+
</ResponseField>
21+
<ResponseField name="method" type={"string"} required>
22+
The name of the method to be invoked (e.g., "initialize", "session/new", "session/prompt").
23+
</ResponseField>
24+
<ResponseField name="params" type={"object"}>
25+
A structured value that holds the parameter values to be used during the invocation of the method.
26+
</ResponseField>
27+
<ResponseField name="jsonrpc" type={"string"} required>
28+
The version of the JSON-RPC protocol. Must be exactly "2.0".
29+
</ResponseField>
30+
31+
### <span class="font-mono">JsonRpcResponse</span>
32+
33+
When a JSON-RPC call is made, the server replies with a response.
34+
35+
**Type:** Object
36+
37+
**Properties:**
38+
39+
<ResponseField name="id" type={"integer | string"} required>
40+
This member is required. It must be the same as the value of the id member in the request object.
41+
</ResponseField>
42+
<ResponseField name="result" type={"any"}>
43+
This member is required on success. This member must not exist if there was an error invoking the method. The value is determined by the method invoked on the server.
44+
</ResponseField>
45+
<ResponseField name="error" type={<a href="#jsonrpcerror">Error</a>}>
46+
This member is required on error. This member must not exist if there was no error triggered during invocation.
47+
</ResponseField>
48+
<ResponseField name="jsonrpc" type={"string"} required>
49+
The version of the JSON-RPC protocol. Must be exactly "2.0".
50+
</ResponseField>
51+
52+
### <span class="font-mono">JsonRpcError</span>
53+
54+
When a JSON-RPC call encounters an error, the response contains the error member with a value that is an object.
55+
56+
**Type:** Object
57+
58+
**Properties:**
59+
60+
<ResponseField name="code" type={"integer"} required>
61+
A number that indicates the error type that occurred.
62+
63+
Standard error codes:
64+
- `-32700`: Parse error - Invalid JSON was received
65+
- `-32600`: Invalid request - The JSON sent is not a valid request object
66+
- `-32601`: Method not found - The method does not exist or is not available
67+
- `-32602`: Invalid params - Invalid method parameter(s)
68+
- `-32603`: Internal error - Internal JSON-RPC error
69+
- `-32800`: Cancelled - The request was cancelled
70+
</ResponseField>
71+
<ResponseField name="message" type={"string"} required>
72+
A short description of the error.
73+
</ResponseField>
74+
<ResponseField name="data" type={"any"}>
75+
A primitive or structured value that contains additional information about the error. This may be omitted.
76+
</ResponseField>
77+
78+
### <span class="font-mono">Notification</span>
79+
80+
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.
81+
82+
**Type:** Object
83+
84+
**Properties:**
85+
86+
<ResponseField name="method" type={"string"} required>
87+
The name of the method to be invoked (e.g., "session/cancel", "session/update").
88+
</ResponseField>
89+
<ResponseField name="params" type={"object"}>
90+
A structured value that holds the parameter values to be used during the invocation of the method.
91+
</ResponseField>
92+
<ResponseField name="jsonrpc" type={"string"} required>
93+
The version of the JSON-RPC protocol. MUST be exactly "2.0".
94+
</ResponseField>
95+
96+
97+
### <span class="font-mono">$/cancelRequest</span>
98+
99+
Cancels a previously sent request by its ID.
100+
101+
This is a standard JSON-RPC notification that can be sent by either party to signal
102+
that they are no longer interested in the response to a previously sent request.
103+
104+
#### <span class="font-mono">CancelNotification</span>
105+
106+
Notification parameters for cancelling a request.
107+
108+
**Type:** Object
109+
110+
**Properties:**
111+
112+
<ResponseField name="id" type={"integer | string"} required>
113+
The ID of the request to cancel. Must match the id from a previously sent request.
114+
</ResponseField>
115+
<ResponseField name="method" type={"string"} required>
116+
The name of the method to be invoked (e.g., "session/cancel", "session/update").
117+
</ResponseField>
118+
<ResponseField name="params" type={"object"}>
119+
A structured value that holds the parameter values to be used during the invocation of the method.
120+
</ResponseField>
121+
6122
## Agent
7123

8124
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)