AgentPlayground

Accomplish anything with agents.

AgentPlayground is an open-source platform where AI agent teams do real work — research, writing, knowledge management, server operations — coordinated by one agent you talk to. This page shows how every subsystem actually works. Nothing here is a mockup: every diagram is drawn from the real source code, and each section names the files it describes.

The Coordinator

You talk to one agent — the Playground Keeper. Every message gives it a reasoning loop of up to 25 tool steps: it can search your knowledge base, create teams and skills, draft multi-team plans, and delegate work, all before it answers. It is the only agent you ever need to address; everything else flows through it.

When it delegates with delegate_to_team, the receiving team runs its own tool loop — up to 10 steps, with tools scoped to that team’s specialty (a dev team gets file and server tools, a research team gets web search, a content team gets writing tools). Multiple delegations issued in a single turn run in parallel: two teams work at the same time, not one after the other, and the Keeper synthesizes both results into one streamed answer.

YouThe KeeperResearch TeamMarketing Teamyour messageReasoning loopup to 25 tool stepsdelegate_to_teamdelegate_to_teamsame turn — both teams run at onceTeam tool loop10 scoped stepsTeam tool loop10 scoped stepsresultresultSynthesisboth results, one answerone streamed answer

Grounded in app/api/chat/route.ts · lib/chat-tools.ts — docs: The coordinator

Example of use

You say: “Research our top three competitors and draft a positioning one-pager.”

  1. The Keeper searches the Brain for anything you already have on those competitors.
  2. In one turn it delegates the research to the Research Team and the one-pager to the Marketing Team — both delegations fire at once.
  3. Each team runs its own scoped tool loop: web searches, notes written back to the Brain.
  4. The Keeper receives both results, synthesizes them into a single answer, and streams it to you with suggested next steps.

The Task Router

Sometimes you don’t want a conversation — you want work done. The quick-task popup takes one sentence. A model reads your actual team roster (names, descriptions, team sizes) and picks the best-fit team, returning its reasoning alongside the pick. It is explicitly instructed never to force a choice: if no team genuinely covers the task, it says so and you land on a manual picker instead of a wrong guess.

You confirm or override, and the task dispatches in the background — the popup returns immediately while the team works. Progress streams into a live activity strip over server-sent events, and the finished result lands on the task record.

1 · Describeone sentence in thequick-task popup2 · Model picksreads your team roster,returns pick + reasoning3 · You confirmsee the reasoning —accept or override4 · Dispatchtask starts in thebackground instantlyoverrideManual pickerchoose playground →team yourselfWatch it runlive activity strip (SSE) +task record with the resultIf no team genuinely fits, the router says so instead of forcing a wrong pick — you land on the manual picker.

Grounded in app/api/route-task/route.ts · components/TaskRouter.tsx — docs: Your first task

Example of use

You say: “Write three cold-email drafts for the real-estate campaign.”

  1. The router proposes the Marketing Team and shows why: its description covers outreach copy.
  2. You press Dispatch. A task record is created and the team starts in the background — the popup closes and you keep working.
  3. The activity strip announces the start and the completion; the drafts wait for you on the task record.

Live Meetings

Call a meeting between teams and individual agents on any topic. A preset sets the depth — Fast is one round, Balanced two, Deep three (with extended thinking on the closing pass when available). Each participant speaks in turn, streamed token by token into its own lane, and each one sees the full discussion so far — they react to each other instead of repeating each other. Every participant can run on a different model.

You are in the room too: interject at any moment and your message joins the discussion before the very next turn, or end the meeting early. Between rounds the Keeper synthesizes agreements and open disagreements. At the end it extracts a neutral summary and three to seven actionable decisions, each matched to a suggested team with a Dispatch button — a meeting ends in work starting, not in a transcript nobody reads. The transcript and decisions are also ingested into the Brain, so future work can cite what was decided.

