Skip to main content
In about five minutes you will publish a template, create an agent and a session from your backend, and talk to the agent from a browser page that shows every message and tool call as it happens. You need one paddock API key and no account at any model provider.
1

Get an API key

Sign in to the console, open API Keys, and create a key. It is shown once; keep it in your backend’s environment:
Every server SDK reads PADDOCK_API_KEY when you do not pass a key. Never ship this key to a browser; the browser gets a session token instead.
2

Install a server SDK

The packages are not published to npm and PyPI yet. Until they are, build them from the sdk/ directory of the paddock repository; see SDKs.
3

Write a template

A template is a versioned YAML document that defines a kind of agent: its harness, its model, and its system prompt. Save this as template.yaml:
template.yaml
claude-opus is a model from paddock’s catalog, so it runs on paddock’s own provider account. See Models for the others.
4

Create an agent and a session

This script publishes the template, creates an agent from it, opens a session, and mints a one-hour session token for the browser.
Creating an agent returns at once; its sandbox is created the first time a session needs it. Run the script and keep the session ID and the token it prints.
5

Show the session in React

Install the React bindings in your frontend:
useSession loads the session’s history, follows its live stream, and folds both into one state object. Messages being generated arrive as streaming entries whose text grows until the finished assistant message replaces them.
Chat.tsx
Render <Chat sessionId="ses_..." token="pdk_st_..." /> with the values the script printed and send a message. The first turn wakes the agent’s new sandbox, so it takes a few seconds longer than the ones after it.

What just happened

  • The template became version 1 of quickstart. Creating the same document again returns the same version; a changed document becomes version 2.
  • The agent owns one sandbox, created on first use. When all its sessions are idle for a while it sleeps, and the next message wakes it with its conversation and files intact.
  • The browser holds only the session token, which works on that one session and nothing else, and expires after the hour you asked for.
  • Your backend can send to the same session at any time with session.send(text), for example when a build fails. Messages from both sides are processed in the order paddock accepted them.
In a real application your backend creates sessions and tokens on demand and returns them from its own endpoint. Continue with Agents and sessions and Streaming to the browser.