### Get Extended Agent Card Example

Source: https://github.com/a2aproject/a2a-java/blob/main/_autodocs/api-reference-client.md

This example shows how to fetch the agent's updated agent card. It prints the agent's version and the number of skills.

```java
AgentCard updated = client.getExtendedAgentCard(null, null);
System.out.println("Agent version: " + updated.version());
System.out.println("Skills: " + updated.skills().size());
```

--------------------------------

### Build Project

Source: https://github.com/a2aproject/a2a-java/blob/main/CLAUDE.md

Command to clean and install the Maven project. Ensure Java 17+ is installed.

```bash
mvn clean install
```

--------------------------------

### Configure Transport with Config Object Example

Source: https://github.com/a2aproject/a2a-java/blob/main/_autodocs/api-reference-client.md

This example demonstrates configuring a transport with a pre-instantiated configuration object, such as JSONRPCTransportConfig with a provided HTTP client.

```java
builder.withTransport(JSONRPCTransport.class, 
    new JSONRPCTransportConfig(myHttpClient));
```

--------------------------------

### AgentSkill Builder Example

Source: https://github.com/a2aproject/a2a-java/blob/main/_autodocs/types.md

Demonstrates how to create an AgentSkill instance using its builder pattern, including setting ID, name, description, tags, and examples.

```java
AgentSkill skill = AgentSkill.builder()
    .id("weather_search")
    .name("Search Weather")
    .description("Get weather information for a location")
    .tags(List.of("weather", "info"))
    .examples(List.of("weather in LA, CA", "forecast for tomorrow"))
    .build();
```

--------------------------------

### Deploy the A2A Stack

Source: https://github.com/a2aproject/a2a-java/blob/main/examples/cloud-deployment/README.md

Execute the deployment script to create a Kind cluster and deploy all components. This script handles Kind cluster creation, local registry setup, Strimzi Kafka operator installation, PostgreSQL deployment, Kafka cluster deployment, and A2A agent deployment.

```bash
cd scripts
./deploy.sh
```

--------------------------------

### AgentInterface Instantiation Examples

Source: https://github.com/a2aproject/a2a-java/blob/main/_autodocs/types.md

Shows how to instantiate AgentInterface with different protocol bindings and URLs.

```java
new AgentInterface("jsonrpc", "http://localhost:9999")
new AgentInterface("grpc", "localhost:50051")
new AgentInterface("rest", "https://api.example.com/agent")
```

--------------------------------

### TextPart Examples

Source: https://github.com/a2aproject/a2a-java/blob/main/_autodocs/types.md

Shows how to instantiate TextPart with plain text or with a specified MIME type like 'text/markdown'.

```java
new TextPart("Hello, World!")
new TextPart("markdown content", "text/markdown")
```

--------------------------------

### AuthenticationInfo Examples

Source: https://github.com/a2aproject/a2a-java/blob/main/_autodocs/types.md

Illustrates how to instantiate AuthenticationInfo with different schemes and credentials. Choose the appropriate scheme and provide valid credentials.

```java
new AuthenticationInfo("Bearer", "my-jwt-token")
new AuthenticationInfo("Basic", "base64-encoded-credentials")
new AuthenticationInfo("ApiKey", "my-api-key")
```

--------------------------------

### Configure Transport with Config Builder Example

Source: https://github.com/a2aproject/a2a-java/blob/main/_autodocs/api-reference-client.md

This example shows how to configure a transport (e.g., JSONRPCTransport) using its specific configuration builder, providing custom HTTP client and interceptors.

```java
builder.withTransport(JSONRPCTransport.class, 
    new JSONRPCTransportConfigBuilder()
        .httpClient(customHttpClient)
        .addInterceptor(loggingInterceptor));
```

--------------------------------

### Close Client Example with Try-with-Resources

Source: https://github.com/a2aproject/a2a-java/blob/main/_autodocs/api-reference-client.md

This example demonstrates the proper way to close a client using a try-with-resources statement to ensure all resources are released and avoid leaks.

```java
try (Client client = Client.builder(card)
        .withTransport(JSONRPCTransport.class, new JSONRPCTransportConfig())
        .build()) {
    client.sendMessage(msg);
} // Automatically closed by try-with-resources
```

--------------------------------

### FilePart Examples

Source: https://github.com/a2aproject/a2a-java/blob/main/_autodocs/types.md

Demonstrates creating FilePart instances using a file URI or by providing file name, MIME type, and bytes.

```java
new FilePart(new FileWithUri("https://example.com/data.json", "application/json"))
new FilePart(new FileWithBytes("data.txt", "text/plain", bytes))
```

--------------------------------

### Start Java Server with OpenTelemetry

Source: https://github.com/a2aproject/a2a-java/blob/main/examples/helloworld/client/README.md

Starts the Java server with OpenTelemetry enabled, launching Grafana and OTLP collectors. This is the recommended option for tracing.

```bash
mvn quarkus:dev -Popentelemetry -pl examples/helloworld/server/ -Dquarkus.agentcard.protocol=HTTP+JSON
```

--------------------------------

### ImagePart Example

Source: https://github.com/a2aproject/a2a-java/blob/main/_autodocs/types.md

Shows how to create an ImagePart with a URL, MIME type, and descriptive alt text for accessibility.

```java
new ImagePart("https://example.com/image.png", "image/png", "Description of image")
```

--------------------------------

### Subscribe to Task Example

Source: https://github.com/a2aproject/a2a-java/blob/main/_autodocs/api-reference-client.md

This example demonstrates how to subscribe to a task after it has been initially sent. It shows how to use the task ID from a previous response to set up event consumers for resumed task updates.

```java
// Original request
client.sendMessage(A2A.toUserMessage("Long-running task"));
String taskId = "task-456";  // From response

// Later, after disconnection
client.subscribeToTask(
    new TaskIdParams(taskId),
    List.of((event, card) -> {
        if (event instanceof TaskUpdateEvent tue) {
            System.out.println("Resumed - status: " + tue.getTask().status().state());
        }
    }),
    null, null
);
```

