Build agents in Python

Vidbyte SDK

vidbyte-sdk is a free, MIT-licensed Python library (Python 3.11+, pip install vidbyte-sdk, alpha) for building, evaluating, and tracing your own AI agents: agents and tools, middleware such as a per-run US-dollar spending cap and context compaction, evals, multi-agent pipelines, tracing, and a local MCP server. Agent types include Agent, CodingAgent, InfiniteMemoryAgent, CodexHarnessAgent, and JevAgent, and you run them with your own model provider account or a Vidbyte API key.

What you can build with the SDK

The SDK runs on your computer, inside your own Python project. With your own provider key, your agent calls the model directly and that provider bills you. With only a Vidbyte API key, model calls go through Vidbyte and are billed to your Vidbyte API balance at the provider's rate plus 2%.

Agents — Give a model a name, instructions, and a provider, then send it a task with run().
Tools — Let an agent call your own Python functions, search the web, or read files.
Teams of agents — Chain focused agents together so each one handles one part of a larger job.
Spending caps — Stop a run at a US-dollar limit with AgentLoopSettings(max_spend_usd=0.50) (vidbyte-sdk 0.4.0+). The SDK checks spend before each model and tool call, so one step can go slightly past the limit. It works on linear runtimes with models the SDK's price list can price; MCTS search, the actor-model runtimes, and CodexHarnessAgent refuse it with a ConfigurationError.
Guardrails — Add retries and safety checks that apply to every run.
Evaluations — Test an agent against example tasks and score its answers before you ship it.

vidbyte-sdk on GitHub

Source code, installation instructions, and examples for the official Python SDK.

Open the repository

SDK README

Tools, teams of agents, guardrails, and evaluations, with a code sample for each.

Read the README

Install it and run your first agent

Four steps take you from an empty folder to an agent that prints its answer in your terminal.

Install the SDK
Install vidbyte-sdk from PyPI. A virtual environment keeps it separate from your other projects.
Install
bash
python -m pip install vidbyte-sdk
Set your model provider key
Your agent calls the model with your own provider key. For OpenAI, set OPENAI_API_KEY in the terminal you will run the agent from. On Windows PowerShell, use $env:OPENAI_API_KEY = "your-openai-key".
macOS or Linux
bash
export OPENAI_API_KEY="your-openai-key"
Write your agent
Create a file called agent.py. The agent gets a name, short instructions, a provider, and a model.
agent.py
Python
1from vidbyte import VidbyteSDK 2 3agent = VidbyteSDK().agents.base( 4 name="retry-reviewer", 5 system_prompt="Compare engineering options against the stated constraints.", 6 provider="openai", 7 model_name="gpt-5.5", 8) 9reply = agent.run("Compare backoff with jitter and fixed retries.") 10print(reply.content)
Run it
Run the file. The agent sends the task to the model and prints its answer in your terminal.
Run
bash
python agent.py

What do I need to run it?

Python 3.11 or newer and an API key from a model provider. Plain agents don't need a Vidbyte account, API key, or balance. JevAgent does: its Jev calls need a Vidbyte API key with the models:invoke permission and a positive API balance.

What does it cost?

The SDK itself is free and MIT-licensed. Model use is billed by the provider whose key you use. Calls made with a Vidbyte API key are billed to your API balance: model calls at the provider's rate plus 2%, and JevAgent's Jev calls at Jev's rate plus a 10% markup on each run.

Can I cap what an agent run spends in US dollars?

Yes. Set AgentLoopSettings(max_spend_usd=...) in vidbyte-sdk 0.4.0 and later. The runtime checks the run's measured spend between steps and stops once it reaches the cap, so treat it as a threshold, not a maximum bill: a step already under way can finish past it. The linear, Jev, and infinite-memory runtimes enforce it. An agent on any other runtime, or on a model the SDK cannot price, is refused when you create it, before it spends anything.

Does vidbyte-sdk include evals and an MCP server?

Yes. EvalCase, EvalSuite, and EvalRunner test an agent against example tasks and score its answers. The vidbyte-mcp-server command, installed with the SDK, exposes Vidbyte agents, tools, and prompts as MCP tools over stdio, so MCP clients such as Codex and Claude can call them.

View vidbyte-sdk on PyPI

Add a decision layer with JevAgent

JevAgent pairs your agent with Jev, a decision model that makes quick judgment calls during a run: whether a request is clear enough to start, which specialist should take it, and whether the work is really finished. It is in preview, and its capabilities are rolling out one at a time.