@agent-play/cli 3.0.1 → 3.2.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@agent-play/cli",
-  "version": "3.0.1",
-  "description": "Command-line tool for Agent Play: login, API keys, and agent registration against the web UI.",
+  "version": "3.2.0",
+  "description": "Command-line tool for Agent Play: node configurations, agent starter kit, and agent registration against the web UI.",
   "private": false,
   "type": "module",
   "bin": {
@@ -9,6 +9,7 @@
   },
   "files": [
     "dist",
+    "templates",
     "README.md"
   ],
   "repository": {
@@ -20,12 +21,17 @@
     "access": "public"
   },
   "scripts": {
-    "build": "tsup src/cli.ts --format esm --platform node --target node20 --out-dir dist --clean"
+    "build": "tsup src/cli.ts --format esm --platform node --target node20 --out-dir dist --clean --external @agent-play/node-tools && node ../../scripts/copy-root-file.mjs cli && cp README.md dist/README.md",
+    "test": "vitest run",
+    "smoke:initialize": "node ./scripts/smoke-initialize.mjs"
+  },
+  "dependencies": {
+    "@agent-play/node-tools": "1.0.0"
   },
-  "dependencies": {},
   "devDependencies": {
     "@types/node": "^22.10.0",
     "tsup": "^8.5.1",
-    "typescript": "~5.9.3"
+    "typescript": "~5.9.3",
+    "vitest": "^4.1.1"
   }
 }

package/templates/agent-starter/langchain/.env.example

@@ -0,0 +1,6 @@
+AGENT_PLAY_WEB_UI_URL=https://agent-play.com
+AGENT_PLAY_MAIN_NODE_ID=
+AGENT_PLAY_AGENT_NODE_ID_1=
+AGENT_PLAY_AGENT_NODE_ID_2=
+OPENAI_API_KEY=
+P2A_WEBRTC_ENABLED=1

package/templates/agent-starter/langchain/README.md

@@ -0,0 +1,24 @@
+# __PROJECT_NAME__
+
+Starter scaffold generated by `agent-play initialize`.
+
+## Quick start
+
+1. Install dependencies:
+   - `npm install`
+2. Prepare local env:
+   - `cp .env.example .env`
+3. If you skipped bootstrap during initialize:
+   - `npx agent-play create-main-node`
+   - `npx agent-play create-agent-node` (once or twice)
+   - copy values from `~/.agent-play/credentials.json` into `.env`
+4. Run:
+   - `npm run dev`
+
+## Node identity env contract
+
+- `AGENT_PLAY_MAIN_NODE_ID`: main developer node id.
+- `AGENT_PLAY_AGENT_NODE_ID_1`: first agent node id.
+- `AGENT_PLAY_AGENT_NODE_ID_2`: optional second agent node id.
+
+The generated runtime uses env variables for node ids; no hardcoded identities are embedded.

package/templates/agent-starter/langchain/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "__PROJECT_NAME__",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@agent-play/sdk": "^3.2.1",
+    "@langchain/openai": "^1.3.0",
+    "dotenv": "^17.3.1",
+    "express": "^4.21.2",
+    "langchain": "^1.2.36",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/node": "^22.10.0",
+    "tsx": "^4.21.0",
+    "typescript": "~5.9.3"
+  }
+}

package/templates/agent-starter/langchain/src/bare-server.ts

@@ -0,0 +1,12 @@
+import { loadEnv } from "./load-env.js";
+import { registerAgents } from "./register-agents.js";
+
+export async function startServer(): Promise<void> {
+  loadEnv();
+  const { world, registeredAgentIds } = await registerAgents();
+  console.log(`Registered ${String(registeredAgentIds.length)} agent(s):`);
+  for (const id of registeredAgentIds) {
+    console.log(`  - ${id}`);
+  }
+  await world.hold().for(30 * 60);
+}

package/templates/agent-starter/langchain/src/builtins/definitions.ts

