SDK Reference

The TypeScript SDK for capturing AI agent actions. Install it, wrap your client, and every action is recorded automatically.

Installation

npm install @agentreceipt/sdk

Set the AGENTRECEIPT_API_KEY environment variable or pass the key directly to createClient.

createClient(options)

Creates an AgentReceipt client instance. This is the entry point for all SDK functionality.

function createClient(options: {
  apiKey: string
  baseUrl?: string  // defaults to https://agentreceipt.io
}): AgentReceiptClient

Name	Type	Required	Description
`apiKey`	string	Yes	Your project API key. Starts with ar_live_ or ar_test_.
`baseUrl`	string	No	Override the API endpoint. Defaults to https://agentreceipt.io.

agent.ts

import { createClient } from '@agentreceipt/sdk'

const ar = createClient({
  apiKey: process.env.AGENTRECEIPT_API_KEY
})

wrapOpenAI(client, options?)

Wraps an OpenAI client. Every chat.completions.create call is intercepted, including streaming and tool calls.

function wrapOpenAI<T>(client: T, options?: {
  sessionName?: string
}): T

Name	Type	Required	Description
`client`	OpenAI	Yes	An OpenAI client instance.
`options.sessionName`	string	No	Human-readable session label. Shows up in the dashboard, e.g. "Process invoice #441".

Returns the original OpenAI client with all methods intact. Streaming responses are buffered and sent as a single event. Tool calls are captured with their arguments and results.

openai-example.ts

import OpenAI from 'openai'
import { createClient } from '@agentreceipt/sdk'

const ar = createClient({ apiKey: process.env.AGENTRECEIPT_API_KEY })
const openai = ar.wrapOpenAI(new OpenAI(), {
  sessionName: 'Process invoice #441'
})

const response = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Parse this invoice.' }]
})

wrapAnthropic(client, options?)

Wraps an Anthropic client. Covers messages.create and messages.stream. Tool use and structured output are captured.

function wrapAnthropic<T>(client: T, options?: {
  sessionName?: string
}): T

Name	Type	Required	Description
`client`	Anthropic	Yes	An Anthropic client instance.
`options.sessionName`	string	No	Human-readable session label.

anthropic-example.ts

import Anthropic from '@anthropic-ai/sdk'
import { createClient } from '@agentreceipt/sdk'

const ar = createClient({ apiKey: process.env.AGENTRECEIPT_API_KEY })
const anthropic = ar.wrapAnthropic(new Anthropic(), {
  sessionName: 'Classify support ticket'
})

const response = await anthropic.messages.create({
  model: 'claude-sonnet-4-20250514',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Classify this ticket.' }]
})

wrapGemini(client, options?)

Wraps a Google Generative AI client. Covers models.generateContent and models.generateContentStream.

function wrapGemini<T>(client: T, options?: {
  sessionName?: string
}): T

Name	Type	Required	Description
`client`	GoogleGenAI	Yes	A Google Generative AI client instance.
`options.sessionName`	string	No	Human-readable session label.

gemini-example.ts

import { GoogleGenAI } from '@google/genai'
import { createClient } from '@agentreceipt/sdk'

const ar = createClient({ apiKey: process.env.AGENTRECEIPT_API_KEY })
const gemini = ar.wrapGemini(new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY }), {
  sessionName: 'Summarize document'
})

const response = await gemini.models.generateContent({
  model: 'gemini-2.0-flash',
  contents: 'Summarize this document.'
})

wrapMistral(client, options?)

Wraps a Mistral client. Covers chat.complete and chat.stream.

function wrapMistral<T>(client: T, options?: {
  sessionName?: string
}): T

Name	Type	Required	Description
`client`	Mistral	Yes	A Mistral client instance.
`options.sessionName`	string	No	Human-readable session label.

mistral-example.ts

import { Mistral } from '@mistralai/mistralai'
import { createClient } from '@agentreceipt/sdk'

const ar = createClient({ apiKey: process.env.AGENTRECEIPT_API_KEY })
const mistral = ar.wrapMistral(new Mistral({ apiKey: process.env.MISTRAL_API_KEY }), {
  sessionName: 'Extract entities'
})

const response = await mistral.chat.complete({
  model: 'mistral-large-latest',
  messages: [{ role: 'user', content: 'Extract entities from this text.' }]
})

wrapVercelAI(functions, options?)

Wraps Vercel AI SDK functions. Pass in the functions you use and get back wrapped versions that capture every call.

function wrapVercelAI(functions: {
  generateText?: typeof generateText
  streamText?: typeof streamText
  generateObject?: typeof generateObject
  streamObject?: typeof streamObject
}, options?: {
  sessionName?: string
}): typeof functions

