@agentiam/openai

The official AgentIAM adapter for the raw OpenAI SDK.

If you are building an AI agent from scratch using openai directly, this adapter intercepts tool calls generated by the model and enforces your IAM policies before executing the underlying functions.

Installation

npm install @agentiam/core @agentiam/openai

Quickstart

import { OpenAI } from "openai";
import { createAgentIAM, definePolicy } from "@agentiam/core";
import { runGuardedTools, resumeGuardedTool } from "@agentiam/openai";

const openai = new OpenAI();

// 1. Define your tool logic
const tools = {
  delete_database: async () => { /* ... */ }
};

// 2. Define your IAM policy
const policy = definePolicy({
  id: "openai-example",
  name: "OpenAI Example",
  defaultDecision: "deny",
  rules: [
    {
      id: "require-approval-delete",
      decision: "approval_required",
      when: { action: "delete_database" }
    }
  ]
});

const iam = createAgentIAM({ policy });

// 3. Process LLM Responses
const response = await openai.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Delete the database." }],
  tools: [/* your tool definitions */]
});

const message = response.choices[0].message;

if (message.tool_calls) {
  // Pass the raw tool calls through AgentIAM
  const results = await runGuardedTools({
    iam,
    toolCalls: message.tool_calls,
    tools
  });

  for (const result of results) {
    if (result.status === "executed") {
      console.log("Executed successfully!", result.output);
    } else if (result.status === "denied") {
      console.log("Action blocked by policy.");
    } else if (result.status === "pending") {
      console.log(`Approval required. Checkpoint ID: ${result.checkpointId}`);
      
      // ... Prompt user for approval ...
      await iam.checkpoints.approve(result.checkpointId);
      
      // Resume execution
      const output = await resumeGuardedTool({
        iam,
        checkpointId: result.checkpointId,
        tools
      });
      console.log("Executed after approval:", output);
    }
  }
}

Strict Mode

By default, runGuardedTools returns a structured array of results, even for pending checkpoints. If you prefer to throw errors on pending checkpoints, you can enable strict mode:

import { ApprovalRequiredError, ClarificationRequiredError } from "@agentiam/openai";

try {
  await runGuardedTools({
    iam,
    toolCalls: message.tool_calls,
    tools,
    strict: true
  });
} catch (error) {
  if (error instanceof ApprovalRequiredError) {
    console.log("Need approval for checkpoint:", error.checkpointId);
  }
}