Tabstack for the OpenAI Agents SDK

@tabstack/openai-agents gives your OpenAI Agents SDK agents reliable web access: schema-enforced extraction, multi-source research, AI transformation, and browser automation, all as native Agents SDK tools backed by the official @tabstack/sdk.

Install

npm

npm install @tabstack/openai-agents @openai/agents zod

pnpm

pnpm add @tabstack/openai-agents @openai/agents zod

yarn

yarn add @tabstack/openai-agents @openai/agents zod

@openai/agents (v0.13 or later) and zod are peer dependencies.

Zod 4 is required: the Agents SDK depends on it, and the adapter uses Zod 4’s native z.toJSONSchema to advertise each tool’s parameters.

The agent loop calls OpenAI, so OPENAI_API_KEY must be set alongside your Tabstack key.

Create and Setup Your API Key

Before you can start using Tabstack API, you’ll need to create an API key and set it up in your environment.

1. Create Your API Key

1. Visit the Tabstack Console
2. Sign in to your account (or create one if you haven’t already)
3. Navigate to the API Keys section and click the “Manage API Keys”
4. Once you are on the API Keys page, Click “Create New API Key”
5. Give your key a descriptive name (e.g., “Development”, “Production”) and click the “Create API Key”
6. Copy the generated API key and store it securely

Your API key will only be shown once. Make sure to copy and store it in a secure location.

2. Set Up Environment Variable

For security and convenience, we recommend storing your API key as an environment variable rather than hardcoding it in your scripts.

macOS/Linux

# Add to your shell profile (~/.bashrc, ~/.zshrc, or ~/.bash_profile)
export TABSTACK_API_KEY="your_api_key_here"

# Or set it temporarily for the current session
export TABSTACK_API_KEY="your_api_key_here"

# Reload your shell or run:
source ~/.bashrc  # or ~/.zshrc

Windows (Command Prompt)

# Set temporarily for current session
set TABSTACK_API_KEY=your_api_key_here

# Set permanently (requires restart)
setx TABSTACK_API_KEY "your_api_key_here"

Windows (PowerShell)

# Set temporarily for current session
$env:TABSTACK_API_KEY = "your_api_key_here"

# Set permanently for current user
[Environment]::SetEnvironmentVariable("TABSTACK_API_KEY", "your_api_key_here", "User")

3. Verify Your Setup

Test that your environment variable is set correctly:

macOS/Linux/Windows (Git Bash):

echo $TABSTACK_API_KEY

Windows (Command Prompt):

echo %TABSTACK_API_KEY%

Windows (PowerShell):

echo $env:TABSTACK_API_KEY

You should see your API key printed in the terminal.

Quickstart

import { Agent, run } from "@openai/agents";
import { tabstackTools } from "@tabstack/openai-agents";

const agent = new Agent({
  name: "Research assistant",
  instructions:
    "You are a research assistant with web intelligence tools. Use research_question for open " +
    "questions that need multiple sources, extract_page_content to read a specific URL as " +
    "markdown, and the extract tools to pull structured fields from a page. Always cite sources.",
  tools: tabstackTools,
});

const result = await run(agent, "What are Vercel's pricing plans, with sources?");
console.log(result.finalOutput);

tabstackTools is an array of ready-to-use tools that resolves TABSTACK_API_KEY lazily on first call, so importing the package never requires a key to be set.

The tools

Tool	Export	What it does
extract_structured_data	extractStructuredDataTool	Pull specific fields from a URL into a JSON shape you define.
extract_page_content	extractPageContentTool	Fetch a page as clean markdown.
research_question	researchQuestionTool	Synthesize a cited answer across multiple pages.
generate_structured_data	generateStructuredDataTool	Fetch a page, then AI-transform it into derived or reshaped JSON.
automate_browser_task	automateBrowserTaskTool	Run a multi-step, natural-language browser task.

Import individual tools for a subset, or use the tabstackTools array for all of them:

import { Agent } from "@openai/agents";
import { extractPageContentTool, researchQuestionTool } from "@tabstack/openai-agents";

const agent = new Agent({
  name: "Research assistant",
  instructions: "Summarize pages and research questions.",
  tools: [researchQuestionTool, extractPageContentTool],
});

Tool inputs

The model fills these in, but it helps to know the shapes:

• extract_structured_data: url, json_schema_json (a JSON-encoded JSON Schema string).
• extract_page_content: url.
• research_question: query.
• generate_structured_data: url, instructions, json_schema_json.
• automate_browser_task: task, plus optional url, guardrails, data, country, max_iterations, max_validation_attempts.

See Schema design for writing json_schema_json that extracts reliably.

Optional inputs

The model can pass these for finer control; they are sent to Tabstack only when present.

• extract_structured_data, extract_page_content, generate_structured_data:
  • effort: "min", "standard", or "max". Use "max" for JS-heavy pages. See Effort levels.
  • nocache: bypass the cache.
  • country: ISO 3166-1 alpha-2 code for geotargeting.
• research_question: mode ("fast" or "balanced"), nocache.
• automate_browser_task: guardrails (constraints on what the agent may do), data (context for form filling), country, max_iterations, max_validation_attempts.

Strict mode and schemas

The Agents SDK forces strict JSON Schema mode whenever a tool’s parameters is a Zod schema, and passing strict: false alongside a Zod schema throws. Strict mode cannot represent two constructs these tools rely on:

• optional fields (strict mode requires every property to appear in required), and
• automate_browser_task’s open data object, which needs a schema-valued additionalProperties that strict mode forbids.

So the adapter converts each schema to a JSON Schema and registers the tools with strict: false. The model still sees full field descriptions, and every call is validated inside execute before the request runs, so malformed model output fails fast with a clear error.

Configuration

For a custom API key or base URL, or to reuse one client, build the tools explicitly:

import { createTabstackOpenAIAgentsTools } from "@tabstack/openai-agents";

const tools = createTabstackOpenAIAgentsTools({ apiKey: process.env.MY_KEY });
// or pass an SDK client you already have: createTabstackOpenAIAgentsTools({ client })

Error handling

When a tool call fails it throws TabstackToolError (a normalized message plus an HTTP status for API errors). The Agents SDK catches tool errors and surfaces them to the model as a tool result, so a failing call does not abort the run by default.

Related

• Integrations overview
• Tabstack TypeScript SDK
• Schema design
• Claude Agent SDK integration and Vercel AI SDK integration