A TypeScript-first agent app kit. Write instructions in Markdown and tools in TypeScript, and get an agent you can run, inspect, approve and replay.
npm create plico@latest my-agent -- --provider anthropic
cd my-agent && npm install
npx plico run --dry . # no API key neededAdd a key to .env, run npm run dev, and chat with your agent in Studio.
Studio ships inside @plico-ai/cli. Every row above is one event from the run's log.
my-agent/
├── agent.md instructions, in Markdown
├── plico.config.ts model, provider, settings
├── skills/ Markdown the agent loads when it needs it
├── tools/ TypeScript tools, with approvals
├── evals/ cases that run in CI with no model, or live against it
├── artifacts/ files the agent produces
└── memory/
Everything is a file you can read, review in a pull request, and commit next to your app code.
Instructions are plain Markdown:
# Internal Ops Agent
You help the internal ops team triage requests.
- Use `create_ticket` to open a ticket.
- Use `close_ticket` only when the person asks. A person approves each call.Tools are typed TypeScript. The handler's input is inferred from inputSchema:
import { defineTool } from "@plico-ai/sdk";
export default defineTool({
name: "close_ticket",
description: "Close a support ticket. This cannot be undone.",
inputSchema: {
type: "object",
properties: { ticketId: { type: "string" } },
required: ["ticketId"],
additionalProperties: false,
},
capabilities: ["ticket:write"],
approval: { required: true, reason: "Closing a ticket cannot be undone." },
handler: async ({ ticketId }) => ({ ticketId, status: "closed" }),
});When the model calls close_ticket, the run pauses and Studio asks a person to approve it.
Declare an output schema in agent.md frontmatter or plico.config.ts to require a validated
structured result. The final run.completed event and run result include structuredOutput;
output stays text. GET /v1/schemas lets clients discover the declared shapes. See run schemas.
- File-first. The project is a directory tree. No hidden state, no code generation, no build step.
- One event log. Every run is a durable, replayable trace. Studio, evals, streaming and the HTTP API all read from it.
- Human approval. Mark a tool as needing approval and the run waits until someone decides.
- Studio included. Chat, inspect run events, review approvals, and diff the artifacts your agent writes.
- Evals without a model. Scripted cases replay in CI, so a change to a prompt or tool is checked in seconds.
- Any provider. Anthropic, OpenAI, Google, or any OpenAI-compatible endpoint (Ollama, OpenRouter, LiteLLM).
- Embeds in your backend.
createPlicomounts the API in Express, Hono or Next.js, tags runs with your own metadata, and leaves authentication to your app. - OpenTelemetry tracing. Export spans to the collector you already run.
| Package | Purpose |
|---|---|
create-plico |
npm create plico: scaffold a project |
@plico-ai/cli |
The plico command: validate, run, serve, eval, readiness |
@plico-ai/sdk |
defineTool and defineConfig for your project |
@plico-ai/server |
The HTTP API and createPlico for embedding |
@plico-ai/runtime |
The run loop and event store |
@plico-ai/core |
Project loading and validation |
@plico-ai/contracts |
Wire types |
Plico is a developer preview (0.1). The HTTP API under /v1 takes additive changes only; the TypeScript exports can change in any 0.x minor release. It needs Node 22.18 or later. Follow the milestones for what is planned.
- Quickstart: scaffold, run, and approve a tool call
- Project layout, Tools, Providers
- Approvals, Evals, Events, Upgrading, and how Plico compares
- Embed in a backend and the HTTP API
- Example: a refund agent and
examples/internal-ops-agent, complete projects - Build with an AI coding agent:
llms.txt, a scaffoldedAGENTS.mdand a Claude skill
See CONTRIBUTING.md to set up the repository and run the checks.
Apache-2.0. See LICENSE and NOTICE.
Eval runs save version 2 reports, including scores and trial transcripts, under
.plico/evals/<id>.json. Use plico eval --save-baseline to write evals/baseline.json
and commit it, then plico eval --baseline evals/baseline.json --tolerance 0.05
to fail on regressions. See the eval guide.
Report comparisons include newly added cases. Incomplete live cases retain completed trial transcripts, and report listings ignore unsupported schema versions.
Studio?s Evals view lets you browse saved reports, inspect trial transcripts with scores and judge reasons, and compare two reports side by side.
