AgentTel
Agent-Ready Telemetry

AgentTel enriches OpenTelemetry telemetry with the structured context AI agents need to autonomously diagnose, reason about, and resolve production incidents — without human interpretation of dashboards. Works across the full stack: JVM backends (Java, Kotlin, Scala), Go backends, Node.js/TypeScript backends, Python backends (FastAPI, Django, Flask), and browser frontends (TypeScript/JavaScript).

Standard observability answers "What happened?" AgentTel adds "What does an AI agent need to know to act on this?"

Modern observability tools generate massive volumes of telemetry — traces, metrics, logs — optimized for human consumption through dashboards and alert rules. AI agents tasked with autonomous incident response face critical gaps:

• No behavioral context — Spans lack baselines, so agents can't distinguish normal from anomalous
• No topology awareness — Agents don't know which services are critical, who owns them, or what depends on what
• No decision metadata — Is this operation retryable? Is there a fallback? What's the runbook?
• No actionable interface — Agents can read telemetry but can't query live system state or execute remediation

AgentTel closes these gaps at the instrumentation layer.

Core principle: telemetry should carry enough context for AI agents to reason and act autonomously.

AgentTel enriches telemetry at three levels — all configurable via YAML, no code changes required:

Topology is set once on the OTel Resource and automatically associated with all telemetry by the SDK. Baselines and decision metadata are attached per-operation on spans. This avoids redundant data on every span while ensuring agents always have the full context.

Try AgentTel in one command — starts a demo payment service with OTel Collector and Jaeger:

cd examples/spring-boot-example
docker compose -f docker/docker-compose.yml up --build

Then open Jaeger to see enriched traces, Swagger UI for the API, and MCP Tool Docs for the agent interface.

Every span is automatically enriched with agent-actionable attributes:

A complete toolkit for AI agent interaction with production systems:

Browser SDK for agent-ready frontend observability:

IDE-integrated MCP server for automated instrumentation setup:

Full observability for AI/ML workloads on the JVM:

Full lifecycle tracing for AI agents with 70+ semantic attributes:

Three integration styles — programmatic, annotation, or YAML config:

Programmatic:

AgentTracer tracer = AgentTracer.create(openTelemetry)
    .agentName("incident-responder")
    .agentType(AgentType.SINGLE)
    .build();

try (AgentInvocation inv = tracer.invoke("Diagnose high latency")) {
    inv.step(StepType.THOUGHT, "Need to check service metrics");
    try (ToolCallScope tool = inv.toolCall("get_service_health")) {
        tool.success();
    }
    inv.complete(true);
}

@AgentMethod annotation (Spring Boot):

@AgentMethod(name = "incident-responder", type = "single", maxSteps = 100)
public IncidentReport diagnose(String incidentId) {
    // Automatically wrapped in AgentInvocation — no manual tracer calls
    return analyzeAndRespond(incidentId);
}

YAML config (Spring Boot):

agenttel:
  agentic:
    agents:
      incident-responder:
        type: single
        max-steps: 100
        loop-threshold: 5

AgentTel supports multiple integration paths — pick what fits your stack:

Maven:

<dependencies>
    <!-- Core: span enrichment, baselines, anomaly detection, SLO tracking -->
    <dependency>
        <groupId>dev.agenttel</groupId>
        <artifactId>agenttel-spring-boot-starter</artifactId>
        <version>0.3.0-alpha</version>
    </dependency>

    <!-- Optional: GenAI instrumentation -->
    <dependency>
        <groupId>dev.agenttel</groupId>
        <artifactId>agenttel-genai</artifactId>
        <version>0.3.0-alpha</version>
    </dependency>

    <!-- Optional: Agent interface layer (MCP server, incident context, remediation) -->
    <dependency>
        <groupId>dev.agenttel</groupId>
        <artifactId>agenttel-agent</artifactId>
        <version>0.3.0-alpha</version>
    </dependency>
</dependencies>

Gradle:

// build.gradle.kts
dependencies {
    // Core: span enrichment, baselines, anomaly detection, SLO tracking
    implementation("dev.agenttel:agenttel-spring-boot-starter:0.3.0-alpha")

    // Optional: GenAI instrumentation
    implementation("dev.agenttel:agenttel-genai:0.3.0-alpha")

    // Optional: Agent interface layer (MCP server, incident context, remediation)
    implementation("dev.agenttel:agenttel-agent:0.3.0-alpha")
}

All enrichment is driven by YAML configuration -- no code changes needed:

