> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/agentclientprotocol/typescript-sdk/llms.txt
> Use this file to discover all available pages before exploring further.

# JSON-RPC Types

> JSON-RPC 2.0 message types and internal implementation details

## Overview

The ACP TypeScript SDK uses JSON-RPC 2.0 for message exchange between clients and agents. This page documents the internal JSON-RPC types used by the SDK.

<Note>
  These types are primarily for internal use by the SDK. Most applications will use the higher-level APIs provided by `AgentSideConnection` and `ClientSideConnection` rather than working with these types directly.
</Note>

## Message Types

### AnyMessage

```typescript theme={null}
type AnyMessage = AnyRequest | AnyResponse | AnyNotification;
```

A union type representing any valid JSON-RPC 2.0 message that can be sent or received over an ACP connection.

## Request Types

### AnyRequest

```typescript theme={null}
type AnyRequest = {
  jsonrpc: "2.0";
  id: string | number | null;
  method: string;
  params?: unknown;
};
```

Represents a JSON-RPC 2.0 request message.

**Properties:**

* `jsonrpc` ("2.0") - JSON-RPC version identifier (always "2.0")
* `id` (string | number | null) - Unique identifier for matching requests with responses
* `method` (string) - The method name to invoke (e.g., "session/prompt")
* `params` (unknown, optional) - Method parameters

**Example:**

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "session/prompt",
  "params": {
    "sessionId": "session-123",
    "messages": [
      {
        "role": "user",
        "content": "Hello!"
      }
    ]
  }
}
```

## Response Types

### AnyResponse

```typescript theme={null}
type AnyResponse = {
  jsonrpc: "2.0";
  id: string | number | null;
} & Result<unknown>;
```

Represents a JSON-RPC 2.0 response message, which can contain either a successful result or an error.

**Properties:**

* `jsonrpc` ("2.0") - JSON-RPC version identifier
* `id` (string | number | null) - ID matching the original request
* Either `result` or `error` (from `Result<unknown>`)

**Success Example:**

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "stopReason": "end_turn"
  }
}
```

**Error Example:**

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32601,
    "message": "Method not found: unknown/method",
    "data": {
      "method": "unknown/method"
    }
  }
}
```

### Result

```typescript theme={null}
type Result<T> =
  | {
      result: T;
    }
  | {
      error: ErrorResponse;
    };
```

A discriminated union representing either a successful result or an error.

**Success Variant:**

* `result` (T) - The successful response data

**Error Variant:**

* `error` (ErrorResponse) - The error information

### ErrorResponse

```typescript theme={null}
type ErrorResponse = {
  code: number;
  message: string;
  data?: unknown;
};
```

Represents a JSON-RPC 2.0 error object.

**Properties:**

* `code` (number) - Numeric error code (see [Error Codes](/api/error-codes))
* `message` (string) - Human-readable error message
* `data` (unknown, optional) - Additional error information

**Example:**

```json theme={null}
{
  "code": -32602,
  "message": "Invalid params",
  "data": {
    "sessionId": {
      "_errors": ["Required"]
    }
  }
}
```

## Notification Types

### AnyNotification

```typescript theme={null}
type AnyNotification = {
  jsonrpc: "2.0";
  method: string;
  params?: unknown;
};
```

Represents a JSON-RPC 2.0 notification message. Notifications are like requests but do not expect a response (no `id` field).

**Properties:**

* `jsonrpc` ("2.0") - JSON-RPC version identifier
* `method` (string) - The notification method name
* `params` (unknown, optional) - Notification parameters

**Example:**

```json theme={null}
{
  "jsonrpc": "2.0",
  "method": "session/update",
  "params": {
    "sessionId": "session-123",
    "message": {
      "type": "text",
      "text": "Processing your request..."
    }
  }
}
```

## Handler Types

### RequestHandler

```typescript theme={null}
type RequestHandler = (
  method: string,
  params: unknown
) => Promise<unknown>;
```

A function type for handling incoming JSON-RPC requests.

**Parameters:**

* `method` (string) - The method being invoked
* `params` (unknown) - The method parameters

**Returns:** Promise resolving to the result value

**Throws:** Should throw `RequestError` for application errors

**Example:**

```typescript theme={null}
const requestHandler: RequestHandler = async (method, params) => {
  switch (method) {
    case "session/prompt":
      const validatedParams = PromptRequestSchema.parse(params);
      return await handlePrompt(validatedParams);
    
    case "session/new":
      const validatedParams = NewSessionRequestSchema.parse(params);
      return await createSession(validatedParams);
    
    default:
      throw RequestError.methodNotFound(method);
  }
};
```

### NotificationHandler

```typescript theme={null}
type NotificationHandler = (
  method: string,
  params: unknown
) => Promise<void>;
```

A function type for handling incoming JSON-RPC notifications.

**Parameters:**

* `method` (string) - The notification method
* `params` (unknown) - The notification parameters

**Returns:** Promise resolving when the notification is handled

**Example:**

```typescript theme={null}
const notificationHandler: NotificationHandler = async (method, params) => {
  switch (method) {
    case "session/update":
      const update = SessionNotificationSchema.parse(params);
      await displayUpdate(update);
      break;
    
    case "session/cancel":
      const cancel = CancelNotificationSchema.parse(params);
      await cancelSession(cancel.sessionId);
      break;
    
    default:
      console.warn(`Unknown notification: ${method}`);
  }
};
```

## Internal Types

### PendingResponse

```typescript theme={null}
type PendingResponse = {
  resolve: (response: unknown) => void;
  reject: (error: ErrorResponse) => void;
};
```

An internal type used to track pending requests waiting for responses.

**Properties:**

* `resolve` (function) - Called when a successful response is received
* `reject` (function) - Called when an error response is received

<Note>
  This type is used internally by the Connection class to manage the request/response lifecycle. You typically won't interact with it directly.
</Note>

## Message Flow

### Request-Response Flow

```typescript theme={null}
// Client sends request
const request: AnyRequest = {
  jsonrpc: "2.0",
  id: 1,
  method: "session/prompt",
  params: { sessionId: "session-123", messages: [...] },
};

