Purpose

The Playground is a graphical interface for interacting with agents. It lets you browse threads, send messages, inspect tool calls, and adjust context parameters without writing code.

When to Use This Skill

•Testing agents during development
•Manually verifying agent behavior
•Debugging unexpected responses
•Experimenting with prompts and context options
•Demoing agents to stakeholders
•Inspecting tool calls and results
•Analyzing message structure and metadata

Set Up Playground API Endpoint

Create a Convex function that exposes playground APIs:

typescript

// convex/playground.ts
import { definePlaygroundAPI } from "@convex-dev/agent";
import { components } from "./_generated/api";
import { weatherAgent, supportAgent, creativeAgent } from "./agents";

export const {
  isApiKeyValid,
  listAgents,
  listUsers,
  listThreads,
  listMessages,
  createThread,
  generateText,
  fetchPromptContext,
} = definePlaygroundAPI(components.agent, {
  agents: [weatherAgent, supportAgent, creativeAgent],
});

Generate API Key

bash

# Generate API key from CLI
npx convex run --component agent apiKeys:issue '{"name":"my-key"}'

# Output:
# { "id": "abc123def456", "name": "my-key" }

Use Hosted Playground

Access the online playground:

code

1. Visit: https://get-convex.github.io/agent/
2. Enter your Convex deployment URL (from .env.local)
3. Enter your API key
4. Select your playground path (default: "playground")
5. Choose an agent and user to test

Run Playground Locally

bash

# Install and run local playground
npx @convex-dev/agent-playground

# Uses VITE_CONVEX_URL from .env.local
# Open browser to http://localhost:5173

Playground Features

code

1. User Selection
   - Pick a user to view their threads
   - See all conversations for that user

2. Thread Browsing
   - List all threads for selected user
   - View thread metadata (title, summary)
   - Click to open a thread

3. Message History
   - View all messages in thread
   - See message ordering and step order
   - Inspect message metadata
   - View tool call details

4. Send Message
   - Type a message to test agent
   - Configure save options
   - Send and see response in real-time
   - View usage information

5. Context Configuration
   - Adjust recentMessages count
   - Enable/disable text search
   - Enable/disable vector search
   - Set search result limits
   - Test different context options

6. Tool Call Analysis
   - View tool calls and parameters
   - See tool results
   - Inspect tool execution details

Test Multiple Agents

Switch between agents in playground:

typescript

// convex/playground.ts
export const {
  isApiKeyValid,
  listAgents,
  // ...
} = definePlaygroundAPI(components.agent, {
  agents: [fastAgent, creativeAgent, analyticalAgent, supportAgent],
});

Manage API Keys

Generate and revoke keys:

bash

# Generate new key (or reissue existing)
npx convex run --component agent apiKeys:issue '{"name":"dev-key"}'

# Reusing a name revokes and reissues

# Multiple keys for different environments:
npx convex run --component agent apiKeys:issue '{"name":"prod-key"}'
npx convex run --component agent apiKeys:issue '{"name":"staging-key"}'

Key Principles

•Security via API keys: Keys needed to access playground
•Read-only by default: Doesn't modify data unless you send messages
•Real-time updates: See agent responses immediately
•Context control: Experiment with context settings live
•No code needed: Use without writing any code

Development Workflow

code

1. Define agent (convex/agents.ts)
2. Export in playground (convex/playground.ts)
3. Generate API key
4. Open playground
5. Test agent
6. Debug behavior
7. Adjust agent
8. Repeat

Next Steps

•See debugging for logging context
•See fundamentals for agent setup
•See rate-limiting for understanding costs