--------------------------------

### Get Task Response Example

Source: https://github.com/a2aproject/a2a-java/blob/main/transport/rest/README.md

Example of a JSON response when retrieving a task. The response includes the task's ID, context ID, status, artifacts, and history.

```json
{
  "id": "task-1",
  "contextId": "ctx-1",
  "status": {
    "state": "TASK_STATE_COMPLETED",
    "timestamp": "2023-10-27T10:00:00Z"
  },
  "artifacts": [],
  "history": []
}
```

--------------------------------

### Install Python Dependencies with uv

Source: https://github.com/a2aproject/a2a-java/blob/main/examples/helloworld/server/README.md

Installs Python dependencies for the client using uv, including creating a virtual environment and installing the package in editable mode.

```bash
# Install uv if you don't have it already
# On macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# On Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Install the package using uv
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e .
```

--------------------------------

### List Push Notification Configs Response Example

Source: https://github.com/a2aproject/a2a-java/blob/main/transport/rest/README.md

Example JSON structure for the response when listing push notification configurations. Includes a list of configurations and a pagination token.

```json
{
  "configs": [ ... ],
  "nextPageToken": ""
}
```

--------------------------------

### Get Task Request Example

Source: https://github.com/a2aproject/a2a-java/blob/main/transport/rest/README.md

Example of a GET request to retrieve the current state of a task by its ID. The historyLength query parameter can be used to control the amount of history included.

```http
GET /{tenant}/tasks/{taskId}?historyLength=10
```

--------------------------------

### AgentCapabilities Builder Example

Source: https://github.com/a2aproject/a2a-java/blob/main/_autodocs/types.md

Demonstrates how to create an AgentCapabilities instance using its builder pattern.

```java
AgentCapabilities caps = AgentCapabilities.builder()
    .streaming(true)
    .pushNotifications(false)
    .extendedAgentCard(true)
    .build();
```

--------------------------------

### List Tasks Response Example

Source: https://github.com/a2aproject/a2a-java/blob/main/transport/rest/README.md

Example JSON structure for the response when listing tasks. Includes task details, pagination tokens, and total size.

```json
{
  "tasks": [ ... ],
  "nextPageToken": "",
  "pageSize": 50,
  "totalSize": 3
}
```

--------------------------------

### Example MicroProfile Config Properties

Source: https://github.com/a2aproject/a2a-java/blob/main/_autodocs/configuration.md

Example configuration for executor and timeout settings using MicroProfile Config. Useful for tuning performance and resource management.

```properties
# Executor configuration for high-concurrency streaming
a2a.executor.core-pool-size=20
a2a.executor.max-pool-size=100
a2a.executor.keep-alive-seconds=120

# Timeout configuration for LLM-based agents
a2a.blocking.agent.timeout.seconds=120
a2a.blocking.consumption.timeout.seconds=10
```

--------------------------------

### ClientConfig Builder Example

Source: https://github.com/a2aproject/a2a-java/blob/main/_autodocs/api-reference-client.md

Demonstrates how to build a ClientConfig object using the builder pattern. Configure streaming, polling, output modes, and history length.

```java
ClientConfig config = new ClientConfig.Builder()
    .setStreaming(true)           // Enable streaming if server supports
    .setPolling(false)            // Disable polling (use streaming instead)
    .setUseClientPreference(true) // Use client's transport preference
    .setAcceptedOutputModes(List.of("text"))
    .setHistoryLength(10)         // Request last 10 context messages
    .build();
```

--------------------------------

### Send Message Request Example

Source: https://github.com/a2aproject/a2a-java/blob/main/transport/rest/README.md

Example of a POST request to send a message to the agent. The request body should be in JSON format, containing the message and configuration details.

```http
POST /{tenant}/message:send
Content-Type: application/json
```

```json
{
  "message": {
    "messageId": "msg-1",
    "role": "ROLE_USER",
    "parts": [
      {"text": "Hello, what can you do?"}
    ],
    "contextId": "ctx-1"
  },
  "configuration": {
    "historyLength": 10,
    "returnImmediately": false,
    "acceptedOutputModes": ["text/plain"]
  }
}
```

--------------------------------

### Artifact Example and Part Iteration

Source: https://github.com/a2aproject/a2a-java/blob/main/_autodocs/types.md

Illustrates creating an Artifact with text and file parts, and then iterating through the parts to process them based on their type.

```java
Artifact artifact = artifact(List.of(
    new TextPart("Analysis complete"),
    new FilePart(new FileWithUri("http://example.com/report.pdf"))
));

for (Part<?> part : artifact.parts()) {
    if (part instanceof TextPart text) {
        System.out.println("Text: " + text.text());
    }
}
```

--------------------------------

### Direct HTTP Client Usage (GET Request)

Source: https://github.com/a2aproject/a2a-java/blob/main/extras/http-client-vertx/README.md

Demonstrates how to obtain and use the A2AHttpClient for a simple GET request. Ensure the client is closed after use to release resources.

```java
import org.a2aproject.sdk.client.http.A2AHttpClient;
import org.a2aproject.sdk.client.http.A2AHttpClientFactory;
import org.a2aproject.sdk.client.http.A2AHttpResponse;

// Get the client via factory (returns VertxA2AHttpClient if available)
try (A2AHttpClient client = A2AHttpClientFactory.create()) {
    // Simple GET request
    A2AHttpResponse response = client.createGet()
        .url("https://api.example.com/data")
        .addHeader("Authorization", "Bearer token")
        .get();

    if (response.success()) {
        System.out.println(response.body());
    }
}
```

--------------------------------

### TaskEvent and TaskUpdateEvent example

Source: https://github.com/a2aproject/a2a-java/blob/main/_autodocs/api-reference-client.md

Example of how to process TaskEvent and TaskUpdateEvent. This snippet shows how to differentiate between task status updates and artifact updates.

