A2EA Docs | Agent Telemetry and Economic Attribution

Overview

What A2EA measures

A2EA measures agent work after it runs. It answers practical questions: how much work ran, how often it succeeded, how fast it completed, and what value that created compared with a baseline.

Task events in

Your backend, worker, or agent runtime sends task execution events with ID, agent, timestamp, duration, type, and outcome.

Performance factors

A2EA calculates speed, accuracy, and after-hours coverage for the submitted work.

Value out

A2EA compares those factors with baselines and estimates dollar value.

Default onboarding: create an account, copy the workspace API key, install the SDK, and send one tracked event. The first 100 accepted events are included on the free test tier.

Quickstart

Send the first tracked event

This path is for production-style server-side telemetry. Keep the workspace API key in your backend or worker environment. Do not embed the key in public browser code.

1. Create workspace

Sign up at signup.html. A2EA provisions the managed workspace, opens the console, and starts the 100-event free test tier.

2. Copy API key

Open API Keys in the console and copy the value used in the X-A2EA-API-Key header.

3. Track one function

Install the SDK, initialize a client with the workspace key, and decorate one agent function.

pip install a2ea-py

export A2EA_API_KEY="a2ea_..."
export A2EA_BASE_URL="https://a2ea-backend-526z2hkxna-uc.a.run.app"

Python SDK

Instrument an agent function

The SDK handles signing, background delivery, retries, and shutdown flushing so application code only needs to wrap the function being measured.

import os
import time
from a2ea import A2EAClient

client = A2EAClient(
    api_key=os.environ["A2EA_API_KEY"],
    base_url=os.getenv("A2EA_BASE_URL", "https://a2ea-backend-526z2hkxna-uc.a.run.app"),
    agent_id="agent_research_worker_01",
)

@client.track_agent(task_type="data_processing")
def run_agent(payload):
    result = process(payload)
    return result

try:
    run_agent({"jobId": "job_001"})
finally:
    client.flush(timeout=5)
    client.close()

SDK constructor

api_keyRequired workspace API key. Store it in backend or worker environment variables.

base_urlOptional API host. Defaults to the production backend unless A2EA_BASE_URL is set.

agent_idOptional stable identifier for the agent, worker, or runtime submitting telemetry.

Reliability behavior

Telemetry submission runs outside the tracked function path.
Transient failures retry with exponential backoff.
Failed events remain available from get_local_fallback_buffer().
Call flush() before process exit for short-lived jobs.

HTTP API

Production endpoints

The public API is versioned under /api/v1. Use the SDK for telemetry when possible; raw HTTP is available for server-side integrations that need it.

GET/health

GET/api/v1/config/public

POST/api/v1/tenant/register

GET/api/v1/workspace/status

POST/api/v1/telemetry/score

GET/api/v1/telemetry/fleet-analytics

GET/api/v1/telemetry/recent

GET/api/v1/telemetry/agent/:id/billing

POST/api/v1/billing/checkout

GET/api/v1/billing/status

Score request

POST https://a2ea-backend-526z2hkxna-uc.a.run.app/api/v1/telemetry/score
Content-Type: application/json
X-A2EA-API-Key: a2ea_...

{
  "profile": "high_volume_data_processing",
  "telemetry": [
    {
      "eventId": "evt_001",
      "agentId": "agent_pipeline_014",
      "timestamp": "2026-09-16T12:00:00Z",
      "durationMs": 12000,
      "taskType": "data_processing",
      "outcome": "success",
      "verification": {
        "keyId": "workspace-api-key",
        "algorithm": "hmac_sha256",
        "signature": "hex_encoded_hmac"
      }
    }
  ]
}

Score response shape

{
  "ok": true,
  "moduleTrace": ["Telemetry extracted", "Performance compared", "Value calculated"],
  "fleetBaseline": {
    "avgDurationMs": 18000,
    "avgVerification": 1,
    "successRate": 0.95,
    "coverageRate": 0.1,
    "totalRecords": 42,
    "coldStartFallback": false
  },
  "performanceFactors": {
    "accuracyFactor": 1,
    "speedFactorAvgDurationMs": 12000,
    "coverageFactor": 0,
    "successfulTasks": 1,
    "totalTasks": 1
  },
  "comparisonMetrics": {
    "speedComparisonMetricUsd": 0,
    "accuracyComparisonMetricUsd": 1.25,
    "coverageComparisonMetricUsd": 0
  },
  "performanceScore": {
    "profile": "high_volume_data_processing",
    "profileLabel": "High-Volume Data Processing",
    "taskType": "data_processing",
    "weightProfile": { "speed": 0.65, "accuracy": 0.2, "coverage": 0.15 },
    "rawComparativeEconomicValueUsd": 0.25,
    "verificationScore": 1,
    "comparativeEconomicValueUsd": 0.25,
    "tamperEvidentHash": "sha256_hex"
  },
  "verificationSummary": {
    "verifiedEvents": 1,
    "algorithm": "hmac_sha256",
    "keyId": "workspace-api-key",
    "verificationScore": 1,
    "verificationMode": "production_verified"
  }
}

