Your first agent in about five minutes
Quickstart
Pick one path and follow its numbered steps. The CLI path runs a hosted research task with no code. The SDK path builds and runs a small Python agent on your computer.
Before you start
Python 3.11 or newer — Check with
python --version. Both packages install from PyPI with pip, and they can share one virtual environment: the released vidbyte-cli (0.3.4) requires vidbyte-sdk 0.4.2 or newer (below 0.5), so installing the CLI next to a current SDK keeps it.A terminal — Terminal on macOS or Linux, or PowerShell on Windows.
For the CLI path — A Vidbyte account. You will create an API key and add balance in the steps below.
For the SDK path — A Vidbyte account with an API key and some API balance, because SDK agents send model calls through Vidbyte by default. An API key from a model provider such as OpenAI is optional; with
model_mode=TextModelMode.DIRECTit is all you need, and no Vidbyte account is required.
Choose your path
Both paths end with a working agent. Choose the CLI if you want results without writing code, or the SDK if you want an agent inside your own Python project.
Install the CLI
Install
vidbyte-clifrom PyPI, then check that the command works.Install and check
bashpython -m pip install vidbyte-cli vidbyte-cli --versionCreate a Vidbyte API key
Open Settings → API → Keys and create a key. Copy it right away: Vidbyte shows the full key only once.
Sign in from your terminal
Run
loginand paste your key when asked. The key is checked with Vidbyte and saved only if it works.whoamishows which account is active.Sign in
bashvidbyte-cli login vidbyte-cli whoamiAdd API balance
Hosted research is paid from your account's API balance. Add usage once on the Usage page in settings or on the pricing page.
Start your first research task
Ask a specific question. The command prints a thread ID for the conversation and a run ID for this piece of work.
Start a research thread
bashvidbyte-cli research start "Compare three approaches to reducing latency in an LLM tool-calling workflow. Summarize tradeoffs and cite sources."Watch it, then ask a follow-up
Follow the run until it finishes, then add a follow-up question to the same thread. Replace the placeholders with the IDs from the previous step.
Watch and follow up
bashvidbyte-cli research watch YOUR_RUN_ID vidbyte-cli research add YOUR_THREAD_ID "Focus the comparison on evaluation cost and failure detection."
Install the SDK
Install
vidbyte-sdkfrom PyPI. A virtual environment keeps it separate from your other projects.Install
bashpython -m pip install vidbyte-sdkCreate a Vidbyte API key and add balance
Agents send model calls through Vidbyte's model gateway by default, so they need a Vidbyte API key. Open Settings → API → Keys and create a key with the default permissions, then copy it right away: Vidbyte shows the full key only once. Add a little API balance on the Usage page; each model call is paid from it.
Set your keys
Set
VIDBYTE_API_KEYin the terminal you will run the agent from. Setting your ownOPENAI_API_KEYtoo is optional: Vidbyte then passes it on to OpenAI, OpenAI bills you for the model, and Vidbyte charges only a 2% fee. Without it, Vidbyte pays OpenAI and bills your balance OpenAI's price plus 2%.macOS or Linux
bashexport VIDBYTE_API_KEY="vb_live_your-key" export OPENAI_API_KEY="your-openai-key" # optional: OpenAI bills you, Vidbyte adds 2%Write your agent
Create a file called
agent.py. The agent gets a name, short instructions, a provider, and a model.agent.py
Python1from 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
bashpython agent.py
Run with only your OpenAI key
Pass model_mode=TextModelMode.DIRECT and the agent calls OpenAI straight with your OPENAI_API_KEY: no Vidbyte account, key, or balance, and no Vidbyte fee. Streaming, providers the gateway does not serve, and custom endpoints also need this mode.
agent.py, provider key only
1from vidbyte import TextModelMode, 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 model_mode=TextModelMode.DIRECT, # straight to OpenAI with OPENAI_API_KEY, no Vidbyte key or fee
9)
10reply = agent.run("Compare backoff with jitter and fixed retries.")
11print(reply.content)Try more agent tasks
Each example below is a complete task you can paste. These are agent tasks run by the SDK or CLI, not direct API requests.
Research a topic, then follow up
Use the CLI when you want Vidbyte-hosted research. It uses your API balance. Pass the returned thread ID to research add to keep going.
Research, then follow up
vidbyte-cli research start "Compare the main approaches to evaluating retrieval-augmented generation systems. Summarize tradeoffs and cite sources."
vidbyte-cli research add YOUR_THREAD_ID "Focus the comparison on evaluation cost and failure detection."Review and improve a local codebase
Runs a planner, read-only specialists, and one final agent through Codex on your computer. It needs the codex command on your PATH, which pip does not install. Each run costs $0.02 of API balance, and model use follows your provider subscription.
Explore code changes locally
vidbyte-cli runtime same-host-ensemble "Review this repository's retry handling for duplicate side effects. Compare safe fixes, implement the strongest option, and run focused tests."Turn a goal into next actions
The suggestion agent returns ranked, concrete next steps with handoff details for each one. In the released CLI (0.3.4) it runs on your own Codex or Claude Code and takes 1 cent per requested suggestion from your API balance, so this five-idea run costs 5 cents.
Generate next-step ideas
vidbyte-cli agents suggest run --goal "Turn our onboarding drop-off problem into five testable product experiments for the next two weeks." --count 5Want a reusable workflow to hand your agent? These community skills pair well with the examples above.