// Agent receives request, processes it, sends response
const response: AnyResponse = {
  jsonrpc: "2.0",
  id: 1,
  result: { stopReason: "end_turn" },
};

// Or, if an error occurred:
const errorResponse: AnyResponse = {
  jsonrpc: "2.0",
  id: 1,
  error: {
    code: -32602,
    message: "Invalid params",
    data: { ... },
  },
};
```

### Notification Flow

```typescript theme={null}
// Agent sends notification (no response expected)
const notification: AnyNotification = {
  jsonrpc: "2.0",
  method: "session/update",
  params: {
    sessionId: "session-123",
    message: { type: "text", text: "Thinking..." },
  },
};

// Client receives and processes notification
// No response is sent
```

## Type Guards

### Checking Message Types

You can use type guards to determine which kind of message you're dealing with:

```typescript theme={null}
function isRequest(msg: AnyMessage): msg is AnyRequest {
  return "method" in msg && "id" in msg;
}

function isNotification(msg: AnyMessage): msg is AnyNotification {
  return "method" in msg && !("id" in msg);
}

function isResponse(msg: AnyMessage): msg is AnyResponse {
  return "id" in msg && !("method" in msg);
}

function isSuccessResponse(msg: AnyResponse): boolean {
  return "result" in msg;
}

function isErrorResponse(msg: AnyResponse): boolean {
  return "error" in msg;
}
```

### Usage Example

```typescript theme={null}
function processMessage(message: AnyMessage) {
  if (isRequest(message)) {
    console.log(`Received request: ${message.method}`);
    // Handle request
  } else if (isNotification(message)) {
    console.log(`Received notification: ${message.method}`);
    // Handle notification
  } else if (isResponse(message)) {
    if (isSuccessResponse(message)) {
      console.log(`Received success response for id ${message.id}`);
    } else {
      console.log(`Received error response for id ${message.id}`);
    }
  }
}
```

## Best Practices

### 1. Use Type-Safe Wrappers

Rather than working with `unknown` params, use type-safe wrappers:

```typescript theme={null}
import { z } from "zod";

const PromptRequestSchema = z.object({
  sessionId: z.string(),
  messages: z.array(z.object({
    role: z.enum(["user", "assistant"]),
    content: z.string(),
  })),
});

const requestHandler: RequestHandler = async (method, params) => {
  if (method === "session/prompt") {
    // Validate and get typed params
    const validated = PromptRequestSchema.parse(params);
    // Now 'validated' has proper types
    return await handlePrompt(validated);
  }
};
```

### 2. Always Return Proper Errors

Throw `RequestError` instances for application errors:

```typescript theme={null}
const requestHandler: RequestHandler = async (method, params) => {
  try {
    // ... handle request
  } catch (error) {
    if (error instanceof RequestError) {
      throw error; // Already a proper error
    }
    if (error instanceof z.ZodError) {
      throw RequestError.invalidParams(error.format());
    }
    throw RequestError.internalError({ details: error.message });
  }
};
```

### 3. Don't Block Notification Handlers

Notifications should be handled asynchronously without blocking:

```typescript theme={null}
const notificationHandler: NotificationHandler = async (method, params) => {
  // Quick validation and dispatch
  const notification = parseNotification(method, params);
  
  // Don't await long-running operations
  processNotificationAsync(notification).catch(error => {
    console.error("Error processing notification:", error);
  });
  
  // Return immediately
};
```

## See Also

* [RequestError Class](/api/request-error) - Error handling
* [Error Codes](/api/error-codes) - Complete error code reference
* [Stream Utilities](/api/stream) - Message transport
* [JSON-RPC 2.0 Specification](https://www.jsonrpc.org/specification) - Official specification