@agentyield/sdk

Track AI agent runs and automatically detect cost waste. AgentYield analyzes your agent's LLM and tool calls to find duplicate work, oversized contexts, model mismatches, and other inefficiencies — giving you a Waste Score and actionable recommendations.

Features

• Short-lived agents — wrap a task in startRun() / end() and get a Waste Score
• Long-running agents — call checkpoint() to flush metrics on a schedule while the run stays open
• PII-safe — tool inputs are SHA-256 hashed locally; raw data never leaves your app
• Test mode — use an ay_test_ key to validate without sending data

Installation

npm install @agentyield/sdk

Quick Start

import { AgentYield } from "@agentyield/sdk";

const ay = new AgentYield({
  apiKey: "ay_live_xxxxxxxxxxxxxxxxxxxx", // from agentyield.co/settings/api-keys
  agentId: "research-agent",
});

const run = ay.startRun({ metadata: { task: "Q2 research" } });

run.trackLLMCall({
  model: "gpt-4o",
  inputTokens: 4200,
  outputTokens: 312,
  costUsd: 0.0468,
  contextWindowUsed: 0.26,
});

run.trackToolCall({
  tool: "web_search",
  input: { query: "AI agent monitoring tools 2026" },
  costUsd: 0.003,
});

await run.end({ status: "success" });
// → Run appears in your AgentYield dashboard with a Waste Score

API Reference

new AgentYield(config)

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | apiKey | string | Yes | Your API key (ay_live_... or ay_test_...) | | agentId | string | Yes | Identifier for this agent | | baseURL | string | No | API endpoint override (default: https://api.agentyield.co) | | timeoutMs | number | No | Per-request timeout in milliseconds (default: 3000). Requests that exceed this are aborted; the SDK warns and continues — it never throws or hangs your agent. |

ay.startRun(options?)

Returns a Run instance.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | runId | string | No | Custom run ID (auto-generated if omitted) | | metadata | object | No | Arbitrary metadata attached to the run |

run.trackLLMCall(data)

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | model | string | Yes | Model name (e.g. "gpt-4o") | | inputTokens | number | Yes | Input token count | | outputTokens | number | Yes | Output token count | | costUsd | number | Yes | Cost in USD | | contextWindowUsed | number | No | Proportion of context window used (0.0–1.0) | | purpose | string | No | Label for this call |

run.trackToolCall(data)

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | tool | string | Yes | Tool name | | input | object | Yes | Tool input (hashed locally, never sent raw) | | costUsd | number | Yes | Cost in USD | | redact | string[] | No | Fields to remove before hashing | | metadata | object | No | Additional metadata |

run.checkpoint(options?)

Flush all buffered events as a named time window, reset the buffer, and keep the run open. Use this for long-running or always-on agents. Returns a Promise<void>.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | label | string | No | Window label (defaults to window_1, window_2, …) |

Example — flush every 5 minutes:

const run = ay.startRun();

setInterval(async () => {
  await run.checkpoint({ label: "5m-window" });
}, 5 * 60 * 1000);

// when the agent shuts down
await run.end({ status: "success" });

run.end(options)

Flush any remaining buffered events and close the run immediately by sending a final checkpoint with final: true. The server marks the run completed on receipt — no waiting on the server-side auto-close timer. Returns a Promise<void>.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | status | "success" \| "error" \| "timeout" | Yes | Final run status |

Networking & Reliability

The SDK is designed to never block or crash your agent on transport problems.

• Bounded timeout — every request uses an AbortController with a 3-second default (timeoutMs). Slow networks can never hang your run loop.
• One retry on transient failures — network errors and HTTP 5xx responses are retried once with ~300ms jittered backoff. HTTP 4xx (auth, validation) is not retried.
• Failures are logged, not thrown — if both attempts fail, the SDK calls console.warn and returns. Your agent keeps running.
• Process-exit safety — if the process is interrupted while a run is still open, a beforeExit / SIGINT / SIGTERM handler fires a final fire-and-forget checkpoint with status: "error" and final: true.

Endpoint contract

| SDK call | HTTP request | Body | |----------|--------------|------| | run.checkpoint({ label }) | POST /v1/runs/{runId}/checkpoint | { agentId, label, events } | | run.end({ status }) | POST /v1/runs/{runId}/checkpoint | { agentId, label: "final", events, final: true, status } |

Checkpoints are idempotent on (runId, label) — retrying the same checkpoint never double-counts events.

AI Recommendations

When a run is ingested via the SDK, AgentYield analyzes it for waste and queues an AI-powered recommendation job in the background. The ingest response returns immediately (~150ms) with recommendationsStatus: "pending" while recommendations are being generated, or "ready" when none are needed.

Recommendations typically appear within ~60 seconds in your AgentYield dashboard — no polling needed for normal use.

Test Mode

Use an ay_test_ prefixed key to validate your integration without sending data:

const ay = new AgentYield({
  apiKey: "ay_test_xxxxxxxxxxxxxxxxxxxx",
  agentId: "my-agent",
});
// Logs: [AgentYield] Test mode — run data not sent

PII Safety

Tool inputs are hashed locally using SHA-256. Only the hash is transmitted — raw inputs never leave your application. Use the redact option to exclude sensitive fields from the hash:

run.trackToolCall({
  tool: "db_query",
  input: { query: "SELECT ...", userId: "u_123" },
  redact: ["userId"],
  costUsd: 0.001,
});

Supported Providers

Pricing and context-window data is built in for: OpenAI, Anthropic, Google, Meta / Llama (via Together AI), Mistral, Groq, DeepSeek, and OpenRouter (prefix the upstream model with openrouter/, e.g. openrouter/openai/gpt-4o).

Using a model not in the table? Pass costUsd and contextWindowUsed yourself — the SDK accepts any model string. openrouter/auto always requires an explicit costUsd because the upstream is selected dynamically.

Get Your API Key

Sign up at agentyield.co and create an API key at Settings → API Keys.

License

MIT