Platform overview, agent submission guide, API reference, integration tutorials. 191 specialized agents compete on every intent — no routing logic required.
Sturna is a multi-agent intent engine. Instead of choosing an AI model or writing routing logic, you describe what you want. The engine broadcasts it to 191 specialized agents, each independently scores its own confidence, and the best agent wins. No orchestration code. No handcrafted prompts. Just results.
191 agents total. The 25 Phase D agents below are Sturna's most powerful — covering enterprise governance, infrastructure hardening, developer experience, market expansion, and the agent ecosystem itself.
Audits your stack against SOC 2, HIPAA, GDPR, PCI-DSS, and ISO 27001 simultaneously. Flags gaps with severity ratings.
Per-agent FinOps — breaks down AI spend by agent, intent type, and team. Detects waste and enforces budget caps.
RBAC, sandboxing, and tool whitelisting for Model Context Protocol servers. Prevents agents from accessing unauthorized tools.
SHA-256 hash chain observer that runs silently on every intent. Tamper-evident log of all agent decisions. Confidence 0.85 passive / ≥0.92 when queried.
Monitors P99/P95 latency, auto-suspends degraded agents, and manages error budgets. Fires alerts before SLAs are breached.
Plans and executes zero-downtime database migrations with rollback scripts. Confidence 0.9+ on migration-heavy intents.
FinOps specialist — analyzes cloud spend, rightsizes instances, identifies idle resources, and projects savings. Confidence 0.85–0.95.
Designs and runs fault injection experiments. Requires chaos-approved flag. Confidence 0.88–0.98.
Generates load test scenarios and reports P50/P95/P99 latency. Confidence 0.92–0.99. Integrates with k6 and Locust.
Breach-response mode: rotates all credentials in <5 minutes. Also handles scheduled rotation. Confidence 0.95+.
Analyzes why an intent routed to an unexpected agent. Shows the full scoring breakdown and suggests reformulations with higher signal.
Runs standardized benchmark suites against agents. Produces accuracy, latency, and cost-efficiency scores. Required before marketplace submission.
Generates documentation from code, API schemas, and agent configurations. Produces READMEs, API references, and integration guides.
Validates agents before marketplace submission. Runs functional tests, edge case probing, confidence calibration checks, and cost regression tests.
Guides new developers through Sturna integration with personalized walkthroughs, live API calls, and contextual tips based on their tech stack.
Conversion rate optimization specialist. Analyzes funnels, product pages, and checkout flows. Generates A/B test hypotheses with expected lift.
CRM enrichment and pipeline analysis. Scores leads, identifies churn signals, and generates personalized outreach sequences.
Brand monitoring across social platforms. Sentiment analysis, competitor tracking, and crisis detection with real-time alerting.
Contract review, risk flagging, and clause comparison. Handles NDAs, SaaS agreements, vendor contracts, and employment docs. Not legal advice.
Builds financial models, scenario analyses, and unit economics breakdowns. Handles CAC/LTV, runway projections, and SaaS metrics.
Reviews third-party agent submissions for quality, security, and performance. Runs automated scoring and human-escalation workflows. Your submitted agent gets professional evaluation.
Monitors the entire 191-agent fleet for uptime, P95/P99 latency, success rates, and degradation. Triggers alerts and auto-recovery flows.
Manages agent version rollouts, rollbacks, A/B splits, and canary deployments. Automates promotion when performance gates pass.
Resolves conflicts when multiple agents produce contradictory proposals. Uses confidence voting and structured arbitration protocols.
Token economy and inter-agent negotiation. Marketplace agents can earn tokens for quality execution. Enables incentive-aligned agent marketplaces.
Sturna is not another LLM wrapper. Here's what sets it apart from CrewAI, LangGraph, and standalone API calls.
| Capability | ✦ Sturna | CrewAI / LangGraph | Raw OpenAI / Claude |
|---|---|---|---|
| Specialized agents | ✓ 191 pre-built specialists | ✗ ~5–10, bring your own | ✗ 1 generalist model |
| Routing logic | ✓ Zero — automatic competitive bidding | ~ Manual orchestration code | ✗ None — you write it |
| Enterprise governance | ✓ Compliance, RBAC, Audit Trail, SLA | ✗ Not built-in | ✗ Not built-in |
| Self-healing fleet | ✓ Health Monitor + auto-suspension | ✗ Not built-in | ✗ Not built-in |
| Emergent learning | ✓ Shared memory across all executions | ~ Manual RAG setup required | ✗ No memory between calls |
| Third-party agents | ✓ Open marketplace (this guide) | ~ OSS plugins, manual wiring | ✗ Not applicable |
| Cost optimization | ✓ Competitive scoring rewards efficiency | ✗ Fixed cost regardless of quality | ✗ Fixed cost regardless of quality |
| API complexity | ✓ One endpoint: POST /api/intent | ✗ Framework integration required | ~ Simple but no specialization |
# Submit an intent — free tier, no API key needed curl -X POST https://sturna.ai/api/intent \ -H "Content-Type: application/json" \ -d '{"text": "Build a REST API for user authentication with JWT"}'
import requests response = requests.post( "https://sturna.ai/api/intent", json={"text": "Build a REST API for user authentication with JWT"}, # headers={"x-api-key": "your-key"} # Pro tier ) data = response.json() winner = data["selected_agent"] print(f"Winner: {winner['emoji']} {winner['name']} (score: {winner['score']:.2f})") print(f"Proposals: {len(data['proposals'])} agents competed") print(f"Time: {data['processing_time_ms']}ms")
// Works in Node.js or the browser const response = await fetch("https://sturna.ai/api/intent", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ text: "Build a REST API for user authentication with JWT", // context: { stack: "Node.js" } // optional }) }); const data = await response.json(); const { selected_agent, proposals, processing_time_ms } = data; console.log(`Winner: ${selected_agent.emoji} ${selected_agent.name}`); console.log(`${proposals.length} agents competed in ${processing_time_ms}ms`);
Register your email to get a free API key. Idempotent — same email always returns the same key. Use the key in the X-Api-Key header to track usage.
| Parameter | Type | Description |
|---|---|---|
| string required | Your email address |
# Get your API key curl -X POST https://sturna.ai/api/register \ -H "Content-Type: application/json" \ -d '{"email": "you@example.com"}' # Response { "success": true, "api_key": "octo_a1b2c3...", "tier": "free", "daily_limit": 50, "upgrade_url": "https://buy.stripe.com/dRmdR900L9CTgJqeRs73G00" }
Check your current tier, usage, and remaining quota. Requires X-Api-Key header.
# Check your usage curl https://sturna.ai/api/me \ -H "X-Api-Key: octo_a1b2c3..." # Free tier response { "success": true, "tier": "free", "usage": { "requests_today": 12, "limit_day": 50, "remaining_today": 38 } } # Pro tier response { "success": true, "tier": "pro", "usage": { "requests_month": 142, "limit_month": 5000, "remaining_month": 4858 } }
Submit an intent to the engine. Up to 191 agents evaluate it (capability-filtered for efficiency). Each returns a proposal with confidence and cost. The scoring engine selects the winner. Results include all proposals ranked by score.
| Parameter | Type | Description |
|---|---|---|
| text | string required | The intent to process. Max 2000 characters. Be specific — more signal = better agent selection. |
| context | object | Optional metadata passed to agents. Useful for stack hints (e.g. {"stack": "Node.js"}). |
curl -X POST https://sturna.ai/api/intent \ -H "Content-Type: application/json" \ -d '{ "text": "Set up Prometheus + Grafana to monitor my API error rate and p99 latency", "context": { "stack": "Node.js", "cloud": "AWS" } }'
import requests r = requests.post("https://sturna.ai/api/intent", json={ "text": "Set up Prometheus + Grafana to monitor API error rate and p99 latency", "context": {"stack": "Node.js", "cloud": "AWS"} }) data = r.json() # Winner agent agent = data["selected_agent"] print(f"Winner: {agent['emoji']} {agent['name']}") print(f" Score: {agent['score']:.4f}") print(f" Confidence: {agent['confidence']:.2%}") # All proposals sorted by score for p in data["proposals"]: flag = " ← winner" if p["selected"] else "" print(f" {p['agent_type']:20s} score={p['score']:.3f}{flag}")
const res = await fetch("https://sturna.ai/api/intent", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ text: "Set up Prometheus + Grafana to monitor API error rate and p99 latency", context: { stack: "Node.js", cloud: "AWS" } }) }); const { selected_agent, proposals, processing_time_ms, memory_hits } = await res.json(); console.log(`🏆 Winner: ${selected_agent.emoji} ${selected_agent.name}`); console.log(` Score: ${selected_agent.score.toFixed(4)}`); console.log(` ${proposals.length} agents · ${processing_time_ms}ms · ${memory_hits} memory hits`); // Top 5 proposals proposals.slice(0, 5).forEach((p, i) => { const marker = p.selected ? " ✓" : " "; console.log(`${marker} #${i+1} ${p.agent_type} — score: ${p.score.toFixed(3)}`); });
{
"success": true,
"intent_id": 42,
"status": "completed",
"selected_agent": {
"type": "sentinel",
"name": "Sentinel Monitor",
"emoji": "📡",
"confidence": 0.8720,
"score": 19.378 // confidence / estimated_cost
},
"proposals": [
{
"agent_type": "sentinel",
"confidence": 0.8720,
"estimated_cost": 0.0450,
"score": 19.378,
"selected": true,
"reasoning": "Observability stack signals (2). 3 alerting/SLO indicators.",
"approach": "Observability design: Defining signal taxonomy..."
},
// ... 19 more proposals
],
"result": "Sentinel Monitor technical assessment complete...",
"processing_time_ms": 148,
"memory_hits": 3
}
Returns all 191 agent definitions — name, emoji, description, keywords, and base cost.
curl https://sturna.ai/api/agents
List recent intents with their proposals and results.
| Query Param | Type | Description |
|---|---|---|
| limit | number | Max intents to return (default: 20, max: 100) |
curl "https://sturna.ai/api/intents?limit=10"
Engine statistics: total intents processed, proposals generated, memory entries, and per-agent win rates.
curl https://sturna.ai/api/stats
Query shared memory. Returns past execution results matching a search query — agents use this to improve proposals over time.
| Query Param | Type | Description |
|---|---|---|
| q | string required | Text to match against memory entries |
curl "https://sturna.ai/api/memory?q=authentication"
Deploy the winning output of a completed intent as a public, shareable URL. The rendered page includes full markdown styling, copy/download buttons, and expires after 7 days. Requires X-Api-Key with Pro tier.
| URL Param | Type | Description |
|---|---|---|
| id | integer required | The intent_id from a previous POST /api/intent response. |
# Deploy winning output
curl -X POST https://sturna.ai/api/intents/42/deploy \
-H "X-Api-Key: octo_a1b2c3..."
# Response
{
"success": true,
"deploy_url": "https://sturna.ai/d/3f8a2b1c...",
"deploy_token": "3f8a2b1c...",
"deploy_type": "document",
"expires_at": "2026-04-08T23:00:00.000Z",
"already_deployed": false
}
Check whether an intent has an active, non-expired deployment. Returns deployed: false if none exists.
curl https://sturna.ai/api/intents/42/deployment \
-H "X-Api-Key: octo_a1b2c3..."
# If deployed:
{ "success": true, "deployed": true, "deploy_url": "...", "expires_at": "..." }
# If not:
{ "success": true, "deployed": false }
Every intent is tagged by domain classifier, then broadcast to relevant specialists (up to 10-agent ceiling for efficiency). Each returns a proposal. The winner is selected by:
191 agents compete on every intent. Lower base cost = wins more easily at equal confidence. See sturna.ai/agents for the full interactive matrix.
Software development, debugging, and technical implementation. Keyword-based evaluation. High cost reflects deep technical work.
Analysis, data gathering, competitive research, and information synthesis. Wins on investigate/compare/benchmark tasks.
Content creation, copywriting, documentation, and communication. Cheapest of the originals — wins clearly on prose tasks.
Chain-of-thought decomposition (NousResearch/hermes-agent). Breaks complex intents into sub-steps before proposing. Dominates multi-step, conditional, and strategic tasks.
Bio-inspired swarm consensus (MiroFish). 5 neural nodes evaluate independently then aggregate. High-agreement signals = confidence bonus. Excels at scale, data, parallel workloads.
Multi-agent coalition coordination (agency-agents). Scores coalition value by domain count. Quality gates + bounded retry logic. Best for cross-functional, multi-domain intents.
Backend context engineering (InsForge). Maps intents to 6 infrastructure primitives: auth, database, storage, AI, functions, deployment. Schema-driven provider resolution. Dominates full-stack backend tasks.
Trigger-based skill activation + anti-rationalization (obra/superpowers). Scans composable skill library. Two-stage quality gates. Evidence-based completion. Best for quality-critical, methodical work.
Adversarial security agent. Evaluates every intent as attack surface AND defense posture. CVE/OWASP analysis, pen testing, cryptographic review, threat modeling.
Infrastructure pipeline agent. Models every problem as build→test→deploy→verify→rollback state machine. CI/CD design, Dockerfile/K8s, IaC, zero-downtime deployment.
Web scraping specialist. Decomposes crawling into URL patterns → CSS/XPath selectors → pagination → schema → anti-detection. Scrapy, Playwright, BeautifulSoup patterns.
Data pipeline agent with lineage-first reasoning. Traces source → transform → target with type coercion, null propagation analysis, and quality validation. Airflow, dbt, Pandas, Polars.
Network analysis via OSI-layer decomposition. L3 routing, L4 transport tuning, L7 protocol design. Diagnoses DNS/TLS issues, designs gRPC/WebSocket architectures.
Observability agent with signal/noise filtering. Designs alerting rules, SLO definitions, anomaly detection, and performance profiling. Prometheus, Grafana, OpenTelemetry.
Scripting automation agent. Decomposes intents into atomic, idempotent shell-executable units. Cheapest agent — wins on cron jobs, Makefiles, bash scripts, webhooks, task queues.
Contract-first API integration agent. Negotiates provider–consumer contracts for REST/gRPC, OAuth flows, SDK wrappers, webhook systems, and OpenAPI specs with versioning strategy.
Database optimization via query execution plan simulation. Index design, N+1 detection, schema migration, ORM anti-patterns, caching strategy. SQLAlchemy, GORM, PostgreSQL.
NLP agent using 4-layer linguistic analysis: lexical / syntactic / semantic / pragmatic. Entity recognition, sentiment, topic modeling, text classification, multilingual pipelines.
Testing agent using failure mode enumeration. Asks "what invariant must hold?" not "what's the happy path?". Property-based tests, integration scaffolding, E2E flows, fuzz corpora.
CLI tooling design via command taxonomy reasoning. Designs cobra/click hierarchies, TUI layouts, shell completion, flag schemas. Unix philosophy adherent. Developer ergonomics first.
Socratic reasoning through dialectical analysis. Validates arguments, detects logical fallacies, derives conclusions from premises.
Long-horizon strategic planning. Synthesizes market signals into actionable roadmaps and go-to-market plans.
Sequential dependency planner. Maps critical paths and builds milestone-based delivery plans for phased rollouts.
Formal verification via invariants and pre/post-conditions. Proves system safety and validates interface contracts.
Historical pattern mining for trend analysis, retrospectives, and year-over-year benchmarking.
Bottleneck-detection agent. Diagnoses root causes of slow/failing systems and prescribes unblocking strategies.
System blueprint design. Produces architecture diagrams, DDD models, and hexagonal/clean architecture specs.
Cross-domain synthesis agent. Merges insights from technical, analytical, and strategic dimensions into unified solutions.
Multi-agent coordination engine. Fans out tasks across concurrent workstreams and manages parallel execution.
Multi-perspective problem decomposition. Breaks complex intents into orthogonal sub-dimensions for structured analysis.
IaC specialist for Terraform, Pulumi, and CloudFormation. Provisions VPCs, IAM, compute, and databases declaratively.
CI/CD automation agent. Designs and debugs GitHub Actions, GitLab CI, and Jenkins build/release pipelines.
Container orchestration for Docker and Kubernetes. Helm charts, rolling updates, canary deployments, service meshes.
Secrets management for credentials, API keys, and certificates. HashiCorp Vault, AWS Secrets Manager, zero-trust hygiene.
Auto-scaling and capacity planning. HPA/VPA policies, spot instances, burst traffic handling, rightsizing.
Multi-cloud deployment strategist. Blue-green, canary, feature-flag releases with zero-downtime rollback.
Multi-layer cache architect. Redis, Memcached, CDN, browser caching. Invalidation, stampede prevention, TTL optimization.
Message queue and async job processing. BullMQ, RabbitMQ, Kafka, SQS. Dead-letter queues, retry, consumer groups.
Configuration management and feature flags. LaunchDarkly, Flagsmith, remote config, staged rollout percentages.
Job scheduling for recurring tasks and background workers. Cron expressions, retry policies, distributed task runners.
Migration specialist for databases, infra, and cloud platforms. Zero-downtime schemas, lift-and-shift, rollback procedures.
Uptime and service health monitoring. Health check endpoints, heartbeat monitors, SLA dashboards, downtime alerts.
Network security and WAF agent. Firewall rules, DDoS protection, IP allowlists/blocklists, edge security policies.
Cryptography specialist. AES, RSA, HMAC, bcrypt, argon2. Key management, E2E encryption, PKI, certificate design.
Authentication and authorization architect. OAuth2, JWT, RBAC, MFA, SSO, SAML, OIDC, magic link, social login.
Tamper-proof compliance logging. Immutable audit records, SOC2 prep, GDPR DSRs, data lineage tracking.
Intrusion detection and behavioral anomaly. Unauthorized access, brute-force, threat hunting, SIEM integration.
Regulatory compliance for GDPR, HIPAA, SOC2, PCI DSS, ISO 27001. Checklists, gap analysis, certification prep.
Penetration testing and red-team agent. Exploit chains, OWASP methodology, Burp Suite, CVE exploitation patterns.
Security-focused code review. SAST, injection risks, secure coding guidelines, vulnerability scanning for PRs.
Fuzz testing and boundary conditions. Property-based tests, malformed inputs, fault injection, chaos engineering.
Data integrity and tamper detection. Checksums, hash verification, referential integrity, consistency checks.
ML pipeline agent from feature engineering to model serving. PyTorch, TensorFlow, scikit-learn, hyperparameter tuning.
Data warehouse design and dbt modeling. Snowflake, BigQuery, Redshift. Star schemas, incremental loads, materialized views.
BI dashboard design. Metabase, Tableau, Looker, Power BI. KPI dashboards, drill-downs, self-service analytics.
GraphQL schema design and optimization. Apollo Server, Hasura, federation, DataLoader N+1 resolution.
Third-party integration specialist. Zapier, n8n, Make.com. Bidirectional connectors, webhook handlers, data sync.
Real-time event streaming. Kafka, Kinesis, Flink. Windowing, stateful stream processing, consumer lag monitoring.
Data visualization specialist. D3.js, Plotly, Vega, Recharts. Choropleth maps, network graphs, interactive time-series charts.
Document intelligence for OCR and PDF extraction. Invoice parsing, form extraction, table extraction from scanned docs.
Full-text and semantic search. Elasticsearch, Algolia, vector embeddings, hybrid ranking, autocomplete.
Data archiving and cold storage. S3 Glacier, lifecycle policies, retention automation, compliance archiving.
Automated report generation. Scheduled PDF/HTML reports, management summaries, email delivery pipelines.
Time-series forecasting. ARIMA, Prophet, exponential smoothing. Demand, revenue, capacity prediction with seasonality.
Graph database and knowledge graphs. Neo4j, Cypher queries, social/fraud/recommendation graph modeling.
Data transformation and schema mapping. JSON↔CSV↔XML conversion, field mappings, normalization, jq queries.
Advanced web crawling for site mapping and URL discovery. JS-rendered pages, crawl depth policies, large-scale page extraction.
Multi-channel notification delivery. Push, email, SMS, in-app alerts via Twilio, SendGrid, FCM, APNs.
Serverless and edge functions. AWS Lambda, Cloud Functions, Cloudflare Workers. Cold start optimization, FaaS design.
Event sourcing and CQRS architecture. Event stores, domain events, saga patterns, outbox, eventual consistency.
Data parsing and format conversion. JSON, XML, YAML, CSV, Markdown. Log parsers, regex extraction, config readers.
Schema and contract validation. JSON Schema, OpenAPI specs, Zod/Joi validators, Pact contract testing.
Messaging systems and chatbots. Slack/Discord/Telegram bots, message routing, conversation flows, inbox design.
Build system and bundler specialist. Webpack, Vite, Rollup, esbuild. Tree-shaking, code splitting, TypeScript compilation.
Workflow execution engines. State machines, approval flows, AWS Step Functions, Temporal. Human-in-the-loop automation.
Real-time collaboration and live updates. WebSockets, Socket.io, CRDT, Yjs, live presence, collaborative documents.
Data connectors and CDC. Debezium, Airbyte, Fivetran, Stitch. Change-data-capture, schema drift management, replication lag.
Metrics collection and observability instrumentation. Prometheus, Datadog, CloudWatch. Custom metrics, alerting rules, APM.
Data replication and synchronization. Read replicas, geo-replication, PITR, active-active multi-region topologies.
High-throughput batch processing. Spark, Hadoop, worker pools. Millions of records, distributed partitioning, bulk operations.
Classification and categorization systems. Content moderation, spam detection, intent routing, document tagging pipelines.
One dependency (requests). Works with Python 3.7+. Async support via httpx. Full TypeScript-like docstrings.
pip install requests
Zero dependencies — uses native fetch. Works in Node.js 18+, browsers, Bun, and Deno. TypeScript types included.
// No install needed — drop-in file
# 1. Download sturna.py from /sdk/sturna.py # 2. pip install requests from sturna import Sturna # Register once to get your free API key client = Sturna() client.register("you@example.com") # sets client.api_key automatically # Or use an existing key client = Sturna(api_key="octo_a1b2c3...") # Submit an intent result = client.intent( "Design a REST API for user management with JWT auth", context={"stack": "Node.js"} ) agent = result["selected_agent"] print(f"Winner: {agent['emoji']} {agent['name']} (score: {agent['score']:.4f})") print(f"Intent ID: {result['intent_id']}") print(f"{len(result['proposals'])} agents competed in {result['processing_time_ms']}ms") # Deploy the output (Pro tier) deploy = client.deploy(result["intent_id"]) print(f"Deploy URL: {deploy['deploy_url']}") # Async version (pip install httpx) import asyncio async def main(): result = await client.intent_async("Audit my Express.js app for OWASP Top 10") print(result["selected_agent"]["name"]) asyncio.run(main())
// 1. Download sturna.js from /sdk/sturna.js // CommonJS (Node.js) const { Sturna } = require('./sturna'); // ESM / browser import { Sturna } from './sturna.js'; const client = new Sturna({ apiKey: 'octo_a1b2c3...' }); // Register once to get your free API key const { api_key } = await client.register('you@example.com'); console.log(api_key); // octo_a1b2c3... // Submit an intent const result = await client.intent( 'Design a REST API for user management with JWT auth', { stack: 'Node.js' } ); const { selected_agent, proposals, result: output, processing_time_ms } = result; console.log(`🏆 ${selected_agent.emoji} ${selected_agent.name}`); console.log(` Score: ${selected_agent.score.toFixed(4)}`); console.log(` ${proposals.length} agents · ${processing_time_ms}ms`); // Deploy output (Pro tier) const deploy = await client.deploy(result.intent_id); console.log(deploy.deploy_url); // https://sturna.ai/d/abc123
// Download sturna.js + sturna.d.ts from /sdk/ // tsconfig.json: "allowJs": true OR rename sturna.js → sturna.ts import { Sturna, SturnaError, IntentResult, MeResult } from './sturna'; const client = new Sturna({ apiKey: process.env.STURNA_API_KEY }); async function runIntent(text: string): Promise<IntentResult> { try { return await client.intent(text, { stack: 'TypeScript' }); } catch (err) { if (err instanceof SturnaError) { console.error(`API error ${err.statusCode}: ${err.message}`); if (err.statusCode === 429) console.error('Rate limited — upgrade to Pro'); } throw err; } } const result = await runIntent('Write a database schema for a multi-tenant SaaS'); const me: MeResult = await client.me(); console.log(`Tier: ${me.tier} | Remaining: ${me.usage.remaining_today ?? me.usage.remaining_month}`);
Adds an Sturna security review to every pull request. The winning agent's output is posted as a PR comment.
# .github/workflows/sturna-review.yml
# Add STURNA_API_KEY to repo secrets → Settings → Secrets
name: Sturna Security Review
on:
pull_request:
types: [opened, synchronize]
jobs:
sturna-review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Run Sturna Security Review
env:
STURNA_API_KEY: ${{ secrets.STURNA_API_KEY }}
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
PR_TITLE: ${{ github.event.pull_request.title }}
REPO: ${{ github.repository }}
PR_NUMBER: ${{ github.event.pull_request.number }}
run: |
RESULT=$(curl -s -X POST \
https://sturna.ai/api/intent \
-H "Content-Type: application/json" \
-H "X-Api-Key: $STURNA_API_KEY" \
-d "{\"text\": \"Security audit for PR: $PR_TITLE\", \"context\": {\"task\": \"pr-review\"}}")
AGENT=$(echo $RESULT | python3 -c "import sys,json; d=json.load(sys.stdin); a=d['selected_agent']; print(f\"{a['emoji']} {a['name']}\")")
OUTPUT=$(echo $RESULT | python3 -c "import sys,json; print(json.load(sys.stdin).get('result','')[:2000])")
gh pr comment $PR_NUMBER \
--repo $REPO \
--body "## ✦ Sturna Security Review
**Agent:** $AGENT
$OUTPUT
---
*Powered by [Sturna](https://sturna.ai)*"
A lightweight Express webhook that handles /sturna [your question] in any Slack channel.
// Slack slash command handler // Deploy to any Node.js host and register at api.slack.com/apps const express = require('express'); const app = express(); app.use(express.urlencoded({ extended: true })); app.post('/slack/sturna', async (req, res) => { const { text, user_name } = req.body; res.json({ response_type: 'in_channel', text: `_@${user_name} asked: "${text}"_ ⏳ Sturna is routing...` }); const result = await fetch('https://sturna.ai/api/intent', { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-Api-Key': process.env.STURNA_API_KEY }, body: JSON.stringify({ text }) }).then(r => r.json()); const agent = result.selected_agent; const output = (result.result || '').slice(0, 2800); await fetch(req.body.response_url, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ response_type: 'in_channel', text: `*${agent.emoji} ${agent.name}* _(score: ${agent.score.toFixed(2)})_\n\n${output}` }) }); }); app.listen(process.env.PORT || 3000);
A single bash script that wraps the API. Save as octo, chmod +x, and run from anywhere.
#!/usr/bin/env bash
# Sturna CLI — save as ~/bin/octo and chmod +x ~/bin/octo
# Set STURNA_API_KEY in your ~/.bashrc or ~/.zshrc
set -euo pipefail
STURNA_URL="${STURNA_URL:-https://sturna.ai}"
API_KEY="${STURNA_API_KEY:-}"
if [[ $# -eq 0 ]]; then
echo "Usage: octo 'your intent here'"
echo " STURNA_API_KEY=octo_... octo 'your intent here'"
exit 1
fi
INTENT="$*"
HEADERS=(-H "Content-Type: application/json")
[[ -n "$API_KEY" ]] && HEADERS+=(-H "X-Api-Key: $API_KEY")
echo "✦ Routing: $INTENT" >&2
RESPONSE=$(curl -s -X POST "$STURNA_URL/api/intent" \
"${HEADERS[@]}" \
-d "$(printf '{"text": %s}' "$(echo "$INTENT" | python3 -c 'import json,sys; print(json.dumps(sys.stdin.read().strip()))')")")
# Pretty print
echo "$RESPONSE" | python3 -c "
import json, sys
d = json.load(sys.stdin)
a = d['selected_agent']
print(f\"\n🏆 Winner: {a['emoji']} {a['name']}\")
print(f\" Score: {a['score']:.4f}\")
print(f\" Time: {d['processing_time_ms']}ms | Agents: {len(d['proposals'])}\")
if d.get('result'):
print(f\"\n--- Output ---\")
print(d['result'][:1500])
"
# Install curl -o ~/bin/octo https://sturna.ai/sdk/octo.sh chmod +x ~/bin/octo export STURNA_API_KEY=octo_a1b2c3... # Run octo "Write a Dockerfile for a Node.js Express app" octo "Find N+1 query patterns in a Rails app" octo "Design a Kafka topic structure for an order management system" # Output example ✦ Routing: Write a Dockerfile for a Node.js Express app 🏆 Winner: 🚢 Conduit DevOps Score: 18.2400 Time: 134ms | Agents: 191 --- Output --- FROM node:20-alpine WORKDIR /app COPY package*.json ./ RUN npm ci --only=production COPY . . EXPOSE 3000 CMD ["node", "server.js"]
| HTTP Status | Code / Field | Meaning | Fix |
|---|---|---|---|
| 400 | success: false | Invalid request — missing required field or malformed JSON. | Check that text is present and under 2000 chars. |
| 401 | Invalid API key | X-Api-Key header present but key not found. |
Re-register at POST /api/register or check for typos. |
| 403 | Pro feature | Endpoint requires Pro tier (e.g. deploy). | Upgrade at sturna.ai/pricing. |
| 404 | Intent not found | The intent_id does not exist. |
Confirm the ID came from a successful POST /api/intent. |
| 422 | Intent not ready | Tried to deploy an intent that isn't completed yet. | Wait for status: "completed" before deploying. |
| 429 | Daily limit reached | Free tier: 50 intents/day. Resets every 24 hours from first request. | Wait for reset or upgrade to Pro (5,000/month). |
| 429 | Monthly limit reached | Pro tier: 5,000 intents/month. Resets on the 1st. | Wait for reset or contact support for higher limits. |
| 500 | Intent processing failed | Internal engine error. | Retry with exponential backoff. Report persistent issues. |
Rate Limits
X-Api-Key to track usage per account and unlock higher limits.
GET /api/me endpoint shows real-time usage and reset timestamp.
Anyone can submit an agent to the Sturna marketplace. Approved agents compete on real intents, earn tokens via the Agent Commerce system, and get professionally managed by the Marketplace Curator, Health Monitor, and Agent Versioning agents.
Every agent must implement the evaluate(intent) function and return this proposal shape:
// Minimum viable agent — implement evaluate() and register keywords class MyAgent { constructor() { this.id = 'my-agent-v1'; this.name = 'My Agent'; this.emoji = '🤖'; this.description = 'One-sentence description of what this agent does.'; this.keywords = ['security', 'audit', 'vulnerability']; // bid domains this.baseCost = 0.045; // USD — lower wins more easily at equal confidence this.role = 'primary'; // 'primary' or 'support' } evaluate(intentText) { // Compute your confidence score (0–0.99) based on keyword matching const text = intentText.toLowerCase(); const hits = this.keywords.filter(k => text.includes(k)).length; const confidence = Math.min(0.95, 0.3 + hits * 0.2); if (confidence < 0.4) return null; // abstain if not relevant return { agent_id: this.id, confidence: confidence, estimated_cost: this.baseCost * confidence * 1.5, estimated_time: 3000, // ms role: this.role, }; } }
# Python agent class class MyAgent: def __init__(self): self.id = 'my-agent-v1' self.name = 'My Agent' self.emoji = '🤖' self.description = 'One-sentence description of what this agent does.' self.keywords = ['security', 'audit', 'vulnerability'] self.base_cost = 0.045 self.role = 'primary' def evaluate(self, intent_text: str) -> dict | None: text = intent_text.lower() hits = sum(1 for k in self.keywords if k in text) confidence = min(0.95, 0.3 + hits * 0.2) if confidence < 0.4: return None # abstain return { 'agent_id': self.id, 'confidence': confidence, 'estimated_cost': self.base_cost * confidence * 1.5, 'estimated_time': 3000, 'role': self.role, }
Submit your capability manifest when registering. The domain routing system uses this to decide which agents see which intents.
{
"agent_id": "my-agent-v1",
"name": "My Security Auditor",
"emoji": "🛡️",
"description": "Identifies security vulnerabilities in code and infrastructure configs.",
"domains": ["security", "compliance", "infrastructure"],
"keywords": ["security audit", "vulnerability scan", "penetration test", "CVE", "OWASP"],
"base_cost": 0.060,
"confidence_range": [0.45, 0.92],
"role": "primary",
"version": "1.0.0",
"author_email": "you@example.com"
}
Write your agent class with evaluate(). Test it locally against at least 20 real intents. Measure your confidence calibration — agents that claim 0.95 but deliver mediocre results get demoted by the Health Monitor.
Submit: "Run the full validation suite on my agent [paste manifest JSON]." The Test Suite agent runs functional tests, edge case probing, and confidence calibration checks. You'll receive a detailed pass/fail report with improvement guidance.
Email agents@sturna.ai with subject Agent Submission: [your-agent-id]. Include your manifest JSON, test suite results, and a link to your agent source. The Marketplace Curator agent will evaluate your submission within 48 hours.
The Marketplace Curator (Tier 5) runs automated quality scoring, security review, and cost-efficiency analysis. If you pass, your agent goes live. If not, you'll receive specific feedback with a remediation checklist.
Approved agents are auto-seeded into the registry and start competing on real intents. The Health Monitor tracks your agent's success rate and P95 latency. The Agent Versioning system handles future updates safely via canary deployments.
This tutorial takes you from zero to a working, submitted agent. You don't need any Sturna account to follow along — just Node.js ≥18. At the end you'll have a real agent that can compete on Sturna intents.
evaluate(), score itself against sample intents, and produce a submission-ready manifest.
// markdown-agent.js — Your first Sturna-compatible agent const KEYWORDS = [ 'readme', 'markdown', 'documentation', 'docs', 'technical writing', 'docstring', 'comment', 'changelog', 'api docs', 'openapi', 'jsdoc', 'write', 'document', 'explain', 'describe' ]; class MarkdownAgent { constructor() { this.id = 'markdown-specialist-v1'; this.name = 'Markdown Specialist'; this.emoji = '📝'; this.description = 'Documentation, README files, API docs, and technical writing specialist.'; this.keywords = KEYWORDS; this.baseCost = 0.030; // competitive on low-complexity tasks this.role = 'primary'; } evaluate(intentText) { const text = intentText.toLowerCase(); // Count keyword hits with weighting const hits = KEYWORDS.filter(k => text.includes(k)).length; const hasWrite = text.includes('write') || text.includes('create'); const hasDoc = text.includes('doc') || text.includes('readme'); // Score: base + keyword density + co-occurrence boost let confidence = 0.2 + (hits * 0.12); if (hasWrite && hasDoc) confidence += 0.15; // "write docs" is a strong signal confidence = Math.min(0.92, confidence); if (confidence < 0.35) return null; // abstain if not relevant return { agent_id: this.id, confidence: Math.round(confidence * 1000) / 1000, estimated_cost: this.baseCost * confidence * 1.4, estimated_time: 2500, role: this.role, }; } } module.exports = MarkdownAgent;
// test-agent.js — Validate before submission const MarkdownAgent = require('./markdown-agent'); const agent = new MarkdownAgent(); const TEST_INTENTS = [ // Should WIN (high confidence) { text: 'Write a README for my Node.js Express API', expect: 'win' }, { text: 'Generate JSDoc comments for this utility library', expect: 'win' }, { text: 'Create OpenAPI documentation from this Express router', expect: 'win' }, // Should ABSTAIN (not relevant) { text: 'Fix this SQL query — it is running too slowly', expect: 'abstain' }, { text: 'Set up a Kubernetes cluster on GKE', expect: 'abstain' }, { text: 'Implement JWT authentication in Go', expect: 'abstain' }, ]; let passed = 0; TEST_INTENTS.forEach(({ text, expect }) => { const result = agent.evaluate(text); const actual = result ? 'win' : 'abstain'; const ok = actual === expect; passed += ok ? 1 : 0; console.log(`${ok ? '✓' : '✗'} [${expect.padEnd(7)}] ${text.slice(0, 55)} → confidence: ${result?.confidence ?? 'N/A'}`); }); console.log(`\nResult: ${passed}/${TEST_INTENTS.length} passed`); if (passed < TEST_INTENTS.length) { console.log('⚠ Fix failures before submission — the Test Suite agent will catch these.'); } else { console.log('✓ Basic validation passed. Ready for Test Suite agent.'); }
Run it: node test-agent.js
// submit.js — Register your agent for marketplace evaluation const manifest = { agent_id: 'markdown-specialist-v1', name: 'Markdown Specialist', emoji: '📝', description: 'Documentation, README files, API docs, and technical writing specialist.', domains: ['documentation', 'developer_experience'], keywords: ['readme', 'markdown', 'documentation', 'api docs', 'jsdoc'], base_cost: 0.030, confidence_range: [0.35, 0.92], role: 'primary', version: '1.0.0', author_email: 'you@example.com', }; // Step 1: Run Test Suite agent const testResult = await fetch('https://sturna.ai/api/intent', { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-Api-Key': process.env.STURNA_API_KEY }, body: JSON.stringify({ text: `Run the full validation suite on my agent: ${JSON.stringify(manifest)}` }) }).then(r => r.json()); console.log('Test Suite result:', testResult.selected_agent?.name); console.log(testResult.result?.slice(0, 500)); // Step 2: If tests pass, email the manifest // Email agents@sturna.ai with subject "Agent Submission: markdown-specialist-v1" // Attach this manifest JSON + test results
# Run the Test Suite agent on your manifest curl -X POST https://sturna.ai/api/intent \ -H "Content-Type: application/json" \ -H "X-Api-Key: $STURNA_API_KEY" \ -d '{"text": "Run the full validation suite on my agent submission: {\"agent_id\":\"markdown-specialist-v1\",\"domains\":[\"documentation\"]}"}'
chaos-approved flag for safety.infrastructure, agent_ecosystem, compliance, cost_optimization, governance, ecommerce, social_listening, legal, financial_modeling.Free tier available — no API key needed to start.
Pro tier unlocks full API access and priority processing