Agents

The bundle declares what the agent is and what it can do. Deploy it and you get a callable resource.

swarmlord.jsonc

{
  "name": "morning-briefing",
  "model": {
    "providerId": "openrouter",
    "modelId": "~anthropic/claude-haiku-latest"
  },
  "instructions": "You are a concise morning-briefing assistant.",
  "mcps": ["sendblue"],
  "secretGrants": ["SENDBLUE_API_KEY_ID", "SENDBLUE_API_SECRET_KEY"],
  "triggers": [{ "kind": "cron", "expression": "0 9 * * 1-5" }],
  "command": {
    "status": { "template": "Summarize today's status in 3 bullets." }
  }
}

Fields

Field	Purpose
`name`	Stable handle. URLs and `swarmlord run <name>` reference this.
`model`	`providerId` + `modelId`. See Models below.
`instructions`	System prompt.
`mcps`	Built-in MCP ids — see MCPs.
`secretGrants`	Secret keys the agent is allowed to read.
`triggers`	Cron and webhook triggers that self-fire the agent.
`command`	Custom CLI subcommands.
`customTools`	JSON-Schema tool blocks the model can call.

JSONC comments and $schema URLs are supported. The full schema is published at https://api.swarmlord.ai/schema/swarmlord.json.

Models

Models are routed through OpenRouter, so any model listed at openrouter.ai/models is supported. Just paste the OpenRouter id into modelId:

{
  "providerId": "openrouter",
  // swap modelId for any id from openrouter.ai/models:
  "modelId": "anthropic/claude-opus-4.8"
  // "modelId": "openai/gpt-5.5"
  // "modelId": "google/gemini-3.5-flash"
  // "modelId": "x-ai/grok-4.3"
}

Use a ~vendor/model-latest alias to always run on the latest revision — e.g. ~anthropic/claude-sonnet-latest or ~openai/gpt-mini-latest. Override per-call with session.send(..., { modelId }) to try a different model mid-conversation. Billing tracks the actual model used, in USD.

Deploying

swarmlord deploy

Re-running upserts: same name → same agent id, new revision.

Calling

Every invocation creates a fresh session.

const session = await client.agent("morning-briefing").createSession();

Triggers

An agent can fire itself.

"triggers": [
  { "kind": "cron",    "expression": "0 9 * * 1-5" },
  { "kind": "webhook", "suffix": "github" }
]

Cron — standard 5-field expressions plus @hourly, @daily, @weekly. Resolution is one minute. Webhook — the platform mints POST /trigger/<userId>/<agentId>/<suffix>. POST anything to that URL (from GitHub, Stripe, Slack — anything) and the agent runs with the request body as input.

Custom CLI commands

"command": {
  "greet": { "template": "Say hello to ${1} in one sentence." }
}

$ swarmlord greet Zach
Hello Zach! Hope you're having a fantastic day.

Templates support ${1}, ${2}, and named flags. The CLI dispatches the resolved prompt against the agent.

Get started

Concepts

Guides

Fields

Models

Deploying

Calling

Triggers

Custom CLI commands

​Fields

​Models

​Deploying

​Calling

​Triggers

​Custom CLI commands

Fields

Models

Deploying

Calling

Triggers

Custom CLI commands