AGNT Studio

Prompts are not code. They're natural language. They're the one artifact that humans will always want to read, tweak, and iterate on — long after AI writes 100% of the application code around them. Burying them in a codebase alongside TypeScript and YAML makes no sense. It's like editing blog posts by SSH-ing into a server — that's what everyone did in 2005, until CMSes made it obsolete.

AGNT Studio is the CMS for prompts. Manage them like content, not source code. API-first design — agents are the primary users — with a companion visual editor for humans.

Why AGNT Studio

Here's how most teams manage prompts today:

# somewhere in your codebase...
SYSTEM_PROMPT = """You are a helpful customer support agent for {company}.
Be friendly and concise. Always offer to escalate..."""

Changing a single word requires a code change, a PR review, a deploy, and a prayer that nothing breaks. Your product manager can't tweak the tone. Your prompt engineer can't test a different instruction set. Your support team can't update the FAQ response without filing a ticket.

AGNT Studio has two UIs: the API (the primary interface, designed for coding agents) and the AGNT Studio app (a companion editor for humans). Both have full access to the same system. An agent can create a prompt, iterate on it via traces, publish it, and monitor it in production — entirely through the API. A human can do the same thing in the AGNT Studio app. Or both can work on the same prompt at the same time.

The before and after

Without AGNT Studio:

1. Want to change a prompt -> open the codebase
2. Find the right string/file
3. Make the edit, open a PR
4. PR reviewed, merged, deployed
5. Hope it works in production
6. Something's off -> repeat from step 1

With AGNT Studio (agent):

1. GET /traces -> find the underperforming call
2. POST /playground/sessions -> open trace in playground
3. PATCH /blocks -> tweak the prompt, POST /run -> re-run
4. POST /save -> save edits to draft
5. POST /publish -> production serves new version immediately
6. Something's off -> POST /rollback

With AGNT Studio (human):

1. Open trace in AGNT Studio, see the exact prompt and response
2. Click into playground, edit the block, re-run
3. Save -> publish -> live immediately
4. Something's off -> one-click rollback

Quick Start

1. Create a tenant

# Sign up
curl -X POST https://studio.agnt.ai/api/v1/auth/signup \
  -H "Content-Type: application/json" \
  -d '{"email": "you@company.com", "name": "Your Name"}'

# Create a tenant (workspace)
curl -X POST https://studio.agnt.ai/api/v1/tenants \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Company", "slug": "my-company"}'

2. Create an agent

curl -X POST https://studio.agnt.ai/api/v1/tenants/$TENANT_ID/prompts \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "customer-support",
    "title": "Customer Support Agent",
    "description": "Handles customer inquiries"
  }'

This creates an agent with the default scaffold: system.md, models.json, variables.json.

3. Add content

# List the files (system.md was auto-created)
curl https://studio.agnt.ai/api/v1/tenants/$TENANT_ID/prompts/$PROMPT_ID/files \
  -H "Authorization: Bearer $TOKEN"

# Add a block to system.md
curl -X POST https://studio.agnt.ai/api/v1/tenants/$TENANT_ID/prompts/$PROMPT_ID/files/$FILE_ID/blocks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "text",
    "content": "You are a helpful customer support agent for {company_name}. Be friendly, concise, and always offer to escalate to a human when the customer seems frustrated."
  }'

Notice {company_name} — AGNT Studio auto-detects this and adds it to your variables roster.

4. Add variables

curl -X POST https://studio.agnt.ai/api/v1/tenants/$TENANT_ID/prompts/$PROMPT_ID/variables \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "company_name",
    "type": "string",
    "required": true,
    "defaultValue": "Acme Corp",
    "source": "caller"
  }'

5. Compile

curl -X POST https://studio.agnt.ai/api/v1/tenants/$TENANT_ID/prompts/customer-support/compile \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "variables": {
      "company_name": "Acme Corp"
    }
  }'

Returns the full compiled manifest: system message, tools array, model config — ready to send to any LLM.

6. Publish and deploy

# Create an environment
curl -X POST https://studio.agnt.ai/api/v1/tenants/$TENANT_ID/environments \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Production", "slug": "production", "isPrimary": true}'

# Publish (creates an immutable version)
curl -X POST https://studio.agnt.ai/api/v1/tenants/$TENANT_ID/prompts/customer-support/publish \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"environmentId": "'$ENV_ID'"}'

# Deploy
curl -X POST https://studio.agnt.ai/api/v1/tenants/$TENANT_ID/prompts/$PROMPT_ID/deployments \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"environmentId": "'$ENV_ID'"}'

7. Use in your app (via studio-node)

import { StudioClient } from '@agnt/studio-node';

const studio = new StudioClient({
  tenantId: 'your-tenant-id',
  apiKey: 'your-api-key',
  environment: 'production'
});

// Get the compiled prompt — always the latest deployed version
const prompt = await studio.compile('customer-support', {
  variables: { company_name: 'Acme Corp' }
});

