Building Agents

Learn how to build ACP-compliant agents using the TypeScript SDK

What is an Agent?

In the Agent-Client Protocol (ACP), an agent is a program that uses generative AI to autonomously perform tasks like modifying code, answering questions, and executing operations on behalf of users. Agents communicate with clients (typically code editors or IDEs) through a standardized protocol.

Agent Responsibilities

An ACP-compliant agent is responsible for:

• Session Management: Creating and maintaining conversation sessions with independent contexts and history
• Prompt Processing: Receiving user prompts, processing them with language models, and returning responses
• Tool Execution: Executing tool calls and reporting results back to the client
• Permission Handling: Requesting user permission before performing sensitive operations
• Real-time Updates: Streaming progress updates to the client during prompt processing
• State Management: Tracking session state and handling cancellation requests

Architecture Overview

The ACP TypeScript SDK provides two main components for building agents:

1. AgentSideConnection

   The connection class that handles communication with clients over a bidirectional stream. It provides methods for sending session updates, requesting permissions, and accessing client capabilities.

2. Agent Interface

   The interface you implement to define your agent’s behavior. It includes methods for initialization, session management, prompt processing, and cancellation handling.

import * as acp from "@agentprotocol/acp";

class MyAgent implements acp.Agent {
  private connection: acp.AgentSideConnection;

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

  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 = crypto.randomUUID();
    return { sessionId };
  }

  async authenticate(params: acp.AuthenticateRequest): Promise<void> {
    // Implement authentication if needed
  }

  async prompt(params: acp.PromptRequest): Promise<acp.PromptResponse> {
    // Process the user's prompt
    return { stopReason: "end_turn" };
  }

  async cancel(params: acp.CancelNotification): Promise<void> {
    // Handle cancellation
  }
}

// Create the connection
const stream = acp.ndJsonStream(input, output);
new acp.AgentSideConnection((conn) => new MyAgent(conn), stream);

Example Agent

For a complete working example, see the example agent implementation in the TypeScript SDK repository.

The example demonstrates:

• Session management
• Sending message chunks
• Tool call lifecycle
• Permission requests
• Cancellation handling

Next Steps

AgentSideConnection

Learn about the connection class and its methods

Agent Interface

Implement the required Agent interface methods

Handling Prompts

Process user prompts and send updates

Session Management

Create and manage conversation sessions