Telemetry Schema

Required event fields

Each task event needs enough information to identify the run, measure duration, group it by task type, and record whether it succeeded.

Field	Type	Description
`eventId`	string	Unique event identifier. Allowed characters are ASCII letters, numbers, underscore, hyphen, and dot.
`agentId`	string	Stable identifier for the AI agent, worker, pipeline, or runtime.
`timestamp`	RFC3339 string	UTC timestamp for task execution. Example: `2026-09-16T12:00:00Z`.
`durationMs`	integer	Task duration in milliseconds. Must be between 1 and 86400000.
`taskType`	string	Lowercase task category, such as `data_processing`, `compliance_review`, or `autonomous_operations`.
`outcome`	string	`success` or `failure`.
`verification`	object	HMAC verification envelope with `keyId`, `algorithm`, and `signature`.

Idempotency: use a stable eventId for retries. Duplicate event IDs are ignored at storage time, but clients should still avoid replaying old batches unnecessarily.

Scoring Model

How performance value is calculated

A2EA scores a batch by calculating speed, accuracy, and coverage, comparing them with baselines, then weighting the results for the selected task profile.

Performance factors

accuracyFactor: successful tasks divided by total tasks.
speedFactorAvgDurationMs: average duration for the submitted batch.
coverageFactor: share of tasks outside configured business hours.

Comparison metrics

Speed value: time saved versus baseline multiplied by labor rate.
Accuracy value: avoided failures multiplied by remediation cost.
Coverage value: off-hours gain multiplied by delay cost.

Profile	Expected task type	Speed	Accuracy	Coverage
`accuracy_sensitive_compliance`	`compliance_review`	10%	70%	20%
`high_volume_data_processing`	`data_processing`	65%	20%	15%
`balanced_operations`	`autonomous_operations`	35%	40%	25%

score =
  (speedComparisonMetricUsd * speedWeight) +
  (accuracyComparisonMetricUsd * accuracyWeight) +
  (coverageComparisonMetricUsd * coverageWeight)

comparativeEconomicValueUsd = rawScore * verificationScore

Baselines: A2EA builds task-type baselines from recent workspace telemetry and falls back to defaults for new workspaces.

Dashboard

What each console page shows

Home

Workspace readiness, onboarding state, and high-level attribution status once telemetry starts arriving.

Telemetry

Task-type summaries and recent accepted events for the workspace.

API Keys

Current workspace key, connection status, copy/reveal controls, and rotate/revoke actions.

Billing

Free test quota remaining, checkout status, usage counters, and value summaries.

Security

Authentication and verification

A2EA separates user authentication from telemetry authentication. Dashboard requests use Firebase identity tokens. Telemetry ingestion uses the workspace API key plus signed verification data.

API key header

X-A2EA-API-Key: a2ea_...

Identifies the organization and workspace. Store it as a backend secret.

HMAC signature

event_id={eventId}|agent_id={agentId}|timestamp={timestamp}|duration_ms={durationMs}|task_type={taskType}|outcome={outcome}

The SDK signs this canonical string with HMAC-SHA256 using the workspace API key.

Production guidance: run telemetry submission from trusted backend code, workers, queues, or serverless functions. Browser-only telemetry can expose long-lived keys and should be avoided until scoped browser tokens exist.

Billing

Usage and value reporting

A2EA tracks accepted telemetry usage and includes a free test tier before upgrade is required. Billing dashboards show free quota remaining, usage counters, checkout status, and estimated value from current telemetry.

Free test

New workspaces can accept up to 100 unique telemetry events before upgrade. Duplicate eventId retries do not consume additional free quota.

Usage

Accepted task counts are accumulated as workspace usage.

Economic value

Agent billing views estimate savings from speed and accuracy metrics and subtract an estimated runtime cost.

Upgrade

When the free quota reaches zero, telemetry scoring returns a quota error until upgrade is started from the Billing page.

Troubleshooting

Common integration issues

401 or 403 from telemetry

Check that X-A2EA-API-Key is present, copied from the current workspace, and not truncated.

Signature mismatch

Use the SDK first. For raw HTTP, confirm canonical timestamp normalization and sign exactly the fields shown in the security section.

Dashboard is empty

The workspace exists but no telemetry has been accepted yet. Send one tracked SDK event and refresh Telemetry.

Task type rejected

The selected profile expects a matching task type. For example, high_volume_data_processing expects data_processing.

Connect an agent and measure its value.

What A2EA measures

Task events in

Performance factors

Value out

Send the first tracked event

1. Create workspace

2. Copy API key

3. Track one function

Instrument an agent function

SDK constructor

Reliability behavior

Production endpoints

Score request

Score response shape

Required event fields

How performance value is calculated

Performance factors

Comparison metrics

What each console page shows

Home

Telemetry

API Keys

Billing

Authentication and verification

API key header

HMAC signature

Usage and value reporting

Free test

Usage

Economic value

Upgrade

Common integration issues

401 or 403 from telemetry

Signature mismatch

Dashboard is empty

Task type rejected