// prompt.system -> compiled system message
// prompt.tools -> tool definitions array
// prompt.model -> model config

// Pass to your LLM client
const response = await anthropic.messages.create({
  model: prompt.model.name,
  system: prompt.system,
  tools: prompt.tools,
  messages: [{ role: 'user', content: userMessage }]
});

// Trace is auto-created in AGNT Studio for observability

Now anyone on your team can update the prompt in AGNT Studio's editor — no code change, no deploy needed.

Core Concepts

The Mental Model

An agent in AGNT Studio is a folder:

my-support-agent/
  system.md          <- System instructions (block document)
  messages/
    greeting.md      <- User-facing message
    escalation.md    <- Escalation instructions
  variables.json     <- Variable contract ({user_name}, {plan_tier})
  tools.json         <- Tool definitions
  models.json        <- Model config (provider, temperature, etc.)

Two operations:

1. Compile — turn the folder into an LLM API call (resolve variables, evaluate conditions, flatten blocks, map to API fields)
2. Export — send the folder somewhere (download, GitHub, runtime feed)

Everything else — versioning, conditions, library references, environments — layers on top of this.

Blocks

Every .md file is an ordered list of blocks. Blocks are the atomic unit of content.

A block can be:

• Inline — text you write directly
• Library reference — linked to a reusable block from your library

Library references stay linked: update the source once, every agent that uses it sees the change. This is how you maintain consistency across dozens of agents.

Block types: text, heading, divider, variable, component_ref, assistant_ref, skill_ref

Variables

Variables are the contract between your app and your prompt. They define what values flow in at compile time.

{
  "key": "plan_tier",
  "type": "enum",
  "enumValues": ["free", "pro", "enterprise"],
  "required": true,
  "source": "caller"
}

Types: string, number, boolean, enum, file

Variables power two things:

1. Interpolation — {user_name} in any .md block resolves to the provided value
2. Conditions — plan_tier == 'enterprise' determines which blocks/files are included

Conditions

Any block, file, or folder can be conditionally included based on variable values.

system.md
  block: base instructions        <- always
  block: enterprise compliance    <- if: plan_tier == 'enterprise'
  block: spanish greeting         <- if: language == 'es'

One prompt blueprint produces different compiled outputs depending on who's calling. No duplication needed.

Operators: eq, neq, gt, lt, in, exists

Conditions support compound logic:

{
  "type": "compound",
  "logic": "AND",
  "conditions": [
    { "type": "leaf", "variable": "plan_tier", "operator": "eq", "value": "enterprise" },
    { "type": "leaf", "variable": "language", "operator": "eq", "value": "en" }
  ]
}

Library

A shared collection of reusable blocks, variables, tools, and skills. Everything in the library can be referenced from any agent.

Impact analysis: Before changing a library item, call GET /library/:type/:name/impact to see exactly which agents use it.

Environments & Versions

Think Git for prompts:

• Draft — your working copy (edit freely)
• Publish — creates an immutable version snapshot (like a commit)
• Environment — a deployment target (staging, production)
• Deploy — activate a version in an environment
• Rollback — revert to the previous version in one call

Diff any two states: draft vs. production, staging vs. production, version 5 vs. version 12.

Skills & MCP

Skills are importable instruction sets that live in the library. They follow the public skill convention:

mcp-builder/
  SKILL.md              <- Entry point
  reference/            <- Supporting docs
  scenarios/            <- Contextual variants
  scripts/              <- Helper scripts
  assets/               <- Images, PDFs, etc.

Skills and tools support two delivery modes:

The compiler auto-generates MCP meta-tools. You don't write them — same source data, different compile target. Toggle at deploy time.

API Reference

Base URL: https://studio.agnt.ai/api/v1

All tenant-scoped endpoints: /api/v1/tenants/:tenantId/...

Auth: Bearer token in Authorization header. Response shape: { data: ... } for single items, { data: [...], pagination: {...} } for lists.

Auth

Tenants

Prompts (Agents)

List filters: status, search, tags (comma-separated), folderId, page, per_page

Files

Blocks

Block create/update body:

{
  "type": "text",
  "content": "Your instruction text here with {variables}",
  "order": 0
}

For library references:

{
  "type": "component_ref",
  "componentId": "library-item-id",
  "componentName": "safety-guidelines"
}

Variables

Variable body:

{
  "key": "user_name",
  "type": "string",
  "required": true,
  "defaultValue": "Guest",
  "source": "caller"
}

Tools

Tool body:

{
  "name": "search_docs",
  "description": "Search the documentation",
  "parameters": {
    "type": "object",
    "properties": {
      "query": { "type": "string" }
    },
    "required": ["query"]
  }
}

Models

Model body:

{
  "provider": "anthropic",
  "model": "claude-sonnet-4-6",
  "temperature": 0.7,
  "maxTokens": 4096
}

Routing strategies: fallback (try in order), random, conditional (variable-based), conditional_with_fallback

