Building a team

How to create and run AI agents using Envelope's workspace — describe what you need, refine the design in conversation, and have AI agents running in minutes.

What this guide covers

You build a team: a set of AI agents with declared roles, a structure (who coordinates whom), and the inputs and outputs the team works with. The whole process happens in the workspace room thread — no JSON, no API calls, no code.

1. Start in your workspace

Go to /workspace and describe the team you want to build. The assistant will ask clarifying questions and propose an agent composition.

Good prompts are outcome-oriented:

"I need a team that reads incoming support tickets, categorises them by urgency, drafts a response, and flags anything above a certain severity for human review before sending."

You don't need to know how many agents, what roles they should have, or what the hierarchy looks like — the assistant will propose all of that and explain its reasoning. You can push back, adjust, or start over at any point.

Attaching reference files — Use the paperclip button in the chat input to attach a file (.txt, .md, .csv, .json, or .pdf up to 5 MB). The contents are included as read-only context for that message — useful for sharing a sample dataset, a spec document, or an example input so the assistant designs agents around your real material rather than hypothetical examples.

2. Review the proposed team

Once the assistant has enough context it will show you a team composition — typically a coordinator agent and one or more specialist agents. For each agent you'll see:

Name and title — the human-readable identity of the agent
Role — manager or specialist
What it does — a plain-language description of its responsibilities
Who it reports to — the reporting structure

If the composition doesn't look right, describe the changes in the chat. "Add a research step before the drafting step" or "remove the escalation agent, I want that handled manually" are both valid instructions.

3. Refine in the thread

Continue the conversation to shape the team exactly how you need it. The assistant updates the design in real time — you don't need to edit any fields manually.

A few things that work well:

"Give the coordinator a more detailed brief — it needs to handle escalations explicitly"
"Add a required credential for our Zendesk integration"
"Add a human review step after the drafting step"
"Make the output a structured summary with subject, body, and severity"

Switch on the flask icon in the input bar at any point to run the team in test mode against a sample input and see what the agents actually produce. Keep refining until the output matches what you need.

4. Add human review gates (if needed)

If your team produces outputs that should be reviewed before continuing — email drafts, outbound messages, enriched records — ask the assistant to add a gate:

"Add a review gate after the email drafter. Show the reviewer the subject and body. If they reject it, re-run the step."

Describe what you need in the thread and the assistant will configure it:

Which step the gate sits after — when it activates
What fields are shown to the reviewer — what they'll see when the run pauses
What happens on rejection — re-run the step, escalate, or halt

When a gate triggers during a run, an amber card appears inline in the thread with the content to review and an Approve & continue button.

5. Test and run

Use the flask icon in the input bar at any time to trigger a test run — this runs each agent with sample data and shows the results inline. It's safe to use at any point without side effects.

When you're ready to run against real data:

Shift+R — triggers a real run
flask icon — triggers a test run

Run results appear inline in the thread as they complete. If something doesn't look right, describe the problem and the assistant will adjust the design.

6. Set a schedule (optional)

After the test, a schedule card appears directly in the thread. Pick one of the presets:

Every weekday 9am — runs Monday to Friday each morning
Every Monday 9am — runs once a week to start the week
Daily at noon — runs every day at midday
Every hour — runs continuously on the hour
Custom — set your own frequency, time, and timezone

If you don't set a schedule, you trigger runs manually with Shift+R whenever you need them. To change the schedule later, just describe it in the thread — "run this every Monday morning" — and the schedule card reappears.

Every team starts as a draft — only you can see and run it. The status strip directly below the room header shows the current state: Private · v1 draft.

To change visibility, click the visibility label in the strip to open a dropdown — or describe it in the thread:

Private — only you. The default while you're building.
Team — everyone in your organisation can find and run it, but it won't appear in the public Library. Use this for internal teams.
Public — listed in the Library for anyone to find and install. Setting to Public publishes the team and the label changes from "v1 draft" to "v1".

Distribution settings — appear in the status strip once visibility is set to Public:

Billing model — Free by default. Click to change to per run or per 1K tokens if you want to charge deployers.
Allow forking — when checked, anyone can copy your team into their own workspace and customise it.

You can also say "set pricing and publish to the library" in the thread and the assistant will walk you through it.

For updating a team after it's been published without breaking existing installs, see the versioning guide.