com.agentclientprotocol.sdk.client

类 AcpAsyncClient

java.lang.Object

com.agentclientprotocol.sdk.client.AcpAsyncClient

public class AcpAsyncClient
extends java.lang.Object

The Agent Client Protocol (ACP) async client implementation that provides asynchronous communication with ACP-compliant agents using Project Reactor's Mono type.

This client implements the ACP specification, enabling applications to interact with autonomous coding agents through a standardized interface. Key features include:

• Asynchronous communication using reactive programming patterns
• Initialize handshake and capability negotiation
• Session creation and management
• Prompt submission with streaming updates
• Authentication support for agents requiring it
• Cancel operations for long-running tasks

The client follows a lifecycle:

1. Initialization - Establishes connection and negotiates protocol version
2. Authentication - Optional authentication step
3. Session Creation - Creates a new agent session with working directory
4. Prompt Interaction - Sends prompts and receives responses
5. Graceful Shutdown - Ensures clean connection termination

This implementation uses Project Reactor for non-blocking operations, making it suitable for high-throughput scenarios and reactive applications. All operations return Mono types that can be composed into reactive pipelines.

Example usage:

 // Create transport
 AgentParameters params = AgentParameters.builder("gemini")
     .arg("--experimental-acp")
     .build();
 StdioAcpClientTransport transport = new StdioAcpClientTransport(params, McpJsonMapper.getDefault());

 // Create client
 AcpAsyncClient client = AcpClient.async(transport)
     .requestTimeout(Duration.ofSeconds(30))
     .build();

 // Initialize
 AcpSchema.InitializeResponse initResponse = client
     .initialize(new AcpSchema.InitializeRequest(1, new AcpSchema.ClientCapabilities()))
     .block();

 // Create session and interact
 String sessionId = client
     .newSession(new AcpSchema.NewSessionRequest("/workspace", List.of()))
     .map(AcpSchema.NewSessionResponse::sessionId)
     .block();

 AcpSchema.PromptResponse response = client
     .prompt(new AcpSchema.PromptRequest(sessionId, List.of(new AcpSchema.TextContent("Fix the bug"))))
     .block();

 client.closeGracefully().block();
 

另请参阅:

AcpSession, AcpSchema

方法概要

限定符和类型	方法和说明
reactor.core.publisher.Mono<AcpSchema.AuthenticateResponse>	authenticate(AcpSchema.AuthenticateRequest authenticateRequest) Authenticates with the agent using the specified authentication method.
reactor.core.publisher.Mono<java.lang.Void>	cancel(AcpSchema.CancelNotification cancelNotification) Cancels ongoing operations for a session.
void	close() Closes the client connection immediately.
reactor.core.publisher.Mono<java.lang.Void>	closeGracefully() Gracefully closes the client connection, allowing pending operations to complete.
NegotiatedCapabilities	getAgentCapabilities() Returns the capabilities negotiated with the agent during initialization.
reactor.core.publisher.Mono<AcpSchema.InitializeResponse>	initialize() Initializes the ACP client with default settings.
reactor.core.publisher.Mono<AcpSchema.InitializeResponse>	initialize(AcpSchema.InitializeRequest initializeRequest) Initializes the connection with the agent.
reactor.core.publisher.Mono<AcpSchema.LoadSessionResponse>	loadSession(AcpSchema.LoadSessionRequest loadSessionRequest) Loads an existing agent session by ID.
reactor.core.publisher.Mono<AcpSchema.NewSessionResponse>	newSession(AcpSchema.NewSessionRequest newSessionRequest) Creates a new agent session with the specified working directory.
reactor.core.publisher.Mono<AcpSchema.PromptResponse>	prompt(AcpSchema.PromptRequest promptRequest) Sends a prompt to the agent within a session.
reactor.core.publisher.Mono<AcpSchema.SetSessionModeResponse>	setSessionMode(AcpSchema.SetSessionModeRequest setModeRequest) Sets the operational mode for a session (e.g., "code", "plan", "review").
reactor.core.publisher.Mono<AcpSchema.SetSessionModelResponse>	setSessionModel(AcpSchema.SetSessionModelRequest setModelRequest) Sets the AI model for the specified session.

从类继承的方法 java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

方法详细资料

initialize

public reactor.core.publisher.Mono<AcpSchema.InitializeResponse> initialize(AcpSchema.InitializeRequest initializeRequest)

Initializes the connection with the agent. This is the first step in the ACP lifecycle and negotiates protocol version and capabilities.

The client sends its protocol version and capabilities, and the agent responds with its supported protocol version, authentication methods, and capabilities.

After initialization, the agent's capabilities can be accessed via getAgentCapabilities().

