> ## 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.

# Quickstart

> Build your first ACP agent in minutes with this step-by-step guide.

This quickstart will guide you through creating a minimal ACP agent that responds to prompts and sends updates back to the client.

<Info>
  This example builds an **Agent**. If you want to build a **Client** instead, see the [Building Clients](/clients/overview) guide.
</Info>

## Prerequisites

Before starting, make sure you have:

* Node.js 18+ installed
* The ACP SDK and Zod installed (see [Installation](/installation))
* A TypeScript project set up

## Build a Minimal Agent

<Steps>
  <Step title="Import the SDK">
    Create a new file `agent.ts` and import the necessary modules:

    ```typescript agent.ts theme={null}
    import * as acp from "@agentclientprotocol/sdk";
    import { Readable, Writable } from "node:stream";
    ```

    The SDK provides all core types and classes, while Node.js streams enable stdio communication.
  </Step>

  <Step title="Implement the Agent interface">
    Create a class that implements the `Agent` interface with the required methods:

    ```typescript agent.ts theme={null}
    class MinimalAgent implements acp.Agent {
      private connection: acp.AgentSideConnection;
      private sessions: Map<string, { pendingPrompt: AbortController | null }>;

      constructor(connection: acp.AgentSideConnection) {
        this.connection = connection;
        this.sessions = new Map();
      }

      async initialize(
        _params: acp.InitializeRequest
      ): Promise<acp.InitializeResponse> {
        return {
          protocolVersion: acp.PROTOCOL_VERSION,
          agentCapabilities: {
            loadSession: false,
          },
        };
      }

      async newSession(
        _params: acp.NewSessionRequest
      ): Promise<acp.NewSessionResponse> {
        const sessionId = Array.from(crypto.getRandomValues(new Uint8Array(16)))
          .map((b) => b.toString(16).padStart(2, "0"))
          .join("");

        this.sessions.set(sessionId, { pendingPrompt: null });

        return { sessionId };
      }

      async authenticate(
        _params: acp.AuthenticateRequest
      ): Promise<acp.AuthenticateResponse | void> {
        return {}; // No authentication required
      }

      async prompt(params: acp.PromptRequest): Promise<acp.PromptResponse> {
        const session = this.sessions.get(params.sessionId);
        if (!session) {
          throw new Error(`Session ${params.sessionId} not found`);
        }

        // Send a text response back to the client
        await this.connection.sessionUpdate({
          sessionId: params.sessionId,
          update: {
            sessionUpdate: "agent_message_chunk",
            content: {
              type: "text",
              text: "Hello! I received your message.",
            },
          },
        });

        return { stopReason: "end_turn" };
      }

      async cancel(params: acp.CancelNotification): Promise<void> {
        this.sessions.get(params.sessionId)?.pendingPrompt?.abort();
      }
    }
    ```

    **Key methods explained:**

    * `initialize()`: Establishes the connection and declares agent capabilities
    * `newSession()`: Creates a new conversation session with a unique ID
    * `authenticate()`: Handles authentication (empty for this example)
    * `prompt()`: Processes user prompts and sends responses via `sessionUpdate()`
    * `cancel()`: Handles cancellation requests from the client
  </Step>

  <Step title="Create the connection">
    Set up stdio streams and create an `AgentSideConnection`:

    ```typescript agent.ts theme={null}
    // Create stdio streams for communication
    const input = Writable.toWeb(process.stdout);
    const output = Readable.toWeb(process.stdin) as ReadableStream<Uint8Array>;

    // Create the ndjson stream
    const stream = acp.ndJsonStream(input, output);

    // Initialize the agent connection
    new acp.AgentSideConnection((conn) => new MinimalAgent(conn), stream);
    ```

    The `AgentSideConnection` automatically:

    * Routes incoming requests to your agent's methods
    * Validates all messages using Zod schemas
    * Handles JSON-RPC 2.0 protocol details
  </Step>

  <Step title="Run your agent">
    Execute your agent using `tsx` or compile with `tsc`:

    <CodeGroup>
      ```bash tsx theme={null}
      npx tsx agent.ts
      ```

      ```bash tsc theme={null}
      npx tsc agent.ts && node agent.js
      ```
    </CodeGroup>

    Your agent is now listening on stdin for ACP messages from a client!
  </Step>

  <Step title="Test with a client">
    You can test your agent by:

    1. Using an ACP-compatible client like [Zed](https://zed.dev)
    2. Running the example client from the SDK (see [Building Clients](/clients/overview))
    3. Sending JSON-RPC messages manually via stdin

    When a client sends a prompt, your agent will respond with "Hello! I received your message."
  </Step>
</Steps>

## Complete Example

Here's the full minimal agent code:

```typescript agent.ts theme={null}
import * as acp from "@agentclientprotocol/sdk";
import { Readable, Writable } from "node:stream";

class MinimalAgent implements acp.Agent {
  private connection: acp.AgentSideConnection;
  private sessions: Map<string, { pendingPrompt: AbortController | null }>;

  constructor(connection: acp.AgentSideConnection) {
    this.connection = connection;
    this.sessions = new Map();
  }

  async initialize(
    _params: acp.InitializeRequest
  ): Promise<acp.InitializeResponse> {
    return {
      protocolVersion: acp.PROTOCOL_VERSION,
      agentCapabilities: { loadSession: false },
    };
  }

  async newSession(
    _params: acp.NewSessionRequest
  ): Promise<acp.NewSessionResponse> {
    const sessionId = Array.from(crypto.getRandomValues(new Uint8Array(16)))
      .map((b) => b.toString(16).padStart(2, "0"))
      .join("");
    this.sessions.set(sessionId, { pendingPrompt: null });
    return { sessionId };
  }

  async authenticate(
    _params: acp.AuthenticateRequest
  ): Promise<acp.AuthenticateResponse | void> {
    return {};
  }

  async prompt(params: acp.PromptRequest): Promise<acp.PromptResponse> {
    const session = this.sessions.get(params.sessionId);
    if (!session) {
      throw new Error(`Session ${params.sessionId} not found`);
    }

    await this.connection.sessionUpdate({
      sessionId: params.sessionId,
      update: {
        sessionUpdate: "agent_message_chunk",
        content: { type: "text", text: "Hello! I received your message." },
      },
    });

    return { stopReason: "end_turn" };
  }

  async cancel(params: acp.CancelNotification): Promise<void> {
    this.sessions.get(params.sessionId)?.pendingPrompt?.abort();
  }
}

const input = Writable.toWeb(process.stdout);
const output = Readable.toWeb(process.stdin) as ReadableStream<Uint8Array>;
const stream = acp.ndJsonStream(input, output);
new acp.AgentSideConnection((conn) => new MinimalAgent(conn), stream);
```

## Understanding the Flow

<Steps>
  <Step title="Connection Initialization">
    The client sends an `initialize` request. Your agent responds with its protocol version and capabilities.
  </Step>

  <Step title="Session Creation">
    The client calls `newSession` to create a conversation context. Your agent generates a unique session ID.
  </Step>

  <Step title="Prompt Processing">
    The client sends prompts via the `prompt` method. Your agent:

    * Processes the prompt (call an LLM, execute tools, etc.)
    * Sends real-time updates via `sessionUpdate()` notifications
    * Returns a final response with a stop reason
  </Step>
</Steps>

<Tip>
  The example agent from `src/examples/agent.ts` in the SDK repository includes advanced features like tool calls, permission requests, and terminal support. Check it out for a more complete implementation!
</Tip>

## Next Steps

Now that you have a working agent, explore more advanced features:

<CardGroup cols={2}>
  <Card title="Building Agents" icon="robot" href="/agents/overview">
    Learn about tool calls, permissions, and advanced agent patterns
  </Card>

  <Card title="Building Clients" icon="laptop" href="/clients/overview">
    Build the client side to connect to your agent
  </Card>

  <Card title="API Reference" icon="code" href="/api/agent-side-connection">
    Explore the full SDK API documentation
  </Card>

  <Card title="Protocol Docs" icon="book" href="https://agentclientprotocol.com">
    Deep dive into the ACP protocol specification
  </Card>
</CardGroup>