Skip to main content

Module 01: First Contact

Your first ACP client β€” launch an agent as a subprocess and send it a prompt.

What You’ll Learn

  • How ACP communication works (subprocess + stdin/stdout JSON-RPC)
  • Configuring agent process parameters with AgentParameters
  • Registering a sessionUpdateHandler to see the agent’s response
  • The three-phase lifecycle: initialize β†’ newSession β†’ prompt

Prerequisites

  1. The Grok CLI with ACP support β€” the tutorial uses Grok as a real ACP agent, launched as grok agent stdio. Your client will launch it as a subprocess and talk to it over stdin/stdout.
  2. Sign in once
    No API key is needed; the module uses the account you signed in with.
  3. Java 17 or later

The Code

The client launches grok agent stdio as a child process. AgentParameters builds the command line. StdioAcpClientTransport spawns the process and handles JSON-RPC message framing over its stdin/stdout. The sessionUpdateHandler is how you see the agent’s response. During prompt(), the agent streams back AgentMessageChunk updates containing the response text. Without a consumer, the prompt completes but you only get the stop reason β€” not the actual answer. From there, ACP follows a three-phase lifecycle: initialize the connection, create a session (with a working directory context), then send prompts.

How It Works

ACP communication follows a three-phase lifecycle:
  1. Initialize β€” client and agent exchange protocol versions and capabilities
  2. New Session β€” establishes a working directory context for the conversation
  3. Prompt β€” sends content and receives a response with a stop reason
The stdio transport is not Grok-specific. Any executable that speaks ACP over stdin/stdout works β€” Grok CLI, a custom agent JAR, or any other ACP-compliant tool. This is the same mechanism Zed, JetBrains, and VS Code use to talk to agents.

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 05: Streaming Updates β€” receive real-time updates while the agent processes your prompt. Or skip to Module 12: Echo Agent to build your own agent (no API key required).