Introducing the Vidbyte SDK

Vidbyte SDK is a Python package. You install it with pip install vidbyte-sdk and import it as vidbyte. What it gives you is not a hosted product you send prompts to — it is the set of parts an agent is made of, assembled in your own process, on your own machine. The unit of work is an Agent, or a BaseAgent when all you need is model execution without a tool loop. You construct one with a system prompt, a provider, and a model, optionally hand it tools and context, and start it with run() or arun().

The reason that distinction matters is what happens after the first response. A chat completion returns text once and stops. An agent keeps going: it calls a tool, reads what came back, decides whether that was enough, and calls another one — until the task is finished or a limit you set stops it. Writing that cycle yourself is mostly bookkeeping. You end up generating JSON schemas from your function signatures, parsing tool calls out of the response, dispatching them, appending results back into the message history in the shape each provider expects, and counting iterations so a confused model cannot loop forever. The SDK owns all of that.

What it does not own is the interesting part. You decide what the system prompt says, which provider and model run it, which tools exist at all, what context goes into the window, and which policies apply. Nothing executes that you did not attach. A tool the agent cannot see is a tool the agent cannot call, which is the whole basis for reasoning about what one of these things is allowed to do.

The package launched as version 0.1.0 and is still alpha; install the latest release from PyPI. It is MIT licensed, requires Python 3.11 or newer, and the source is public on GitHub. Treat the API as still moving — pin a version if you build something you depend on.

It is also intentionally separate from Vidbyte's private platform services. The public package is reusable local agent infrastructure and nothing else: it does not ship proprietary learning models, backend data access, private scoring logic, or production platform internals. It is not a client for Vidbyte's learning app, though it can route model calls, and JevAgent's Jev calls, through Vidbyte with a Vidbyte API key.

There is a simple test for whether you need any of this. If one prompt and one response finishes the job, you do not. Reach for the SDK the moment the work needs a second step that depends on the first — look something up, then decide what to do about it; read a file, then edit it; write a draft, then check the draft against the brief. At that point you are writing an agent loop whether or not you call it one, and the only question is whether you write the plumbing yourself.

Concretely, people use it to build tool-using agents that inspect files and iterate until a stopping condition; coding agents with workspace-bounded file tools and a test run before they claim success; research flows that split planner, researcher, and synthesizer into separate stages; support agents with grounded tools, policy middleware, and an escalation path; and eval suites that compare agent behavior across prompts, models, and graders rather than across vibes.

It is also for teams who are tired of every prototype inventing its own glue. One way to declare a tool, one way to manage a context window, one way to compose a multi-step flow means the agent one person built is legible to the next person who opens it. That is worth more than it sounds like six months into a project with four half-finished harnesses in it.

And it is worth being clear about the other direction. If what you want is a finished product that runs an agent on your behalf, this is the wrong layer — the SDK is the layer underneath that, for people who want to build the thing rather than buy it.

The mental model is three steps. Create an Agent or BaseAgent. Attach a system prompt and a provider/model, plus whatever else the job needs — tools, a context manager, middleware, trace settings, a runtime. Call run() or arun(). Everything below is optional; an agent with a prompt and a model is a valid agent.

Tools are ordinary Python functions marked with the SDK's decorator. You do not write a schema by hand. The SDK reads the signature, derives the JSON schema, presents it to the model, executes whichever call the model selects, and returns the result into the conversation so the next turn can use it. Because tools are just functions, they are testable on their own, and the boundary of what the agent can reach is a list you can read in one place.

Context is data you choose to supply, not a hidden retrieval step. Context dataclasses and managers hold it; context-window algorithms decide what survives as a run grows long. That means compaction and trajectory checkpoints you can reason about, rather than the window silently truncating from the front and taking the instructions with it.

Policy is opt-in. Middleware hooks let you attach retry behavior, audit logging, tool-error handling, iteration caps, and compaction — deliberately, one at a time. Tracing is the same story: presets and structured continual-trace artifacts, so when a run goes wrong you can read what the agent actually did instead of guessing from the final message.

The same pieces scale up when one agent stops being enough. Pipelines compose agents sequentially, in parallel, conditionally, or map-reduce style. Typed state-machine workflows validate a stage's output before a transition is allowed, with guards, branches, retries, and execution limits — useful when a step must not run on malformed input from the step before it. Durable sessions checkpoint a run so it can be resumed, forked, or rewound. And MCP adapters work both ways: expose your agents to MCP clients, or attach third-party MCP servers so the agent can use external tools.

Rather than describe the SDK in the abstract, here is what you can actually reach for once it is installed. Most projects use three or four of these and ignore the rest — the list is a menu, not a checklist.

• Agents and modality-aware model execution, with provider and model registries
• Tool declaration, generated schemas, execution, permissions, and tool catalogs
• Context dataclasses, managers, primitives, and context-window algorithms
• Middleware for policy, retry, audit, limits, tool-error handling, and compaction
• Sequential, parallel, conditional, and map-reduce pipelines
• Typed state-machine workflows with stage validators, guards, branches, and retries
• Swappable runtimes, including linear, search, and actor patterns
• Tracing presets and structured continual-trace artifacts
• Evals: cases, suites, runners, graders, and a local registry
• Durable sessions with checkpoint, fork, and resume over pluggable stores
• MCP server support, plus attachment of third-party MCP servers as tools
• A vidbyte-sdk CLI with skills list, skills show, and skills install

All of it runs locally in your process, and none of it reaches into Vidbyte's private services. Model calls are the one thing that leaves it: since vidbyte-sdk 0.3.1 they go through Vidbyte's model gateway by default, which needs a Vidbyte API key (VIDBYTE_API_KEY) and relays your own provider key for a 2% fee. Pass model_mode=TextModelMode.DIRECT to call your provider straight with your own key and no Vidbyte account.

Start with the published package: pip install vidbyte-sdk. The package is pre-release, so if you want to track the source, clone the repository and install it editable with pip install -e . instead. Either way you import it as vidbyte. Source and docs live on GitHub: https://github.com/cerredz/Vidbyte-SDK.

The panel below has the exact commands, and each example guide below also has an Install tab with the same commands so you never leave the page empty-handed. If you would rather let your coding agent handle setup, the Copy prompt button hands it the whole install brief — what the SDK is, both install paths, the verification command, and an instruction to stop once it reports the installed version.

Below are five templates for agents people actually want: research reports, coding help, customer support, document Q&A, and content writing. They are starting points to copy, not demos to watch.

Each one opens a guide with a copy-paste prompt for your coding agent, install steps, and a short step-by-step walkthrough of how the agent is assembled with the SDK.