参数:

initializeRequest - the initialization request containing protocol version and client capabilities

返回:

a Mono emitting the initialization response with agent capabilities

另请参阅:

AcpSchema.METHOD_INITIALIZE, getAgentCapabilities()

initialize

public reactor.core.publisher.Mono<AcpSchema.InitializeResponse> initialize()

Initializes the ACP client with default settings.

Uses protocol version 1 and default client capabilities. This is a convenience method for the common case where no special capabilities need to be advertised.

返回:

a Mono emitting the initialization response with agent capabilities

另请参阅:

initialize(AcpSchema.InitializeRequest)

getAgentCapabilities

public NegotiatedCapabilities getAgentCapabilities()

Returns the capabilities negotiated with the agent during initialization.

This method returns null if initialize(com.agentclientprotocol.sdk.spec.AcpSchema.InitializeRequest) has not been called yet.

返回:

the negotiated agent capabilities, or null if not initialized

authenticate

public reactor.core.publisher.Mono<AcpSchema.AuthenticateResponse> authenticate(AcpSchema.AuthenticateRequest authenticateRequest)

Authenticates with the agent using the specified authentication method.

Authentication is optional and depends on the agent's configuration. The authentication methods available are returned in the initialize response.

参数:

authenticateRequest - the authentication request specifying the auth method and credentials

返回:

a Mono emitting the authentication response

另请参阅:

AcpSchema.METHOD_AUTHENTICATE

newSession

public reactor.core.publisher.Mono<AcpSchema.NewSessionResponse> newSession(AcpSchema.NewSessionRequest newSessionRequest)

Creates a new agent session with the specified working directory.

A session represents a conversation context with the agent. All prompts within a session share the same working directory and conversation history.

参数:

newSessionRequest - the session creation request with working directory and initial context

返回:

a Mono emitting the session response containing the session ID

另请参阅:

AcpSchema.METHOD_SESSION_NEW

loadSession

public reactor.core.publisher.Mono<AcpSchema.LoadSessionResponse> loadSession(AcpSchema.LoadSessionRequest loadSessionRequest)

Loads an existing agent session by ID.

This allows resuming a previous conversation with the agent, maintaining the full history and context.

参数:

loadSessionRequest - the session load request with session ID

返回:

a Mono emitting the load response confirming the session was loaded

另请参阅:

AcpSchema.METHOD_SESSION_LOAD

setSessionMode

public reactor.core.publisher.Mono<AcpSchema.SetSessionModeResponse> setSessionMode(AcpSchema.SetSessionModeRequest setModeRequest)

Sets the operational mode for a session (e.g., "code", "plan", "review").

Different modes may change how the agent processes prompts and what capabilities it exposes.

参数:

setModeRequest - the set mode request with session ID and desired mode

返回:

a Mono emitting the response confirming the mode change

另请参阅:

AcpSchema.METHOD_SESSION_SET_MODE

setSessionModel

public reactor.core.publisher.Mono<AcpSchema.SetSessionModelResponse> setSessionModel(AcpSchema.SetSessionModelRequest setModelRequest)

Sets the AI model for the specified session.

This allows changing which AI model is used for subsequent prompts in the session.

参数:

setModelRequest - the set model request with session ID and desired model

返回:

a Mono emitting the response confirming the model change

另请参阅:

AcpSchema.METHOD_SESSION_SET_MODEL

prompt

public reactor.core.publisher.Mono<AcpSchema.PromptResponse> prompt(AcpSchema.PromptRequest promptRequest)

Sends a prompt to the agent within a session.

The prompt can contain text, images, or other content types. The agent processes the prompt and may send streaming updates via session/update notifications before returning the final response.

参数:

promptRequest - the prompt request with session ID and content

返回:

a Mono emitting the prompt response with stop reason

另请参阅:

AcpSchema.METHOD_SESSION_PROMPT

cancel

public reactor.core.publisher.Mono<java.lang.Void> cancel(AcpSchema.CancelNotification cancelNotification)

Cancels ongoing operations for a session.

This sends a notification to the agent to stop any in-progress work for the specified session. Note that this is a notification (fire-and-forget), not a request.

参数:

cancelNotification - the cancel notification with session ID and optional reason

返回:

a Mono that completes when the notification is sent

另请参阅:

AcpSchema.METHOD_SESSION_CANCEL

close

public void close()

Closes the client connection immediately.

This closes both the session and the underlying transport.

closeGracefully

public reactor.core.publisher.Mono<java.lang.Void> closeGracefully()

Gracefully closes the client connection, allowing pending operations to complete.

This closes both the session and the underlying transport.

返回:

a Mono that completes when the connection is closed