Author a custom agent.

What an agent is

A CloudSwarm agent is a named, versioned unit that combines: a plan (written in plain English), a skill bundle, a policy envelope, a trigger, a trust tier, and a budget. Every agent runs inside the R1 runtime; the runtime is what makes the agent reliable across retries, timeouts, and partial failures.

Five things to decide before you build

• What should happen. One or two sentences, plain English.
• Which inputs the agent reads. Inboxes, forms, webhooks, schedule.
• Which outputs the agent writes. Drafts, messages, DB rows, purchases.
• What the agent must never do. Goes into the Cedar policy.
• Where the human enters the loop. Every action, outliers only, or never.

Compose skills

Open the agent builder. The left panel is the skills catalog; the center panel is your agent's flow; the right panel is configuration.

• Drop skills into the flow in the order they run.
• Each skill has typed inputs and outputs; the builder auto-wires them where it can.
• When a skill requires credentials, an authorize button appears; click through OAuth or paste an API key.
• Credentials live in the workspace vault, scoped to this agent at least-privilege.

Set credentials

Credentials are per-skill, per-agent. If two agents both use Gmail, each gets its own credential handle; revoking one does not affect the other. The vault is append-only and rotates short-lived tokens automatically.

Define cadence

Three trigger shapes:

• Schedule. Cron expression (5 fields). Timezone-aware. The next three fires are previewed.
• Event. Incoming webhook, file change, mail arrival, external watcher signal.
• Manual. A human clicks run; typical for one-off research or draft work.

Write policy

Every agent inherits its workspace's policy envelope; you can narrow further on the agent. Policies are in Cedar. A minimal agent-level policy might look like:

permit (
  principal == Agent::"shopify-review-responder",
  action    == Action::"email:send",
  resource  in  List::"customer-contacts"
);

forbid (
  principal == Agent::"shopify-review-responder",
  action    == Action::"payment:charge"
);

Policy is a ceiling, not a floor. The agent cannot do anything the policy doesn't permit, regardless of what the plan says.

Choose a trust tier

New agents start at L0 or L1. Read the trust model for the full tier ladder. Most custom agents stay at L1 for a week of supervised runs before promotion to L2 or L3.

Test and ship

• Run the full agent in dry-run mode; nothing leaves the workspace.
• Review every step's input and output in the inspector.
• When it looks right, click "set live" and the agent starts at L1.