Convex Agents Playground

用途

Playground 是一个用于与 Agent 交互的图形界面。它让你无需编写代码即可浏览线程、发送消息、检查工具调用并调整上下文参数。

何时使用此 Skill

• 在开发过程中测试 Agent
• 手动验证 Agent 行为
• 调试意外响应
• 试验提示词和上下文选项
• 向相关方演示 Agent
• 检查工具调用和结果
• 分析消息结构和元数据

设置 Playground API 端点

创建一个公开 playground API 的 Convex 函数：

// 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],
});

生成 API 密钥

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

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

使用托管 Playground

访问在线 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

在本地运行 Playground

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

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

Playground 功能

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

测试多个 Agent

在 playground 中切换 Agent：

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

管理 API 密钥

生成和撤销密钥：

# 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"}'

核心原则

• 通过 API 密钥保障安全：访问 playground 需要密钥
• 默认只读：除非你发送消息，否则不会修改数据
• 实时更新：立即查看 Agent 响应
• 上下文控制：实时试验上下文设置
• 无需代码：无需编写任何代码即可使用

开发工作流

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

后续步骤

• 参见 debugging 了解日志上下文
• 参见 fundamentals 了解 Agent 设置
• 参见 rate-limiting 了解成本