> For the complete documentation index, see [llms.txt](https://docs.bluerock.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bluerock.io/agent-frameworks-integration/agent-to-agent-a2a.md).

# Agent-to-Agent (A2A)

Agent-to-Agent (A2A) communication enables autonomous AI agents to interact, delegate tasks, and exchange data programmatically without human intervention. To resolve interoperability limitations between disparate AI frameworks (such as LangChain, CrewAI, or custom scripts), BlueRock implements a standardized communication layer comprising three core components:

* **Standardized Protocol**: \
  Uniform routing and endpoints that allow agents to exchange structured data reliably regardless of their underlying frameworks.
* **AgentCard**: \
  A discoverable configuration profile defining an agent's identity, supported skills, capabilities, and required input/output formats.
* **Telemetry and Security**: \
  Native tracking of inter-agent prompts and generated artifacts to monitor system behavior, audit workflows, and intercept potentially malicious payloads.

{% hint style="success" icon="lightbulb-exclamation-on" %}
**Important:**

* Telemetry tracing and policy enforcement are supported exclusively on a BlueRock Ubuntu or AL2023 Virtual Machine (VM). Standard Linux environments are not supported.
* Unsanitized data from external agents exposes applications to severe prompt injection attacks. Treat all external input, including `AgentCards`, messages, and artifacts, as untrusted, and fully sanitize this data before constructing LLM prompts in production environments.
  {% endhint %}

## Core Architecture

<figure><img src="https://1983702018-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCNnVnPvaRpvlLmPT6IAN%2Fuploads%2FwLNC5pNwmYMmst4Atmyd%2Fimage.png?alt=media&amp;token=db3d8436-4aea-4aba-813b-ae87ddbb6a99" alt=""><figcaption></figcaption></figure>

* **Agent Execution Space:** \
  The isolated environment hosting the A2A server or client program alongside the embedded `bluerock` sensor.
* **Customer-Managed A2A Program:** \
  Application code built using the Python A2A SDK or sample scripts from the public repository that handles agent tasks, resolves AgentCards, and constructs prompt payloads.
* **BlueRock Sensor (`bluerock`):**\
  The runtime hook library is deployed inside the virtual environment that transparently intercepts A2A card requests, responses, and task executions.
* **BlueRock Control Plane (`bluerockd`):**\
  The background service dispatches policy rules to the sensor, receives intercepted telemetry events via socket, and exports OpenTelemetry (OTEL) logs.
* **CloudWatch or External Event Collector:**\
  The final storage and monitoring target for compliance audits and security dashboards.

## Environment Setup

### Prerequisites

* [Python version 3.13](https://www.python.org/downloads/release/python-3130/) or above.
* Package Manager: Install `uv` for dependency management and execution.

### Clone the Repository

Build custom A2A scripts using the Python A2A SDK or leverage pre-built sample scripts from the A2A samples repository: <https://github.com/a2aproject/a2a-samples>

Clone the public A2A sample repository and navigate to the desired agent directory:

<pre class="language-shellscript"><code class="lang-shellscript"><strong>$ git clone https://github.com/a2aproject/a2a-samples.git
</strong>$ cd a2a-samples/samples/python/agents/helloworld/
</code></pre>

### Install BlueRock Sensor & Load Sensor

Install the custom BlueRock sensor module and then load the sensor into memory using the installation flag.

```shellscript
$ uv pip install /opt/bluerock/python-dist/bluerock-0.0.1-py3-none-any.whl
$ python -m bluerock --install
```

### Policy Configuration

Policies are defined in the policy template that resides at `/opt/bluerock/trex/`. The `a2a` policy block within the agentic sensor manages pattern matching, remediation controls, and transport-level enforcement for Agent-to-Agent interactions.\
\
To learn more about the policy changes and building it, refer to the [Policy Configuration section](/policy-configuration/policy-builder.md).

#### Default Policy Template (`a2a`)

```json
"a2a": {
    "enable": false,
    "remediate": false,
    "card_name_filter": {
        "enable": true,
        "remediate": true,
        "forbidden_card_name_patterns": [
            "[;&|`$]\\s*(?:whoami |id |pwd |ls |cat |curl |wget |nc |bash |sh |cmd\\.exe |powershell )",
            "\\$\\((?:cmd\\.exe|powershell).*?\\)",
            "(?:curl|wget|nc|netcat).*?(?:-X\\s+POST|-d|--data).*?(?:(?i)https?://|[0-9]{1,3}\\.[0-9]{1,3})",
            "(?i)(?:~/.ssh/|\\.ssh/)(?:id_rsa|id_ecdsa|id_ed25519|authorized_keys|known_hosts)",
            "\\b(?:sudo|su|doas)\\s+\\w+",
            "shell_exec\\s*\\(",
            "\\b(?:bash|sh|zsh|fish|csh|tcsh)\\b",
            "\\b(?:ls|cat|grep|ps|rm|mv|cp|chmod|chown)\\b",
            "\\b(?:curl|wget|ssh|scp|rsync|nc|netcat)\\b",
            "\\b(?:systemctl|mount|umount|fdisk|lsblk)\\b",
            "\\b(?:iptables|ufw|firewall-cmd)\\b"
        ]
    },
    "card_description_filter": {
        "enable": true,
        "remediate": true,
        "forbidden_card_description_patterns": [
            "[;&|`$]\\s*(?:whoami |id |pwd |ls |cat |curl |wget |nc |bash |sh |cmd\\.exe |powershell )",
            "\\$\\((?:cmd\\.exe|powershell).*?\\)",
            "(?:curl|wget|nc|netcat).*?(?:-X\\s+POST|-d|--data).*?(?:(?i)https?://|[0-9]{1,3}\\.[0-9]{1,3})",
            "(?i)(?:~/.ssh/|\\.ssh/)(?:id_rsa|id_ecdsa|id_ed25519|authorized_keys|known_hosts)",
            "\\b(?:sudo|su|doas)\\s+\\w+",
            "shell_exec\\s*\\(",
            "\\b(?:bash|sh|zsh|fish|csh|tcsh)\\b",
            "\\b(?:ls|cat|grep|ps|rm|mv|cp|chmod|chown)\\b",
            "\\b(?:curl|wget|ssh|scp|rsync|nc|netcat)\\b",
            "\\b(?:systemctl|mount|umount|fdisk|lsblk)\\b",
            "\\b(?:iptables|ufw|firewall-cmd)\\b"
        ]
    },
    "skills_description_filter": {
        "enable": true,
        "remediate": true,
        "forbidden_skills_description_patterns": [
            "[;&|`$]\\s*(?:whoami |id |pwd |ls |cat |curl |wget |nc |bash |sh |cmd\\.exe |powershell )",
            "\\$\\((?:cmd\\.exe|powershell).*?\\)",
            "(?:curl|wget|nc|netcat).*?(?:-X\\s+POST|-d|--data).*?(?:(?i)https?://|[0-9]{1,3}\\.[0-9]{1,3})",
            "(?i)(?:~/.ssh/|\\.ssh/)(?:id_rsa|id_ecdsa|id_ed25519|authorized_keys|known_hosts)",
            "\\b(?:sudo|su|doas)\\s+\\w+",
            "shell_exec\\s*\\(",
            "\\b(?:bash|sh|zsh|fish|csh|tcsh)\\b",
            "\\b(?:ls|cat|grep|ps|rm|mv|cp|chmod|chown)\\b",
            "\\b(?:curl|wget|ssh|scp|rsync|nc|netcat)\\b",
            "\\b(?:systemctl|mount|umount|fdisk|lsblk)\\b",
            "\\b(?:iptables|ufw|firewall-cmd)\\b"
        ]
    },
    "http_servers": {
        "enable": true,
        "remediate": true,
        "deny_http": false,
        "deny_websocket": false,
        "exception_list": [],
        "force_authentication": false
    }
}
```

#### Policy Configuration Parameters

<table data-header-hidden data-search="false"><thead><tr><th></th><th width="142.6666259765625"></th><th width="114.7777099609375"></th><th></th></tr></thead><tbody><tr><td><strong>Parameter</strong></td><td><strong>Type</strong></td><td><strong>Default</strong></td><td><strong>Description</strong></td></tr><tr><td><code>a2a.enable</code></td><td><code>boolean</code></td><td><code>false</code></td><td>Main toggle to enable or disable the entire A2A sensor inspection block.</td></tr><tr><td><code>a2a.remediate</code></td><td><code>boolean</code></td><td><code>false</code></td><td>Main toggle to activate mitigation or blocking actions for detected A2A policy violations.</td></tr><tr><td><code>a2a.card_name_filter.enable</code></td><td><code>boolean</code></td><td><code>true</code></td><td>Enables pattern inspection specifically on the Agent Card <code>name</code> field.</td></tr><tr><td><code>a2a.card_name_filter.remediate</code></td><td><code>boolean</code></td><td><code>true</code></td><td>Triggers remediation/blocking when a forbidden pattern is matched in the card name.</td></tr><tr><td><code>a2a.card_name_filter.forbidden_card_name_patterns</code></td><td><code>array[string]</code></td><td><em>(RegEx List)</em></td><td>Array of regex patterns used to flag unsafe commands or terms in the Agent Card name.</td></tr><tr><td><code>a2a.card_description_filter.enable</code></td><td><code>boolean</code></td><td><code>true</code></td><td>Enables pattern inspection on the Agent Card <code>description</code> field.</td></tr><tr><td><code>a2a.card_description_filter.remediate</code></td><td><code>boolean</code></td><td><code>true</code></td><td>Triggers remediation/blocking when a forbidden pattern is matched in the card description.</td></tr><tr><td><code>a2a.card_description_filter.forbidden_card_description_patterns</code></td><td><code>array[string]</code></td><td><em>(RegEx List)</em></td><td>Array of regex patterns used to flag unsafe commands or credentials in the card description.</td></tr><tr><td><code>a2a.skills_description_filter.enable</code></td><td><code>boolean</code></td><td><code>true</code></td><td>Enables pattern inspection on skill descriptions (<code>skills[].description</code>) advertised by the agent.</td></tr><tr><td><code>a2a.skills_description_filter.remediate</code></td><td><code>boolean</code></td><td><code>true</code></td><td>Triggers remediation/blocking when a forbidden pattern is matched in any skill description.</td></tr><tr><td><code>a2a.skills_description_filter.forbidden_skills_description_patterns</code></td><td><code>array[string]</code></td><td><em>(RegEx List)</em></td><td>Array of regex patterns used to flag dangerous binary or shell command usage within advertised skills.</td></tr><tr><td><code>a2a.http_servers.enable</code></td><td><code>boolean</code></td><td><code>true</code></td><td>Activates transport-level inspection and policy rules for HTTP-based A2A endpoints.</td></tr><tr><td><code>a2a.http_servers.remediate</code></td><td><code>boolean</code></td><td><code>true</code></td><td>Enforces active transport remediation when policy rules are violated.</td></tr><tr><td><code>a2a.http_servers.deny_http</code></td><td><code>boolean</code></td><td><code>false</code></td><td>When set to <code>true</code>, blocks unencrypted HTTP traffic for A2A communications.</td></tr><tr><td><code>a2a.http_servers.deny_websocket</code></td><td><code>boolean</code></td><td><code>false</code></td><td>When set to <code>true</code>, blocks WebSocket connections used by A2A streaming channels.</td></tr><tr><td><code>a2a.http_servers.exception_list</code></td><td><code>array[string]</code></td><td><code>[]</code></td><td>List of excluded URLs or hosts exempt from transport-level restrictions.</td></tr><tr><td><code>a2a.http_servers.force_authentication</code></td><td><code>boolean</code></td><td><code>false</code></td><td>When set to <code>true</code>, enforces strict authentication requirements on incoming A2A card requests.</td></tr></tbody></table>

## Execution

### Running an A2A Program **Natively on a BlueRock Instance**

Running the A2A Python program directly/natively on the BlueRock VM shell prompt.

1. Start the Server. \
   Run the A2A agent server locally on port `9999`:

   ```shellscript
   $ uv run python __main__.py
   ```

   \
   Expected output:

   ```shellscript
   INFO:     Started server process [82625]
   INFO:     Waiting for application startup.
   INFO:     Application startup complete.
   INFO:     Uvicorn running on http://0.0.0.0:9999 (Press CTRL+C to quit)
   ```
2. Run the Test Client. \
   In a separate host terminal session, execute the test client to verify communication:

   ```shellscript
   $ source .venv/bin/activate
   $ uv run python test_client.py
   ```

   \
   Expected Output:

   ```shellscript
   $Starting an internactive session with A2A Server [http://127.0.0.1:9999]
   Use `exit` to quit.
   user > What is a Cat?
   Initializes the A2ACardResolver instance with an HTTP client

   Successfully fetched the public agent card:

   --- Public Agent Card - Non-Streaming Call ---

   Initializing a non-streaming client.
   Response:
   task {
     id: "bf4a7874-8805-40c8-b3ee-717001ab8a2c"
     context_id: "268b7df9-9a2c-449e-b6e1-51cfabd3628b"
     status {
       state: TASK_STATE_COMPLETED
       message {
         message_id: "b1d9d5eb-b61c-46f8-99f4-1c7fa95f1a30"
         role: ROLE_AGENT
         parts {
           text: "Request is completed!"
         }
       }
       timestamp {
         seconds: 1786103559
         nanos: 986411000
       }
     }
     artifacts {
       artifact_id: "1a5604b0-8d51-4e56-8143-5ea07efb464e"
       parts {
         text: "Hello, World! I have received your request (What is a Cat?)"
         media_type: "text/plain"
       }
     }
     history {
       message_id: "cdeac187-0996-4b82-8551-faf26f5ec889"
       context_id: "268b7df9-9a2c-449e-b6e1-51cfabd3628b"
       task_id: "bf4a7874-8805-40c8-b3ee-717001ab8a2c"
       role: ROLE_USER
       parts {
         text: "What is a Cat?"
       }
     }
     history {
       message_id: "288438e2-a0bf-4f22-9213-291093f8f510"
       role: ROLE_AGENT
       parts {
         text: "Processing request..."
       }
     }
   }

   --
   user > 

   ```

### Running an A2A Program as a Container (Docker) with BlueRock Sensor

Running the A2A Python program as a container with BlueRock Sensor.

1. Create a Dockerfile.\
   In the root directory of your A2A agent application, ensure you have a `Dockerfile` that installs dependencies and copies the BlueRock Sensor<br>

   ```docker
   ARG PYTHON_VERSION=3.13
   FROM python:${PYTHON_VERSION}-slim

   COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/

   WORKDIR /app

   COPY python-packages/<sensor-pkg-1>*.deb python-packages/<sensor-pkg-2>*.deb /app/
   COPY ai_agents/python/a2a/hello_world_agent/agent_executor.py \
        ai_agents/python/a2a/hello_world_agent/pyproject.toml \
        ai_agents/python/a2a/hello_world_agent/__main__.py \
        ai_agents/python/a2a/hello_world_agent/README.md /app/

   RUN apt-get update && \
       apt-get install -y --no-install-recommends curl vim net-tools && \
       apt-get clean && \
       rm -rf /var/lib/apt/lists/* && \
       dpkg -i <sensor-pkg-1>*.deb <sensor-pkg-2>*.deb && \
       rm -f <sensor-pkg-1>*.deb <sensor-pkg-2>*.deb

   RUN pip install /opt/bluerock/python-dist/*.whl && \
       python -m bluerock --install

   EXPOSE 9999

   CMD ["uv", "run", ".", "--host", "0.0.0.0"]
   ```
2. Build the Container Image

   Navigate to the directory containing your application files and build the Docker image:

   ```shellscript
   $ docker build -t helloworld-a2a-server:latest .
   ```

   \
   Expected Output:

   ```shellscript
   [+] Building 8.4s (10/10) FINISHED
    => [internal] load build definition from Dockerfile
    => => transferring dockerfile: 341B
    => [internal] load .dockerignore
    => [1/5] FROM docker.io/library/python:3.13-slim
    => [2/5] WORKDIR /app
    => [3/5] COPY . /app
    => [4/5] RUN pip install --no-cache-dir /tmp/bluerock-0.0.1-py3-none-any.whl uv
    => [5/5] RUN python -m bluerock --install
    => exporting to image
    => => naming to docker.io/library/helloworld-a2a-server:latest
   ```
3. Run the Container Image.

   ```shellscript
   $ docker run -d \
     --name helloworld-a2a-server \
     -p 9999:9999 \
     -v /run/bluerock:/run/bluerock \
     helloworld-a2a-server:latest
   ```

   \
   Expected output:

   ```shellscript
   Using CPython 3.12.13 interpreter at: /usr/local/bin/python3
   Creating virtual environment at: .venv
      Building helloworld @ file:///app
   Downloading pygments (1.2MiB)
   Downloading pydantic-core (2.0MiB)
   Downloading cryptography (4.5MiB)
    Downloaded pydantic-core
    Downloaded cryptography
    Downloaded pygments
         Built helloworld @ file:///app
   Installed 42 packages in 99ms
   INFO:     Started server process [50]
   INFO:     Waiting for application startup.
   INFO:     Application startup complete.
   INFO:     Uvicorn running on http://0.0.0.0:9999 (Press CTRL+C to quit)
   ```
4. Run the Test Client In a separate host terminal session, execute the test client to communicate with the containerized agent:

   ```shellscript
   $ uv run python test_client.py
   ```

   \
   **Expected Output:**<br>

   ```shellscript
   Starting an internactive session with A2A Server [http://127.0.0.1:9999]
   Use `exit` to quit.
   user > What is a cat?
   Initializes the A2ACardResolver instance with an HTTP client

   Successfully fetched the public agent card:
   ...

   Response:
   task {
     id: "78a383c3-1934-4859-bb46-b79692bc2c59"
     status {
       state: TASK_STATE_COMPLETED
     }
     artifacts {
       parts {
         text: "Hello, World! I have received your request (What is a cat?)"
         media_type: "text/plain"
       }
     }
     history {
       role: ROLE_USER
       parts {
         text: "What is a cat?"
       }
     }
   }
   ```

## **Example OTEL Event**

Below is an example of the OpenTelemetry event captured by the BlueRock sensor daemon during an A2A task invocation and exported to CloudWatch:

```json
{
  "resource": {
    "service.name": "bluerock"
  },
  "scope": {
    "name": "bluerockd"
  },
  "attributes": {
    "domain": "gyro",
    "origin": "bluepython",
    "event_name": "python_a2a_event",
    "component_id": "default/<component_uuid>",
    "hostid": "ip-<host_ip>.compute.internal",
    "sensor_id": 7222,
    "type": "event"
  },
  "body": {
    "event": "client_recv_response",
    "card": "Hello World Agent",
    "server": "http://<server_host>:9999",
    "result": {
      "task": {
        "id": "<task_uuid>",
        "contextId": "<context_uuid>",
        "status": {
          "state": "TASK_STATE_COMPLETED",
          "timestamp": "2026-08-07T14:14:06.991877Z",
          "message": {
            "role": "ROLE_AGENT",
            "parts": [
              {
                "text": "Request is completed!"
              }
            ]
          }
        },
        "history": [
          {
            "role": "ROLE_USER",
            "parts": [
              {
                "text": "<user_prompt>"
              }
            ]
          },
          {
            "role": "ROLE_AGENT",
            "parts": [
              {
                "text": "Processing request..."
              }
            ]
          }
        ],
        "artifacts": [
          {
            "artifactId": "<artifact_uuid>",
            "parts": [
              {
                "mediaType": "text/plain",
                "text": "<agent_response>"
              }
            ]
          }
        ]
      }
    }
  },
  "severity_number": 9,
  "severity_text": "INFO"
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.bluerock.io/agent-frameworks-integration/agent-to-agent-a2a.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.