@@ -0,0 +1,66 @@
+import { ChatOpenAI } from "@langchain/openai";
+import { createAgent } from "langchain";
+import { calculatorTools, policeReportTools } from "./toolkits/starter-tools.js";
+
+function randomAgentName(prefix: string): string {
+  return `${prefix}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
+function randomSystemPrompt(prefix: string, rolePrompt: string): string {
+  const nonce = Math.random().toString(36).slice(2, 10);
+  return `${rolePrompt} Session nonce: ${nonce}. Agent label: ${prefix}.`;
+}
+
+function requiredEnv(name: string): string {
+  const value = process.env[name]?.trim();
+  if (value === undefined || value.length === 0) {
+    throw new Error(`Missing required env var: ${name}`);
+  }
+  return value;
+}
+
+export type StarterAgentDefinition = {
+  nodeId: string;
+  name: string;
+  type: "langchain";
+  agent: ReturnType<typeof createAgent>;
+};
+
+export function getStarterAgentDefinitions(agentCount: 1 | 2): StarterAgentDefinition[] {
+  const model = new ChatOpenAI({
+    apiKey: requiredEnv("OPENAI_API_KEY"),
+    model: process.env.OPENAI_MODEL?.trim() || "gpt-4.1",
+  });
+  const first = {
+    nodeId: requiredEnv("AGENT_PLAY_AGENT_NODE_ID_1"),
+    name: randomAgentName("CalculatorAgent"),
+    type: "langchain" as const,
+    agent: createAgent({
+      name: randomAgentName("lc-calculator-agent"),
+      model,
+      tools: [...calculatorTools],
+      systemPrompt: randomSystemPrompt(
+        "Calculator Agent",
+        "You are a rigorous calculator agent for production operations. Always validate the equation format, show the extracted coefficient and brief reasoning, and ask clarifying questions when equation syntax is ambiguous. Use chat_tool for conversational explanations and assist_calculate_coefficient for structured extraction."
+      ),
+    }),
+  };
+  if (agentCount === 1) {
+    return [first];
+  }
+  const second = {
+    nodeId: requiredEnv("AGENT_PLAY_AGENT_NODE_ID_2"),
+    name: randomAgentName("PoliceReportAgent"),
+    type: "langchain" as const,
+    agent: createAgent({
+      name: randomAgentName("lc-police-report-agent"),
+      model,
+      tools: [...policeReportTools],
+      systemPrompt: randomSystemPrompt(
+        "Police Report Agent",
+        "You are a police report intake agent. Collect factual, time-stamped incident details, separate witness statements from assumptions, and maintain neutral language suitable for official records. Use chat_tool for guided conversation and assist_collect_scene_details to gather structured scene data."
+      ),
+    }),
+  };
+  return [first, second];
+}

package/templates/agent-starter/langchain/src/builtins/toolkits/starter-tools.ts

@@ -0,0 +1,84 @@
+import { tool } from "langchain";
+import { z } from "zod";
+
+const calculatorChatTool = tool(
+  ({ message }: { message: string }) => `calculator:${message}`,
+  {
+    name: "chat_tool",
+    description: "Production-style calculator assistant chat tool.",
+    schema: z.object({
+      message: z.string(),
+    }),
+  }
+);
+
+const assistCalculateCoefficient = tool(
+  ({
+    equation,
+    variable,
+  }: {
+    equation: string;
+    variable: string;
+  }) => `coefficient:${equation}:${variable}`,
+  {
+    name: "assist_calculate_coefficient",
+    description:
+      "Extract the coefficient of a variable from a linear or polynomial equation string.",
+    schema: z.object({
+      equation: z.string(),
+      variable: z.string(),
+    }),
+  }
+);
+
+const policeChatTool = tool(
+  ({ message }: { message: string }) => `police:${message}`,
+  {
+    name: "chat_tool",
+    description: "Production-style police incident reporting chat tool.",
+    schema: z.object({
+      message: z.string(),
+    }),
+  }
+);
+
+const assistCollectSceneDetails = tool(
+  ({
+    location,
+    incidentType,
+    witnesses,
+    injuriesReported,
+    suspectDescription,
+    immediateRisk,
+  }: {
+    location: string;
+    incidentType: string;
+    witnesses?: string;
+    injuriesReported?: boolean;
+    suspectDescription?: string;
+    immediateRisk?: "low" | "medium" | "high";
+  }) =>
+    `scene:${location}:${incidentType}:${witnesses ?? ""}:${String(injuriesReported ?? false)}:${
+      suspectDescription ?? ""
+    }:${immediateRisk ?? "low"}`,
+  {
+    name: "assist_collect_scene_details",
+    description:
+      "Collect structured details from an incident scene report for police documentation.",
+    schema: z.object({
+      location: z.string(),
+      incidentType: z.string(),
+      witnesses: z.string().optional(),
+      injuriesReported: z.boolean().optional(),
+      suspectDescription: z.string().optional(),
+      immediateRisk: z.enum(["low", "medium", "high"]).optional(),
+    }),
+  }
+);
+
+export const calculatorTools = [
+  calculatorChatTool,
+  assistCalculateCoefficient,
+] as const;
+
+export const policeReportTools = [policeChatTool, assistCollectSceneDetails] as const;

package/templates/agent-starter/langchain/src/express-server.ts

@@ -0,0 +1,27 @@
+import express from "express";
+import { loadEnv } from "./load-env.js";
+import { registerAgents } from "./register-agents.js";
+
+export async function startServer(): Promise<void> {
+  loadEnv();
+  const port = Number(process.env.PORT ?? "3100");
+  const host = process.env.HOST ?? "0.0.0.0";
+
+  const app = express();
+  app.use(express.json());
+  app.get("/health", (_req, res) => {
+    res.json({ ok: true });
+  });
+
+  const { world, registeredAgentIds } = await registerAgents();
+  console.log(`Registered ${String(registeredAgentIds.length)} agent(s):`);
+  for (const id of registeredAgentIds) {
+    console.log(`  - ${id}`);
+  }
+
+  app.listen(port, host, () => {
+    console.log(`[starter-express] listening on http://${host}:${String(port)}`);
+  });
+
+  await world.hold().for(30 * 60);
+}