# application.yml
agenttel:
  # Topology: set once on the OTel Resource, associated with all telemetry
  topology:
    team: payments-platform
    tier: critical
    domain: commerce
    on-call-channel: "#payments-oncall"
  dependencies:
    - name: postgres
      type: database
      criticality: required
      timeout-ms: 5000
      circuit-breaker: true
    - name: stripe-api
      type: rest_api
      criticality: required
      fallback: "Return cached pricing"

  # Reusable operational profiles — reduce repetition across operations
  profiles:
    critical-write:
      retryable: false
      escalation-level: page_oncall
      safe-to-restart: false
    read-only:
      retryable: true
      idempotent: true
      escalation-level: notify_team

  # Per-operation baselines and decision metadata
  # Use bracket notation [key] for operation names with special characters
  operations:
    "[POST /api/payments]":
      profile: critical-write
      expected-latency-p50: "45ms"
      expected-latency-p99: "200ms"
      expected-error-rate: 0.001
      retryable: true               # overrides profile default
      idempotent: true
      runbook-url: "https://wiki/runbooks/process-payment"
    "[GET /api/payments/{id}]":
      profile: read-only
      expected-latency-p50: "15ms"
      expected-latency-p99: "80ms"

  baselines:
    rolling-window-size: 1000
    rolling-min-samples: 10
  anomaly-detection:
    z-score-threshold: 3.0

Annotations are optional -- YAML config above is sufficient. Use @AgentOperation when you want IDE autocomplete and compile-time validation. Reference profiles to avoid repeating values:

@AgentOperation(profile = "critical-write")
@PostMapping("/api/payments")
public ResponseEntity<PaymentResult> processPayment(@RequestBody PaymentRequest req) {
    // Your business logic — spans are enriched automatically
}

When both YAML config and annotations define the same operation, YAML config takes priority. Per-operation values override profile defaults.

// Expose telemetry to AI agents via MCP
McpServer mcp = new AgentTelMcpServerBuilder()
    .port(8081)
    .contextProvider(agentContextProvider)
    .remediationExecutor(remediationExecutor)
    .build();
mcp.start();

AI agents can now call tools like get_service_health, get_incident_context, list_remediation_actions, and execute_remediation over JSON-RPC.

Resource attributes (set once per service, associated with all telemetry):

agenttel.topology.team         = "payments-platform"
agenttel.topology.tier         = "critical"
agenttel.topology.domain       = "commerce"
agenttel.topology.
agenttel.topology.dependencies = [{"name":"postgres","type":"database",...}]

Span attributes (per operation, only on operations with registered metadata):

agenttel.baseline.latency_p50_ms = 45.0
agenttel.baseline.latency_p99_ms = 200.0
agenttel.baseline.error_rate     = 0.001
agenttel.baseline.source         = "static"
agenttel.decision.retryable      = true
agenttel.decision.runbook_url    = "https://wiki/runbooks/process-payment"
agenttel.decision.escalation_level = "page_oncall"
agenttel.anomaly.detected        = false
agenttel.slo.budget_remaining    = 0.85

When an incident occurs, agents get structured context via MCP:

=== INCIDENT inc-a3f2b1c4 ===
SEVERITY: HIGH
SUMMARY: POST /api/payments experiencing elevated error rate (5.2%)

## WHAT IS HAPPENING
Error Rate: 5.2% (baseline: 0.1%)
Latency P50: 312ms (baseline: 45ms)
Patterns: ERROR_RATE_SPIKE

## WHAT CHANGED
Last Deploy: v2.1.0 at 2025-01-15T14:30:00Z

## WHAT IS AFFECTED
Scope: operation_specific
User-Facing: YES
Affected Deps: stripe-api

## SUGGESTED ACTIONS
  - [HIGH] rollback_deployment: Rollback to previous version (NEEDS APPROVAL)
  - [MEDIUM] enable_circuit_breakers: Circuit break stripe-api

pip install agenttel[fastapi]

# Optional extras
pip install agenttel[openai]       # OpenAI instrumentation
pip install agenttel[anthropic]    # Anthropic instrumentation
pip install agenttel[langchain]    # LangChain instrumentation
pip install agenttel[all]          # Everything

# agenttel.yml
agenttel:
  topology:
    service-name: payment-service
    team: payments-platform
    tier: critical
    domain: commerce
    on-call-channel: "#payments-oncall"
  operations:
    "POST /api/payments":
      expected-latency-p50: 45ms
      expected-latency-p99: 200ms
      retryable: true
      runbook-url: "https://wiki/runbooks/process-payment"
  slo:
    availability:
      target: 0.999
      type: availability

from fastapi import FastAPI
from agenttel.fastapi import instrument_fastapi

app = FastAPI()
instrument_fastapi(app)  # One-line integration

All spans are now enriched with topology, baselines, anomaly detection, and SLO tracking — identical attributes to the JVM SDK.

go get go.agenttel.dev/agenttel-go@latest

# agenttel.yml — same format as JVM/Python SDKs
agenttel:
  topology:
    service-name: payment-service
    team: payments-platform
    tier: critical
  operations:
    "POST /api/payments":
      expected-latency-p50: 45ms
      expected-latency-p99: 200ms
      retryable: true

import (
    agenttel "go.agenttel.dev/agenttel-go"
    agmw "go.agenttel.dev/agenttel-go/middleware/http"
)

cfg, _ := agenttel.LoadConfigFile("agenttel.yml")
engine := agenttel.NewEngineBuilder(cfg).Build()

