Agent Frameworks Integration

The BlueRock runtime provides native telemetry tracing for multiple agent ecosystems, including LangChain, CrewAI, Anthropic, Google Agent Development Kit (ADK), OpenAI, and LiteLLM. By embedding the bluerock sensor directly into the execution space, the BlueRock runtime automatically hooks into internal orchestration and lifecycle engines. The integration requires no architectural changes to the codebase and no manual analytics callbacks.

Important:

The telemetry tracing feature is supported only on the BlueRock Ubuntu or AL2023 Virtual Machine (VM). The system does not support this feature on a generic Ubuntu Linux VM.

Core Architecture

The architecture remains consistent across all BlueRock agent integrations:

1. Agent Execution Space: The environment where the specific agent program runs alongside the bluerock sensor. The environment must operate within a BlueRock Ubuntu or AL2023 VM.

2. Event Collector: The component capturing telemetry from the execution space.

3. bluerockd: The BlueRock Control Plane processing intercepted execution tasks and intents.

4. CloudWatch or External Event Collector: The final destination for aggregated telemetry and logs.

Environment Setup

Prerequisites

• Python version 3.13 or above.

• Package Manager: Install uv for dependency management and execution.

Framework Configuration Reference

Different frameworks require specific primary packages and example scripts. The project name parameter can be any string (for example, search_agent or file_agent); enter the desired project name when substituting the <Enter_Project_Name_Here> placeholder. Reference the table below when substituting the remaining placeholder values in the subsequent setup steps.

Framework	<Package_Name>	Example Scripts
LangChain	langchain	chat_agent.py
CrewAI	crewai	help_agent_crewai.py
Anthropic	anthropic	search_agent.py
Google ADK	google_adk	search_agent_gemini.py
OpenAI	openai	hello_world_oai.py
LiteLLM	litellm	search_agent_litellm.py

Note:

The <Package_Name> represents the primary framework entry point. Additional packages and adapters required by custom implementations (for example: langchain_ollama, mcp, or fastmcp) can be dynamically appended to the dependency installation command.

Install the uv Package Manager

Run the installation script to install the package manager.

$ curl -LsSf https://astral.sh/uv/install.sh | sh

Provision the Isolated Project Environment

Initialize the local project workspace using Python 3.13 (or above) and establish project dependencies using the target framework details from the reference table.

$ uv init --python python3.13 <Enter_Project_Name_Here>
$ cd <Enter_Project_Name_Here>
$ uv venv --python python3.13
$ source .venv/bin/activate
$ uv add <Package_Name> [Additional_Packages...]

Inject and Register BlueRock Sensors

Deploy the custom BlueRock telemetry sensor library directly within the activated workspace context. Activate runtime sensor hooks using the installation flag.

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

Stage the Agent Script

Add the script based on the selected agent framework. If required, use the example scripts from BlueRock.

Agent Execution Block

Important:

• Bind appropriate authorization environment variables to the parent terminal session to initiate runtime actions.

• The Anthropic, LiteLLM, LangChain, and CrewAI scripts use the OPENAI_API_KEY environment variable as a standard label, whereas accept native Large Language Model (LLM) API keys for authentication.

Execution Variable Reference

Reference the table below when substituting placeholder values in the execution commands.

Framework	<API_Key_Variable>
LangChain	OPENAI_API_KEY
CrewAI	OPENAI_API_KEY
Anthropic	OPENAI_API_KEY
Google ADK	GOOGLE_API_KEY
OpenAI	OPENAI_API_KEY
LiteLLM	OPENAI_API_KEY

Local Execution

Set the required environment variable and execute the primary workspace script using the package manager.

$ export <API_Key_Variable>=<api_key>
$ uv run <Example_Script>

Containerized Execution

Run the target agent as a Docker application. Securely mount the BlueRock socket into the container.

$ docker run -d --name <Container_Name> \
  --rm \
  -e <API_Key_Variable>=<api_key> \
  -v /run/bluerock:/run/bluerock \
  <Image_Name>

Note:

<Container_Name> can be any arbitrary name assigned to the container. <Image_Name> must match the exact tag assigned when building or pulling the Docker image. Run docker images in the terminal to list all locally available images and corresponding tags.

Sensor Configuration and Telemetry Events

The sensors are governed by the bru_policy.json configuration file, located in the /opt/bluerock/trex/ directory on a BlueRock instance or VM. The policy defines separate configuration blocks to activate interception hooks for fundamental LLM calls versus higher-level agentic orchestration.

Depending on the active ecosystem, the sensor automatically captures distinct execution and lifecycle events.

LLM Sensors

The llm block controls the tracing of direct interactions with foundational models. Activating specific vendor flags within this block allows the sensor to capture raw generation requests, tokens, and response latencies.

bru_policy.json

