Convex Agents Playground

目的

Playground は、エージェントとやり取りするためのグラフィカルインターフェースです。スレッドの閲覧、メッセージの送信、ツール呼び出しの確認、コードを書かずにコンテキストパラメーターを調整できます。

このスキルを使う場面

• 開発中にエージェントをテストする
• エージェントの動作を手動で検証する
• 予期しない応答をデバッグする
• プロンプトやコンテキストオプションを試す
• 関係者にエージェントをデモする
• ツール呼び出しと結果を確認する
• メッセージの構造とメタデータを分析する

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

複数のエージェントをテストする

Playground でエージェントを切り替えます。

// 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 へのアクセスにはキーが必要です
• デフォルトでは読み取り専用：メッセージを送信しない限り、データは変更されません
• リアルタイム更新：エージェントの応答をすぐに確認できます
• コンテキストの制御：コンテキスト設定をその場で試せます
• コード不要：コードを書かずに使用できます

開発ワークフロー

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

次のステップ

• ログのコンテキストについては、デバッグを参照してください
• エージェントの設定については、基本事項を参照してください
• コストについては、レート制限を参照してください