Integration Documentation

npm install @agentyield/sdk

import OpenAI from "openai"
import { AgentYield } from "@agentyield/sdk"

const openai = new OpenAI()
const ay = new AgentYield({
  apiKey: process.env.AGENTYIELD_API_KEY,
  agentId: "research-agent",
})

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

// Your code — LLM call
const response = await openai.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Summarize the competitive landscape for Q2" }],
})

// [AgentYield] Track the LLM call — SDK computes cost automatically
run.trackLLMCall({
  model: response.model,
  inputTokens: response.usage.prompt_tokens,
  outputTokens: response.usage.completion_tokens,
  costUsd: ay.computeCost(response.model, response.usage),
  contextWindowUsed: response.usage.prompt_tokens / 128_000,
  purpose: "competitive_summary",
})

// Your code — tool call
const searchResults = await webSearch("AI agent monitoring tools 2026")

// [AgentYield] Track tool usage — no cost for free tools, pass 0
run.trackToolCall({
  tool: "web_search",
  input: { query: "AI agent monitoring tools 2026" },
  costUsd: 0, // web_search cost varies by provider — pass actual cost or 0
  metadata: { resultCount: searchResults.length },
})

await run.end({ status: "success" })

import OpenAI from "openai"
// [AgentYield] Import the SDK
import { AgentYield } from "@agentyield/sdk"

const openai = new OpenAI()
// [AgentYield] Initialize with your API key
const ay = new AgentYield({
  apiKey: process.env.AGENTYIELD_API_KEY,
  agentId: "support-monitor",
})

// [AgentYield] Start a run to track this worker
const run = ay.startRun({ metadata: { env: "production" } })

// [AgentYield] Flush to AgentYield every 5 minutes — run stays open
const flushInterval = setInterval(async () => {
  await run.checkpoint({ label: `window-${new Date().toISOString()}` })
}, 5 * 60 * 1000)

// Your code — process tasks from a queue indefinitely
for await (const ticket of supportTicketQueue) {

  try {

    const response = await openai.chat.completions.create({

      model: "gpt-4o",

      messages: [{ role: "user", content: ticket.body }],

    })

    run.trackLLMCall({

      model: response.model,

      inputTokens: response.usage.prompt_tokens,

      outputTokens: response.usage.completion_tokens,

      costUsd: ay.computeCost(response.model, response.usage),

      contextWindowUsed: response.usage.prompt_tokens / ay.contextWindowSize(response.model),

      purpose: "ticket_response",

    })

    await postReply(ticket.id, response.choices[0].message.content)

  } catch (err) {

    // Log the error but keep the agent running

    console.error(`[agent] Failed to process ticket ${ticket.id}:`, err)

  }

}

// Graceful shutdown — flush remaining events and close the run
process.on("SIGTERM", async () => {
  clearInterval(flushInterval)
  // [AgentYield] End the run on shutdown
  await run.end({ status: "success" })
  process.exit(0)
})

import OpenAI from "openai"
import { AgentYield } from "@agentyield/sdk"

const openai = new OpenAI()
const ay = new AgentYield({
  apiKey: process.env.AGENTYIELD_API_KEY,
  agentId: "task-queue-agent",
})

const run = ay.startRun()

async function processTask(task: Task) {
  try {
    // Your code — LLM call
    const response = await openai.chat.completions.create({
      model: "gpt-4o",
      messages: [{ role: "user", content: task.prompt }],
    })

    // [AgentYield] Track the LLM call — SDK handles cost and context math
    run.trackLLMCall({
      model: response.model,
      inputTokens: response.usage.prompt_tokens,
      outputTokens: response.usage.completion_tokens,
      costUsd: ay.computeCost(response.model, response.usage),
      contextWindowUsed: response.usage.prompt_tokens / ay.contextWindowSize(response.model),
      purpose: "task_processing",
    })

    // Your code — write result to database
    await db.write({ id: task.id, result: response.choices[0].message.content })

    // [AgentYield] Track the tool call — no cost for internal db writes
    run.trackToolCall({
      tool: "db_write",
      input: { id: task.id },
      costUsd: 0,
    })

    // [AgentYield] Flush after each task completes
    await run.checkpoint({ label: `task-${task.id}` })

  } catch (err) {
    console.error(`[agent] Failed to process task ${task.id}:`, err)
  }
}

// Your code — process tasks from a queue indefinitely
for await (const task of taskQueue) {
  await processTask(task)
}

// Graceful shutdown
process.on("SIGTERM", async () => {
  await run.end({ status: "success" })
  process.exit(0)
})

await run.checkpoint({ label: "morning-batch" });
await run.checkpoint({ label: "afternoon-batch" });
await run.checkpoint(); // → "window_3"

/skill install agentyield

AGENTYIELD_API_KEY=ay_live_xxxxxxxxxxxxxxxxxxxx

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

run.trackToolCall({
  tool: "db_query",
  input: {
    table: "users",
    filter: { email: "[email protected]", ssn: "123-45-6789" }
  },
  redact: ["filter.email", "filter.ssn"], // PII removed before hashing
  costUsd: 0, // internal query — no direct API cost
})
// → Hash is computed on { table: "users", filter: {} }
// → Raw values never leave your application