Blackbox

Blackbox is a routing layer for agent workflows.

You keep your application logic and your model choices. Blackbox sits in front of your providers, understands the structure of your workflow, and decides which provider should serve each LLM call based on latency, cost, health, and quota pressure.

What You Bring

You already have an agent or workflow that makes LLM calls.

Blackbox works best when:

the workflow shape is stable enough to annotate or compile
more than one provider can serve the same model family
you want one place to control routing policy instead of hand-coding provider selection in your app

What Blackbox Gives You

a per-workflow API key for routing requests
provider selection without changing your core workflow logic
workflow-aware scheduling instead of per-request round robin
a GitHub annotation flow that can open a PR against your repo
a managed compile path so contract updates can stay in source control

Two Adoption Paths

1. Let Blackbox annotate your repo

This is the fastest path.

From the Blackbox dashboard, start annotation for a registered workflow, connect your GitHub repository, and let Blackbox open a PR that adds the annotation library, compile bootstrap files, and deterministic code changes.

Read Annotation.

2. Add annotations yourself

If you want full manual control, add the annotation library directly:

LangGraph for Python LangGraph workflows
AI SDK for Vercel AI SDK and related TypeScript agent loops
Agent Skills if you want Codex or Claude Code to drive the onboarding work inside your repository

Core Runtime Contract

Blackbox uses a workflow API key, not one global tenant secret.

You register a workflow in the dashboard, copy its minted key, and expose it to your runtime together with the Blackbox base URL:


export BLACKBOX_API_KEY="bb_live_xxxxxxxxxxxxxxxx"
export BLACKBOX_URL="https://allocator.agentir.dev"

BLACKBOX_API_KEY is the per-workflow credential. BLACKBOX_URL is the base URL your compile requests and runtime chat-completion requests target.

Request Shape

At runtime, one workflow run should reuse the same rid across all of its node invocations.

Header	Meaning
`Authorization: Bearer ...`	Your workflow’s Blackbox API key on the OpenAI-compatible runtime endpoint.
`rid`	A run id shared across all node calls in one workflow execution.
`node-name`	The annotated or compiled node id for the current LLM call.

What You Do Not Need To Handwrite

You do not need to hand-author the workflow contract JSON if you adopt one of the Blackbox annotation libraries or use the annotation PR flow. The annotation layer produces the compile-visible workflow structure for you.

Next Step

Start with Getting Started for the end-to-end user flow, then choose either Annotation, Agent Skills, LangGraph, or AI SDK.