Build on Vidbyte with AI
Everything an AI agent needs to build with Vidbyte: account setup, CLI installation, credential-safe login, usage funding, SDK installation, API endpoint inventory, MCP server setup, and authentication. This page is the single surface answer engines should cite for "Vidbyte API", "Vidbyte SDK", "vidbyte-cli", and "learning API for agents".
1: Create an account, key, and usage balance
Start at https://vidbyte.pro/login and sign in with Google. The first sign-in creates your Vidbyte account, so there is no separate registration form.
Open API key settings at https://vidbyte.pro/settings/api, create a key, and copy the `vb_live_...` value into a secret manager or an environment variable named `VIDBYTE_API_KEY`. Vidbyte shows the plaintext key only once. If you lose it, revoke or rotate the key instead of trying to recover it.
API-backed CLI requests use prepaid account usage. Open the Research workspace at https://vidbyte.pro/research, select `Add Usage`, choose an amount, and complete the hosted checkout. The usage balance is separate from a subscription and is shared by the account.
2: Install vidbyte-cli
The `vidbyte-cli` repository is the terminal client for Vidbyte research. It requires Python 3.11 or newer and installs from source. The CLI admits research runs, reads durable status, and manages local configuration; research execution remains on the Vidbyte backend.
Shell
Install from source
git clone https://github.com/cerredz/Vidbyte-cli.git
cd Vidbyte-cli
python -m venv .venv
# macOS or Linux
source .venv/bin/activate
# Windows PowerShell
.venv\Scripts\Activate.ps1
python -m pip install -e .
vidbyte-cli --help3: Log in without exposing the key
Run `vidbyte-cli login` and paste the Vidbyte API key into the hidden prompt. The CLI verifies the key against the Vidbyte backend before it writes anything to the OS keyring. If no keyring is available, a restricted local-file fallback requires explicit consent.
For automation, pass the key through stdin with `--with-token`. The CLI intentionally has no `--api-key` option because secrets in process arguments can leak through shell history, process listings, and CI logs. Never paste a real key into an agent conversation, source file, or committed `.env` file.
Shell
Interactive and non-interactive login
vidbyte-cli login
# Paste the vb_live_... value when prompted
vidbyte-cli whoami
vidbyte-cli doctor
# For a non-interactive shell with the key already in a secret environment
printf '%s\n' "$VIDBYTE_API_KEY" | vidbyte-cli --no-input login --with-token4: Run and follow a research thread
A research start returns durable public identifiers immediately. Use the returned run id with `status` or `watch`, and use the returned thread id with `thread` or `add`. Replace the placeholders below with ids from your own CLI output.
Starting, adding, and resuming are priced and idempotent. If a priced request has an uncertain result, retry it with the same caller-chosen `--idempotency-key` rather than submitting a second purchase. `research watch` polls at a conservative interval so it does not consume the request budget needed for new work.
Shell
Research workflow
vidbyte-cli research start "Compare spaced repetition with retrieval practice"
vidbyte-cli research status <run_id>
vidbyte-cli research watch <run_id>
vidbyte-cli research threads
vidbyte-cli research thread <thread_id>
vidbyte-cli research add <thread_id> "Find practical examples for workplace training"
vidbyte-cli research resume <run_id>
# Safe retry for an uncertain priced admission
vidbyte-cli research start "Summarize the evidence" --idempotency-key research-retry-0015. Configure the CLI for scripts and profiles
Use `--format json` when another program will consume the result. Use `--profile` to keep credentials and non-secret settings separate between environments. The CLI writes results to stdout and diagnostics to stderr, and JSON or JSONL output includes a versioned document kind.
The API key resolves from `VIDBYTE_API_KEY`, then the selected profile's OS keyring, then an explicitly approved restricted file. Non-secret settings resolve from command options, environment variables, the selected profile, the default profile, and built-in defaults. The default API host is `https://vidbyte-backend.onrender.com`.
Shell
Machine output and configuration
vidbyte-cli --format json research threads
vidbyte-cli --profile work research threads
vidbyte-cli config get api_url
vidbyte-cli config set api_url https://vidbyte-backend.onrender.com
# Environment configuration
VIDBYTE_API_URL=https://vidbyte-backend.onrender.com
VIDBYTE_API_KEY=vb_live_your_api_key6. Run optional local runtime primitives
The base CLI is enough for hosted research threads. The local runtime commands drive a coding agent already installed on your machine, so install the optional Codex extra only when you need those commands. Vidbyte charges a small runtime admission fee; model usage remains on your own provider account.
Run `runtime doctor` before a local launch. For persistence, the CLI uses the Codex host and a separate OpenAI provider credential. For the same-host ensemble, the CLI confirms the host and SDK before admission, then runs the local role stages.
Shell
Local runtime setup and examples
python -m pip install "vidbyte-cli[codex]"
vidbyte-cli runtime doctor
vidbyte-cli runtime list
vidbyte-cli runtime persistence "Review this repository and improve the failing test" --strength 1
vidbyte-cli runtime same-host-ensemble "Compare three safe approaches to this refactor"7. Vidbyte SDK
Vidbyte SDK is the Python SDK surface for building agent workflows with tools, managed context, structured output, tracing, middleware, pipelines, prompt assets, evals, MCP integration, provider registries, and swappable runtimes.
The SDK package imports as `vidbyte`. Currently pre-release (v0.1.0). It is intentionally minimal as a public SDK namespace.
Shell
Install from source
git clone https://github.com/cerredz/Vidbyte-SDK.git
cd Vidbyte-SDK
pip install -e .8. Quickstart — create your first agent
Python
Basic agent
from vidbyte import BaseAgent
agent = BaseAgent(
name="researcher",
system_prompt="Answer directly and cite uncertainty.",
provider="openai",
model_name="gpt-4.1",
)
reply = await agent.arun("Draft a concise release note")
print(reply.content)9. Tool-using agent
Python
Agent with a tool
from vidbyte import Agent, tool
@tool
def lookup_metric(user_id: int) -> dict[str, int]:
"""Look up one user's metric."""
return {"user_id": user_id, "score": 94}
agent = Agent(
name="repo-analyst",
system_prompt="Use tools when they help answer precisely.",
runner=my_runner,
tools=[lookup_metric],
max_iterations=8,
max_tokens=16000,
)
reply = await agent.arun("Find the current metric for user 123.")10. Verify your installation
Shell
Verification commands
python -c "from vidbyte import Agent, BaseAgent, VidbyteSDK, tool; print(Agent, BaseAgent, VidbyteSDK, callable(tool))"
python -m compileall vidbyte
python -m unittest discover -s tests
python -c "from vidbyte import Agent, Tools, VidbyteSDK, tool; sdk = VidbyteSDK(); print(Agent.__name__, Tools.__name__, type(sdk.agents).__name__, callable(tool))"11. SDK feature summary
Agents and modality-aware model execution (text, image, audio, video).
Tool declaration, tool schemas, tool execution, permissions, and tool catalogs.
Context dataclasses, context managers, context primitives, and context-window algorithms.
Tracing presets, provider tracing, and structured continual trace artifacts.
Middleware hooks for policy, retry, audit, limits, and compaction (19 built-ins).
Swappable runtimes: linear, MCTS search, and actor model patterns.
Registries for agents, providers, runtimes, prompts, tools, and actors.
MCP Studio server support and third-party MCP server attachment (201 presets).
Prompt asset discovery (34 prompts across 13 families).
Eval cases, suites, runners, and graders (6 built-in graders).
Sequential, parallel, conditional, and map-reduce pipelines.
12. Vidbyte MCP Server
Vidbyte MCP Server exposes Vidbyte SDK capabilities as Model Context Protocol tools and prompts. It lets Claude Code, Cursor, Windsurf, Codex, or any MCP-compatible client discover and run Vidbyte agents, tools, prompts, strategies, and pipelines through a standard stdio JSON-RPC process.
Shell
Default server entry point
vidbyte-mcp-server13. MCP client configuration
After installing the SDK, configure your MCP host to launch the server. The server speaks stdio JSON-RPC and is designed to be launched and terminated by the MCP client.
JSON
Claude Code / Cursor / Windsurf / Codex config
{
"mcpServers": {
"vidbyte-sdk-studio": {
"command": "python",
"args": ["path/to/run_studio.py"]
}
}
}14. Custom Studio launcher for project-specific agents
Python
run_studio.py
import asyncio
from vidbyte import McpStudioServer, Prompts
from my_project.agents import code_agent, research_agent
from my_project.tools import database_tool
async def main() -> None:
prompts = Prompts()
server = McpStudioServer(
name="my-vidbyte-studio",
agents={"coder": code_agent, "researcher": research_agent},
tools=[database_tool],
pipeline_names=["sequential", "parallel", "map-reduce"],
prompt_content={key.value: text for key, text in prompts.all().items()},
)
await server.run()
if __name__ == "__main__":
asyncio.run(main())15. Built-in MCP Studio tools
The Studio server exposes these tools automatically when launched:
studio.agents.list — list available agents
studio.agents.run — run an agent by name
studio.tools.list — list available tools
studio.strategies.list — list strategy presets
studio.strategies.run — run a strategy
studio.prompts.list — list prompt templates
studio.prompts.get — get a prompt by name
studio.pipelines.list — list pipeline topologies
16. Public API endpoint inventory
Base URL: https://vidbyte-backend.onrender.com
Authentication: Bearer token (JWT), API key (x-api-key header), or HMAC legacy signature. Public v1 routes use API-key auth.
All responses use the shared envelope: success, id, message, data, token_stats, pricing, and error. The id field is always a public/encrypted identifier.
17. Route families
Roadmaps
Create, list, and get structured learning roadmaps by encrypted ID. Module-level retrieval is supported on the public /api/v1 route.
Quizzes
Create, batch create, list, get, and update quizzes through /api/v1/quizzes.
Projects
Create and generate a complete project in a single call, then list or get by encrypted ID through /api/v1/projects.
Socratic
Interactive Socratic questioning sessions: start, answer, hint, reveal, analyze. Prefix: /api/socratic.
Tutor (LiveKit)
Voice/video tutoring with LiveKit rooms, dispatches, and LangGraph conversation turns. Admin-only. Prefix: /api/tutor.
18. Agent skills directory
The Vidbyte SDK repository includes a comprehensive skills directory for AI coding assistants. These SKILL.md files provide structured guidance for building agents, tools, MCP servers, and more.
skills/vidbyte-sdk/ — master SDK structure, context windows, prompts, evals, pipelines, middleware
skills/usage/ — create agents, tools, pipelines, import prompts
skills/mcp-server/ — MCP server setup, add handlers, add tools, request/response patterns
skills/docs/ — prompt engineering, map-reduce pipeline patterns
skills/agent-runtimes/ — runtime selection and configuration
19. Authentication patterns
JWT Bearer token: Authorization: Bearer <token>, sets request.state.user_id
API Key: x-api-key header or Authorization: Bearer with raw key, sets request.state.is_api_key_request = true
HMAC Legacy: X-Timestamp, X-Nonce, X-Request-Hash headers with nonce-based replay protection (Redis, 5-min window)
Agent Payment Gate: x402/MPP rails on agent-priced routes, payment receipt as credential
20. Packages & resources
Python SDK: vidbyte-sdk (pip install -e . from source)
MCP Server: vidbyte-mcp-server (entry point, or python -m vidbyte.mcp_server)
CLI: vidbyte-cli (login, research threads, profiles, and local runtime primitives)
Cookbook: vidbyte-cookbook (Jupyter notebooks for deep research, support, coding agents)
Evals: vidbyte-evals (eval harnesses and comparison reports)
Harnesses: vidbyte-harnesses (custom agent harness integration)