```java
if (event instanceof TaskUpdateEvent tue) {
    Task task = tue.getTask();
    TaskUpdateEventKind update = tue.getUpdateEvent();
    
    if (update instanceof TaskStatusUpdateEvent status) {
        System.out.println("New status: " + task.status().state());
    } else if (update instanceof TaskArtifactUpdateEvent artifact) {
        System.out.println("New artifact: " + artifact.artifact().parts());
    }
}
```

--------------------------------

### Install JBang on Linux/macOS with wget

Source: https://github.com/a2aproject/a2a-java/blob/main/examples/helloworld/client/src/main/java/org/a2aproject/sdk/examples/helloworld/INSTALL_JBANG.md

Use this command to install JBang on Linux or macOS using wget. It downloads and executes the JBang installer script.

```bash
# OR using wget
wget -q https://sh.jbang.dev -O - | bash -s - app setup
```

--------------------------------

### AgentCard Builder Example

Source: https://github.com/a2aproject/a2a-java/blob/main/_autodocs/types.md

Demonstrates how to construct an AgentCard using its builder pattern. This is useful for programmatically creating agent manifests with specific metadata.

```java
AgentCard card = AgentCard.builder()
    .name("My Agent")
    .description("Does something useful")
    .version("1.0.0")
    .capabilities(AgentCapabilities.builder()
        .streaming(true)
        .pushNotifications(false)
        .build())
    .defaultInputModes(List.of("text"))
    .defaultOutputModes(List.of("text"))
    .skills(List.of(AgentSkill.builder()
        .id("skill-1")
        .name("My Skill")
        .build()))
    .supportedInterfaces(List.of(
        new AgentInterface("jsonrpc", "http://localhost:9999")))
    .build();

```

--------------------------------

### SPI Provider Registration Example

Source: https://github.com/a2aproject/a2a-java/blob/main/extras/http-client-vertx/README.md

Illustrates the content of the `META-INF/services/org.a2aproject.sdk.client.http.A2AHttpClientProvider` file for registering the Vert.x HTTP client provider.

```plaintext
org.a2aproject.sdk.client.http.VertxA2AHttpClientProvider
```

--------------------------------

### Run Java A2A Server

Source: https://github.com/a2aproject/a2a-java/blob/main/examples/helloworld/server/README.md

Starts the Java A2A server using Maven. This is the default command.

```bash
cd examples/helloworld/server
mvn quarkus:dev
```

--------------------------------

### Install JBang on Windows with Scoop

Source: https://github.com/a2aproject/a2a-java/blob/main/examples/helloworld/client/src/main/java/org/a2aproject/sdk/examples/helloworld/INSTALL_JBANG.md

Install JBang on Windows using the Scoop package manager.

```powershell
scoop install jbang
```

--------------------------------

### Run Python A2A Server with uv

Source: https://github.com/a2aproject/a2a-java/blob/main/examples/helloworld/client/README.md

Start the Python A2A server using uv. The server will be accessible at http://localhost:9999.

```bash
uv run .
```

--------------------------------

### Send Streaming Message Request Example

Source: https://github.com/a2aproject/a2a-java/blob/main/transport/rest/README.md

Example of a POST request to send a message and stream task updates as Server-Sent Events (SSE). Requires streaming capabilities to be enabled on the agent.

```http
POST /{tenant}/message:stream
Content-Type: application/json
Accept: text/event-stream
```

```json
{
  "message": {
    "messageId": "msg-1",
    "role": "ROLE_USER",
    "parts": [
      {"text": "Hello, what can you do?"}
    ],
    "contextId": "ctx-1"
  },
  "configuration": {
    "historyLength": 10,
    "returnImmediately": false,
    "acceptedOutputModes": ["text/plain"]
  }
}
```

--------------------------------

### Build and Install Project (Skip Tests)

Source: https://github.com/a2aproject/a2a-java/blob/main/CONTRIBUTING.md

Build the a2a-java project and skip running tests. Use this command when tests are not immediately necessary or are causing issues.

```bash
mvn clean install -DskipTests=true
```

--------------------------------

### TaskPushNotificationConfig Builder Example

Source: https://github.com/a2aproject/a2a-java/blob/main/_autodocs/types.md

Demonstrates how to create a TaskPushNotificationConfig instance using its builder pattern, specifying task ID, webhook URL, and authentication.

```java
TaskPushNotificationConfig config = TaskPushNotificationConfig.builder()
    .taskId("task-123")
    .url("https://my-app.com/webhooks/tasks")
    .authentication(new AuthenticationInfo("Bearer", "my-token"))
    .build();
```

--------------------------------

### Agent Card Response Example

Source: https://github.com/a2aproject/a2a-java/blob/main/transport/rest/README.md

Example JSON structure for the AgentCard object. Includes agent name, description, version, supported interfaces, capabilities, skills, and default input/output modes.

```json
{
  "name": "My Agent",
  "description": "An example agent",
  "version": "1.0.0",
  "supportedInterfaces": [ ... ],
  "capabilities": {
    "streaming": true,
    "pushNotifications": false
  },
  "skills": [ ... ],
  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["text/plain"]
}
```

--------------------------------

### Verify Build and Changes

Source: https://github.com/a2aproject/a2a-java/blob/main/RELEASE.md

Review all project changes using git diff and ensure the build is successful with mvn clean install.

```bash
# Review all changes
git diff

# Verify build works
mvn clean install
```

--------------------------------

### Start External OpenTelemetry Collector

Source: https://github.com/a2aproject/a2a-java/blob/main/examples/helloworld/client/README.md

Starts an external OpenTelemetry collector using Docker, listening on the default OTLP gRPC port. This is an alternative for tracing when not using the Java server.

```bash
docker run -p 5317:4317 otel/opentelemetry-collector
```

--------------------------------

### Running All BOM Tests

Source: https://github.com/a2aproject/a2a-java/blob/main/boms/README.md

Command to clean, install, and skip tests for all BOM modules.

```bash
mvn clean install -DskipTests -pl boms/sdk,boms/extras,boms/reference
```

