Send Your First Zookeeper Prompt with Python

This quickstart shows you how to send your first Zookeeper prompt from Python over a WebSocket. You will ask Zookeeper to generate a simple part, wait for the streamed response, and save the generated model as a STEP file.

In Zoo Design Studio, Zookeeper is the conversational CAD agent that helps create, edit, and reason about models. The same agent is available to developers through the Zookeeper WebSocket.

This tutorial uses two WebSocket-backed steps: Zookeeper generates editable KCL, then zoo-kcl executes that project and sends a Modeling WebSocket export command to produce the STEP file.

What you will build

You will run a Python script that sends this prompt to Zookeeper:

When the request completes, the script writes the generated model to zookeeper-output.step.

Prerequisites

Before you start, make sure you have:

• A Zoo account
• Python installed on your computer
• A terminal app, such as Terminal on macOS or Linux, or PowerShell on Windows

Get an API token

We will need an API token in order to use any of Zoo's services.

Keep your token private. Do not share it or commit it to source control.

Set your API token

Set your API token as the ZOO_API_TOKEN environment variable. The script sends it as a bearer token when it opens the WebSocket. Currently this is the way that the Python SDK reads the API token to authenticate.

On macOS or Linux, run:

On Windows PowerShell, run:

Create a Python project

Create a folder for the quickstart and move into it.

On Windows PowerShell, macOS, Linux, run:

Create and activate a virtual environment so the tutorial dependencies stay separate from the rest of your Python installation.

On macOS or Linux, run:

On Windows PowerShell, run:

This guide uses the raw Zookeeper WebSocket instead of the Zoo Python SDK. It does not use the Zoo CLI. The zoo-kcl package provides the KCL execution layer that talks to the Modeling WebSocket and sends the final export command.

Write the script

Create a file named zookeeper_prompt.py and paste in this script:

Send the prompt

Run the script:

The script opens a WebSocket to wss://api.zoo.dev/ws/ml/zookeeper, sends your prompt, and prints streamed response text as it arrives.

When Zookeeper edits the project, the script keeps the latest returned KCL in memory. Zookeeper always returns a project with a top-level main.kcl. When the stream ends, zoo-kcl executes main.kcl from memory, and the Modeling WebSocket exports the scene as STEP. The script writes only zookeeper-output.step.

You should see output similar to:

Open the generated STEP file in Zoo Design Studio or another CAD tool to inspect the model.

WebSocket message shape

The client sends a user message as JSON:

Zookeeper streams JSON messages back over the same socket. The messages you will usually care about are:

• conversation_id, sent when the socket is ready
• delta, streamed assistant text
• tool_output, generated project edits that the script exports to STEP
• error, a typed error response
• end_of_stream, the end of the current prompt response

Write better prompts

Zookeeper works best when your prompt includes the part type, important features, and any dimensions or constraints you already know.

Good first prompts usually include:

• The object you want, such as a bracket, enclosure, gear, fixture, or adapter
• The main features, such as holes, tabs, ribs, slots, bosses, or cutouts
• Approximate dimensions if they matter
• The intended use or manufacturing constraint if it affects the design

For example:

If the result is not what you wanted, make the next prompt more specific and run the script again.

Next steps

Now that you have sent your first prompt, you can:

• Try a different part description in PROMPT.
• Send existing project files in current_files so Zookeeper can edit them.
• Change kcl.FileExportFormat.Step if you want another output format.
• Continue the model in Zoo Design Studio.
• Read the Zookeeper guide for the broader assistant workflow.