Swarm pipelines are sequential multi-agent workflows where each agent runs its own full agentic loop (LLM + tools) and passes its output forward to the next agent in the chain. Swarms replace cron-based Telegram-style polling coordination with direct programmatic orchestration -- agents execute in dependency order within a single, budget-controlled pipeline.
Endpoint
POST /internal/agent/swarm
This is an internal OIDC-authenticated endpoint on the agent executor service. It is not directly accessible to end users. The main API enqueues swarm requests via Cloud Tasks, and the agent executor processes them asynchronously.
Concept
A swarm is an ordered pipeline of autonomous agents. Each agent operates independently with its own model, system prompt, tools, and integrations, but receives the accumulated context from all preceding agents. Unlike ensemble consensus (which refines a single output through multiple models), swarm pipelines chain distinct stages of a workflow where each stage has a fundamentally different job.
+-------------------+ +-------------------+ +-------------------+
| Agent 1 | | Agent 2 | | Agent 3 |
| "Researcher" | | "Writer" | | "Editor" |
| | | | | |
| system_prompt | | system_prompt | | system_prompt |
| task_prompt | | + CONTEXT from | | + CONTEXT from |
| model + tools | | Agent 1 | | Agent 2 |
| | | model + tools | | model + tools |
| [agentic loop] |---->| [agentic loop] |---->| [agentic loop] |
| | | | | |
+-------------------+ +-------------------+ +-------------------+
| | |
v v v
Output A Output A + B Output A + B + C
(research) (draft post) (final polished post)
Why Swarms Replace Cron-Based Coordination
Before swarms, multi-step workflows required cron-based scheduling with message-passing through Telegram or webhook chains. Each agent ran independently on its own schedule, with no guaranteed ordering, no shared budget, and no automatic context passing. Swarms solve this by:
Guaranteed ordering via depends_on dependency resolution (topological sort)
Automatic context injection from predecessor outputs into successor system prompts
Unified credit budget enforced across the entire pipeline (max_total_credits)
Atomic failure handling -- the pipeline stops cleanly when an agent fails, preserving partial results
Request Body
Parameter Reference
Parameter
Type
Required
Constraints
Description
user_id
string
Yes
--
Authenticated user ID for credit billing.
task_id
string
No
--
Parent task ID for Firestore tracking and credential loading.
swarm_id
string
Yes
--
Identifier for this swarm pipeline. Used in Firestore records and logs.
plan
string
Yes
guru or pro
User plan. Determines rate limits and iteration caps per agent.
agents
array
Yes
1--10 agents
Ordered list of agents in the pipeline.
max_total_credits
float
No
>= 1
Credit budget for the entire swarm. Pipeline halts if exceeded. Default: 2000.
context
string
No
--
Additional context injected into the first agent's system prompt.
Agent Object
Field
Type
Required
Constraints
Description
name
string
Yes
Unique within swarm
Human-readable agent name. Used in context markers and Firestore records.
system_prompt
string
Yes
--
System-level instructions for this agent's role and behavior.
task_prompt
string
Yes
--
The specific task this agent must accomplish. Sent as the user message.
model
string
No
Valid model ID
LLM model for this agent. Default: claude-sonnet.
temperature
float
No
0.0--2.0
Model temperature. Default: 0.7.
max_tokens
integer
No
256--65536
Maximum tokens per LLM call. Default: 4096.
max_iterations
integer
No
1--25
Maximum agentic loop iterations. Default: 10.
tools
array
No
--
Tools available to this agent (e.g., http_get, api_call, http_post, webhook). Default: ["http_get", "api_call"].
integrations
array
No
--
Platform integration IDs for URL validation (e.g., newsapi, slack).
webhook_urls
array
No
HTTPS only, max 3
Webhook URLs this agent can call via the webhook tool.
depends_on
string
No
Valid agent name
Name of the agent whose output this agent requires. If omitted, agents execute in array order.
Dependency Resolution
The executor resolves agent execution order using topological sort on the depends_on graph. Agents without a depends_on field execute in array order, with each implicitly depending on the previous agent.
Algorithm
The _resolve_order() method walks the dependency tree recursively:
Build a name-to-agent map from the agents list.
For each agent, recursively visit its depends_on dependency first.
Track the current visit path to detect circular dependencies.
Append each agent to the ordered list once all its dependencies are resolved.
Cycle Detection
If the depends_on graph contains a cycle (e.g., A depends on B, B depends on A), the executor raises a ValueError with the message "Circular dependency detected: {name}" and the swarm fails immediately before any agent executes.
Context Injection Between Agents
The core mechanism that connects agents in a swarm is context injection. When an agent has a depends_on dependency, the predecessor's complete output is injected into the successor's system prompt:
Injection Rules
Condition
Behavior
First agent in pipeline
Receives global context field (if provided) as ADDITIONAL CONTEXT
Agent with depends_on
Receives predecessor's output between --- CONTEXT FROM PREVIOUS AGENT --- markers
Predecessor failed
No context injected (empty string). The dependent agent runs without predecessor context.
Predecessor completed
Full output text injected
No depends_on, not first
No context injection (runs independently)
Context injection happens at the system-prompt level so the agent treats predecessor output as authoritative background information, not as a user instruction. This prevents prompt injection from one agent's output affecting the next agent's core behavior.
Pipeline Mechanics
Agentic Loop Per Agent
Each agent runs a full agentic loop, identical to the standard single-agent execution:
LLM receives system prompt (with injected predecessor context) and task prompt as user message.
LLM may return tool_use content blocks.
Tools are executed server-side with DNS pinning, URL validation, and credential injection.
Tool results are fed back to the LLM as tool_result messages.
Loop repeats until the LLM produces a final text answer (no tool calls) or max_iterations is reached.
If max_iterations is exhausted without a final answer, the agent's last assistant text output is extracted and the agent completes with status max_iterations. The pipeline continues to the next agent.
Credit Budget Enforcement
Credits are enforced at the swarm level via max_total_credits, not per agent:
Before each agent starts, the executor checks the remaining budget.
Each LLM call within an agent's loop is charged through the main API's standard credit reservation system.
Credits accumulate across all agents.
If the budget runs out, the pipeline halts. Completed agents' results are preserved.
Credits consumed before exhaustion are not refunded.
Failure Handling
The pipeline stops immediately when any agent fails. This is a deliberate design choice -- downstream agents depend on predecessor context, so continuing after a failure would produce unreliable output.
Failure Mode
Behavior
LLM call error
Agent marked failed with error detail. Pipeline stops.
Tool execution error
Error returned to LLM as tool result. Agentic loop continues (LLM decides next step).
Budget exhausted
Pipeline halts before next agent. Completed agents preserved.
Max iterations
Agent completes with status max_iterations. Pipeline continues to next agent.
Each agent's result is stored in a subcollection, providing a complete audit trail:
SSE Events
When triggered via a streaming-capable endpoint, the swarm executor emits Server-Sent Events to report pipeline progress in real time. This enables frontends to show per-agent progress indicators.
agent_start
Emitted when an agent begins execution.
agent_done
Emitted when an agent completes (successfully or with failure).
On agent failure:
swarm_done
Emitted when the entire pipeline finishes.
On pipeline failure:
Plan Limits
Plan
Max Agents per Swarm
Max Iterations per Agent
Max Credits per Execution
Notes
Free
Not available
--
--
Swarms are not available on the Free plan.
Guru
5
10
100
Agent iterations and credits use Guru limits.
Pro
10
25
500
Full access to all swarm configurations.
Active Swarm Configurations
The platform provides five pre-configured swarm templates for common business workflows:
1. Content Pipeline
A three-agent pipeline for producing research-backed blog content.
Order
Agent
Model
Tools
Task
1
Trend Researcher
gpt-5.2 (T=0.3)
http_get, api_call
Identify trending topics and gather source material.
2
Blog Writer
claude-sonnet (T=0.7)
--
Write a structured blog post based on research findings.
3
Editor
gemini-3.1-pro (T=0.3)
--
Edit for clarity, tone, SEO, and factual accuracy.
2. Customer Success
A three-agent pipeline for onboarding analysis and proactive customer engagement.
Order
Agent
Model
Tools
Task
1
Onboarding Analyst
gpt-5.2 (T=0.3)
http_get
Analyze customer onboarding data and identify friction points.
2
Success Strategist
claude-opus (T=0.5)
--
Develop a retention strategy with milestones and triggers.
3
Comms Drafter
claude-sonnet (T=0.6)
--
Draft personalized outreach emails for each milestone.
3. Partnership BD
A three-agent pipeline for business development outreach.
Order
Agent
Model
Tools
Task
1
Opportunity Scout
gpt-5.2 (T=0.4)
http_get, api_call
Research potential partners and evaluate strategic fit.
2
Pitch Drafter
claude-sonnet (T=0.6)
--
Draft partnership proposals tailored to each prospect.
3
Follow-up Manager
gemini-3.1-pro (T=0.4)
--
Create follow-up sequences and objection handling scripts.
4. GTM Marketing
A three-agent pipeline for go-to-market content and outreach.
Order
Agent
Model
Tools
Task
1
SEO Strategist
gpt-5.2 (T=0.3)
http_get
Perform keyword research and competitive SEO analysis.
2
Content Creator
claude-sonnet (T=0.7)
--
Produce SEO-optimized content based on keyword strategy.
3
Outbound SDR
gemini-3.1-pro (T=0.5)
--
Generate personalized outreach sequences for target accounts.
5. DevOps Pipeline
A three-agent pipeline for incident response automation.
Order
Agent
Model
Tools
Task
1
Incident Analyzer
gpt-5.2 (T=0.2)
http_get, api_call
Analyze incident logs and identify root cause.
2
Runbook Generator
claude-sonnet (T=0.4)
--
Generate remediation runbook with executable steps.
3
Status Updater
gemini-3.1-pro (T=0.3)
--
Draft stakeholder communications and status page updates.
Use Cases
Content Pipeline (Research, Write, Edit)
The most common swarm pattern. A researcher agent gathers data using web tools, a writer produces structured content from the research, and an editor polishes for publication. Each agent's expertise is distinct -- the researcher needs tool access, the writer needs creative temperature, and the editor needs low-temperature precision.
Operational Automation
Swarms excel at multi-step operational workflows: incident analysis followed by runbook generation followed by stakeholder communication. Each step requires different domain expertise and produces a different output format.
Business Development
Scout potential opportunities, draft tailored pitches, and create follow-up sequences -- all in a single pipeline with budget controls. The dependency chain ensures each agent builds on the previous agent's work.
Example Request
Example Response
Error Handling
Error
HTTP Status
Description
INSUFFICIENT_CREDITS
402
User does not have enough credits for the estimated swarm cost.
An agent's model or tool call failed. Partial results returned.
INVALID_MODEL
400
An agent specifies a model not in the model registry.
On pipeline failure, the response includes all completed agent results and the failure detail for the failing agent. Credits consumed before the failure are not refunded.
Example dependency graph:
trend-researcher (no deps)
|
v
blog-writer (depends_on: "trend-researcher")
|
v
editor (depends_on: "blog-writer")
{agent.system_prompt}
--- CONTEXT FROM PREVIOUS AGENT ---
{previous_agent.output}
--- END CONTEXT ---
for each agent in ordered pipeline:
remaining_budget = max_total_credits - total_credits_consumed
if remaining_budget <= 0:
log "budget exhausted at agent {name}"
break pipeline
execute agent (each LLM call charges through main API)
total_credits_consumed += agent.credits_used
execution_id: string # UUID hex (generated by SwarmOrchestrator)
swarm_id: string # From request (e.g., "content-pipeline-swarm")
task_id: string # Parent task ID (if applicable)
user_id: string # Owner UID
status: "completed" | "partial" | "failed"
agents_completed: int # Count of successfully completed agents
agents_total: int # Total agents in pipeline
content: string # Final agent's output (truncated to 10K chars in response)
total_credits: float # Sum of all agent credit usage
tokens_in: int # Total input tokens across all agents
tokens_out: int # Total output tokens across all agents
error: string | null # Error detail if pipeline failed
created_at: timestamp
name: string # Agent name (e.g., "trend-researcher")
status: "completed" | "failed" | "max_iterations"
output: string # Agent's final text output
credits_used: float # Credits consumed by this agent
tokens_in: int # Input tokens for this agent's LLM calls
tokens_out: int # Output tokens for this agent's LLM calls
iterations: int # Number of agentic loop iterations used
duration_seconds: float # Wall-clock execution time
tool_calls: [ # Log of all tool calls made during execution
{
tool: string, # Tool name (http_get, api_call, http_post, webhook)
status: "success" | "blocked",
url: string, # Target URL
response_status: int, # HTTP response status code
latency_ms: float, # Round-trip latency
blocked_reason: string | null # Reason if blocked by security layer
}
]
error: string | null # Error detail if agent failed
POST /internal/agent/swarm
Authorization: Bearer <OIDC token>
{
"user_id": "uid_abc123",
"task_id": "agent_tasks/content-pipeline",
"swarm_id": "content-pipeline-swarm",
"plan": "pro",
"agents": [
{
"name": "trend-researcher",
"system_prompt": "You are a technology research analyst specializing in cloud infrastructure. Your research must include specific data points and authoritative sources.",
"task_prompt": "Identify the top 3 trending topics in edge computing for Q1 2026. For each, provide a summary, key statistics, and 3 sources.",
"model": "gpt-5.2",
"temperature": 0.3,
"max_tokens": 4096,
"max_iterations": 10,
"tools": ["http_get", "api_call"],
"integrations": ["newsapi", "perplexity"]
},
{
"name": "blog-writer",
"system_prompt": "You are a technical content writer. Write clear, authoritative content for a senior technical audience.",
"task_prompt": "Write a 1500-word blog post covering the edge computing trends identified by the researcher. Include code examples where relevant.",
"model": "claude-sonnet",
"temperature": 0.7,
"max_tokens": 8192,
"max_iterations": 5,
"depends_on": "trend-researcher"
},
{
"name": "editor",
"system_prompt": "You are a senior technical editor. Review for accuracy, clarity, tone, and SEO. Preserve the author's voice.",
"task_prompt": "Edit the blog post for publication. Check technical claims against the original research. Optimize headings for SEO.",
"model": "gemini-3.1-pro",
"temperature": 0.3,
"max_tokens": 8192,
"max_iterations": 3,
"depends_on": "blog-writer"
}
],
"max_total_credits": 2000,
"context": "Target: company engineering blog. Tone: professional but approachable."
}