"llm": {
    "enable": true,
    "gemini": true,
    "openai": true,
    "anthropic": true,
    "litellm": true
}

Agentic Sensors

The Agentic configuration blocks (such as crewai and langchain) hook into multi-step reasoning, tool execution, memory retrieval, and agent delegation. These are enabled independently of the base LLM sensors.

bru_policy.json

"crewai": {
    "enable": true
},
"langchain": {
    "enable": true
}

Standardized Sample Events by Sensor Type

LLM Sensors

• OpenAI

  {
    "body": {
      "context": { "process": { "pid": "<MASKED_PID>" } },
      "entity_id": "<MASKED_ENTITY_ID>",
      "event": "chat_completion_start",
      "model": "gpt-4o",
      "messages": [
        { "role": "user", "content": "Why is the sky blue?" }
      ],
      "run_id": "<MASKED_RUN_ID>"
    },
    "severity_number": 0,
    "severity_text": "INFO",
    "attributes": {
      "domain": "gyro",
      "event_name": "python_openai_event",
      "origin": "bluepython",
      "sensor_id": 0000
    },
    "scope": { "name": "bluerockd" },
    "resource": { "service.name": "bluerock" }
  }

• Anthropic

  {
    "body": {
      "context": { "process": { "pid": "<MASKED_PID>" } },
      "entity_id": "<MASKED_ENTITY_ID>",
      "event": "message_create_start",
      "model": "claude-3-5-sonnet-20241022",
      "messages": [
        { "role": "user", "content": "Hello, Claude. Why is the sky blue?" }
      ],
      "max_tokens": 1024,
      "run_id": "<MASKED_RUN_ID>"
    },
    "severity_number": 0,
    "severity_text": "INFO",
    "attributes": {
      "domain": "gyro",
      "event_name": "python_anthropic_event",
      "origin": "bluepython",
      "sensor_id": 0000
    },
    "scope": { "name": "bluerockd" },
    "resource": { "service.name": "bluerock" }
  }

• LiteLLM

  {
    "body": {
      "context": { "process": { "pid": "<MASKED_PID>" } },
      "entity_id": "<MASKED_ENTITY_ID>",
      "event": "completion_start",
      "model": "claude-sonnet-4-5-20250929",
      "messages": [
        { "role": "user", "content": "Hello, what is a rainbow?" }
      ],
      "run_id": "<MASKED_RUN_ID>"
    },
    "severity_number": 0,
    "severity_text": "INFO",
    "attributes": {
      "domain": "gyro",
      "event_name": "python_litellm_event",
      "origin": "bluepython",
      "sensor_id": 0000
    },
    "scope": { "name": "bluerockd" },
    "resource": { "service.name": "bluerock" }
  }

Agentic Sensors

• LangChain

  {
    "body": {
      "chain_type": "AgentExecutor",
      "context": { "process": { "pid": "<MASKED_PID>" } },
      "entity_id": "<MASKED_ENTITY_ID>",
      "event": "chain_start",
      "inputs": {
        "question": "What files do I have in the folder?"
      },
      "run_id": "<MASKED_RUN_ID>"
    },
    "severity_number": 0,
    "severity_text": "INFO",
    "attributes": {
      "domain": "gyro",
      "event_name": "python_langchain_event",
      "origin": "bluepython",
      "sensor_id": 0000
    },
    "scope": { "name": "bluerockd" },
    "resource": { "service.name": "bluerock" }
  }

• CrewAI

  {
    "body": {
      "context": { "process": { "pid": "<MASKED_PID>" } },
      "entity_id": "<MASKED_ENTITY_ID>",
      "event": "crew_kickoff_started",
      "crew_name": "AssistantCrew",
      "tasks": ["task_one"],
      "agents": ["Helpful assistant"],
      "run_id": "<MASKED_RUN_ID>"
    },
    "severity_number": 0,
    "severity_text": "INFO",
    "attributes": {
      "domain": "gyro",
      "event_name": "python_crewai_event",
      "origin": "bluepython",
      "sensor_id": 0000
    },
    "scope": { "name": "bluerockd" },
    "resource": { "service.name": "bluerock" }
  }

• Google Gemini

  {
    "body": {
      "context": { "process": { "pid": "<MASKED_PID>" } },
      "entity_id": "<MASKED_ENTITY_ID>",
      "event": "agent_run_start",
      "agent_name": "search_agent",
      "model": "gemini-2.5-flash",
      "query": "why is the sky blue?",
      "run_id": "<MASKED_RUN_ID>"
    },
    "severity_number": 0,
    "severity_text": "INFO",
    "attributes": {
      "domain": "gyro",
      "event_name": "python_google_adk_event",
      "origin": "bluepython",
      "sensor_id": 0000
    },
    "scope": { "name": "bluerockd" },
    "resource": { "service.name": "bluerock" }
  }