package/templates/agent-starter/langchain/src/index.ts

@@ -0,0 +1,6 @@
+import { startServer } from "__SERVER_MODULE__";
+
+void startServer().catch((error: unknown) => {
+  console.error(error);
+  process.exitCode = 1;
+});

package/templates/agent-starter/langchain/src/load-env.ts

@@ -0,0 +1,5 @@
+import { config } from "dotenv";
+
+export function loadEnv(): void {
+  config();
+}

package/templates/agent-starter/langchain/src/register/register-builtins.ts

@@ -0,0 +1,62 @@
+import {
+  langchainRegistration,
+  RemotePlayWorld,
+  type RegisteredPlayer,
+} from "@agent-play/sdk";
+import { getStarterAgentDefinitions } from "../builtins/definitions.js";
+import { executeToolCapability } from "../tool-handlers/execute-tool-capability.js";
+
+type RegisterResult = {
+  world: RemotePlayWorld;
+  registeredAgentIds: string[];
+};
+
+function requiredEnv(name: string): string {
+  const value = process.env[name]?.trim();
+  if (value === undefined || value.length === 0) {
+    throw new Error(`Missing required env var: ${name}`);
+  }
+  return value;
+}
+
+export async function registerBuiltinAgents(): Promise<RegisterResult> {
+  const mainNodeId = requiredEnv("AGENT_PLAY_MAIN_NODE_ID");
+  const world = new RemotePlayWorld({ logging: "on" });
+  const openAiApiKey = process.env.OPENAI_API_KEY?.trim();
+  if (openAiApiKey !== undefined && openAiApiKey.length > 0) {
+    world.initAudio({
+      openai: {
+        apiKey: openAiApiKey,
+      },
+    });
+  }
+  await world.connect({ mainNodeId });
+
+  const hasSecondAgent =
+    (process.env.AGENT_PLAY_AGENT_NODE_ID_2?.trim() ?? "").length > 0;
+  const definitions = getStarterAgentDefinitions(hasSecondAgent ? 2 : 1);
+  const registeredAgentIds: string[] = [];
+  const chatAgentsByPlayerId = new Map<string, unknown>();
+  const registeredPlayers: RegisteredPlayer[] = [];
+  for (const def of definitions) {
+    const registered = await world.addAgent({
+      name: def.name,
+      type: def.type,
+      agent: langchainRegistration(def.agent),
+      nodeId: def.nodeId,
+      enableP2a: "on",
+    });
+    registeredAgentIds.push(registered.id);
+    registeredPlayers.push(registered);
+  }
+  for (let i = 0; i < registeredPlayers.length; i++) {
+    chatAgentsByPlayerId.set(registeredPlayers[i].id, definitions[i].agent);
+  }
+  world.subscribeIntercomCommands({
+    playerIds: registeredPlayers.map((player) => player.id),
+    executeTool: executeToolCapability,
+    chatAgentsByPlayerId: chatAgentsByPlayerId as Map<string, never>,
+  });
+
+  return { world, registeredAgentIds };
+}

package/templates/agent-starter/langchain/src/register-agents.ts

@@ -0,0 +1 @@
+export { registerBuiltinAgents as registerAgents } from "./register/register-builtins.js";

package/templates/agent-starter/langchain/src/tool-handlers/assist-brainstorm.ts

@@ -0,0 +1,8 @@
+export function executeAssistBrainstorm(args: {
+  prompt?: string;
+}): Record<string, unknown> {
+  const prompt = typeof args.prompt === "string" ? args.prompt : "";
+  return {
+    summary: `Brainstorm starter for: ${prompt}`,
+  };
+}

package/templates/agent-starter/langchain/src/tool-handlers/assist-calculate-coefficient.ts

