@bulwark/llamaindex

Bulwark integration for LlamaIndex.TS — authenticated tools and credential-aware agents.

Installation

npm install @bulwark/llamaindex

Quick Start

import { Anthropic } from "@llamaindex/anthropic";
import { ReActAgent } from "llamaindex";
import { BulwarkToolbox } from "@bulwark/llamaindex";

const toolbox = new BulwarkToolbox({
  tenantId: process.env.BULWARK_TENANT_ID!,
  agentId: process.env.BULWARK_AGENT_ID!,
  agentApiKey: process.env.BULWARK_AGENT_KEY!,
  userId: "usr_01j...",
});

await toolbox.init();

const tools = await toolbox.getTools();

const agent = new ReActAgent({
  llm: new Anthropic({ model: "claude-opus-4-6" }),
  tools,
});

const response = await agent.chat({
  message: "Search GitHub for authentication libraries",
});

console.log(response.message.content);

await toolbox.close();

BulwarkToolbox

class BulwarkToolbox {
  constructor(options: BulwarkToolboxOptions);

  // Initialize — creates a Bulwark agent session
  init(): Promise<void>;

  // Get LlamaIndex-compatible tools with credential injection
  getTools(): Promise<FunctionTool[]>;

  // Create a proxied fetch function
  createProxyFetch(credentialId: string): ProxyFetch;

  // Close — completes the Bulwark session
  close(): Promise<void>;
}

Custom Tool with Proxy

import { FunctionTool } from "llamaindex";

const githubTool = FunctionTool.from(
  async ({ query }: { query: string }) => {
    const proxyFetch = toolbox.createProxyFetch("cred_github");
    const res = await proxyFetch(
      `https://api.github.com/search/repositories?q=${encodeURIComponent(query)}`
    );
    const data = await res.json();
    return data.items
      .slice(0, 5)
      .map((r: { full_name: string }) => r.full_name)
      .join("\n");
  },
  {
    name: "github_search",
    description: "Search GitHub repositories",
    parameters: {
      type: "object",
      properties: {
        query: { type: "string", description: "Search query" },
      },
      required: ["query"],
    },
  }
);

Agent with CIBA

import { BulwarkToolbox, withCIBAApproval } from "@bulwark/llamaindex";

const paymentTool = withCIBAApproval(
  FunctionTool.from(executePay, payMetadata),
  {
    toolbox,
    userId: "usr_01j...",
    scope: "approve:payment",
    buildMessage: (args) => `Approve payment of $${args.amount}?`,
  }
);

QueryEngine with Credential Injection

import { BulwarkRetriever } from "@bulwark/llamaindex";

const retriever = new BulwarkRetriever({
  toolbox,
  credentialId: "cred_notion",
  source: "notion",
  workspaceId: "ws_123",
});

const queryEngine = RetrieverQueryEngine.fromArgs({ retriever });
const response = await queryEngine.query({ query: "Find our auth docs" });