---
title: "Instrument Java agents | Grafana Cloud documentation"
description: "Install the Agent Observability Java SDK and capture your first generation from a Java agent."
---

> For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt).

# Instrument Java agents

This guide shows you how to install the Agent Observability Java SDK, instrument an LLM call, and verify that generation data reaches Agent Observability.

## Before you begin

- A Grafana Cloud stack with Agent Observability enabled.
- Java 17 or later.
- Your Agent Observability generation export endpoint URL.
- A Cloud Access Policy Token. Refer to [Collect credentials from Grafana Cloud](/docs/grafana-cloud/observe-and-act/agent-observability/get-started/grafana-cloud/#collect-credentials-from-grafana-cloud) for step-by-step instructions.

## Install the SDK

Add the Agent Observability SDK dependency to your project. For Maven:

xml ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```xml
<dependency>
    <groupId>com.grafana.agento11y</groupId>
    <artifactId>agento11y-core</artifactId>
</dependency>
```

Provider helpers and framework integrations are available as separate artifacts.

## Capture a generation

java ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```java
Agento11yClient client = new Agento11yClient(new Agento11yClientConfig()
    .setGenerationExport(new GenerationExportConfig()
        .setProtocol(GenerationExportProtocol.HTTP)
        .setEndpoint("<AGENTO11Y_ENDPOINT>")
        .setAuth(new AuthConfig()
            .setMode(AuthMode.TENANT)
            .setTenantId("<TENANT_ID>"))));

try {
    client.withGeneration(
        new GenerationStart()
            .setConversationId("conv-1")
            .setModel(new ModelRef()
                .setProvider("openai")
                .setName("gpt-4o")),
        recorder -> {
            recorder.setResult(new GenerationResult()
                .setOutput(List.of(
                    new Message()
                        .setRole(MessageRole.ASSISTANT)
                        .setParts(List.of(MessagePart.text("Hello"))))));
            return null;
        }
    );
} finally {
    client.shutdown();
}
```

Replace *AGENTO11Y\_ENDPOINT* and *TENANT\_ID* with your values.

### Use environment variables instead

If you set `AGENTO11Y_ENDPOINT`, `AGENTO11Y_PROTOCOL`, `AGENTO11Y_AUTH_MODE`, `AGENTO11Y_AUTH_TENANT_ID`, and `AGENTO11Y_AUTH_TOKEN`, the SDK reads them at client construction. Refer to [Configure your SDK](/docs/grafana-cloud/observe-and-act/agent-observability/get-started/grafana-cloud/#configure-your-sdk).

java ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```java
Agento11yClient client = new Agento11yClient();
```

## Use a provider helper

Provider helpers are available for OpenAI, Anthropic, and Gemini. They capture generations automatically from your LLM client calls.

## Use a framework integration

A Google ADK framework integration is available for Java.

## Configure authentication in code

For Grafana Cloud, use basic auth with your Cloud Access Policy Token:

java ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```java
new AuthConfig()
    .setMode(AuthMode.BASIC)
    .setTenantId("<INSTANCE_ID>")
    .setBasicPassword("<API_KEY>")
```

## Set up traces and metrics

The SDK emits OpenTelemetry spans and metrics alongside generation data. To export them, configure OpenTelemetry in your application before creating the client. Without this, traces and metrics are silently lost.

Refer to [Set up traces and metrics](/docs/grafana-cloud/observe-and-act/agent-observability/get-started/grafana-cloud/#set-up-traces-and-metrics) for Grafana Cloud OTLP options and [SDK configuration](/docs/grafana-cloud/observe-and-act/agent-observability/configure/sdk/#opentelemetry-setup) for setup snippets.

## Verify data

Open Agent Observability in Grafana Cloud and navigate to **Conversations**. Your generation should appear within a few seconds. Check your **Traces** and **Metrics** data sources for SDK-emitted spans and metrics.

## Next steps

- [Configure SDK options](/docs/grafana-cloud/observe-and-act/agent-observability/configure/sdk)
- [Instrument with framework integrations](/docs/grafana-cloud/observe-and-act/agent-observability/guides/instrument-agents)