Module connections 

Establishing connections using role types and connection builders.

To communicate over ACP, you need to establish a connection. This involves choosing a role type that matches your role and using a connection builder to configure and run the connection.

Choosing a Role Type

Your role type determines what messages you can send and who you can send them to. Choose based on what you’re building:

You are building…	Use this role type
A client that talks to an agent	Client
An agent that responds to clients	Agent
A proxy in a conductor chain	Proxy

The Connection Builder Pattern

Every role type has a builder() method that returns a connection builder. The builder lets you configure handlers, then connect to a transport:

Client.builder()
    .name("my-client")
    .connect_with(transport, async |cx| {
        // Use `cx` to send requests and handle responses
        Ok(())
    })
    .await?;

The Connection Context

Inside connect_with, you receive a ConnectionTo (connection context) that lets you interact with the remote peer:

// Send a request and wait for the response
let response = cx.send_request(InitializeRequest::new(ProtocolVersion::V1))
    .block_task()
    .await?;

// Send a notification (fire-and-forget)
cx.send_notification(StatusUpdate { message: "hello".into() })?;

Sending Requests

When you call send_request(), you get back a SentRequest that represents the pending response. You have two main ways to handle it:

Option 1: Block and wait

Use block_task() when you need the response before continuing:

let response = cx.send_request(MyRequest {})
    .block_task()
    .await?;
// Use response here

Option 2: Schedule a callback

Use on_receiving_result() when you want to handle the response asynchronously:

cx.send_request(MyRequest {})
    .on_receiving_result(async |result| {
        match result {
            Ok(response) => { /* handle success */ }
            Err(error) => { /* handle error */ }
        }
        Ok(())
    })?;
// Continues immediately, callback runs when response arrives

See Ordering for important details about how these differ.

Next Steps

• Sessions - Create multi-turn conversations
• Callbacks - Handle incoming requests from the remote peer