// Wrap your handler with AgentTel middleware
handler := agmw.Middleware(mux,
    agmw.WithBaselineProvider(engine.BaselineProvider()),
    agmw.WithTopology(engine.TopologyRegistry()),
)

Also supports Gin (middleware/gin) and gRPC (middleware/grpc) out of the box. See Go Quickstart for details.

npm install @agenttel/node @opentelemetry/api @opentelemetry/sdk-trace-node

# agenttel.yml — same format as all other SDKs
agenttel:
  topology:
    service-name: payment-service
    team: payments-platform
    tier: critical
  operations:
    "POST /api/payments":
      expected-latency-p50: 45ms
      expected-latency-p99: 200ms
      retryable: true

import { AgentTelEngineBuilder, expressMiddleware, loadConfig } from '@agenttel/node';

const config = loadConfig('agenttel.yml');
const engine = new AgentTelEngineBuilder()
  .withTeam(config.topology?.team ?? 'my-team')
  .withTier(config.topology?.tier ?? 'critical')
  .build();

app.use(expressMiddleware({
  baselineProvider: engine.baselineProvider,
  topology: engine.topologyRegistry,
}));

Also supports Fastify (fastifyPlugin). See Node.js Quickstart for details.

npm install @agenttel/web

import { AgentTelWeb } from '@agenttel/web';

AgentTelWeb.init({
  appName: 'checkout-web',
  appVersion: '1.0.0',
  environment: 'production',
  collectorEndpoint: '/otlp',

  routes: {
    '/checkout/:step': {
      businessCriticality: 'revenue',
      baseline: { pageLoadP50Ms: 800, apiCallP50Ms: 300 },
      decision: { escalationLevel: 'page_oncall', runbookUrl: 'https://wiki/runbooks/checkout' },
    },
  },

  journeys: {
    checkout: {
      steps: ['/products', '/cart', '/checkout/shipping', '/checkout/payment', '/confirmation'],
      baseline: { completionRate: 0.65, avgDurationS: 300 },
    },
  },

  anomalyDetection: {
    rageClickThreshold: 3,
    apiFailureCascadeThreshold: 3,
    errorLoopThreshold: 5,
  },
});

The SDK automatically instruments page loads, SPA navigation, API calls, clicks, and errors — with cross-stack correlation via W3C Trace Context headers.

Run the instrument agent as an MCP server in your IDE (Cursor, VS Code, etc.):

pip install agenttel-instrument
agenttel-instrument --config instrument.yml

Then ask your IDE agent: "Analyze my codebase and generate AgentTel configuration" — it will scan your endpoints, detect dependencies, and generate a complete agenttel.yml.

┌─────────────────────────────────────────────────────────────────────┐
│                         Your Application                            │
│    Backend: application.yml + @AgentOperation                       │
│    Frontend: AgentTelWeb.init(config)                               │
├──────────────────────────┬──────────────────┬───────────────────────┤
│  agenttel-spring-boot-   │  agenttel-       │  agenttel-web         │
│  starter                 │  javaagent-      │  (@agenttel/web)      │
│  Auto-config · BPP · AOP │  extension       │  Browser SDK          │
│  (Spring Boot apps)      │  (any JVM app)   │  (TypeScript/JS)      │
├──────────────┬───────────┴──┬───────────────┴───────────────────────┤
│agenttel-core │agenttel-genai│     agenttel-agent                    │
│              │              │                                       │
│ SpanProcessor│ LangChain4j  │ MCP Server (JSON-RPC)                 │
│ Baselines    │ Spring AI    │ Health Aggregation                    │
│ Anomaly      │ Anthropic SDK│ Incident Context + Reporting          │
│  Detection   │ OpenAI SDK   │ Remediation Framework                 │
│ SLO Tracking │ Bedrock SDK  │ Trend Analysis · SLO Reports          │
│ Pattern      │ Cost Calc    │ Executive Summaries                   │
│  Matching    │              │ Cross-Stack Context                   │
├──────────────┴──────────────┴───────────────────────────────────────┤
│                          agenttel-api                                │
│       @AgentOperation · AgentTelAttributes · Data Models            │
├─────────────────────────────────────────────────────────────────────┤
│                      OpenTelemetry SDK                               │
└─────────────────────────────────────────────────────────────────────┘

  agenttel-go (Go SDK — full feature parity)
  Core · net/http · Gin · gRPC · GenAI · Agent/MCP · Agentic Observability

  agenttel-node (Node.js SDK — full feature parity)
  Core · Express · Fastify · GenAI · Agent/MCP · Agentic Observability

  agenttel-python (Python SDK — full feature parity)
  Core · FastAPI · GenAI · Agent/MCP · Agentic Observability

  agenttel-instrument (IDE MCP Server — Python)
  Codebase analysis · Config generation · Validation · Auto-improvements

Full documentation site: agenttel.dev

Working examples to get you started quickly:

Each example includes a README with step-by-step instructions and curl commands to exercise the instrumentation.