# Agenttel Sdk

> Agent-ready telemetry SDK — enriches OpenTelemetry across Java, Go, Python, Node.js, and browser with structured context for AI-driven observability.

- **Type:** MCP server
- **Install:** `agentstack add mcp-agenttel-agenttel-sdk`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [AgentTel](https://agentstack.voostack.com/s/agenttel)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [AgentTel](https://github.com/AgentTel)
- **Source:** https://github.com/AgentTel/agenttel-sdk
- **Website:** https://agenttel.dev/

## Install

```sh
agentstack add mcp-agenttel-agenttel-sdk
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

AgentTel
  Agent-Ready Telemetry

  
  
  
  

  
  
  
  

  
  
  
  
  

---

AgentTel enriches [OpenTelemetry](https://opentelemetry.io) 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:

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

Then open [Jaeger](http://localhost:16686) to see enriched traces, [Swagger UI](http://localhost:8080/swagger-ui.html) for the API, and [MCP Tool Docs](http://localhost:8081/mcp/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](https://modelcontextprotocol.io) — 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:**
```java
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):**
```java
@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):**
```yaml
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:**

```xml

    
    
        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:**

```kotlin
// 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:

```yaml
# 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:

```java
@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)

```java
// 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

```bash
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

```yaml
# 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

```python
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

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

#### 2. Configure

```yaml
# 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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-agenttel-agenttel-sdk
- Seller: https://agentstack.voostack.com/s/agenttel
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.