{"_id":"@agent-runner/studio","_rev":"2-67b4a97a1d21db9a956a483bad128562","name":"@agent-runner/studio","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@agent-runner/studio","version":"0.1.0","keywords":["ai","agents","studio","development","mcp"],"author":{"name":"Aaron Bidworthy"},"license":"MIT","_id":"@agent-runner/studio@0.1.0","maintainers":[{"name":"aparry3","email":"aaron.parry.18@gmail.com"}],"homepage":"https://github.com/aparry3/agent-runner#readme","bugs":{"url":"https://github.com/aparry3/agent-runner/issues"},"dist":{"shasum":"0e077a972ef81f196b8e0ffb091ae35681055bcb","tarball":"https://registry.npmjs.org/@agent-runner/studio/-/studio-0.1.0.tgz","fileCount":11,"integrity":"sha512-pB7QmPync7NuURLWOnnGOcqaV4X6eBBllD8Li/PRtl8kzpnaX24ncuffLnQcLQyehdciyLBHJ0euHkJpG2GJew==","signatures":[{"sig":"MEUCIGS7QxOOKSOV9M0sAbtfpuogwluBkhKpK7gt9iq53IahAiEAoU+V3Luozio2BPkBGxxbERgBlbYrG9bgSCgQiVaoTpE=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":304088},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=20.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./middleware":{"types":"./dist/middleware.d.ts","import":"./dist/middleware.js"}},"gitHead":"15bbcff48ae585a4816b8d26f0625634da2adbea","scripts":{"dev":"tsup --watch","test":"vitest run","build":"tsup && vite build","dev:ui":"vite --config vite.config.ts","build:ui":"vite build","typecheck":"tsc --noEmit","test:watch":"vitest","build:server":"tsup","prepublishOnly":"tsup && vite build"},"_npmUser":{"name":"aparry3","email":"aaron.parry.18@gmail.com"},"repository":{"url":"git+https://github.com/aparry3/agent-runner.git","type":"git","directory":"packages/studio"},"_npmVersion":"10.9.4","description":"Development studio for agent-runner — visual agent editor, playground, tool catalog, and eval dashboard","directories":{},"_nodeVersion":"22.21.0","dependencies":{"hono":"^4.7.0","react":"^19.2.4","react-dom":"^19.2.4","react-router-dom":"^7.13.1","@hono/node-server":"^1.19.11"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"zod":"^3.24.0","tsup":"^8.4.0","vite":"^7.3.1","vitest":"^3.0.0","typescript":"^5.7.0","@types/node":"^22.0.0","@types/react":"^19.2.14","@types/react-dom":"^19.2.3","@agent-runner/core":"workspace:*","@vitejs/plugin-react":"^5.1.4"},"peerDependencies":{"@agent-runner/core":">=0.1.0"},"_npmOperationalInternal":{"tmp":"tmp/studio_0.1.0_1773227463461_0.4980523317316221","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@agent-runner/studio","version":"0.1.1","description":"Development studio for agent-runner — visual agent editor, playground, tool catalog, and eval dashboard","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./middleware":{"types":"./dist/middleware.d.ts","import":"./dist/middleware.js"}},"keywords":["ai","agents","studio","development","mcp"],"publishConfig":{"access":"public"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/aparry3/agent-runner.git","directory":"packages/studio"},"homepage":"https://github.com/aparry3/agent-runner#readme","author":{"name":"Aaron Bidworthy"},"dependencies":{"@hono/node-server":"^1.19.11","hono":"^4.7.0","react":"^19.2.4","react-dom":"^19.2.4","react-router-dom":"^7.13.1"},"peerDependencies":{"@agent-runner/core":">=0.1.1"},"devDependencies":{"@types/node":"^22.0.0","@types/react":"^19.2.14","@types/react-dom":"^19.2.3","@vitejs/plugin-react":"^5.1.4","tsup":"^8.4.0","typescript":"^5.7.0","vite":"^7.3.1","vitest":"^3.0.0","zod":"^3.24.0","@agent-runner/core":"0.1.1"},"engines":{"node":">=20.0.0"},"scripts":{"build":"tsup && vite build","build:server":"tsup","build:ui":"vite build","dev":"tsup --watch","dev:ui":"vite --config vite.config.ts","test":"vitest run","test:watch":"vitest","typecheck":"tsc --noEmit"},"_id":"@agent-runner/studio@0.1.1","bugs":{"url":"https://github.com/aparry3/agent-runner/issues"},"_integrity":"sha512-2VMgKrD4sIi9n28n6sBUo/0yyGRBMS5zLfSwGAHgCFo5VqrYVKopdYZe0g52JdH7ODp8v1e/NFNKnKf0SjQmJg==","_resolved":"/tmp/1334482f33c1f46fbd05f52ec22d13c9/agent-runner-studio-0.1.1.tgz","_from":"file:agent-runner-studio-0.1.1.tgz","_nodeVersion":"22.22.0","_npmVersion":"10.9.4","dist":{"integrity":"sha512-2VMgKrD4sIi9n28n6sBUo/0yyGRBMS5zLfSwGAHgCFo5VqrYVKopdYZe0g52JdH7ODp8v1e/NFNKnKf0SjQmJg==","shasum":"5830783f12b12867f0a6f42d3a77c2c9da0a66e5","tarball":"https://registry.npmjs.org/@agent-runner/studio/-/studio-0.1.1.tgz","fileCount":13,"unpackedSize":314497,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIGTz+6q0aPToFEI409TSzClpjgW7HiAehhpssXjMoG1RAiEA2QnLnGxqovEuA0tc3/gImTQKO1CqQGwfmcXHvoWxjCE="}]},"_npmUser":{"name":"aparry3","email":"aaron.parry.18@gmail.com"},"directories":{},"maintainers":[{"name":"aparry3","email":"aaron.parry.18@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/studio_0.1.1_1773230671521_0.9044223856675835"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-11T11:11:03.270Z","modified":"2026-03-11T12:04:31.800Z","0.1.0":"2026-03-11T11:11:03.608Z","0.1.1":"2026-03-11T12:04:31.693Z"},"bugs":{"url":"https://github.com/aparry3/agent-runner/issues"},"author":{"name":"Aaron Bidworthy"},"license":"MIT","homepage":"https://github.com/aparry3/agent-runner#readme","keywords":["ai","agents","studio","development","mcp"],"repository":{"type":"git","url":"git+https://github.com/aparry3/agent-runner.git","directory":"packages/studio"},"description":"Development studio for agent-runner — visual agent editor, playground, tool catalog, and eval dashboard","maintainers":[{"name":"aparry3","email":"aaron.parry.18@gmail.com"}],"readme":"# @agent-runner/studio\n\n[![npm version](https://img.shields.io/npm/v/@agent-runner/studio.svg)](https://www.npmjs.com/package/@agent-runner/studio)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n[![Node.js](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen.svg)](https://nodejs.org)\n\nVisual development UI for [agent-runner](https://github.com/aparry3/agent-runner). Define, test, and debug agents with a browser-based studio — agent editor, interactive playground, tool catalog, MCP server management, eval dashboard, session browser, and invocation logs.\n\n## Install\n\n```bash\nnpm install @agent-runner/studio @agent-runner/core\n# or\npnpm add @agent-runner/studio @agent-runner/core\n# or\nyarn add @agent-runner/studio @agent-runner/core\n```\n\n## Quick Start\n\nThe fastest way to launch Studio:\n\n```bash\nnpx agent-runner studio\n```\n\nOr programmatically:\n\n```typescript\nimport { createRunner, defineAgent } from \"@agent-runner/core\";\nimport { createStudio } from \"@agent-runner/studio\";\n\nconst runner = createRunner();\n\nrunner.registerAgent(defineAgent({\n  id: \"greeter\",\n  name: \"Greeter\",\n  systemPrompt: \"You are a friendly greeter.\",\n  model: { provider: \"openai\", name: \"gpt-4o-mini\" },\n}));\n\nconst studio = await createStudio(runner, { port: 4000 });\nconsole.log(`Studio running at ${studio.url}`);\n// → Studio running at http://localhost:4000\n```\n\n## Studio Pages\n\n| Page | Description |\n|---|---|\n| **Agent Editor** | Create and edit agent definitions — system prompts, model config, tool references, eval cases |\n| **Playground** | Interactive chat with any registered agent, with session support |\n| **Tool Catalog** | Browse all registered tools (inline + MCP) with schemas and test execution |\n| **MCP Servers** | View connected MCP servers, their status, and available tools |\n| **Evals Dashboard** | Run evaluations and view results with pass/fail breakdowns |\n| **Context Browser** | Inspect shared context buckets and their entries |\n| **Sessions** | Browse conversation sessions and their message history |\n| **Logs** | View invocation logs with token usage, duration, and tool calls |\n\n## Usage\n\n### Standalone Server\n\nLaunch Studio as its own HTTP server:\n\n```typescript\nimport { createRunner } from \"@agent-runner/core\";\nimport { createStudio } from \"@agent-runner/studio\";\n\nconst runner = createRunner({ /* your config */ });\n\nconst studio = await createStudio(runner, {\n  port: 4000,          // default: 4000\n  hostname: \"0.0.0.0\", // default: \"localhost\"\n  onReady: (url) => console.log(`Studio → ${url}`),\n});\n\n// Later: shut down cleanly\nawait studio.close();\n```\n\n### Middleware (Embed in Your App)\n\nMount Studio's API routes inside an existing Hono app:\n\n```typescript\nimport { Hono } from \"hono\";\nimport { studioMiddleware } from \"@agent-runner/studio/middleware\";\n\nconst app = new Hono();\nconst runner = createRunner({ /* your config */ });\n\n// Mount Studio under /studio\napp.route(\"/studio\", studioMiddleware(runner));\n\n// Your other routes\napp.get(\"/api/hello\", (c) => c.json({ hello: \"world\" }));\n```\n\nThe middleware provides all Studio API endpoints — perfect for adding a dev dashboard to an existing service.\n\n## API Reference\n\n### `createStudio(runner, options?)`\n\nCreates and starts a standalone Studio server.\n\n```typescript\nconst studio = await createStudio(runner, options);\n```\n\n**Parameters:**\n\n| Parameter | Type | Description |\n|---|---|---|\n| `runner` | `Runner` | An `@agent-runner/core` Runner instance |\n| `options` | `StudioOptions` | Optional configuration |\n\n**StudioOptions:**\n\n| Option | Type | Default | Description |\n|---|---|---|---|\n| `port` | `number` | `4000` | Port to listen on |\n| `hostname` | `string` | `\"localhost\"` | Hostname to bind to |\n| `onReady` | `(url: string) => void` | — | Callback when server starts |\n\n**Returns:**\n\n| Property | Type | Description |\n|---|---|---|\n| `url` | `string` | The full URL where Studio is running |\n| `app` | `Hono` | The underlying Hono app instance |\n| `close()` | `() => Promise<void>` | Gracefully shut down the server |\n\n### `studioMiddleware(runner)`\n\nCreates a Hono app with Studio API routes, suitable for mounting as middleware.\n\n```typescript\nimport { studioMiddleware } from \"@agent-runner/studio/middleware\";\n\nconst studioApp = studioMiddleware(runner);\napp.route(\"/studio\", studioApp);\n```\n\n## API Endpoints\n\nStudio exposes a REST API that powers the UI. You can also call these endpoints directly:\n\n### Health\n\n| Method | Path | Description |\n|---|---|---|\n| `GET` | `/api/health` | Health check — returns `{ status: \"ok\" }` |\n\n### Agents\n\n| Method | Path | Description |\n|---|---|---|\n| `GET` | `/api/agents` | List all agents |\n| `GET` | `/api/agents/:id` | Get agent definition |\n| `PUT` | `/api/agents/:id` | Create or update an agent |\n| `DELETE` | `/api/agents/:id` | Delete an agent |\n| `POST` | `/api/agents/:id/invoke` | Invoke an agent (playground) |\n\n**Invoke body:**\n\n```json\n{\n  \"input\": \"Hello!\",\n  \"sessionId\": \"optional-session-id\",\n  \"contextIds\": [\"optional-context-ids\"],\n  \"extraContext\": \"optional extra context string\",\n  \"toolContext\": {}\n}\n```\n\n### Tools\n\n| Method | Path | Description |\n|---|---|---|\n| `GET` | `/api/tools` | List all registered tools |\n| `GET` | `/api/tools/:name` | Get tool details and schema |\n| `POST` | `/api/tools/:name/test` | Test-execute a tool with input |\n\n### MCP Servers\n\n| Method | Path | Description |\n|---|---|---|\n| `GET` | `/api/mcp/servers` | List all MCP servers and their status |\n| `GET` | `/api/mcp/servers/:name` | Get status for a specific server |\n| `GET` | `/api/mcp/servers/:name/tools` | List tools from a specific MCP server |\n\n### Sessions\n\n| Method | Path | Description |\n|---|---|---|\n| `GET` | `/api/sessions` | List sessions (optional `?agentId=` filter) |\n| `GET` | `/api/sessions/:id` | Get session messages |\n| `DELETE` | `/api/sessions/:id` | Delete a session |\n\n### Context\n\n| Method | Path | Description |\n|---|---|---|\n| `GET` | `/api/context/:contextId` | Get context entries with size/count |\n| `POST` | `/api/context/:contextId` | Add a context entry |\n| `DELETE` | `/api/context/:contextId` | Clear a context bucket |\n\n### Evals\n\n| Method | Path | Description |\n|---|---|---|\n| `POST` | `/api/evals/:agentId/run` | Run evals for an agent |\n\n### Logs\n\n| Method | Path | Description |\n|---|---|---|\n| `GET` | `/api/logs` | Query logs (`?agentId=`, `?sessionId=`, `?since=`, `?limit=`, `?offset=`) |\n| `GET` | `/api/logs/:id` | Get a specific log entry |\n\n## Examples\n\n### Full Development Setup\n\n```typescript\nimport { createRunner, defineAgent, defineTool, JsonFileStore } from \"@agent-runner/core\";\nimport { SqliteStore } from \"@agent-runner/store-sqlite\";\nimport { createStudio } from \"@agent-runner/studio\";\nimport { z } from \"zod\";\n\nconst runner = createRunner({\n  store: new SqliteStore(\"./dev.db\"),\n  tools: [\n    defineTool({\n      name: \"get_weather\",\n      description: \"Get current weather for a city\",\n      input: z.object({ city: z.string() }),\n      async execute({ city }) {\n        return { temp: 72, condition: \"sunny\", city };\n      },\n    }),\n  ],\n  mcp: {\n    servers: {\n      filesystem: { command: \"npx\", args: [\"-y\", \"@anthropic/mcp-fs\"] },\n    },\n  },\n});\n\nrunner.registerAgent(defineAgent({\n  id: \"assistant\",\n  name: \"Assistant\",\n  systemPrompt: \"You're a helpful assistant with access to weather data.\",\n  model: { provider: \"openai\", name: \"gpt-4o\" },\n  tools: [\n    { type: \"inline\", name: \"get_weather\" },\n    { type: \"mcp\", server: \"filesystem\" },\n  ],\n  eval: {\n    testCases: [\n      {\n        name: \"weather query\",\n        input: \"What's the weather in NYC?\",\n        assertions: [{ type: \"contains\", value: \"sunny\" }],\n      },\n    ],\n  },\n}));\n\nconst studio = await createStudio(runner, {\n  port: 4000,\n  onReady: (url) => console.log(`\\n  🎨 Studio → ${url}\\n`),\n});\n```\n\n### Production: Embed in Express/Hono App\n\n```typescript\nimport { Hono } from \"hono\";\nimport { serve } from \"@hono/node-server\";\nimport { createRunner } from \"@agent-runner/core\";\nimport { PostgresStore } from \"@agent-runner/store-postgres\";\nimport { studioMiddleware } from \"@agent-runner/studio/middleware\";\n\nconst runner = createRunner({\n  store: new PostgresStore(process.env.DATABASE_URL!),\n});\n\nconst app = new Hono();\n\n// Your API routes\napp.get(\"/api/v1/chat\", async (c) => {\n  const result = await runner.invoke(\"chatbot\", c.req.query(\"message\")!);\n  return c.json(result);\n});\n\n// Mount Studio (dev only)\nif (process.env.NODE_ENV !== \"production\") {\n  app.route(\"/studio\", studioMiddleware(runner));\n}\n\nserve({ fetch: app.fetch, port: 3000 });\n```\n\n## Built With\n\n- [Hono](https://hono.dev/) — Lightweight web framework for the API server\n- [React](https://react.dev/) + [React Router](https://reactrouter.com/) — Studio UI\n- [Vite](https://vite.dev/) — UI build tooling\n\n## Related Packages\n\n| Package | Description |\n|---|---|\n| [`@agent-runner/core`](../core) | Core SDK — createRunner, agents, tools, stores |\n| [`@agent-runner/store-sqlite`](../store-sqlite) | SQLite storage adapter |\n| [`@agent-runner/store-postgres`](../store-postgres) | PostgreSQL storage adapter |\n\n## Contributing\n\nSee the main [CONTRIBUTING.md](https://github.com/aparry3/agent-runner/blob/main/CONTRIBUTING.md) for guidelines.\n\n## License\n\nMIT © [Aaron Bidworthy](https://github.com/aparry3)\n","readmeFilename":"README.md"}