Alert triage, threat intelligence research, phishing review, vulnerability prioritization and incident report drafting, run as agent teams on the Swarms API with analysts approving every action.
Alert stream
Triage funnel
claude-sonnet-5-5
grouping by host, account and time window
human
reads the proposed verdict and the evidence lines
Boundaries
A security team's first question is what an agent can touch. The answer on this page is text in, text out. The left box is the standing rule set; the right is where the text comes from.
No autonomous containment
Agents do not isolate hosts, disable accounts, block domains or kill processes. They propose; an analyst carries out any action through the tools the team already uses.
No credential handling
Agents are never given passwords, tokens, API keys for your systems or console sessions. The request contains alert text and log excerpts, and that is all they see.
No silent verdicts
Every verdict is a proposal with its evidence lines. An analyst confirms, changes or rejects it, and both the proposal and the decision are kept.
No following links or detonating files
Reviewers reason from headers, URLs and text they are handed. Sandboxing and detonation stay with your existing tooling.
Analysts approve any action. The agents read, correlate and write.
SIEM
Correlated searches, saved-search results, notable events as text or JSON
EDR
Process trees, alert details and host timelines exported for a time window
Mail gateway
User-reported messages with headers, extracted URLs and body text
Identity provider
Sign-in logs, risk events and group changes for the accounts involved
Cloud audit logs
Control-plane events for the accounts and resources named in the alerts
Ticketing
The incident record the draft report and the agent run logs are attached to
Exports and read-only queries build the task string. Nothing writes back.
Architecture
Four stages in order: a question agent frames what must be answered, a research agent gathers the related events, an analysis agent maps indicators to tactics and techniques, and a synthesis agent drafts the report. Watch one cluster move through, then see the technique map fill in below.
Analysis Agent: waiting on research before mapping indicators.
Report sections
Question Agent waiting on the previous stage
Research Agent waiting on the previous stage
Analysis Agent waiting on the previous stage
Synthesis Agent waiting on the previous stage
Report is a draft. The analyst confirms the verdict and approves any action.
A fast model writes the questions: initial access, scope, persistence, exfiltration. Framing first keeps the research from wandering.
A long-context model gathers every related event and what is known about each indicator, citing the alert line it relies on.
A reasoning model maps each indicator to a tactic and technique with evidence and a confidence, and builds the likely timeline.
The strongest writer drafts the report in your sections, lists open questions plainly, and ends with next steps for the analyst to approve.
Use cases
Each card names the Swarms API swarm type it maps to and the agents you would send in the request. Every output is a proposal or a draft for an analyst or engineer to act on.
A question agent frames what must be answered about an alert cluster, a research agent gathers the related events and indicator context, an analysis agent maps indicators to tactics and techniques, and a synthesis agent drafts the incident report. The analyst confirms the verdict.
Raw alerts from the SIEM and EDR are deduplicated, correlated by host, account and time window, and given a proposed verdict (benign, suspicious, escalate) with the reason. The queue an analyst sees is the correlated set, with the proposed verdicts marked as proposals.
Vendor feed, open-source and internal telemetry agents each summarize what changed in the last day for your sector and stack, and an aggregator writes the digest with the items that touch assets you actually run on top.
User-reported emails go to three reviewers that examine headers, links and content independently and each vote malicious, suspicious or benign. The majority and any dissent go to the analyst who decides whether to pull the message from mailboxes.
A proposed detection rule is scored by judge agents for coverage of the technique, expected false positive rate against your log samples, and performance cost, and an aggregator writes the ruling. The detection engineer decides whether to deploy.
Exposure, exploit and asset agents review the week's scanner findings at the same time: what is reachable, what has a public exploit, what runs on it. The three views are returned together so the patch owner sees why an item is at the top.
Code
The Swarms API examples share one request shape: a name, a swarm_type, a task and a list of agents. Set SWARMS_API_KEY from your Swarms Cloud account before running. No example here has access to a console, a credential or a containment action.
import os
from swarms_client import SwarmsClient
client = SwarmsClient(api_key=os.environ["SWARMS_API_KEY"])
# A HeavySwarm runs four stages in order: question, research, analysis,
# synthesis. The alert cluster and the related events are pasted in; in
# production an integration builds this string from the SIEM. No agent here
# has access to a console, a credential or a containment action.
ALERT_CLUSTER = """
Cluster INC-2026-0419, first seen 2026-11-06 02:14 UTC, 7 alerts, 3 hosts.
- EDR: lsass.exe memory read by an unsigned binary on WKS-2231 (user j.alvarez)
- EDR: same binary hash on WKS-2240 and SRV-FILE-03 within 11 minutes
- SIEM: 4 failed then 1 successful logon for svc_backup from WKS-2231 to SRV-FILE-03
- SIEM: scheduled task created on SRV-FILE-03 named 'WindowsUpdateCheck'
- Proxy: 38 MB POST from SRV-FILE-03 to a domain registered 9 days ago
- Mail: j.alvarez opened an attachment 'Invoice_Q4.pdf.lnk' at 01:58 UTC
"""
response = client.swarms.run(
name="Incident Investigation INC-2026-0419",
description="Question, research, analysis and synthesis on one alert cluster.",
swarm_type="HeavySwarm",
task=(
"Investigate the alert cluster below. Establish the likely sequence of "
"events, map every indicator to a tactic and technique with the evidence "
"for each mapping, list what is still unknown, and draft an incident report "
"in sections: summary, timeline, affected assets, technique mapping, open "
"questions, recommended next steps for the analyst. Mark the report DRAFT.\n"
+ ALERT_CLUSTER
),
agents=[
{
"agent_name": "Question Agent",
"description": "Frames the questions the investigation must answer.",
"system_prompt": "You are an incident commander. From the alerts, write the specific questions that must be answered to understand initial access, scope, persistence and exfiltration. Do not speculate on answers.",
"model_name": "gpt-5.4-mini", # framing is short, a fast model is enough
"max_loops": 1,
},
{
"agent_name": "Research Agent",
"description": "Gathers related events and indicator context.",
"system_prompt": "You are a threat researcher. For each question, pull together the related events from the cluster, what is known about each indicator (hash, domain, task name) and the gaps. Cite the alert line you rely on.",
"model_name": "gemini-2.5-pro", # long context across many events
"max_loops": 1,
},
{
"agent_name": "Analysis Agent",
"description": "Maps indicators to tactics and techniques.",
"system_prompt": "You are a detection analyst. Map every indicator to a tactic and a technique, give the evidence for each mapping and a confidence of low, medium or high. Build the most likely timeline.",
"model_name": "claude-sonnet-5-5",
"max_loops": 1,
},
{
"agent_name": "Synthesis Agent",
"description": "Writes the draft incident report.",
"system_prompt": "You write incident reports for a security operations team. Use the sections requested, keep claims tied to evidence, list the open questions plainly and end with recommended next steps that the analyst, not you, will approve.",
"model_name": "claude-opus-5-5", # the report is the deliverable
"max_loops": 1,
},
],
max_loops=1,
)
print(response)# One alert cluster through question, research, analysis and synthesis.
# The draft report goes to the analyst; no agent here can touch a host.
# Requires: SWARMS_API_KEY from Swarms Cloud, jq for the summary at the end.
curl -s -X POST https://api.swarms.world/v1/swarm/completions \
-H "x-api-key: $SWARMS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Incident Investigation INC-2026-0419",
"description": "Question, research, analysis and synthesis on one alert cluster.",
"swarm_type": "HeavySwarm",
"task": "Investigate cluster INC-2026-0419 (7 alerts, 3 hosts): lsass memory read by an unsigned binary on WKS-2231 (user j.alvarez); same hash on WKS-2240 and SRV-FILE-03 within 11 minutes; 4 failed then 1 successful logon for svc_backup from WKS-2231 to SRV-FILE-03; scheduled task WindowsUpdateCheck created on SRV-FILE-03; 38 MB POST from SRV-FILE-03 to a 9-day-old domain; j.alvarez opened Invoice_Q4.pdf.lnk at 01:58 UTC. Map every indicator to a tactic and technique with evidence, list unknowns, and draft the incident report marked DRAFT.",
"agents": [
{
"agent_name": "Question Agent",
"system_prompt": "You are an incident commander. Write the specific questions the investigation must answer about initial access, scope, persistence and exfiltration. Do not speculate on answers.",
"model_name": "gpt-5.4-mini",
"max_loops": 1
},
{
"agent_name": "Research Agent",
"system_prompt": "You are a threat researcher. For each question, gather the related events and indicator context from the cluster and name the gaps. Cite the alert you rely on.",
"model_name": "gemini-2.5-pro",
"max_loops": 1
},
{
"agent_name": "Analysis Agent",
"system_prompt": "You are a detection analyst. Map every indicator to a tactic and technique with evidence and a confidence level, and build the most likely timeline.",
"model_name": "claude-sonnet-5-5",
"max_loops": 1
},
{
"agent_name": "Synthesis Agent",
"system_prompt": "You write incident reports for a SOC. Use the requested sections, tie claims to evidence, list open questions and end with next steps for the analyst to approve.",
"model_name": "claude-opus-5-5",
"max_loops": 1
}
],
"rules": "Tie every claim to an alert line. Mark anything unknown as unknown.",
"max_loops": 1
}' | jq '{report: .output, usage: .usage}'// Phishing report review as a MajorityVoting swarm. Three reviewers look at
// headers, links and content independently and vote. The analyst decides
// whether to pull the message; this code never touches a mailbox.
const SWARMS_API = "https://api.swarms.world/v1/swarm/completions"
type ReportedEmail = {
reportId: string
from: string
replyTo?: string
subject: string
authResults: string
links: string[]
bodyText: string
}
const reviewer = (name: string, model: string, focus: string) => ({
agent_name: name,
system_prompt:
"You review user-reported emails for a security team. " +
focus +
" Answer MALICIOUS, SUSPICIOUS or BENIGN on the first line, then the specific evidence. Do not open or follow any link; reason from the text you are given.",
model_name: model,
max_loops: 1,
})
export async function reviewPhish(e: ReportedEmail) {
const res = await fetch(SWARMS_API, {
method: "POST",
headers: {
"x-api-key": process.env.SWARMS_API_KEY!,
"Content-Type": "application/json",
},
body: JSON.stringify({
name: `Phish Review ${e.reportId}`,
swarm_type: "MajorityVoting",
task:
`Reported email ${e.reportId}.\nFrom: ${e.from}\nReply-To: ${e.replyTo ?? "(none)"}\nSubject: ${e.subject}\n` +
`Authentication-Results: ${e.authResults}\nLinks:\n${e.links.map((l) => " " + l).join("\n")}\n\nBody:\n${e.bodyText}`,
agents: [
reviewer("Header Reviewer", "gpt-5.4-mini", "Focus on sender domain, reply-to mismatch, SPF, DKIM and DMARC results."),
reviewer("Link Reviewer", "claude-haiku-5-5", "Focus on link domains versus display text, URL shorteners, lookalike domains and credential-harvest patterns."),
reviewer("Content Reviewer", "gemini-2.5-flash", "Focus on urgency, payment or credential requests, and whether the request fits how this sender normally communicates."),
],
max_loops: 1,
}),
})
if (!res.ok) throw new Error(`Swarms API ${res.status}: ${await res.text()}`)
const data = await res.json()
// The majority verdict and each vote go to the analyst's queue as a proposal.
return { proposal: data.output as string, usage: data.usage as { total_tokens: number } }
}
reviewPhish({
reportId: "PR-88213",
from: "Accounts Payable <ap@contoso-invoices.com>",
replyTo: "ap.contoso@gmail.com",
subject: "URGENT: updated bank details for invoice 4471",
authResults: "spf=fail dkim=none dmarc=fail",
links: ["https://contoso-invoices.com/secure/login?ref=4471"],
bodyText: "Please update our bank details before Friday's payment run. Log in to confirm.",
}).then((r) => console.log(r.proposal, r.usage.total_tokens))import os
import requests
BASE = "https://api.swarms.world"
HEADERS = {"x-api-key": os.environ["SWARMS_API_KEY"]}
# Every investigation run is stored in Swarms Cloud with its configuration,
# outcome and usage. This pulls the request history so the SOC can attach the
# agent record to an incident ticket and account for spend per incident.
logs = requests.get(f"{BASE}/v1/swarm/logs", headers=HEADERS, timeout=60).json()
metrics = requests.get(f"{BASE}/v1/metrics/summary", headers=HEADERS, timeout=30).json()
def walk(node, key):
"""Yield every value stored under key anywhere in a nested JSON document."""
if isinstance(node, dict):
for k, v in node.items():
if k == key:
yield v
yield from walk(v, key)
elif isinstance(node, list):
for item in node:
yield from walk(item, key)
# Group runs by the incident id embedded in the swarm name, for example
# "Incident Investigation INC-2026-0419", and total the tokens per incident.
by_incident: dict[str, dict] = {}
for entry in walk(logs, "data"):
if not isinstance(entry, dict):
continue
name = str(entry.get("name", ""))
incident = next((part for part in name.split() if part.startswith("INC-")), "other")
tokens = sum(int(t) for t in walk(entry, "total_tokens") if isinstance(t, (int, float)))
bucket = by_incident.setdefault(incident, {"runs": 0, "tokens": 0, "swarm_types": set()})
bucket["runs"] += 1
bucket["tokens"] += tokens
for st in walk(entry, "swarm_type"):
if isinstance(st, str):
bucket["swarm_types"].add(st)
print(f"{'incident':20s} {'runs':>5s} {'tokens':>12s} swarm types")
for incident, b in sorted(by_incident.items(), key=lambda kv: -kv[1]["tokens"]):
print(f"{incident:20s} {b['runs']:>5d} {b['tokens']:>12,d} {', '.join(sorted(b['swarm_types']))}")
print()
print("account summary:", metrics)
# Attach the raw entries for one incident to its ticket as the agent record.
INCIDENT = "INC-2026-0419"
record = [e for e in walk(logs, "data") if isinstance(e, dict) and INCIDENT in str(e.get("name", ""))]
print(f"{len(record)} runs for {INCIDENT} ready to attach to the ticket")from swarms import Agent, ConcurrentWorkflow
# Vulnerability prioritization on the open-source swarms package (pip install
# swarms). Three agents read the same findings at once and the patch owner
# sees all three views. Nothing here changes a system.
exposure = Agent(
agent_name="Exposure Agent",
system_prompt=(
"You assess network exposure. For each finding, say whether the asset is "
"internet-facing, reachable from user networks only, or isolated, based on "
"the asset notes. Rank findings by exposure."
),
model_name="gpt-5.4-mini",
max_loops=1,
)
exploit = Agent(
agent_name="Exploit Agent",
system_prompt=(
"You assess exploitability. For each CVE, state whether public exploit code "
"or active exploitation is noted in the finding, and whether the affected "
"component is actually in use per the asset notes. Rank by exploitability."
),
model_name="claude-haiku-5-5",
max_loops=1,
)
asset = Agent(
agent_name="Asset Agent",
system_prompt=(
"You assess business impact. For each asset, say what it runs, who owns it "
"and what breaks if it is compromised, from the asset notes. Rank by impact."
),
model_name="gemini-2.5-flash",
max_loops=1,
)
workflow = ConcurrentWorkflow(
name="Vulnerability Prioritization",
description="Exposure, exploitability and impact views on the same findings.",
agents=[exposure, exploit, asset],
max_loops=1,
)
FINDINGS = """
1. CVE-2026-21001, critical, web framework RCE. Asset: web-portal-02, internet-facing,
runs the customer portal, owner: platform team. Public exploit: yes.
2. CVE-2026-20417, high, SMB signing not enforced. Asset: SRV-FILE-03, internal only,
finance shares, owner: infra team. Public exploit: no.
3. CVE-2026-19880, medium, outdated TLS library. Asset: build-runner-07, isolated
build network, owner: dev tooling. Public exploit: no, component unused at runtime.
"""
result = workflow.run("Prioritize these findings for this week's patch window.\n" + FINDINGS)
print(result)The Python SDK (pip install swarms-client) runs one alert cluster through a HeavySwarm: a question agent on a fast model frames the investigation, a long-context model gathers the related events, an analysis agent maps indicators to techniques, and the synthesis agent on the strongest model drafts the report. The analyst confirms the verdict.
Swarms Cloud
Runs from the API land in Swarms Cloud with their inputs, each agent's output, token usage and latency. Name each run after the incident id and the complete agent record for one incident can be pulled and attached to its ticket, as the audit example does.
Runs / min
18
▲ last 30s
p50 latency
2.3s
▼ last 30s
Tokens / min
119.3k
▲ last 30s
Spend / hour
$4.15
▲ last 30s
Every run on the Swarms API appears in Swarms Cloud with its logs, token usage, cost and context use.
Open Swarms CloudThe alert text that was sent, each stage's output, the model ids, token counts and latency, and the analyst's decision your ticketing system recorded. The swarm logs endpoint returns the first four; the decision stays with you.
When an analyst changes a proposed verdict, the proposal and its reason are already in the log. Reviewing those cases weekly is how the triage prompts get better, and the record of each change is the evidence that a person made the call.
What SOC leads, detection engineers and security platform teams ask before they put agents near an alert queue.
An investigation has stages that want different things: framing wants discipline, research wants context length, mapping wants careful reasoning, and the report wants writing quality. HeavySwarm runs question, research, analysis and synthesis as separate agents, so each can run on the model that fits and each stage's output is logged on its own. The analyst can see where a conclusion came from.
Swarm types on the Swarms APINo. Nothing on this page gives an agent a console, a credential or a containment action. The agents return proposed verdicts, mappings and draft reports; analysts approve any action and carry it out through the tools they already use. If a team later decides to expose a tool to an agent, that tool's limits are a separate design decision, and the Swarms Cloud logs show every call.
You put them in the task. The examples paste the alert cluster as text; a production integration builds that string from the SIEM, EDR, mail gateway or ticketing system and sends it on a trigger such as a new correlated cluster. Agents can also call tools you expose, such as a read-only indicator lookup, under limits you set.
Each agent carries its own model_name, so you decide per agent which provider sees what. Teams commonly redact hostnames and usernames into consistent tokens before the request and map them back afterwards. Enterprise accounts can discuss data handling and deployment options with the Swarms team.
Talk to salesEvery run is stored in Swarms Cloud with the request, each agent's output, the model ids, token counts and latency, and the swarm logs endpoint returns the same data. Naming runs after the incident id, as the examples do, lets the audit script on this page pull the complete agent record for one incident and attach it to the ticket.
Model pricingCreate a Swarms Cloud account, copy the investigation example above, and paste in a redacted alert cluster. The draft report shows up in your logs with every stage and its cost.
New Swarms Cloud accounts start with $5 in API credits. Enterprise teams can talk to us about volume pricing, data handling and deployment options.