AI SDK

For TypeScript agents built around the Vercel AI SDK, Blackbox uses the AgentIR AI SDK annotation layer:

• GitHub: KrishM123/agentir-ai-sdk 
• Package: @agentir-annotators/ai-sdk

Install

npm install @agentir-annotators/ai-sdk ai

What You Annotate

AI SDK agent loops often express workflow structure through tools, helper functions, and repeated model calls rather than an explicit static graph.

The annotation layer makes those compile-visible by marking:

• tools
• tool-loop agents
• individual LLM call sites inside the loop

Example

import { tool } from "ai";
import {
  defineAgentIRTool,
  defineToolLoopAgent,
  llmCall,
} from "@agentir-annotators/ai-sdk";
 
const summarize = defineAgentIRTool({
  name: "summarize",
  tool: tool({ /* schema */ }),
  body: async function summarizeBody() {
    await llmCall("summarize_pass", { modelId: "claude-opus-4.7" }, async () => {
      // provider call
    });
  },
});
 
export const agent = defineToolLoopAgent({
  name: "ticket_router",
  tools: [summarize],
  maxIterations: 4,
});

How Blackbox Uses It

These wrappers let Blackbox compile a stable workflow contract from a loop that would otherwise be opaque.

That contract is what allows Blackbox to:

• understand which node is being invoked
• associate repeated calls with one workflow run
• reason about routing at the workflow level rather than as standalone calls

What The Annotation PR May Add

If you use the dashboard annotation flow, the PR may:

• add @agentir-annotators/ai-sdk to package.json
• add wrapper imports such as defineAgentIRTool, defineToolLoopAgent, and llmCall
• wrap supported tool or agent definitions
• add compile bootstrap files under .agentir/ and .github/workflows/

Runtime Requirement

Your runtime still needs the Blackbox API key:

export BLACKBOX_API_KEY="bb_live_xxxxxxxxxxxxxxxx"

Blackbox expects that key on compile requests as the api-key header and on runtime chat-completion requests as Authorization: Bearer ....

Next Step

After annotation is in place, continue to Getting Started and route your node calls through Blackbox.