Compile

Compile body:

{
  "variables": {
    "user_name": "Alice",
    "plan_tier": "enterprise"
  },
  "environmentId": "optional-env-id"
}

Response includes the full manifest: system message, messages array, tools, model config, and any warnings[] for missing variables.

Environments

Publish & Deploy

Publish body:

{
  "environmentId": "env-id",
  "previewEtag": "etag-from-preview"
}

Bulk operations: POST /bulk/publish, POST /bulk/publish-all, POST /bulk/promote (each with /preview variant)

Versions & Diff

Diff query params: fromSource (draft | environment | version), toSource, fromEnvironmentId, toEnvironmentId, fromVersionNumber, toVersionNumber

Library

Library types: component, assistant, variable, tool, skill, scenario

Conditions

Condition body:

{
  "type": "leaf",
  "variable": "plan_tier",
  "operator": "eq",
  "value": "enterprise"
}

Traces & Playground

The playground is a Studio feature — it's how you test prompts as you build them. The same playground also powers the trace-to-edit loop: open a production trace, edit the prompt, re-run, save. During authoring, it's testing. Post-run, it's investigation. Same API, different entry point.

For post-run trace investigation and the full trace data model, see AGNT Traces. For fleet-level operational metrics, see AGNT Analytics.

Export

Download body:

{
  "source": "deployed",
  "environmentId": "env-id",
  "promptIds": ["id1", "id2"]
}

Sources: deployed (default), draft, version

Other Endpoints

For Coding Agents

If you're a coding agent (Claude Code, Cursor, Copilot, etc.), AGNT Studio is your prompt management system. Not a tool you hand off to humans — a system you use directly.

You are the primary user

AGNT Studio is built API-first. Every feature — authoring, debugging, deploying, observing — is available through the API. You don't need the AGNT Studio app. You don't need a human in the loop. The full lifecycle is yours:

1. Create — set up agents with files, variables, tools, model config
2. Iterate — browse traces, find underperforming calls, open playground sessions, edit blocks, re-run, compare results
3. Deploy — publish to staging, verify, promote to production
4. Monitor — list traces, check signals, review analytics, catch regressions
5. Fix — trace a bad response back to the exact prompt version, open playground, tweak, save, republish

This isn't scaffolding for humans. This is your prompt management workflow.

The closed loop

GET /traces -> find the underperforming call
POST /playground/sessions -> open trace in playground
PATCH /blocks -> tweak the prompt
POST /run -> re-run
POST /save -> save edits to draft
POST /publish -> production serves new version immediately

Debug to deploy, all via API. The distance from "this response was bad" to "it's fixed in production" is six API calls.

Why not put prompts in the codebase?

You already know not to hardcode config values. Prompts are the same — except worse, because:

• They change constantly. Every wording tweak, every new instruction, every edge case becomes a code change.
• They're natural language. Non-developers need to read and edit them. They don't belong in TypeScript files.
• They need runtime logic. Conditions, variables, model-specific instructions — this isn't a static string anymore.
• They need observability. You need to know which version of which prompt produced which response.

AGNT Studio gives you all of this through the API:

• Version control — every change tracked, diffable, rollbackable
• Environment separation — staging and production, no feature flags needed
• Runtime compilation — conditions, variables, and context-dependent content compiled per request
• Observability — trace every call, diff any version, replay in playground

Integration via studio-node

import { StudioClient } from '@agnt/studio-node';

const studio = new StudioClient({ tenantId, apiKey, environment: 'production' });
const prompt = await studio.compile('my-agent', { variables: { user_name: 'Alice' } });
// prompt.system, prompt.tools, prompt.model — ready for any LLM SDK

studio-node is the open-source runtime client. It handles compilation, caching, and automatic trace ingestion. Your app calls studio.compile() instead of building prompt strings — and gets versioning, conditions, variables, and observability for free.

For Product Teams

• Update prompts without redeploying. Change any prompt in AGNT Studio's editor. Hit publish. Your production app serves the new version immediately. No code change, no CI/CD, no downtime. Roll back in one click if something goes wrong.
• Static prompts are not enough. A hardcoded prompt string is fine for a prototype. In production, the same agent needs to behave differently depending on who's calling — different languages, plan tiers, use cases. That means conditions, variables, and runtime compilation. AGNT Studio handles this natively.
• Reusable building blocks. Write your safety guidelines once. Reference them from every agent. Update the source, every agent updates. No copy-paste drift.
• Version control built in. Every publish creates an immutable snapshot. Diff any two versions. Full audit trail of who changed what and when.
• The trace-to-edit loop. See a production response you don't like? Open the trace, edit the prompt, re-run, save. Closed loop. No developer needed. Minutes, not sprint cycles.
• Collaboration. Your prompt engineer, your product manager, and your AI coding agent all work on the same prompt. Comments, suggestions, reviews — the full workflow. Prompts are natural language — collaboration should feel like writing, not like coding.