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.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 — An API key from a model provider such as OpenAI. You do not need a Vidbyte key or balance.
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-sdkSet your model provider key
Your agent calls the model with your own provider key. For OpenAI, set
OPENAI_API_KEYin the terminal you will run the agent from.macOS or Linux
bashexport 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
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-4.1", 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
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. Install the Codex extra first. Each run costs $0.02 of API balance, and model use follows your provider subscription.
Explore code changes locally
python -m pip install "vidbyte-cli[codex]"
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. Each model call it makes goes through Vidbyte and is billed to your API balance.
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.