--------------------------------

### Create A2A Client using ClientBuilder

Source: https://github.com/a2aproject/a2a-java/blob/main/README.md

Example of creating an A2A client with specified configurations, event consumers, and a streaming error handler.

```java
// First, get the agent card for the A2A server agent you want to connect to
AgentCard agentCard = new A2ACardResolver("http://localhost:1234").getAgentCard();

// Specify configuration for the ClientBuilder
ClientConfig clientConfig = new ClientConfig.Builder()
        .setAcceptedOutputModes(List.of("text"))
        .build();

// Create event consumers to handle responses that will be received from the A2A server
// (these consumers will be used for both streaming and non-streaming responses)
List<BiConsumer<ClientEvent, AgentCard>> consumers = List.of(
    (event, card) -> {
        if (event instanceof MessageEvent messageEvent) {
            // handle the messageEvent.getMessage()
            ...
        } else if (event instanceof TaskEvent taskEvent) {
            // handle the taskEvent.getTask()
            ...
        } else if (event instanceof TaskUpdateEvent updateEvent) {
            // handle the updateEvent.getTask()
            ...
        }
    }
);

// Create a handler that will be used for any errors that occur during streaming
Consumer<Throwable> errorHandler = error -> {
    // handle the error.getMessage()
    ...
};

// Create the client using the builder
Client client = Client
        .builder(agentCard)
        .clientConfig(clientConfig)
        .withTransport(JSONRPCTransport.class, new JSONRPCTransportConfig())
        .addConsumers(consumers)
        .streamingErrorHandler(errorHandler)
        .build();
```

--------------------------------

### Configure gRPC Transport with Channel Factory

Source: https://github.com/a2aproject/a2a-java/blob/main/README.md

Example of configuring the gRPC transport by providing a custom channel factory function.

```java
// Create a channel factory function that takes the agent URL and returns a Channel
Function<String, Channel> channelFactory = agentUrl -> {
    return ManagedChannelBuilder.forTarget(agentUrl)
            ...
            .build();
};

// Configure the client with transport-specific settings
ClientConfig clientConfig = new ClientConfig.Builder()
        .setAcceptedOutputModes(List.of("text"))
        .build();

Client client = Client
        .builder(agentCard)
        .clientConfig(clientConfig)
        .withTransport(GrpcTransport.class, new GrpcTransportConfig(channelFactory))
        .build();
```

--------------------------------

### Implement an Agent (Server-Side)

Source: https://github.com/a2aproject/a2a-java/blob/main/_autodocs/INDEX.md

Example of implementing an agent's behavior using the AgentExecutor interface. This snippet shows how to handle incoming requests, process input, and emit responses.

```java
@ApplicationScoped
public class MyAgentExecutor implements AgentExecutor {
    @Override
    public void execute(RequestContext context, AgentEmitter emitter) throws A2AError {
        if (context.getTask() == null) {
            emitter.submit();
        }
        emitter.startWork();
        
        String userInput = context.getUserInput();
        String result = processInput(userInput);
        
        emitter.addArtifact(List.of(new TextPart(result)));
        emitter.complete();
    }
    
    @Override
    public void cancel(RequestContext context, AgentEmitter emitter) throws A2AError {
        emitter.cancel();
    }
}
```

--------------------------------

### Run Java A2A Server with OpenTelemetry Profile

Source: https://github.com/a2aproject/a2a-java/blob/main/examples/helloworld/server/README.md

Starts the Java A2A server using Maven with the 'opentetelemetry' profile enabled to activate distributed tracing.

```bash
mvn quarkus:dev -Popentelemetry
```

--------------------------------

### Default Queue Properties

Source: https://github.com/a2aproject/a2a-java/blob/main/_autodocs/configuration.md

Example of default internal queue settings defined in a properties file. This specifies the size of the event queue.

```properties
# Queue settings (internal)
a2a.eventqueue.size=1000
```

--------------------------------

### Create a User Message with Role

Source: https://github.com/a2aproject/a2a-java/blob/main/_autodocs/api-reference-a2a-utilities.md

This example demonstrates how to construct a message object originating from the user, utilizing the `Message.Role.ROLE_USER` enum value.

```java
Message userMsg = Message.builder()
    .role(Message.Role.ROLE_USER)
    .parts(List.of(new TextPart("Hello")))
    .build();
```

--------------------------------

### Source Shell Configuration

Source: https://github.com/a2aproject/a2a-java/blob/main/examples/helloworld/client/src/main/java/org/a2aproject/sdk/examples/helloworld/INSTALL_JBANG.md

After installation, restart your terminal or source your shell configuration file to apply changes. Use the appropriate command for your shell.

```bash
source ~/.bashrc   # For Bash
```

```bash
source ~/.zshrc    # For Zsh
```

--------------------------------

### Message Builder Example

Source: https://github.com/a2aproject/a2a-java/blob/main/_autodocs/types.md

Shows how to create a Message object using its builder. This is commonly used when sending user messages to an agent or when constructing messages on the server-side.

```java
Message msg = Message.builder()
    .role(Message.Role.ROLE_USER)
    .parts(List.of(new TextPart("Hello")))
    .contextId("session-123")
    .taskId("task-456")
    .build();

```

--------------------------------

### Add Vert.x WebClient Dependency (Maven)

Source: https://github.com/a2aproject/a2a-java/blob/main/extras/http-client-vertx/README.md

Example Maven dependency configuration to add the Vert.x WebClient library. Use a version compatible with your project's framework.

```xml
<dependency>
    <groupId>io.vertx</groupId>
    <artifactId>vertx-web-client</artifactId>
    <version>4.x.x</version> <!-- Use version compatible with your framework -->
</dependency>
```

--------------------------------

### Run Java A2A Server with GRPC

Source: https://github.com/a2aproject/a2a-java/blob/main/examples/helloworld/server/README.md

Starts the Java A2A server using Maven, specifically configuring it to use the GRPC transport protocol.

