feat: split playground API for Node.js-only LLM providers

[Minoo7]

Adds two new functions to allow separation of V8-safe queries/mutations from Node.js-only actions in the playground API:

• definePlaygroundQueries - V8-safe queries and mutations
• definePlaygroundActions - Node.js actions for text generation

Problem

When using LLM providers that require Node.js modules (e.g., Vertex AI with google-auth-library, http, https), the current definePlaygroundAPI causes bundler errors because:

1. Queries/mutations MUST run in V8 runtime (Convex restriction)
2. Actions CAN use Node.js runtime (with "use node" directive)
3. The combined definePlaygroundAPI pulls all dependencies (including Node.js-only ones) into the V8 bundle, causing errors like:

   Could not resolve "http"
   Could not resolve "https" 
   Could not resolve "stream"
   

Solution

Split the API into two separate functions that can be imported independently:

Usage Example

// convex/playground.ts (V8 runtime - no "use node")
import { definePlaygroundQueries } from "@convex-dev/agent";
import { components } from "./_generated/api";

export const { isApiKeyValid, listAgents, listUsers, listThreads, listMessages, createThread } = 
  definePlaygroundQueries(components.agent, {
    agents: [{ 
      name: "MyAgent", 
      instructions: "...", 
      tools: ["tool1", "tool2"] 
    }],
  });

// convex/playgroundActions.ts (Node.js runtime)
"use node";
import { definePlaygroundActions } from "@convex-dev/agent";
import { components } from "./_generated/api";
import { myVertexAgent } from "./agent";

export const { generateText, fetchPromptContext } = 
  definePlaygroundActions(components.agent, { 
    agents: [myVertexAgent] 
  });

Changes

• Added definePlaygroundQueries() - takes static AgentInfo[] instead of Agent[] to avoid importing Node.js dependencies
• Added definePlaygroundActions() - takes Agent[] and exports only actions
• Added new types: AgentInfo, PlaygroundQueriesAPI, PlaygroundActionsAPI
• Preserved definePlaygroundAPI for backward compatibility with providers that work in V8 (e.g., OpenAI via fetch)

[coderabbitai]

Walkthrough

The playground API has been refactored into modular components, introducing separate definePlaygroundQueries and definePlaygroundActions builders alongside a combined definePlaygroundAPI function. New types expose API surfaces and agent information, with corresponding exports added to the public API.

Changes

Cohort / File(s)	Change Summary
Core Playground API Implementation src/client/definePlaygroundAPI.ts	Added new public types (PlaygroundQueriesAPI, PlaygroundActionsAPI, AgentInfo) and helper type (RunQueryCtx). Implemented three builder functions: definePlaygroundQueries for V8-safe queries/mutations with API key validation, definePlaygroundActions for Node.js-only actions with agent logic, and combined definePlaygroundAPI. Replaced monolithic API definition with modularized documentation and implementations.
Public API Exports src/client/index.ts	Re-exported new functions (definePlaygroundQueries, definePlaygroundActions) and types (PlaygroundQueriesAPI, PlaygroundActionsAPI, AgentInfo) from definePlaygroundAPI.js. Maintains backward compatibility by preserving existing definePlaygroundAPI and PlaygroundAPI exports.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

• Review the type definitions and their relationships (PlaygroundQueriesAPI, PlaygroundActionsAPI, AgentInfo)
• Verify the builder functions properly separate V8-safe queries from Node.js-only actions
• Confirm API key validation and agent info exposure are correctly implemented
• Validate that backward compatibility is maintained through definePlaygroundAPI

Poem

🐰 ✨
Split the APIs with finesse and care,
Queries and actions now paired,
Modular magic in every function,
V8-safe and Node.js in utter junction!
The playground now breathes with delight. 🎪

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 42.86% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'feat: split playground API for Node.js-only LLM providers' directly and clearly summarizes the main change—splitting the playground API to separate V8-safe operations from Node.js-only functionality.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

src/client/definePlaygroundAPI.ts (1)

90-264: Well-implemented V8-safe API with comprehensive documentation.

The function correctly provides V8-safe queries and mutations while accepting static AgentInfo[] to avoid Node.js dependencies. The documentation with examples is excellent.

Note on code duplication: The implementations of validateApiKey, listUsers, listThreads, listMessages, and createThread are duplicated between definePlaygroundQueries, definePlaygroundActions, and definePlaygroundAPI. While this duplication may be intentional to keep the APIs independent, consider extracting common implementations into shared internal helpers to improve maintainability and reduce the risk of inconsistent bug fixes.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between ba05770 and ba348c9.

📒 Files selected for processing (2)

• src/client/definePlaygroundAPI.ts (1 hunks)
• src/client/index.ts (1 hunks)

🧰 Additional context used

🧬 Code graph analysis (1)

src/client/definePlaygroundAPI.ts (1)

src/client/types.ts (1)

• AgentComponent (328-328)

🔇 Additional comments (6)

src/client/index.ts (1)

131-139: LGTM! Clean extension of the public API surface.

The new exports properly expose the split playground API functions and their associated types, while maintaining backward compatibility with the existing definePlaygroundAPI and PlaygroundAPI exports.

src/client/definePlaygroundAPI.ts (5)

38-44: LGTM! Type exports follow established patterns.

The new PlaygroundQueriesAPI and PlaygroundActionsAPI types correctly use the ApiFromModules utility to infer types from their respective builder functions, consistent with the existing PlaygroundAPI type.

---

51-62: LGTM! Well-designed type for V8-safe agent metadata.

The AgentInfo type appropriately captures static agent configuration without requiring Node.js-dependent Agent instances. The structure aligns with the information extracted from actual agents in definePlaygroundAPI (line 558-565).

---

292-456: LGTM! Node.js actions properly separated with clear documentation.

The function correctly provides Node.js-only actions while requiring actual Agent instances. The implementation properly handles agent validation and provides comprehensive error messages. The documentation with examples clearly shows the "use node" directive requirement.

---

458-490: Excellent documentation for the combined API.

The JSDoc clearly explains the limitations and when to use the split APIs instead. The prominent warning about Node.js-only dependencies and the cross-references to definePlaygroundQueries and definePlaygroundActions will help users choose the right approach.

---

64-64: LGTM! Good abstraction for shared validation logic.

The RunQueryCtx type appropriately abstracts the minimal context needed for API key validation, allowing the validateApiKey helper to work in both query and action contexts.

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/get-convex/agent/@convex-dev/agent@194

commit: ba348c9

[ianmacartney]

High level:

1. I don't see where the playground client is being configured to find the actions in a separate place from the queries
2. I want the implementation to be shared for the combined & separate implementations - e.g. to have the unified one call both individually and return both. Too much duplicated code right now , from what I can tell