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.DIRECT it 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.

  1. Install the CLI

    Install vidbyte-cli from PyPI, then check that the command works.

    Install and check

    bash
    python -m pip install vidbyte-cli vidbyte-cli --version
  2. Create a Vidbyte API key

    Open Settings → API → Keys and create a key. Copy it right away: Vidbyte shows the full key only once.

  3. Sign in from your terminal

    Run login and paste your key when asked. The key is checked with Vidbyte and saved only if it works. whoami shows which account is active.

    Sign in

    bash
    vidbyte-cli login vidbyte-cli whoami
  4. Add 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.

  5. 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

    bash
    vidbyte-cli research start "Compare three approaches to reducing latency in an LLM tool-calling workflow. Summarize tradeoffs and cite sources."
  6. 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

    bash
    vidbyte-cli research watch YOUR_RUN_ID vidbyte-cli research add YOUR_THREAD_ID "Focus the comparison on evaluation cost and failure detection."

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

bash
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

bash
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

bash
vidbyte-cli agents suggest run --goal "Turn our onboarding drop-off problem into five testable product experiments for the next two weeks." --count 5

Want a reusable workflow to hand your agent? These community skills pair well with the examples above.

Next steps