```bash
mvn quarkus:dev -Dquarkus.agentcard.protocol=GRPC
```

--------------------------------

### Verify JBang Installation

Source: https://github.com/a2aproject/a2a-java/blob/main/examples/helloworld/client/src/main/java/org/a2aproject/sdk/examples/helloworld/INSTALL_JBANG.md

Run this command after installation to verify that JBang is installed correctly. It should display the installed version number.

```bash
jbang --version
```

--------------------------------

### Server Development Entry Points

Source: https://github.com/a2aproject/a2a-java/blob/main/_autodocs/overview.md

Steps for server developers to implement agent behavior, provide agent card information, and use the AgentEmitter for responses.

```java
1. Implement `org.a2aproject.sdk.server.agentexecution.AgentExecutor`
2. Provide `org.a2aproject.sdk.spec.AgentCard` via CDI producer
3. Use a reference server implementation or integrate with your framework
4. Use `AgentEmitter` to send responses
```

--------------------------------

### Install JBang on Windows with PowerShell

Source: https://github.com/a2aproject/a2a-java/blob/main/examples/helloworld/client/src/main/java/org/a2aproject/sdk/examples/helloworld/INSTALL_JBANG.md

Use this PowerShell command to install JBang on Windows. It downloads and executes the JBang installer script.

```powershell
iex "& { $(iwr https://ps.jbang.dev) } app setup"
```

--------------------------------

### Install JBang on Linux/macOS with curl

Source: https://github.com/a2aproject/a2a-java/blob/main/examples/helloworld/client/src/main/java/org/a2aproject/sdk/examples/helloworld/INSTALL_JBANG.md

Use this command to install JBang on Linux or macOS using curl. It downloads and executes the JBang installer script.

```bash
# Using curl
curl -Ls https://sh.jbang.dev | bash -s - app setup
```

--------------------------------

### Run Java A2A Server with HTTP+JSON

Source: https://github.com/a2aproject/a2a-java/blob/main/examples/helloworld/server/README.md

Starts the Java A2A server using Maven, specifically configuring it to use the HTTP+JSON transport protocol.

```bash
mvn quarkus:dev -Dquarkus.agentcard.protocol=HTTP+JSON
```

--------------------------------

### Check Kafka CRD Installation

Source: https://github.com/a2aproject/a2a-java/blob/main/examples/cloud-deployment/README.md

Verify if the Kafka Custom Resource Definition (CRD) is installed.

```bash
kubectl get crd kafkas.kafka.strimzi.io
```

--------------------------------

### Install JBang on Windows with Chocolatey

Source: https://github.com/a2aproject/a2a-java/blob/main/examples/helloworld/client/src/main/java/org/a2aproject/sdk/examples/helloworld/INSTALL_JBANG.md

Install JBang on Windows using the Chocolatey package manager.

```powershell
choco install jbang
```

--------------------------------

### MessageEvent example

Source: https://github.com/a2aproject/a2a-java/blob/main/_autodocs/api-reference-client.md

Example of how to process a MessageEvent. This snippet demonstrates how to extract the message payload from the event.

```java
if (event instanceof MessageEvent me) {
    Message msg = me.getMessage();
    System.out.println("Parts: " + msg.parts());
}
```

--------------------------------

### Send a Message to an Agent (Client-Side)

Source: https://github.com/a2aproject/a2a-java/blob/main/_autodocs/INDEX.md

Example of how to send a message to an agent using the A2A client. Requires importing AgentCard, Client, MessageEvent, Message, and A2A utilities.

```java
Client client = Client.builder(card)
    .withTransport(JSONRPCTransport.class, new JSONRPCTransportConfig())
    .addConsumer((event, card) -> {
        if (event instanceof MessageEvent me) {
            System.out.println("Response: " + me.getMessage().parts());
        }
    })
    .build();

Message msg = A2A.toUserMessage("Hello, agent!");
client.sendMessage(msg);
```

--------------------------------

### Start Task Processing

Source: https://github.com/a2aproject/a2a-java/blob/main/_autodocs/api-reference-server.md

Marks the task as WORKING, indicating the agent is processing the request. Use this to signal the start of active work.

```java
void startWork()
```

```java
emitter.startWork();  // Agent is now processing
```

--------------------------------

### Create v0.3 Compatibility Client

Source: https://github.com/a2aproject/a2a-java/blob/main/README.md

Initializes a v0.3 compatibility client by resolving the agent card, finding the v0.3 interface, and configuring the transport.

```java
AgentCard card = new A2ACardResolver("http://localhost:1234").getAgentCard();

// Find the v0.3 interface from the agent card
AgentInterface v03Interface = card.supportedInterfaces().stream()
        .filter(iface -> A2AProtocol_v0_3.PROTOCOL_VERSION.equals(iface.protocolVersion()))
        .findFirst()
        .orElseThrow();

// Create the v0.3 compatibility client
Client_v0_3 client = ClientBuilder_v0_3.forUrl(v03Interface.url())
        .withTransport(JSONRPCTransport_v0_3.class, new JSONRPCTransportConfigBuilder_v0_3())
        .build();
```

--------------------------------

### Run A2A Cloud Example Client Test

Source: https://github.com/a2aproject/a2a-java/blob/main/examples/cloud-deployment/README.md

Execute the test client to verify multi-pod behavior. This command compiles and runs the Java client, connecting to the agent service exposed via NodePort at http://localhost:8080. It tests load balancing, event replication, and persistence.

```bash
cd ../server
mvn test-compile exec:java \
  -Dexec.mainClass="org.a2aproject.sdk.examples.cloud.A2ACloudExampleClient" \
  -Dexec.classpathScope=test \
  -Dagent.url="http://localhost:8080"
```

--------------------------------

### Server-Sent Events (SSE) Stream Example

Source: https://github.com/a2aproject/a2a-java/blob/main/transport/rest/README.md

Example of a Server-Sent Events (SSE) stream response for streaming messages. Each data field contains a JSON-serialized StreamResponse.