New meetingpick teams and/or individual agents,per-participant model, preset: 1–3 roundsdiscussion round — repeats per presetEach participant takes a streamed turnone live lane per participant — each seesthe whole discussion so farKeeper synthesis between roundsagreements, disagreements, and thequestions the next round must answernext roundYou interjectany time — joinsbefore the verynext turnEnd meetingwraps up early,goes to decisionsKeeper extracts decisionsneutral summary + 3–7 actionable decisions,each matched to a suggested teamDispatch a decisionone click → background task for the suggestedteam — progress streams while you watchIngested into the Braintranscript + decisions, searchablelater, playground-tagged

Grounded in lib/meetings/engine.ts · app/api/live-meetings/ — docs: Meetings

Example of use

You say: “Should we launch the new pack this month? — with Marketing and Research, Fast preset.”

  1. Both team leads stream their takes live, each in its own lane, reacting to one another.
  2. You interject: 'budget is capped at $500' — it enters the discussion before the next turn.
  3. The Keeper closes with decisions like 'Prepare a $500 launch plan — suggested: Marketing Team'.
  4. One click on Dispatch turns that decision into a background task; the meeting is saved to the Brain.

The Brain — RAG Pipeline

Everything the platform learns lands in the Brain, its retrieval-augmented knowledge base. Office files you upload (.xlsx, .docx, .pptx, .pdf, .csv) are converted to Markdown automatically. Every document is deduplicated by content hash, split into roughly 500-token chunks with a 64-token overlap, and embedded into 768-dimension vectors by a local embedding model — embedding never requires a paid API. The vectors live in PostgreSQL with the pgvector extension.

When any agent works, a semantic search — cosine similarity with a recency boost — pulls the most relevant chunks into its context before it answers. Agents ground their answers in your actual documents, not guesses. The Brain is also a workspace in its own right: markdown vault notes that agents and you both read and edit, a knowledge-graph view of how notes connect, and an MCP endpoint that lets external LLMs search it (see Integrations below).

Sourcesuploads · chat ·meetings · task resultsExtractOffice/PDF → markdown(automatic)Chunk~500-token pieces,64-token overlapEmbed768-dim vectors,computed locallyStorePostgreSQL + pgvector,deduped by hashSemantic searchcosine similarity +recency boostInjected into agent contexttop matches added beforethe agent answersAlso part of the Brainmarkdown vault notes agents and you both edit · a knowledge-graph view · an MCP endpoint for external LLMs

Grounded in lib/brain/ingest.ts · lib/brain/index.ts · app/api/files/upload/route.ts · app/api/brain/ — docs: The Brain

Example of use

You say: “(you upload competitor-pricing.xlsx, then a week later ask:) How do our prices compare to competitor X?”

  1. At upload time the sheet was converted to Markdown, chunked, embedded, and indexed — automatically.
  2. Your question is embedded and searched against every chunk in the Brain.
  3. The exact rows from that spreadsheet arrive in the agent's context before it writes a word.
  4. The answer cites your real numbers — and the agent can write its comparison back as a new note.

The Filekeeper

Knowledge bases rot without a caretaker, so the platform seeds one. The Filekeeper is an agent whose only job is Brain and file hygiene: it sorts the inbox into the right folders, resolves strays and duplicates (preferring to edit an existing note over creating a new one), and maintains Status/Latest-Work.md — a one-page running record of what every team and project is currently doing. It operates under a hard rule: it never deletes a note without asking you first.

Unsorted notesinbox/, strays,duplicatesThe Filekeeperseeded hygiene agent —never deletes withoutasking you firstSorted foldersPersonal/ Business/ Teams/Projects/ Meetings/Status/Latest-Work.mdone page: what every teamand project is doing now

Grounded in lib/default-skills.ts (FILEKEEPER_TEAM) — docs: The Brain

Example of use

You say: “Clean up the Brain inbox.”

  1. The Keeper delegates to the Filekeeper with your instruction.
  2. It searches for duplicates before touching anything, then moves notes into the standing folder structure — Business/, Teams/, Projects/, Meetings/.
  3. It updates Status/Latest-Work.md so the one-page picture of work in progress stays current.
  4. It reports exactly what it moved and created — and asks before deleting anything at all.

Server-Control Agents

