Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.vane.build/llms.txt

Use this file to discover all available pages before exploring further.

​
Installation

npm install @vane.build/openai-agents
Peer dependency: @openai/agents >= 0.0.1.

​
Three-line setup

import { createVaneHooks } from '@vane.build/openai-agents';
import { run } from '@openai/agents';

const hooks = createVaneHooks({
  baseUrl: process.env.COUNSEL_URL!,
  apiKey: process.env.COUNSEL_API_KEY!,
  agentId: 'researcher-1',
});

await run(agent, 'Review this contract.', { hooks });

​
createVaneHooks()

Returns a RunHooks object compatible with the OpenAI Agents SDK run() function.

​
Options

OptionTypeRequiredDescription
baseUrlstringYesBase URL of your Vane instance.
apiKeystringYesCompany-scoped API key.
agentIdstringYesAgent identifier that appears on every record.
companyIdstringNoCompany ID embedded in attestation payloads. If omitted, the API key’s company is used.

​
What gets attested

HookactionTypePayload fields
onToolStart(deferred — tracked internally)—
onToolEnd"tool-call"agent, tool, output, durationMs
onAgentStart"agent-start"agent
onAgentEnd"agent-end"agent, output
onHandoff"agent-handoff"from, to
Tool duration is tracked by pairing onToolStart and onToolEnd using a "agentName::toolName" key. This is sufficient for agents that don’t call the same tool twice concurrently in a single turn.

​
Error handling

Attestation calls are fire-and-forget. Errors are logged to console.error and execution continues.

​
VaneRunHooks type

interface VaneRunHooks {
  onToolStart?: (context: object, agent: { name?: string }, tool: { name?: string }) => Promise<void>;
  onToolEnd?: (context: object, agent: { name?: string }, tool: { name?: string }, result: string) => Promise<void>;
  onAgentStart?: (context: object, agent: { name?: string }) => Promise<void>;
  onAgentEnd?: (context: object, agent: { name?: string }, output: unknown) => Promise<void>;
  onHandoff?: (context: object, agent: { name?: string }, targetAgent: { name?: string }) => Promise<void>;
}
The hook signatures are a structural match for @openai/agents RunHooks. If the SDK changes its hook signatures, TypeScript will surface an error at the run() call site, not inside this package.

​
Full example

import { Agent, run, tool } from '@openai/agents';
import { createVaneHooks } from '@vane.build/openai-agents';
import { z } from 'zod';

const hooks = createVaneHooks({
  baseUrl: process.env.COUNSEL_URL!,
  apiKey: process.env.COUNSEL_API_KEY!,
  agentId: 'contract-reviewer',
  companyId: 'acme',
});

const searchTool = tool({
  name: 'web_search',
  description: 'Search the web',
  parameters: z.object({ query: z.string() }),
  execute: async ({ query }) => `Results for: ${query}`,
});

const agent = new Agent({
  name: 'ContractReviewer',
  instructions: 'You review contracts for compliance issues.',
  tools: [searchTool],
});

const result = await run(agent, 'Find EU AI Act obligations for AI providers.', { hooks });
console.log(result.finalOutput);
Every tool call, agent start, agent end, and handoff in this run will produce a signed record in Vane.

​
Multi-agent handoffs

When agents hand off to each other, Vane records the handoff: 
{
  "actionType": "agent-handoff",
  "payload": {
    "agentId": "contract-reviewer",
    "companyId": "acme",
    "actionType": "agent-handoff",
    "payload": {
      "from": "ContractReviewer",
      "to": "ComplianceChecker"
    }
  }
}
This gives you a complete picture of which agent did what, and which agents handed off to which others, all in the signed attestation chain.