```text
: SSE stream started

id: 0
data: {"statusUpdate":{"taskId":"task-1","contextId":"ctx-1","status":{"state":"TASK_STATE_WORKING"}}}

id: 1
data: {"artifactUpdate":{"taskId":"task-1","contextId":"ctx-1","artifact":{"artifactId":"a-1","parts":[{"text":"Hello!"}]}}}

id: 2
data: {"statusUpdate":{"taskId":"task-1","contextId":"ctx-1","status":{"state":"TASK_STATE_COMPLETED"}}}
```

--------------------------------

### Build Client Instance with Builder Pattern

Source: https://github.com/a2aproject/a2a-java/blob/main/_autodocs/api-reference-client.md

Use the `Client.builder()` static method to construct a `Client` instance. Configure transport and add event consumers as needed.

```java
AgentCard card = A2A.getAgentCard("http://localhost:9999");
Client client = Client.builder(card)
    .withTransport(JSONRPCTransport.class, new JSONRPCTransportConfig())
    .addConsumer((event, agentCard) -> {
        if (event instanceof MessageEvent me) {
            System.out.println("Response: " + me.getMessage().parts());
        }
    })
    .build();
```

--------------------------------

### Client Development Entry Points

Source: https://github.com/a2aproject/a2a-java/blob/main/_autodocs/overview.md

Steps for client developers to discover an agent, build a client with a specific transport, and send messages.

```java
1. Import `org.a2aproject.sdk.client.Client` and `org.a2aproject.sdk.A2A`
2. Call `A2A.getAgentCard(String url)` to discover an agent
3. Build a client: `Client.builder(agentCard).withTransport(...).build()`
4. Send messages: `client.sendMessage(...)`
```

--------------------------------

### Synchronous HTTP GET Request

Source: https://github.com/a2aproject/a2a-java/blob/main/extras/http-client-vertx/README.md

Shows how to perform a synchronous HTTP GET request using the A2AHttpClient. This method blocks the calling thread until a response is received.

```java
A2AHttpResponse response = client.createGet()
    .url("https://example.com")
    .get(); // ← Blocks until response received
```

--------------------------------

### Client.builder

Source: https://github.com/a2aproject/a2a-java/blob/main/_autodocs/api-reference-client.md

Constructs a `Client` instance using the builder pattern. This is the recommended way to create a client, allowing for configuration of transports, consumers, and error handlers.

```APIDOC
## Client.builder(AgentCard agentCard)

### Description
Factory method to create a `ClientBuilder` for configuring and building a `Client` instance.

### Method
`public static ClientBuilder builder(@NonNull AgentCard agentCard)`

### Parameters
#### Path Parameters
* None

#### Query Parameters
* None

#### Request Body
* None

### Returns
`ClientBuilder` - A new builder instance for configuring the client.

### Example
```java
AgentCard card = A2A.getAgentCard("http://localhost:9999");
Client client = Client.builder(card)
    .withTransport(JSONRPCTransport.class, new JSONRPCTransportConfig())
    .addConsumer((event, agentCard) -> {
        if (event instanceof MessageEvent me) {
            System.out.println("Response: " + me.getMessage().parts());
        }
    })
    .build();
```
```

--------------------------------

### RFC 7807 Problem Details JSON Example

Source: https://github.com/a2aproject/a2a-java/blob/main/transport/rest/README.md

An example of an error response conforming to RFC 7807 Problem Details. This structure is used for all error responses from the A2A protocol.

```json
{
  "type": "https://a2a-protocol.org/errors/task-not-found",
  "title": "Task not found",
  "status": 404,
  "details": ""
}
```

--------------------------------

### Kafka Topic Creation: Multiple Partitions

Source: https://github.com/a2aproject/a2a-java/blob/main/extras/queue-manager-replicated/README.md

Create a Kafka topic with multiple partitions (e.g., 10) and a replication factor (e.g., 3). This enables horizontal scalability and consumer parallelism.

```bash
kafka-topics.sh --create --topic replicated-events --bootstrap-server localhost:9092 --partitions 10 --replication-factor 3
```

--------------------------------

### startWork()

Source: https://github.com/a2aproject/a2a-java/blob/main/_autodocs/api-reference-server.md

Marks the task as WORKING, indicating the agent is processing the request.

```APIDOC
## startWork()

### Description
Marks the task as WORKING, indicating the agent is processing the request.

### Method
void

### Endpoint
N/A (Method call)

### Parameters
None

### Request Example
```java
emitter.startWork();
```

### Response
None
```

--------------------------------

### Asynchronous HTTP GET Request with Server-Sent Events

Source: https://github.com/a2aproject/a2a-java/blob/main/extras/http-client-vertx/README.md

Illustrates performing an asynchronous HTTP GET request that supports Server-Sent Events (SSE). This method returns immediately with a CompletableFuture, allowing other work to proceed.

```java
CompletableFuture<Void> future = client.createGet()
    .url("https://example.com/stream")
    .getAsyncSSE(
        message -> handleMessage(message),
        error -> handleError(error),
        () -> handleComplete()
    ); // ← Returns immediately

// Do other work
future.join(); // Optional: wait for completion
```

--------------------------------

### GET /tasks/{taskId}

Source: https://github.com/a2aproject/a2a-java/blob/main/transport/rest/README.md

Retrieves the current state of a task by ID.

```APIDOC
## GET /tasks/{taskId}

### Description
Retrieves the current state of a task by ID.

### Method
GET

### Endpoint
`/{tenant}/tasks/{taskId}`

### Parameters
#### Path Parameters
- **taskId** (string) - Required - The ID of the task to retrieve.

#### Query Parameters
- **historyLength** (integer) - Optional - Maximum number of history messages to include. Omit for no limit; `0` for none.

### Response
#### Success Response (200)
- **task** (object) - A `Task` object containing the task's current state.
  - **id** (string) - The ID of the task.
  - **contextId** (string) - The ID of the context.
  - **status** (object) - The status of the task.
    - **state** (string) - The current state of the task.
    - **timestamp** (string) - The timestamp of the status update.
  - **artifacts** (array) - An array of artifacts associated with the task.
  - **history** (array) - An array of history messages for the task.

### Response Example
```json
{
  "id": "task-1",
  "contextId": "ctx-1",
  "status": {
    "state": "TASK_STATE_COMPLETED",
    "timestamp": "2023-10-27T10:00:00Z"
  },
  "artifacts": [],
  "history": []
}
```
```