Name	Type	Required	Description
`functions`	object	Yes	An object containing the Vercel AI SDK functions you want to wrap.
`options.sessionName`	string	No	Human-readable session label.

vercel-ai-example.ts

import { generateText, generateObject } from 'ai'
import { openai } from '@ai-sdk/openai'
import { createClient } from '@agentreceipt/sdk'

const ar = createClient({ apiKey: process.env.AGENTRECEIPT_API_KEY })
const ai = ar.wrapVercelAI({ generateText, generateObject }, {
  sessionName: 'Generate report'
})

const { text } = await ai.generateText({
  model: openai('gpt-4o'),
  prompt: 'Write a summary of this quarter.'
})

startSession(name?)

Creates a session manually. Use this when you need to track tool calls or decisions that happen outside of an LLM call, or when you want explicit control over session boundaries.

function startSession(name?: string): Session

Name	Type	Required	Description
`name`	string	No	A human-readable name for this session. Shows up in the dashboard, e.g. "Process invoice #441".

The returned Session object has the following methods:

type Session = {
  readonly id: string
  readonly name?: string
  trackTool: (name: string, input: unknown, fn: () => Promise<unknown>) => Promise<unknown>
  trackDecision: (name: string, reasoning: string, outcome: string) => Promise<void>
  end: () => Promise<void>
}

manual-session.ts

import { createClient } from '@agentreceipt/sdk'

const ar = createClient({ apiKey: process.env.AGENTRECEIPT_API_KEY })
const session = ar.startSession('Process invoice #441')

// Track tool calls and decisions within this session
await session.trackTool('look-up-vendor', { name: 'Acme Corp' }, async () => {
  return await db.vendors.findByName('Acme Corp')
})

await session.trackDecision('approve-payment', 'Amount within limit', 'approved')
await session.end()

trackTool(name, input, fn, options?)

Wraps an async function and records it as a tool call event. Captures the name, input, output, and duration. If the function throws, the error is recorded as an event and then re-thrown.

function trackTool<T>(
  name: string,
  input: unknown,
  fn: () => Promise<T>,
  options?: { compliance?: ComplianceMetadata }
): Promise<T>

Name	Type	Required	Description
`name`	string	Yes	A descriptive name for the tool, e.g. "send-email", "query-database".
`input`	unknown	Yes	The input data passed to the tool. Stored as the event input payload.
`fn`	() => Promise<T>	Yes	The async function to execute. Its return value is captured as the event output.
`options.compliance`	ComplianceMetadata	No	Optional compliance tags for this event. See Compliance metadata.

track-tool-example.ts

const vendor = await session.trackTool(
  'look-up-vendor',
  { vendorName: 'Acme Corp' },
  async () => {
    return await db.vendors.findByName('Acme Corp')
  }
)

// vendor is the return value of the wrapped function
console.log(vendor.name) // "Acme Corp"

trackDecision(name, reasoning, outcome, options?)

Records a decision event. Use this when your agent makes a choice that should be visible in the receipt, like approving a payment or selecting a routing path.

function trackDecision(
  name: string,
  reasoning: string,
  outcome: string,
  options?: { compliance?: ComplianceMetadata }
): Promise<void>

Name	Type	Required	Description
`name`	string	Yes	A descriptive name for the decision, e.g. "approve-payment".
`reasoning`	string	Yes	Why the decision was made. This is stored in the event payload.
`outcome`	string	Yes	The result of the decision, e.g. "approved", "rejected", "escalated".
`options.compliance`	ComplianceMetadata	No	Optional compliance tags for this event.

track-decision-example.ts

await session.trackDecision(
  'approve-payment',
  'Invoice amount $4,500 is within the $5,000 auto-approval limit. Vendor is verified.',
  'approved'
)

trackHumanReview(params)

Records a human review event. Use this when a person reviews and approves, rejects, or modifies an agent's proposed action.

function trackHumanReview(params: {
  reviewer: string
  decision: 'approved' | 'rejected' | 'modified'
  notes?: string
  compliance?: ComplianceMetadata
}): Promise<void>

Name	Type	Required	Description
`reviewer`	string	Yes	Who reviewed the action. Could be a name, email, or user ID.
`decision`	'approved' \| 'rejected' \| 'modified'	Yes	The reviewer's decision.
`notes`	string	No	Optional notes from the reviewer.
`compliance`	ComplianceMetadata	No	Optional compliance tags for this event.

track-human-review-example.ts

await session.trackHumanReview({
  reviewer: 'jane@acme.com',
  decision: 'approved',
  notes: 'Vendor verified. Amount looks correct.'
})