diff --git a/docs/docs.json b/docs/docs.json index d770659a..f94bcb8e 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -67,6 +67,7 @@ "protocol/slash-commands", "protocol/extensibility", "protocol/transports", + "protocol/cancellation", "protocol/schema" ] }, diff --git a/docs/protocol/cancellation.mdx b/docs/protocol/cancellation.mdx new file mode 100644 index 00000000..261f274d --- /dev/null +++ b/docs/protocol/cancellation.mdx @@ -0,0 +1,20 @@ +--- +title: "Cancellation" +description: "Mechanisms for request cancellation" +--- + +ACP uses JSON-RPC 2.0 for making requests and getting responses. + +The JSON-RPC specification doesn't define any standard mechanism for request cancellation and keeps it up to the implementation. + +- The agent and the client **MUST** implement [$/cancelRequest](./schema#%24%2Fcancelrequest) notification method to support per-request cancellation. + +- 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: + - an error response with the Cancelled [error code `-32800`](./schema#param-code) + - a valid response with the appropriate data (e.g., a partial result or a valid result with the Cancelled marker) + +- The calling side **MAY** implement graceful cancellation processing by waiting for the cancelled response (error code `-32800`) from the remote side. + +- 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. + +- 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)) diff --git a/docs/protocol/schema.mdx b/docs/protocol/schema.mdx index 5e6cf08c..3f1c58a7 100644 --- a/docs/protocol/schema.mdx +++ b/docs/protocol/schema.mdx @@ -3,6 +3,135 @@ title: "Schema" description: "Schema definitions for the Agent Client Protocol" --- +## JSON RPC + +The Agent Client Protocol uses JSON RPC 2.0 for communication. + +### JsonRpcRequest + +A JSON-RPC request is represented by sending a request object to the remote side. + +**Type:** Object + +**Properties:** + + + An identifier established by the calling side. The id must be a integer or + string. + + + The name of the method to be invoked (e.g., "initialize", "session/new", + "session/prompt"). + + + A structured value that holds the parameter values to be used during the + invocation of the method. + + + The version of the JSON-RPC protocol. Must be exactly "2.0". + + +### JsonRpcResponse + +When a JSON-RPC call is made, the server replies with a response. + +**Type:** Object + +**Properties:** + + + This member is required. It must be the same as the value of the id member in + the request object. + + + 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. + +Error}> + This member is required on error. This member must not exist if there was no + error triggered during invocation. + + + The version of the JSON-RPC protocol. Must be exactly "2.0". + + +### JsonRpcError + +When a JSON-RPC call encounters an error, the response contains the error member with a value that is an object. + +**Type:** Object + +**Properties:** + + + A number that indicates the error type that occurred. + +Standard error codes: + +- `-32700`: Parse error - Invalid JSON was received +- `-32600`: Invalid request - The JSON sent is not a valid request object +- `-32601`: Method not found - The method does not exist or is not available +- `-32602`: Invalid params - Invalid method parameter(s) +- `-32603`: Internal error - Internal JSON-RPC error +- `-32800`: Cancelled - The request was cancelled + + + + A short description of the error. + + + A primitive or structured value that contains additional information about the error. This may be omitted. + + +### Notification + +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. + +**Type:** Object + +**Properties:** + + + The name of the method to be invoked (e.g., "session/cancel", + "session/update"). + + + A structured value that holds the parameter values to be used during the + invocation of the method. + + + The version of the JSON-RPC protocol. MUST be exactly "2.0". + + +### $/cancelRequest + +Cancels a previously sent request by its ID. + +This is a standard JSON-RPC notification that can be sent by either party to signal +that they are no longer interested in the response to a previously sent request. + +#### CancelNotification + +Notification parameters for cancelling a request. + +**Type:** Object + +**Properties:** + + + The ID of the request to cancel. Must match the id from a previously sent + request. + + + The name of the method to be invoked (e.g., "session/cancel", + "session/update"). + + + A structured value that holds the parameter values to be used during the + invocation of the method. + + ## Agent Defines the interface that all ACP-compliant agents must implement. diff --git a/schema/meta.json b/schema/meta.json index 0f0c6c42..19520414 100644 --- a/schema/meta.json +++ b/schema/meta.json @@ -1,4 +1,7 @@ { + "jsonRpcMethods": { + "cancel_request": "$/cancelRequest" + }, "agentMethods": { "authenticate": "authenticate", "initialize": "initialize", diff --git a/schema/schema.json b/schema/schema.json index 7db21b69..0f563c23 100644 --- a/schema/schema.json +++ b/schema/schema.json @@ -1,5 +1,16 @@ { "$defs": { + "CancelNotification": { + "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.", + "properties": { + "id": { + "description": "ID of JsonRPC request to cancel", + "type": "integer" + } + }, + "type": "object", + "x-method": "$/cancelRequest" + }, "AgentCapabilities": { "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)", "properties": {