Agents on this platform can operate a real server — stated plainly, because it is both the most powerful capability here and the one you should understand before enabling. The vps_exec tool runs shell commands on a server you configure, over SSH: reading logs, restarting Docker Compose services, running migrations, moving files. A pattern blocklist rejects known-destructive commands before anything is sent. And the whole capability is off by default: without your SSH key in the environment (VPS_SSH_KEY), the tool cannot reach anything. You decide whether this door exists at all.

install_tool goes a step further — an agent can extend its own toolbox. Every requested package (npm, pip, or an MCP server) is safety-scored first against registry metadata, downloads, and license. Failing packages are blocked outright; low-scoring ones require an explicit second confirmation before anything installs. What does install is registered as a CLI function scoped to the requesting team, so the capability stays attributable.

vps_exec — shell accessAgent commande.g. docker composerestart dashboardPattern blocklistknown-destructivecommands rejectedSSH to your serverkey comes only fromyour environmentOutputreturned to theagent, cappedinstall_tool — safety-scored package installsPackage requestnpm · pip ·MCP serverSafety checkscore /10: registry,license, downloads —failures blockedInstall over SSHinto /opt/agent-toolson your serverTeam functionregistered for therequesting teamapprovedlow scoreConfirm gatenothing installs without anexplicit second confirmationOff by default: without your SSH key in the environment, neither tool can reach any server

Grounded in lib/chat-tools.ts (vps_exec, install_tool) · lib/tool-installer/installer.ts — docs: Tool catalog

Example of use

You say: “The dashboard container looks unhealthy — check why and restart it.”

  1. The agent runs docker ps and a log tail on your server through vps_exec; each command passes the blocklist first.
  2. It reads the error from the output, restarts the service with docker compose, and verifies it came back healthy.
  3. The capped command output lands in your chat — you see exactly what was run and what came back.

Projects

Client work, experiments, and demos need isolation — and a clean exit. A project gets its own file folder (projects/<slug>/), and every file tool used by any team working inside the project is locked to that folder server-side. It gets its own Brain namespace (project:<slug>) so project notes never leak into your global knowledge. Tasks, plans, and chats created inside it all carry the project’s ID. Teams are only ever borrowed by reference — project work never modifies a team’s configuration.

When it’s over: Delete shows a full preview of every trace — folder size, tasks, chats, plans, which teams get unlinked — then removes it all in one tap. No residue, no cleanup sessions.

Project: client-demo — everything inside carries the labelOwn folderprojects/client-demo/ —file tools locked insideOwn Brain namespaceproject:client-demo —notes stay in itLabeled recordstasks, plans and chatsall carry the projectIdProject workspacedashboard, chat, files,schedule, settingsYour teamsborrowed by reference —configs never modifiedDelete projectshows a full preview ofevery trace firstOne-tap cascade teardown — folder, namespace, tasks, chats, plans. Zero residue.

Grounded in lib/tool-context.ts · app/api/projects/ — docs: Playgrounds vs. projects

Example of use

You say: “Create a project for the client demo we're building this week.”

  1. The project appears with its own dashboard, chat, files, and schedule.
  2. Every team you pull in writes files only into the project's folder and notes only into its namespace.
  3. Demo's done: Delete previews 14 files, 6 tasks, 2 chats — one tap and every trace is gone. Your teams are untouched.

The Playground Library

Playgrounds are portable. Any playground you build — its teams, agents, and skills — exports as a pack: a zip with a declarative manifest. Installing one is just as direct: upload a zip, one-click a free pack from the catalog, or redeem a code for a paid pack. An install creates a real, working playground in your sidebar in seconds, running on your own API keys.

This is how finished setups move between people: polish a playground once, export it, and a friend — or a customer — installs the identical thing on their machine. Paid packs are fulfilled with single-use redemption codes. Inside the app, the Store is the browsing surface for the catalog.

Your playgroundteams, agents, skills —workingExport as packone click →zip manifestPack .zipportable andsellableshare it, or sell it with a redemption codeInstallupload · free one-click· redeem a codeA real new playgroundlive in the sidebar with itsteams — on your own keys

Grounded in lib/library-packs.ts · app/api/library/install/route.ts — docs: Browse & install, Export as pack

Example of use

