Skip to content
MenuStep 1: Build & Deploy

Step 1: Build and deploy your agent

  1. Clone the template

    git clone https://github.com/vercel-internal-playground/ship26-backends-workshop-template.git my-agent
cd my-agent
    The template is one Vercel project with two parts: the chat UI, which works out of the box, and an empty slot for your backend, which you build. Your backend presses the move and say buttons on the game server, which we host.

    This is the template

    You deploy it to your own Vercel account

    Your
    backend
    here

    Game server

    Hosted by us

    ui/ is the chat you talk to your agent through. It's fully functional, so you don't have to touch it.

    backend/ is empty, apart from a README your coding agent will read. That's your part.

    vercel.json ships both as one app with Vercel Services: /api/* goes to the backend, everything else to the UI.

  2. Build the rest of the friendly agent

    Prompt for your coding agent

    Read `backend/README.md` and build the backend in `backend/`: a friendly agent that spawns my character and walks it around the game. Use Python, FastAPI, AI SDK for Python, and a model through AI Gateway.

    Adjust it to your own taste. For example, swap the Python bits for Rust if you'd like.

    What the backend needs to implement

    1. An agent loop

      On Python, AI SDK for Python gives you the loop and tool calling, and picks up credentials through OIDC, so no API key needed.

      Python
      import ai

# Goes through AI Gateway. On Vercel, the project's OIDC token
# authenticates the call, so there's no API key to set up.
model = ai.get_model("anthropic/claude-haiku-4.5")

class GameAgent(ai.Agent):
    TOOLS = [spawn, move]  # the two tools below

system = ai.system_message("You're a friendly game character.")
messages = [system, *history]

async with GameAgent().run(model, messages) as stream:
    ...  # tool calls until the model is done; stream it to the UI
      HTTP
      # Any other language: it's the OpenAI Chat Completions API.
POST https://ai-gateway.vercel.sh/v1/chat/completions
Authorization: Bearer <your project's OIDC token>

{"model": "anthropic/claude-haiku-4.5", "messages": [...]}

      More in the OpenAI-compatible API docs.

    2. Two tools: spawn and move

      Each one is a single call to the game server.

      HTTP
      # Send these with every call to the game server.
X-Workshop-Password: <workshop password>
Authorization: Bearer <player secret>  # from your first spawn

POST /game/controls/spawn
{"name": "Explorer"}
# No secret: a new character, and the reply carries its "secret".
# With the secret: that character again.

POST /game/controls/move
{"direction": "up", "steps": 3}  # or "down", "left", "right"; steps 1-5, default 1

# Walks one tile per tick, then returns once the walk ends:
{"status": "applied", "result": {"moved": 3, "x": 25, "y": 26, "xp": 10}}
# A wall stops the walk early: "error": "obstacle" ("rejected" if moved is 0)

      More in the Game API reference.

    3. Three routes for the UI

      The UI calls these on your backend.

      HTTP
      # Every request carries the login from the UI as headers:
# X-Game-URL, X-Game-Password, X-Player-Secret + X-Player-Id (once you have one),
# X-Player-Name (when typed at login)

GET /api/agent
→ {"model": "anthropic/claude-haiku-4.5"}  # shown in the chat header

POST /api/agent/connect
# spawn: no secret creates a character with the name, a secret claims it; return:
→ {"player_id": "...", "name": "Explorer", "secret": "...", "game_url": "..."}

POST /api/agent/chat
← {"messages": [...]}  # the whole conversation, from useChat
→ one agent turn, streamed back as server-sent events
      SSE
      # Response headers
Content-Type: text/event-stream
x-vercel-ai-ui-message-stream: v1

data: {"type":"start"}
data: {"type":"tool-input-available","toolCallId":"c1","toolName":"move","input":{"direction":"up"}}
data: {"type":"tool-output-available","toolCallId":"c1","output":{"status":"applied", ...}}
data: {"type":"text-start","id":"t1"}
data: {"type":"text-delta","id":"t1","delta":"Moved up!"}
data: {"type":"text-end","id":"t1"}
data: {"type":"finish"}
data: [DONE]

      More in the AI SDK UI stream protocol. On Python, AI SDK for Python writes this stream for you.

  3. Create the Vercel project

    vercel link

    Pick “create a new project”. It pulls the project's environment variables for you.

  4. Deploy

    vercel deploy --prod

  5. Log in and spawn your character

    Open your deployment URL and log in with the game URL, the workshop password, and a name. Then find yourself on the big screen.