--------------------------------

### AgentEmitter.submit

Source: https://github.com/a2aproject/a2a-java/blob/main/_autodocs/api-reference-server.md

Marks the task as SUBMITTED. This should be called once at the start of execution if this is a new request.

```APIDOC
## AgentEmitter.submit

### Description
Marks the task as SUBMITTED. Call once at the start of execution if this is a new request.

### Method
`void submit()`

### Parameters
* None

### Example
```java
if (context.getTask() == null) {
    emitter.submit();  // Create and mark task as submitted
}
```
```

--------------------------------

### Run Java Client with OpenTelemetry (Maven)

Source: https://github.com/a2aproject/a2a-java/blob/main/examples/helloworld/client/README.md

Executes the Java client using Maven with OpenTelemetry tracing enabled. Allows specifying the agent card protocol.

```bash
mvn exec:java -Dopentelemetry=true
```

```bash
mvn exec:java -Dquarkus.agentcard.protocol=HTTP+JSON -Dopentelemetry=true
```

--------------------------------

### Build the configured Client instance

Source: https://github.com/a2aproject/a2a-java/blob/main/_autodocs/api-reference-client.md

Builds the configured Client instance. This method performs transport negotiation to select a compatible transport based on client preferences or server interfaces.

```java
public Client build() throws A2AClientException
```

--------------------------------

### Create Release Branch and Commit

Source: https://github.com/a2aproject/a2a-java/blob/main/RELEASE.md

Create a new branch for the release, stage all changes, and commit them with a descriptive message.

```bash
git checkout -b release/0.4.0.Alpha1
git add -A
git commit -m "chore: release 0.4.0.Alpha1"
git push origin release/0.4.0.Alpha1
```

--------------------------------

### Get Push Notification Config

Source: https://github.com/a2aproject/a2a-java/blob/main/transport/rest/README.md

Retrieves a specific push notification configuration for a task.

```APIDOC
## GET /{tenant}/tasks/{taskId}/pushNotificationConfigs/{configId}

### Description
Retrieves a specific push notification configuration for a task.

### Method
GET

### Endpoint
`/{tenant}/tasks/{taskId}/pushNotificationConfigs/{configId}`

### Parameters
#### Path Parameters
- **taskId** (string) - Required - The ID of the task.
- **configId** (string) - Required - The ID of the push notification configuration.

### Response
#### Success Response (200)
- The `TaskPushNotificationConfig` object.
```

--------------------------------

### Run Java Client with Maven (OpenTelemetry)

Source: https://github.com/a2aproject/a2a-java/blob/main/examples/helloworld/client/README.md

Enable OpenTelemetry for the Java client when running with Maven. This allows for distributed tracing and monitoring.

```bash
mvn exec:java -Dopentelemetry=true
```

--------------------------------

### Get Push Notification Config Endpoint

Source: https://github.com/a2aproject/a2a-java/blob/main/transport/rest/README.md

Retrieves a specific push notification configuration for a task.

```http
GET /{tenant}/tasks/{taskId}/pushNotificationConfigs/{configId}
```

--------------------------------

### Running Individual BOM Test

Source: https://github.com/a2aproject/a2a-java/blob/main/boms/README.md

Command to clean, install, and skip tests for a specific BOM module.

```bash
mvn clean install -DskipTests -pl boms/sdk
```

--------------------------------

### Check Kind NodePort Mappings

Source: https://github.com/a2aproject/a2a-java/blob/main/examples/cloud-deployment/README.md

Verify that Kind's extraPortMappings are correctly configured to expose NodePorts.

```bash
docker ps | grep kind-control-plane
```

```bash
# or for Podman:
podman ps | grep kind-control-plane
```

--------------------------------

### build

Source: https://github.com/a2aproject/a2a-java/blob/main/_autodocs/api-reference-client.md

Builds the configured Client instance after performing transport negotiation based on client preferences or server interface order.

```APIDOC
## build()

### Description
Builds the configured `Client` instance. Performs transport negotiation.

### Method
```java
public Client build() throws A2AClientException
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Returns
`Client` — The configured client instance

### Throws
`A2AClientException` — if no compatible transport found or configuration missing
```

--------------------------------

### Get Agent Card

Source: https://github.com/a2aproject/a2a-java/blob/main/transport/rest/README.md

Public discovery endpoint. Returns the agent's self-describing manifest. No authentication required.

```APIDOC
## GET /.well-known/agent-card.json

### Description
Public discovery endpoint. Returns the agent's self-describing manifest. No authentication required.

### Method
GET

### Endpoint
`/.well-known/agent-card.json`

### Response
#### Success Response (200)
- An `AgentCard` object containing agent information such as name, description, version, supported interfaces, capabilities, skills, and default input/output modes.
```

--------------------------------

### Manual Vertx Instance Configuration (Non-CDI)

Source: https://github.com/a2aproject/a2a-java/blob/main/extras/http-client-vertx/README.md

Shows how to manually create and provide a Vert.x instance to the VertxA2AHttpClient when not using CDI. Remember to close the Vertx instance when the application shuts down.

```java
import org.a2aproject.sdk.client.http.VertxA2AHttpClient;
import io.vertx.core.Vertx;

// Create Vertx instance once
Vertx vertx = Vertx.vertx();

