Error handling notification: Could not resolve type id 'config_option_update' as a subtype

[cmoulliard]

Issue / Question

How can a user figure out why they are getting such an error when the model is specified on the ACP client ?

[FirstContact.main()] INFO com.agentclientprotocol.sdk.client.transport.StdioAcpClientTransport - ACP agent starting.
[FirstContact.main()] INFO com.agentclientprotocol.sdk.client.transport.StdioAcpClientTransport - ACP agent started
Connected to agent!
Agent capabilities: AgentCapabilities[loadSession=true, mcpCapabilities=McpCapabilities[http=true, sse=true], promptCapabilities=PromptCapabilities[audio=null, embeddedContext=true, image=true], meta=null]
Session created: ses_1c4eaeddfffe0FvsrWE9cbDz1G
[acp-client-inbound] ERROR com.agentclientprotocol.sdk.spec.AcpClientSession - Error handling notification: Could not resolve type id 'config_option_update' as a subtype of `com.agentclientprotocol.sdk.spec.AcpSchema$SessionUpdate`: known type ids = [agent_message_chunk, agent_thought_chunk, available_commands_update, current_mode_update, plan, tool_call, tool_call_update, usage_update, user_message_chunk] (for POJO property 'update')
 at [Source: UNKNOWN; byte offset: #UNKNOWN] (through reference chain: com.agentclientprotocol.sdk.spec.AcpSchema$SessionNotification["update"])

Success! Stop reason: END_TURN

Code used

The following example is working fine using opencode acp" but raise the error reported when we set the model client.setSessionModel(modelId);

/*
 * Module: First Contact
 *
 * Your first ACP client - connect to Opencode CLI and get a response.
 *
 * This module demonstrates the minimal code needed to:
 * 1. Create a transport to communicate with an ACP agent
 * 2. Build a client
 * 3. Initialize the connection
 * 4. Create a session
 * 5. Send a prompt and receive a response
 *
 * Prerequisites:
 * - Opencode CLI installed
 * - GCloud Vertex AI: project, location and credientials
 * - ACP Java SDK on classpath
 */

import java.util.List;

import com.agentclientprotocol.sdk.client.AcpClient;
import com.agentclientprotocol.sdk.client.AcpSyncClient;
import com.agentclientprotocol.sdk.client.transport.AgentParameters;
import com.agentclientprotocol.sdk.client.transport.StdioAcpClientTransport;
import com.agentclientprotocol.sdk.spec.AcpSchema;
import com.agentclientprotocol.sdk.spec.AcpSchema.AgentMessageChunk;
import com.agentclientprotocol.sdk.spec.AcpSchema.NewSessionRequest;
import com.agentclientprotocol.sdk.spec.AcpSchema.PromptRequest;
import com.agentclientprotocol.sdk.spec.AcpSchema.TextContent;

public class FirstContact {

    public static void main(String[] args) {
        // Check for required API key before starting
        checkAIApiKey();

        // 1. Configure agent process - tells the transport how to launch the agent
        var params = AgentParameters.builder("opencode")
                .arg("acp")
                .build();

        // 2. Create transport (launches subprocess when client connects)
        var transport = new StdioAcpClientTransport(params);

        // 3. Build sync client with an update consumer that prints the agent's response
        try (AcpSyncClient client = AcpClient.sync(transport)
                .sessionUpdateConsumer(notification -> {
                    if (notification.update() instanceof AgentMessageChunk msg) {
                        System.out.print(((TextContent) msg.content()).text());
                    }
                })
                .build()) {

            // 4. Initialize - handshake with the agent
            var initResponse = client.initialize();
            System.out.println("Connected to agent!");
            System.out.println("Agent capabilities: " + initResponse.agentCapabilities());

            // 5. Create a session - workspace context for conversation
            var s = client.newSession(
                    new NewSessionRequest(".", List.of()));
            System.out.println("Session created: " + s.sessionId());

            var modelId = new AcpSchema.SetSessionModelRequest(s.sessionId(),
                    "google-vertex-anthropic/claude-sonnet-4-6@default");
            client.setSessionModel(modelId); // THAT FAILS HERE !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

            // 6. Send a prompt - the magic moment!
            var response = client
                    .prompt(new PromptRequest(s.sessionId(),
                            List.of(new TextContent("What is 2+2? Reply with just the number."))));

            // 7. Done! Print the result
            System.out.println("\nSuccess! Stop reason: " + response.stopReason());
            System.out.println("\nMeta data: " + response.meta());

        } catch (Exception e) {
            System.err.println("Error: " + e.getMessage());
            e.printStackTrace();
        }
    }

    /**
     * Verify AI_API_KEY is set before attempting to connect.
     */
    private static void checkAIApiKey() {

        String apiKey = System.getenv("GOOGLE_APPLICATION_CREDENTIALS");
        String location = System.getenv("VERTEX_LOCATION");
        String project = System.getenv("GOOGLE_CLOUD_PROJECT");

        if (apiKey == null || apiKey.isBlank()) {
            System.err.println("""
                    ERROR: GOOGLE_APPLICATION_CREDENTIALS environment variable is not set.
                    """);
            System.exit(1);
        }

        if (location == null || location.isBlank()) {
            System.err.println("""
                    ERROR: VERTEX_LOCATION environment variable is not set.
                    """);
            System.exit(1);
        }

        if (project == null || project.isBlank()) {
            System.err.println("""
                    ERROR: GOOGLE_CLOUD_PROJECT environment variable is not set.
                    """);
            System.exit(1);
        }
    }
}

[cmoulliard]

Remark: As ACP API is changing, that would be great that this project tags also the API in order to figure which ACP Spec/schema it currently supports !

Temporary workaround
Here is a temporary workaround that I implemented part of the package com.agentclientprotocol.sdk.spec.AcpSchema class to support the missing value: config_option_update

	/**
	 * Session update - different types of updates
	 */
	@JsonTypeInfo(use = JsonTypeInfo.Id.NAME, property = "sessionUpdate", visible = true)
	@JsonSubTypes({ @JsonSubTypes.Type(value = UserMessageChunk.class, name = "user_message_chunk"),
			@JsonSubTypes.Type(value = AgentMessageChunk.class, name = "agent_message_chunk"),
			@JsonSubTypes.Type(value = AgentThoughtChunk.class, name = "agent_thought_chunk"),
			@JsonSubTypes.Type(value = ToolCall.class, name = "tool_call"),
			@JsonSubTypes.Type(value = ToolCallUpdateNotification.class, name = "tool_call_update"),
			@JsonSubTypes.Type(value = Plan.class, name = "plan"),
			@JsonSubTypes.Type(value = AvailableCommandsUpdate.class, name = "available_commands_update"),
			@JsonSubTypes.Type(value = CurrentModeUpdate.class, name = "current_mode_update"),
			@JsonSubTypes.Type(value = UsageUpdate.class, name = "usage_update"),
			@JsonSubTypes.Type(value = ConfigOptionUpdate.class, name = "config_option_update")})
	public interface SessionUpdate {
...
@JsonIgnoreProperties(ignoreUnknown = true)
	@JsonInclude(JsonInclude.Include.NON_NULL)
	public record ConfigOptionUpdate(@JsonProperty("sessionUpdate") String sessionUpdate,
									 @JsonProperty("configOptions") List<ConfigOption> configOptions) implements SessionUpdate {
	}

	@JsonIgnoreProperties(ignoreUnknown = true)
	@JsonInclude(JsonInclude.Include.NON_NULL)
	public record ConfigOption(
			@JsonProperty("id") String id,                 // e.g., "model", "thought_level"
			@JsonProperty("name") String name,             // Human-readable label
			@JsonProperty("description") String description,// Optional detailed explanation
			@JsonProperty("category") String category,     // Semantic category ("model", "mode", "thought_level")
			@JsonProperty("type") String type,             // Currently "select" (dropdown) per ACP spec
			@JsonProperty("currentValue") String currentValue, // The active selection right now
			@JsonProperty("options") List<ConfigOptionValue> options // Array of available choices
	) {}

	@JsonIgnoreProperties(ignoreUnknown = true)
	@JsonInclude(JsonInclude.Include.NON_NULL)
	public record ConfigOptionValue(
			@JsonProperty("value") String value,           // Machine-readable identifier
			@JsonProperty("name") String name,             // Human-readable label
			@JsonProperty("description") String description // Optional choice description
	) {}
...

With such a change, I can now switch to another model like also to get the config options proposed by the agent

/*
 * Module: First Contact
 *
 * Your first ACP client - connect to Gemini CLI and get a response.
 *
 * This module demonstrates the minimal code needed to:
 * 1. Create a transport to communicate with an ACP agent
 * 2. Build a client
 * 3. Initialize the connection
 * 4. Create a session
 * 5. Send a prompt and receive a response
 *
 * Prerequisites:
 * - Opencode CLI installed
 * -
 * - ACP Java SDK on classpath
 */

import java.util.List;

import com.agentclientprotocol.sdk.client.AcpClient;
import com.agentclientprotocol.sdk.client.AcpSyncClient;
import com.agentclientprotocol.sdk.client.transport.AgentParameters;
import com.agentclientprotocol.sdk.client.transport.StdioAcpClientTransport;
import com.agentclientprotocol.sdk.spec.AcpSchema;
import com.agentclientprotocol.sdk.spec.AcpSchema.AgentMessageChunk;
import com.agentclientprotocol.sdk.spec.AcpSchema.NewSessionRequest;
import com.agentclientprotocol.sdk.spec.AcpSchema.PromptRequest;
import com.agentclientprotocol.sdk.spec.AcpSchema.TextContent;

public class FirstContact {

    public static void main(String[] args) {
        // Check for required API key before starting
        checkAIApiKey();

        // 1. Configure agent process - tells the transport how to launch the agent
        var params = AgentParameters.builder("opencode")
                .arg("acp")
                .build();

        // 2. Create transport (launches subprocess when client connects)
        var transport = new StdioAcpClientTransport(params);

        // 3. Build sync client with an update consumer that prints the agent's response
        try (AcpSyncClient client = AcpClient.sync(transport)
                .sessionUpdateConsumer(notification -> {
                    var update = notification.update();
                    if (update instanceof AcpSchema.AgentThoughtChunk thought) {
                        String text = ((TextContent) thought.content()).text();
                        System.out.println("[Thought] " + text);
                    } else if (update instanceof AgentMessageChunk msg) {
                        String text = ((TextContent) msg.content()).text();
                        System.out.print(text);
                    } else if (update instanceof AcpSchema.Plan plan) {
                        System.out.println("[Plan] " + plan.entries().size() + " steps:");
                        plan.entries().forEach(e -> System.out.println("  - " + e.content() + " [" + e.status() + "]"));
                    } else if (update instanceof AcpSchema.ToolCall tool) {
                        System.out.println("[ToolCall] " + tool.title() + " (" + tool.kind() + ") - " + tool.status());
                    } else if (update instanceof AcpSchema.ToolCallUpdateNotification toolUpdate) {
                        System.out.println("[ToolUpdate] " + toolUpdate.title() + " - " + toolUpdate.status());
                    } else if (update instanceof AcpSchema.AvailableCommandsUpdate commands) {
                        System.out.println("[Commands] Available:");
                        commands.availableCommands()
                                .forEach(c -> System.out.println("  /" + c.name() + " - " + c.description()));
                    } else if (update instanceof AcpSchema.CurrentModeUpdate mode) {
                        System.out.println("[Mode] " + mode.currentModeId());
                    } else if (update instanceof AcpSchema.ConfigOptionUpdate options) {
                        System.out.println("[ConfigOption] ");
                        for (var config : options.configOptions()) {
                            System.out.printf("   - [%s] %s (%s)%n", config.category(), config.name(), config.id());
                            System.out.printf("     Current Value: %s%n", config.currentValue());
                            System.out.println("     Available Choices:");

                            if (config.options() != null) {
                                for (var choice : config.options()) {
                                    System.out.printf("       - %s: %s%n", choice.value(), choice.name());
                                }
                            }
                        }
                    } else {
                        System.out.println("[Update] " + update.getClass().getSimpleName());
                    }
                })
                .build()) {

            // 4. Initialize - handshake with the agent
            var initResponse = client.initialize();
            System.out.println("Connected to agent!");
            System.out.println("Agent capabilities: " + initResponse.agentCapabilities());

            // 5. Create a session - workspace context for conversation
            var s = client.newSession(
                    new NewSessionRequest(".", List.of()));
            System.out.println("Session created: " + s.sessionId());

            System.out.println("Set the model to claude-sonnet-4.6 ...");
            client.setSessionModel(new AcpSchema.SetSessionModelRequest(s.sessionId(),
                    "google-vertex-anthropic/claude-sonnet-4-6@default"));

            // 6. Send a prompt - the magic moment!
            var response = client
                    .prompt(new PromptRequest(s.sessionId(),
                            List.of(new TextContent("What is 2+2? Reply with just the number."))));

            // 7. Done! Print the result
            System.out.println("\nSuccess! Stop reason: " + response.stopReason());
            //System.out.println("\nMeta data: " + response.meta());

        } catch (Exception e) {
            System.err.println("Error: " + e.getMessage());
            e.printStackTrace();
        }
    }

    /**
     * Verify AI_API_KEY is set before attempting to connect.
     */
    private static void checkAIApiKey() {

        String apiKey = System.getenv("GOOGLE_APPLICATION_CREDENTIALS");
        String location = System.getenv("VERTEX_LOCATION");
        String project = System.getenv("GOOGLE_CLOUD_PROJECT");

        if (apiKey == null || apiKey.isBlank()) {
            System.err.println("""
                    ERROR: GOOGLE_APPLICATION_CREDENTIALS environment variable is not set.
                    """);
            System.exit(1);
        }

        if (location == null || location.isBlank()) {
            System.err.println("""
                    ERROR: VERTEX_LOCATION environment variable is not set.
                    """);
            System.exit(1);
        }

        if (project == null || project.isBlank()) {
            System.err.println("""
                    ERROR: GOOGLE_CLOUD_PROJECT environment variable is not set.
                    """);
            System.exit(1);
        }
    }
}

[cmoulliard]

There is nevertheless an issue as the response is not showed within the terminal when the lines are executed:

            var response = client
                    .prompt(new PromptRequest(
                            s.sessionId(),
                            List.of(new TextContent("What is 2+2? Reply with just the number."))));