Skip to content
Vonzio docs

Quickstart

This walkthrough builds a tiny but real agent: a “morning briefing” that reads your Gmail and summarizes anything that needs attention. It exercises authentication, profiles, integrations, and playbooks all at once.

If you only want to send one message, the Getting started page is enough.

  1. Mint an API token.

    Settings → API tokens → Create. Name it quickstart, copy the value (starts with rc_…), and stash it in your shell:

    Terminal window
    export VONZIO_TOKEN="rc_…"
    export VONZIO_API="https://app.vonz.io"

  2. Confirm auth works.

    Terminal window
    curl -sS -H "Authorization: Bearer $VONZIO_TOKEN" \
      "$VONZIO_API/v1/profiles" | jq '.[].slug'

    You should see your profile slugs. If you get 401, check the token; if 404, check the base URL — production is app.vonz.io, not vonz.io.

  3. Connect Gmail.

    Dashboard → Settings → Integrations → “Connect Gmail”. The OAuth flow stores an encrypted refresh token in the platform’s vault. The agent will pull a fresh access token on every Gmail tool call.

  4. Scope Gmail to your profile (optional but recommended).

    Same row → “Scope: all agents” → switch to “Specific agents” → check only the profile that should see your inbox. Other profiles won’t see gmail_* tools at all. See Integrations & scope.

  5. Schedule the morning briefing playbook.

    Profiles → your profile → Playbooks → New. Use this prompt:

    Scheduled run (morning briefing, weekday mornings).
    

    Search Gmail for emails from the last 24h that look like they need a
    response or action. Use gmail_search with queries like
    "is:unread newer_than:1d" and "in:inbox -from:me newer_than:1d".
    

    Pick the top 3 by importance. For each, summarize in one sentence and
    include the message id so I can pull it up later.
    

    Deliver the summary via mcp_notify__notify_user with channel="telegram"
    (or the channel you've configured). Skip the call entirely if there's
    nothing worth surfacing — don't send empty digests.

    Schedule: 0 13 * * 1-5 (8am EDT weekdays). notify_on: none — the agent handles delivery itself.

  6. Test it now.

    You can manually fire any playbook via REST:

    Terminal window
    PLAYBOOK_ID="pb_…"  # from the playbooks list
    curl -sS -X POST -H "Authorization: Bearer $VONZIO_TOKEN" \
      "$VONZIO_API/v1/playbooks/$PLAYBOOK_ID/run"

    The agent will run in the background. Watch your configured channel.

What just happened

Section titled “What just happened”
  • The agent ran in a fresh Docker container with a clean filesystem.
  • It got injected MCP servers based on your profile’s config — memory, gmail (because of the integration), notify, vonzio (platform operations).
  • The gmail_* tool calls authenticated against Google using your stored refresh token, scoped server-side.
  • The agent’s final response was delivered through mcp_notify__notify_user to whichever channel you configured.
  • The session expired after completion (playbook sessions are ephemeral) — but you can still find it in your workspaces list if it qualifies (see Workspaces).

Where to go next

Section titled “Where to go next”
  • Add Telegram thread-claim: configure playbook notifications with claim_thread=true so your replies route back to the same agent context. See Telegram integration.
  • Bank data: connect a Teller enrollment for finance-style agents. See Teller integration.
  • Custom tools: write a tool file and add it to your profile. See Tools, skills, subagents.
  • The full API: REST and WebSocket reference.