Skip to main content

Module 02: Protocol Basics

Deep dive into the ACP initialize handshake and version negotiation.

What You’ll Learn

  • The InitializeRequest and InitializeResponse structure
  • Protocol version negotiation semantics
  • Client and agent capability exchange

How It Works

The initialize handshake is the first message exchange in ACP — it must complete before any session or prompt operations. Both sides exchange:
  1. Protocol version — they agree on a compatible version
  2. Client capabilities — what the client can provide (file system access, terminal execution)
  3. Agent capabilities — what the agent supports (session loading, image content, MCP)

The Code

Module 01 called client.initialize() with defaults. Here we register file handlers, and let the client advertise what they imply, then call initialize() the same way. The InitializeResponse tells us what the agent supports:
As of 0.80.0, initialize(InitializeRequest) is removed: capabilities come from the client builder, either derived from registered handlers (as above) or set explicitly with clientCapabilities(..) (Module 17), and initialize() sends them. See the 0.80.0 migration guide.

Source Code

View on GitHub

Running the Example

Requires the Grok CLI on your PATH, signed in once with grok login. The module launches it as grok agent stdio; no API key is needed.

Next Module

Module 03: Sessions — create and manage conversation sessions.