try {
    // Create client with shared Vertx instance
    try (VertxA2AHttpClient client = new VertxA2AHttpClient(vertx)) {
        A2AHttpResponse response = client.createGet()
            .url("https://example.com")
            .get();
    }
    // Client is closed, but Vertx instance remains open
} finally {
    // Close Vertx when application shuts down
    vertx.close();
}
```

--------------------------------

### Build All A2A SDK Modules

Source: https://github.com/a2aproject/a2a-java/blob/main/extras/opentelemetry/integration-tests/README.md

Before running integration tests, build all A2A SDK modules. This command ensures all dependencies are available.

```bash
mvn clean install -DskipTests
```

--------------------------------

### Get Agent Card Endpoint

Source: https://github.com/a2aproject/a2a-java/blob/main/transport/rest/README.md

Public discovery endpoint to retrieve the agent's self-describing manifest. No authentication is required.

```http
GET /.well-known/agent-card.json
```

--------------------------------

### Get a specific task

Source: https://github.com/a2aproject/a2a-java/blob/main/_autodocs/api-reference-client.md

Retrieves the current state of a task by its ID. Use this when you need to check the status of a known task.

```java
Task task = client.getTask(new TaskQueryParams("task-123"));
System.out.println("Status: " + task.status().state());
```

--------------------------------

### Project Structure

Source: https://github.com/a2aproject/a2a-java/blob/main/examples/cloud-deployment/README.md

Overview of the directory structure for the cloud deployment project, including server code, Kubernetes manifests, and scripts.

```tree
cloud-deployment/
├── server/
│   ├── src/main/java/org/a2aproject/sdk/examples/cloud/
│   │   ├── CloudAgentCardProducer.java       # Agent card configuration
│   │   └── CloudAgentExecutorProducer.java   # Agent business logic
│   ├── src/main/resources/
│   │   └── application.properties            # Application configuration
│   ├── src/test/java/org/a2aproject/sdk/examples/cloud/
│   │   └── A2ACloudExampleClient.java        # Test client
│   ├── pom.xml                               # Maven dependencies
│   └── Dockerfile                            # Container image
├── k8s/
│   ├── 00-namespace.yaml                     # Kubernetes namespace
│   ├── 01-postgres.yaml                      # PostgreSQL deployment
│   ├── 02-kafka.yaml                         # Strimzi Kafka cluster
│   ├── 03-kafka-topic.yaml                   # Kafka topic
│   ├── 04-agent-configmap.yaml               # Configuration
│   └── 05-agent-deployment.yaml              # Agent deployment + service
├── strimzi-1.0.0/
│   └── strimzi-cluster-operator-1.0.0.yaml   # Pinned from https://strimzi.io/install/latest?namespace=kafka
├── scripts/
│   ├── deploy.sh                             # Automated deployment
│   ├── verify.sh                             # Health checks
│   └── cleanup.sh                            # Resource cleanup
└── README.md                                 # This file
```

--------------------------------

### Usage with Try-with-Resources

Source: https://github.com/a2aproject/a2a-java/blob/main/extras/http-client-vertx/README.md

Demonstrates the correct way to instantiate and use VertxA2AHttpClient using a try-with-resources statement. This ensures the client is automatically closed, preventing memory leaks.

```java
try (VertxA2AHttpClient client = new VertxA2AHttpClient()) {
    // Use client
} // Automatically closed
```

--------------------------------

### Run Java Client with Maven (HTTP+JSON and OpenTelemetry)

Source: https://github.com/a2aproject/a2a-java/blob/main/examples/helloworld/client/README.md

Combine transport protocol selection (HTTP+JSON) with OpenTelemetry enablement when running the Java client via Maven. This provides both specific communication and monitoring capabilities.

```bash
mvn exec:java -Dquarkus.agentcard.protocol=HTTP+JSON -Dopentelemetry=true
```

--------------------------------

### Deploy A2A Stack with Podman

Source: https://github.com/a2aproject/a2a-java/blob/main/examples/cloud-deployment/README.md

Use this command to deploy the A2A stack when using Podman as the container tool instead of Docker. Note that Kind's support for Podman is experimental on Linux, and a reboot may resolve occasional issues.

```bash
./deploy.sh --container-tool podman
```

--------------------------------

### Default Timeout Properties

Source: https://github.com/a2aproject/a2a-java/blob/main/_autodocs/configuration.md

Example of default timeout settings defined in a properties file. These specify timeouts for agent blocking and consumption.

```properties
# Default timeouts
a2a.blocking.agent.timeout.seconds=30
a2a.blocking.consumption.timeout.seconds=5
```

--------------------------------

### Default Executor Properties

Source: https://github.com/a2aproject/a2a-java/blob/main/_autodocs/configuration.md

Example of default executor settings defined in a properties file. These control thread pool size and keep-alive.

```properties
# Default executor settings
a2a.executor.core-pool-size=5
a2a.executor.max-pool-size=50
a2a.executor.keep-alive-seconds=60
```

--------------------------------

### Configure JSON-RPC Transport (Default)

Source: https://github.com/a2aproject/a2a-java/blob/main/_autodocs/configuration.md

Sets up the JSON-RPC transport for clients using the default JDK HTTP client. This is the standard way to establish a connection.

```java
import org.a2aproject.sdk.client.transport.jsonrpc.JSONRPCTransport;
import org.a2aproject.sdk.client.transport.jsonrpc.JSONRPCTransportConfig;

// Default configuration (uses JDK HTTP client)
Client client = Client.builder(card)
    .withTransport(JSONRPCTransport.class, new JSONRPCTransportConfig())
    .build();
```

--------------------------------

### Get User Input with Default Separator

Source: https://github.com/a2aproject/a2a-java/blob/main/_autodocs/api-reference-server.md

Extract all text content from message parts, concatenated without any separator, using `context.getUserInput()`.

```java
public String getUserInput()
```

--------------------------------

### Verify A2A Deployment

Source: https://github.com/a2aproject/a2a-java/blob/main/examples/cloud-deployment/README.md

Run the verification script after deployment to check the status of essential components. This script confirms the existence of the 'a2a-demo' namespace, running PostgreSQL, ready Kafka, and the status of agent pods and services.

```bash
./verify.sh
```