What is an agent spec?
An agent spec is the document Envelope produces when you finish designing your AI agents. It captures everything about the design in a single structured file — who the agents are, what each one is responsible for, which tools they can use, how they hand work to each other, and where a human needs to review before the next step runs.
Think of it like a design brief or an architectural diagram, but machine-readable. Your IT team or engineers can take the file and implement the agents directly, without needing to interpret notes or attend a handoff meeting.
What's inside
An agent spec describes your AI agents in plain terms:
Agents and their roles — each agent has a name, a clear responsibility, and a position in the design. An agent might be "Lead Researcher", "Outreach Writer", or "Triage Agent" — whatever matches the actual work.
Skills and instructions — every agent has a system prompt: the instructions that define what it knows, how it behaves, and when it should escalate. This is what makes an agent good at its job rather than generic. The spec stores these instructions per agent — they're your IP and are never shown to people who install the design.
Which model each agent runs on — each agent can run on a different AI model. An orchestrating manager might run on a frontier model for reasoning and synthesis; a classifier or formatter might run on a faster, cheaper model for throughput. The spec records this decision per agent so it's preserved when the design is handed off or installed.
What each agent can access — the tools and integrations each agent can reach. If an agent reads from HubSpot and writes to Slack, the spec declares that. Access is also scoped by policy — each agent can only call the external services it's explicitly permitted to reach.
How work moves between agents — who delegates to whom (the reporting hierarchy), which agents run in sequence and which run concurrently, and the explicit dependencies between pipeline steps.
Where humans are involved — any approval gates placed in the design. The spec records where the pipeline pauses and waits for a person to review before the next step runs — including what kind of review is needed and what happens if they reject it.
What the agents need to run — a list of credentials and configuration values the agents require (API keys, account identifiers, queue names). The spec lists what's needed by name — it never contains the actual secrets.
What you do with it
Hand it to your IT or engineering team. The file contains everything they need to implement the agents. Point them to the Deploying from a spec guide.
Share it with stakeholders. Before implementation, share a read-only link so colleagues can review the design — which agents exist, what they do, and where humans are in the loop. No account required to view.
Export and version it. The file is safe to commit to Git — it contains no secrets, only structure. Teams often keep the spec alongside their other infrastructure files so changes are tracked and reviewable.
Run it directly. If your team uses Claude or ChatGPT with Envelope's MCP connection, you can run the agents from your AI tool without any engineering handoff.
The format
The spec exports as a .envelope.json file. The format is open (Apache 2.0) and validated against a published schema — which means any tool that supports the standard can read, validate, or run it.
You don't need to understand the format to design AI agents. Envelope generates it from your description. The format matters when it's time to hand off to engineering — and that's what the docs on the right side of this page cover.
→ Export your spec — how to download the file from the builder
→ Share a design — how to share a read-only link before exporting
→ Deploying from a spec — for your IT or engineering team
Frequently asked questions
What's the difference between an agent spec and a prompt? A prompt tells one AI model what to do. An agent spec describes an entire multi-agent workflow — multiple agents with distinct roles, the tools each one can use, how they hand work to each other, and where a human needs to review before the next step runs. It's a design document for an AI system, not an instruction for a single model.
Does the agent spec include my API keys or secrets? No. The spec lists which credentials your agents need — by name — but never stores the actual values. Secrets stay in your Envelope vault and are injected at runtime. An agent spec is safe to commit to Git and share with your engineering team.
Can I run AI agents without writing any code? Yes. Connect Envelope's MCP server to Claude.ai or ChatGPT and run the agents directly from your AI tool — no engineering handoff required. Or use the REST API to trigger runs programmatically from your existing tooling.
How do I know if my agent spec is valid?
Envelope validates your design in the workspace before you export. You can also validate any .envelope.json file manually against the open schema at schema.openenvelope.org/team/v1.json using any standard JSON Schema validator.