@@ -0,0 +1,35 @@
+function normalizeEquation(equation: string): string {
+  return equation.replace(/\s+/g, "");
+}
+
+export function executeAssistCalculateCoefficient(args: {
+  equation?: string;
+  variable?: string;
+}): Record<string, unknown> {
+  const equation = typeof args.equation === "string" ? args.equation : "";
+  const variable = typeof args.variable === "string" ? args.variable : "";
+  if (equation.length === 0 || variable.length === 0) {
+    return {
+      ok: false,
+      error: "equation and variable are required.",
+    };
+  }
+  const normalized = normalizeEquation(equation);
+  const regex = new RegExp(`([+-]?\\d*\\.?\\d*)${variable}`);
+  const match = normalized.match(regex);
+  if (match === null) {
+    return {
+      ok: false,
+      error: `No coefficient found for variable ${variable}.`,
+    };
+  }
+  const raw = match[1];
+  const coefficient =
+    raw === "" || raw === "+" ? 1 : raw === "-" ? -1 : Number(raw);
+  return {
+    ok: Number.isFinite(coefficient),
+    variable,
+    coefficient,
+    equation,
+  };
+}

package/templates/agent-starter/langchain/src/tool-handlers/assist-collect-scene-details.ts

@@ -0,0 +1,32 @@
+export function executeAssistCollectSceneDetails(args: {
+  location?: string;
+  incidentType?: string;
+  witnesses?: string;
+  injuriesReported?: boolean;
+  suspectDescription?: string;
+  immediateRisk?: "low" | "medium" | "high";
+}): Record<string, unknown> {
+  const location = typeof args.location === "string" ? args.location : "";
+  const incidentType =
+    typeof args.incidentType === "string" ? args.incidentType : "";
+  if (location.length === 0 || incidentType.length === 0) {
+    return {
+      ok: false,
+      error: "location and incidentType are required.",
+    };
+  }
+  return {
+    ok: true,
+    scene: {
+      location,
+      incidentType,
+      witnesses: typeof args.witnesses === "string" ? args.witnesses : "",
+      injuriesReported: args.injuriesReported === true,
+      suspectDescription:
+        typeof args.suspectDescription === "string"
+          ? args.suspectDescription
+          : "",
+      immediateRisk: args.immediateRisk ?? "low",
+    },
+  };
+}

package/templates/agent-starter/langchain/src/tool-handlers/chat-tool.ts

@@ -0,0 +1,6 @@
+export function executeChatTool(args: { message?: string }): Record<string, unknown> {
+  const message = typeof args.message === "string" ? args.message : "";
+  return {
+    reply: `Echo from __PROJECT_NAME__: ${message}`,
+  };
+}

package/templates/agent-starter/langchain/src/tool-handlers/execute-tool-capability.ts

@@ -0,0 +1,12 @@
+import { resolveToolCapabilityHandler } from "./tool-capability-registry.js";
+
+export async function executeToolCapability(options: {
+  toolName: string;
+  args: Record<string, unknown>;
+}): Promise<Record<string, unknown>> {
+  const handler = resolveToolCapabilityHandler(options.toolName);
+  if (handler === null) {
+    throw new Error(`unknown tool capability: ${options.toolName}`);
+  }
+  return await Promise.resolve(handler(options.args));
+}

package/templates/agent-starter/langchain/src/tool-handlers/tool-capability-registry.ts

@@ -0,0 +1,49 @@
+import { executeAssistCalculateCoefficient } from "./assist-calculate-coefficient.js";
+import { executeAssistCollectSceneDetails } from "./assist-collect-scene-details.js";
+import { executeChatTool } from "./chat-tool.js";
+
+export type ToolCapabilityHandler = (
+  args: Record<string, unknown>
+) => Record<string, unknown> | Promise<Record<string, unknown>>;
+
+const registry = new Map<string, ToolCapabilityHandler>([
+  ["chat_tool", (args) => executeChatTool({ message: String(args.message ?? "") })],
+  [
+    "assist_calculate_coefficient",
+    (args) =>
+      executeAssistCalculateCoefficient({
+        equation: String(args.equation ?? ""),
+        variable: String(args.variable ?? ""),
+      }),
+  ],
+  [
+    "assist_collect_scene_details",
+    (args) =>
+      executeAssistCollectSceneDetails({
+        location: String(args.location ?? ""),
+        incidentType: String(args.incidentType ?? ""),
+        witnesses:
+          typeof args.witnesses === "string" ? args.witnesses : undefined,
+        injuriesReported:
+          typeof args.injuriesReported === "boolean"
+            ? args.injuriesReported
+            : undefined,
+        suspectDescription:
+          typeof args.suspectDescription === "string"
+            ? args.suspectDescription
+            : undefined,
+        immediateRisk:
+          args.immediateRisk === "low" ||
+          args.immediateRisk === "medium" ||
+          args.immediateRisk === "high"
+            ? args.immediateRisk
+            : undefined,
+      }),
+  ],
+]);
+
+export function resolveToolCapabilityHandler(
+  toolName: string
+): ToolCapabilityHandler | null {
+  return registry.get(toolName) ?? null;
+}

package/templates/agent-starter/langchain/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "noEmit": false,
+    "outDir": "dist"
+  },
+  "include": ["src/**/*.ts"]
+}