Agenttel Sdk

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?"

The Problem

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.

Design Philosophy

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:

| Level | Where | What | Example | |-------|-------|------|---------| | Topology | OTel Resource (once per service) | Service identity, ownership, dependencies | team, tier, on-call channel | | Baselines | Span attributes (per operation) | What "normal" looks like | P50/P99 latency, error rate | | Decisions | Span attributes (per operation) | What an agent is allowed to do | retryable, runbook URL, escalation level |

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.

Quick Demo

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.

What AgentTel Provides

Enriched Telemetry (agenttel-core)

Every span is automatically enriched with agent-actionable attributes:

| Category | Attributes | Purpose | |----------|-----------|---------| | Topology | agenttel.topology.team, tier, domain, dependencies | Service identity and dependency graph | | Baselines | agenttel.baseline.latency_p50_ms, error_rate, source | What "normal" looks like for each operation | | Decisions | agenttel.decision.retryable, idempotent, runbook_url, escalation_level | What an agent is allowed to do | | Anomalies | agenttel.anomaly.detected, pattern, score | Real-time deviation detection | | SLOs | agenttel.slo.budget_remaining, burn_rate | Error budget consumption tracking |

Agent Interface Layer (agenttel-agent)

A complete toolkit for AI agent interaction with production systems:

| Component | Description | |-----------|-------------| | MCP Server | JSON-RPC server implementing the Model Context Protocol — exposes telemetry as tools AI agents can call | | Health Aggregation | Real-time service health from span data with operation-level and dependency-level metrics | | Incident Context | Structured incident packages: what's happening, what changed, what's affected, what to do | | Remediation Framework | Registry of executable remediation actions with approval workflows | | Action Tracking | Every agent decision and action recorded as OTel spans for full auditability | | Context Formatters | Prompt-optimized output formats (compact, full, JSON) tuned for LLM context windows |

Frontend Telemetry (agenttel-web)

Browser SDK for agent-ready frontend observability:

| Feature | Description | |---------|-------------| | Auto-Instrumentation | Page loads (Navigation Timing API), SPA navigation, fetch/XMLHttpRequest interception, click/submit interactions, JavaScript errors | | Journey Tracking | Multi-step user funnel tracking with completion rates, abandonment detection, and duration baselines | | Anomaly Detection | Client-side pattern detection — rage clicks, API failure cascades, slow page loads, error loops, funnel drop-offs | | Cross-Stack Correlation | W3C Trace Context injection on all outgoing requests; backend trace ID extraction from responses | | Route Baselines | Per-route configuration of expected page load times, API response times, error rates, and business criticality | | Decision Metadata | Escalation levels, runbook URLs, retry policies, and fallback pages per route |

Instrumentation Agent (agenttel-instrument)

IDE-integrated MCP server for automated instrumentation setup:

| Tool | Description | |------|-------------| | analyze_codebase | Scans Java/Spring Boot source code — detects endpoints, dependencies, and framework | | instrument_backend | Generates backend config — Gradle/Maven dependencies, annotations, agenttel.yml | | instrument_frontend | Generates frontend config — React route detection, criticality inference, SDK initialization | | validate_instrumentation | Validates agenttel.yml completeness against source code | | suggest_improvements | Analyzes config and suggests fixes — missing baselines, uncovered endpoints, stale thresholds | | apply_improvements | Auto-applies low-risk improvements using live health data; flags high-risk items for review |

GenAI Instrumentation (agenttel-genai)

Full observability for AI/ML workloads on the JVM:

| Framework | Approach | Coverage | |-----------|----------|----------| | Spring AI | SpanProcessor enrichment of existing Micrometer spans | Framework tag, cost calculation | | LangChain4j | Decorator-based full instrumentation | Chat, embeddings, RAG retrieval | | Anthropic SDK | Client wrapper | Messages API with token/cost tracking | | OpenAI SDK | Client wrapper | Chat completions with token/cost tracking | | AWS Bedrock | Client wrapper | Converse API with token/cost tracking |

Agent Observability (agenttel-agentic)

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

| Feature | Description | |---------|-------------| | Invocation Lifecycle | Goal, status, step count, max steps for each agent execution | | Reasoning Steps | Thought, action, observation, evaluation, revision tracking | | Tool Calls | Tool name, success/error/timeout status per call | | Task Decomposition | Nested task breakdown with depth and parent tracking | | Orchestration Patterns | Sequential, parallel, evaluator-optimizer, handoff, ReAct, orchestrator-workers | | Cost Aggregation | Automatic LLM cost rollup from GenAI spans to agent sessions | | Guardrails | Block, warn, log, escalate actions with named guardrails | | Human Checkpoints | Approval, feedback, correction gates with wait time tracking | | Loop Detection | Detects stuck reasoning loops (identical tool calls) | | Quality Signals | Goal achievement, human interventions, eval scores | | RAG Pipeline | Retriever and reranker spans with relevance scoring | | Error Classification | Source (LLM/tool/agent/guardrail/timeout/network), retryability |

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

Quick Start

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

| Path | Best For | Effort | |------|----------|--------| | Spring Boot Starter | Spring Boot applications | Add dependency + YAML config | | Go SDK | Go services (net/http, Gin, gRPC) | go get + YAML config | | Node.js SDK | Express / Fastify services | npm install + YAML config | | Python SDK | FastAPI / Python services | pip install + YAML config | | JavaAgent Extension | Any JVM app (no code changes) | JVM flag + YAML config | | Web SDK | Browser/SPA applications | npm install + init call | | Instrument Agent | IDE-assisted setup | Run MCP server in IDE |

Backend: Spring Boot

1. Add Dependencies

Maven:

    
    
        dev.agenttel
        agenttel-spring-boot-starter
        0.3.0-alpha
    

    
    
        dev.agenttel
        agenttel-genai
        0.3.0-alpha
    

    
    
        dev.agenttel
        agenttel-agent
        0.3.0-alpha
    

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")
}

2. Configure Your Service

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

3. Optional: Annotate for IDE Support

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 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.

4. Start the MCP Server (Optional)

// 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.

5. What You Get

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.on_call_channel = "#payments-oncall"
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

Backend: Python (FastAPI)

1. Install

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

2. Configure

# 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

3. Instrument

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.

Backend: Go

1. Install

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

2. Configure

# 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

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [AgentTel](https://github.com/AgentTel)
- **Source:** [AgentTel/agenttel-sdk](https://github.com/AgentTel/agenttel-sdk)
- **License:** Apache-2.0
- **Homepage:** https://agenttel.dev/

Install and usage instructions live in the source repository linked above.