Agent skill
Convex Agents Playground
Sets up a web UI for testing, debugging, and developing agents without code. Use this to manually test agents, browse conversation history, and verify behavior in real-time.
Install this agent skill to your Project
npx add-skill https://github.com/Sstobo/convex-skills/tree/main/convex-agents-playground
SKILL.md
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:
// 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
# 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:
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
# 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
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:
// convex/playground.ts
export const {
isApiKeyValid,
listAgents,
// ...
} = definePlaygroundAPI(components.agent, {
agents: [fastAgent, creativeAgent, analyticalAgent, supportAgent],
});
Manage API Keys
Generate and revoke keys:
# 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
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
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
Sstobo/convex-skills
Convex Agents Streaming
Streams agent responses in real-time to clients without blocking. Use this for responsive UIs, long-running generations, and asynchronous streaming to multiple clients.
Sstobo/convex-skills
Convex Agents Files
Handles file uploads, image attachments, and media processing in agent conversations. Use this when agents analyze images, process documents, or generate files.
Sstobo/convex-skills
convex-actions-general
This skill should be used when working with Convex actions, HTTP endpoints, validators, schemas, environment variables, scheduling, file storage, and TypeScript patterns. It provides comprehensive guidelines for function definitions, API design, database limits, and advanced Convex features.
Sstobo/convex-skills
betterauth-tanstack-convex
Step-by-step guide for setting up Better Auth authentication with Convex and TanStack Start. This skill should be used when configuring authentication in a Convex + TanStack Start project, troubleshooting auth issues, or implementing sign up/sign in/sign out flows. Covers installation, environment variables, SSR authentication, route handlers, and the expectAuth pattern.
Sstobo/convex-skills
Convex Agents Tools
Enables agents to call external functions, APIs, and database operations through tool definitions. Use this when agents need to fetch data, perform actions, or integrate with external services while maintaining clean separation.
Sstobo/convex-skills
convex-queries
This skill should be used when implementing Convex query functions. It provides comprehensive guidelines for defining, registering, calling, and optimizing queries, including pagination, full text search, and indexing patterns.
Didn't find tool you were looking for?