You say: “(you've built a support-desk playground you're proud of) Export it and send it to a friend.”

  1. Playground settings → Export downloads a pack zip: teams, agents, skills, all declared in a manifest.
  2. Your friend opens the Store in their own install, uploads the zip — or redeems the code you issued.
  3. Seconds later the same playground is live in their sidebar, running on their keys, not yours.

The Local-LLM Flywheel

The platform is designed to get cheaper the more you use it. Every dispatched task first passes a rules-based classifier that costs nothing to run: does this genuinely need a frontier API model, or can a small local model handle it? Classification, extraction, and reformatting tasks route to local models via Ollama at zero token cost when the classifier is confident; complex reasoning, live web work, and long tool chains go to the API.

Two feedback loops close the flywheel. Every completed result is archived into the Brain, so the next agent starts with more context and does less work. And a protocol writer evaluates completed API tasks for repeatable patterns, writing them down as playbooks — over time, more of your routine work qualifies for the free local path.

Task dispatchedfrom chat, router,meetings, plansClassifierrules-based, zero cost:can a local modeldo this?yes, confidentLocal modelsmall models via Ollama— zero token costotherwiseAPI modelcomplex reasoningonlyArchived in the Brainevery result becomescontext for the next taskProtocol writerrepeatable API tasks becomewritten playbooksmore work routes localas protocols accumulate

Grounded in lib/agents/runner.ts · lib/optimizer/classifier.ts — docs: Ollama (local models)

Example of use

You say: “Tag these forty leads by industry.”

  1. The classifier recognizes an extraction/classification task and routes it to a small local model — confidence high, token cost zero.
  2. The tagged list comes back and is archived into the Brain like any other result.
  3. Next month's batch runs the same way — and the archived result is already in context when a bigger task asks about those leads.

Integrations

The coordinator has more than one door. Telegram is bidirectional: message the Keeper from your phone, ask questions with /ask, save notes with /note, search the Brain with /brain — plain messages are captured into the vault automatically. Any MCP-capable LLM client — Claude Desktop, ChatGPT, Cursor — can connect to the platform’s MCP endpoint and drive it with eleven tools: search the Brain, read and write vault notes, list teams, ask a team a question, create and dispatch tasks. External clients are tracked in an API monitor so you always know who called what.

And the platform never assumes one model vendor. Anthropic, OpenAI, NVIDIA, and local Ollama are first-class providers; every agent and every meeting participant can be pinned to its own model, with graceful fallback when a provider is unavailable.

AgentPlaygroundone coordinator,many doors inTelegramtalk to the Keeper fromyour phone — both waysn8n workflowsautomations push notesand data into the BrainMCP clientsClaude Desktop · ChatGPT ·Cursor — 11 toolsModel providersAnthropic · OpenAI · NVIDIA· Ollama — pinned per agent

Grounded in lib/integrations/telegram/bot.ts · app/api/mcp/route.ts · lib/providers/ — docs: Telegram, Drive it from any LLM

Example of use

You say: “(from Claude Desktop, connected over MCP) What does my playground know about the July launch? Dispatch a task to prepare the assets.”

  1. Claude Desktop calls vault_search over the MCP endpoint and reads back your launch notes.
  2. It calls dispatch_task — the task is created and executed by your team on your platform, exactly as if you had typed it in the app.
  3. The call shows up attributed in the API monitor.

Where This Is Going

Roadmap — none of this is shipped yet. Everything above this box is.

  • Permission rings. Three-tier tool-layer enforcement: fully autonomous, autonomous with an audit log, and owner-approves-with-one-tap for anything touching money, keys, or deletion. Enforced in the tool layer — prompts can be injection-attacked, tool scopes cannot.
  • n8n workflow authoring. Today n8n pushes data into the Brain. The next step is agents creating and modifying their own n8n workflows — automations that stay visible and inspectable by humans, with every change recorded.
  • Agent-driven deployment. Agents deploying and restarting their own containers and requesting their own subdomains — gated entirely by the permission rings above.
  • Multi-instance federation. Agent teams living once on a master instance, with separate business instances delegating work across to them — one set of capabilities serving many isolated operations.

See it doing your work.

Download it free and run it on your own machine, read the docs, or have us deploy it on a private server configured for your business.