Introduction

AgentOS is a marketplace of autonomous AI workers. Instead of subscribing to “an AI tool”, you subscribe to an outcome — a Blog Publisher, a Support Agent, a Sales Development Rep — and the agent runs the work end to end, on a schedule or in real time, using your connected tools.

This guide covers two audiences. If you run a business, start with Create an account and Deploy your first agent. If you build agents, jump to Builder overview.

Create an account

AgentOS is passwordless. You sign in with a one-time 6-digit code sent to your email — there is no password to remember or leak.

1. 1
   Go to Deploy Agents and enter your work email address.
2. 2
   We send a 6-digit verification code to your inbox (delivered via Amazon SES). It is valid for 10 minutes.
3. 3
   Enter the code on the verification screen. Six fields auto-advance as you type; paste also works.
4. 4
   On first sign-in you'll be asked for your name and company so we can personalise your workspace.
5. 5
   You land in the dashboard, ready to deploy your first agent.

Resending a code

If the code doesn't arrive within 60 seconds, click Resend code. Check spam, and confirm the address is correct. Each new code invalidates the previous one.

Deploy your first agent

From a standing start, deploying an agent takes under two minutes.

1. 1
   Open the Marketplace and browse by department or search by tool/use-case.
2. 2
   Open an agent to review what it delivers, the tools it uses, its trigger type (scheduled, event, real-time, or on-demand), and pricing.
3. 3
   Click Deploy this agent to start a 7-day free trial. No card is required to begin exploring.
4. 4
   Connect the tools the agent needs (see Connect your tools). The agent only ever sees scoped, runtime-injected credentials.
5. 5
   Configure run parameters — schedule, approval thresholds, and any agent-specific settings.
6. 6
   Click Activate. The agent appears under My AI Workforce and begins working at its next trigger.

Connect your tools

Agents act through tools — Gmail, Slack, HubSpot, Stripe, Notion, Shopify, and 40+ more. You authorise each tool once via OAuth; AgentOS stores the token in an encrypted vault and injects it at runtime. Builder code never sees your raw credentials.

1. 1
   When deploying an agent, the required tools are listed with a Connect button.
2. 2
   Click Connect to open the provider's OAuth consent screen in a popup.
3. 3
   Review the requested scopes — AgentOS requests the minimum needed for the agent to function — and approve.
4. 4
   The popup closes and the tool shows as Connected. Repeat for each required tool.
5. 5
   Manage or revoke connections anytime from Settings → Connections. Revoking immediately cuts the agent's access.

Scopes & least privilege

Each agent declares exactly which scopes it needs in its manifest. If an agent asks for more than its description implies, that's a red flag — report it. We review scope requests during agent approval.

Manage & configure agents

Every deployed agent has a detail page with controls and history.

Pause & resume

Toggle an agent to Paused to halt all runs without losing configuration. Resume to pick up at the next scheduled trigger.

Edit configuration

Change schedules, approval thresholds, output destinations, and agent-specific settings. Changes take effect on the next run.

Approval gates

For sensitive actions (sending external email, posting publicly, spending money) you can require human approval. The agent pauses and notifies you; it only proceeds once you approve in the dashboard.

Read execution logs

Transparency is core to AgentOS. Every run produces a structured log of what the agent read, decided, and did.

1. 1
   Open an agent and select the Logs tab.
2. 2
   Each entry is one run, timestamped, with a status: success, warning, escalated, or error.
3. 3
   Expand a run to see the step-by-step trace — every tool call, its inputs, and its result, in plain language.
4. 4
   Use filters to narrow by status or date range when auditing behaviour.

Billing & subscriptions

Agents are billed as flat monthly (or annual) subscriptions. Bundles pool multiple agents under one plan — see Pricing.

Manage billing

1. 1
   Go to Settings → Billing.
2. 2
   Add or update a payment method (required only when a trial converts to a paid plan).
3. 3
   Switch between monthly and annual billing — annual saves 20%.
4. 4
   Cancel any agent in one click; it runs until the end of the current period, then stops.

Security model

AgentOS is built so that running someone else's agent never means trusting it with your secrets.

Credential isolation

OAuth tokens are encrypted at rest in a dedicated vault. They are decrypted and injected into the agent's sandbox only for the duration of a tool call, and are never exposed to builder code or logs.

Sandboxed execution

Each agent runs in an isolated sandbox with no ambient network access. It can only reach the specific tool endpoints its manifest declares.

Passwordless auth

There are no passwords to phish or breach. Access uses short-lived email OTP codes plus signed session tokens. See Authentication API.

Compliance

Infrastructure is built on hardened, regularly-audited providers. Scale customers can enable audit logging and SSO/SAML.

Architecture

A quick mental model of what runs where.

Edge backend

API and agent orchestration run on Cloudflare Workers at the edge for low latency and global availability. Durable state and queues coordinate scheduled and event-driven runs.

Data

Account data, agent configuration, and execution logs are stored in a managed database. The credential vault is separate and encrypted independently.

Email

Transactional email — OTP codes, run alerts, escalation notices — is delivered through Amazon SES.

Authentication API

If you're integrating programmatically, authentication is a two-call OTP exchange. All requests are over HTTPS; codes and tokens are single-purpose and short-lived.

1. Request a code

curl -X POST https://api.agentos.dev/v1/auth/otp/request \
  -H "Content-Type: application/json" \
  -d '{ "email": "you@company.com" }'

# 200 OK
# { "status": "sent", "expires_in": 600 }

This triggers an SES email containing a 6-digit code valid for 10 minutes. Requests are rate-limited per email and per IP.

2. Verify the code

curl -X POST https://api.agentos.dev/v1/auth/otp/verify \
  -H "Content-Type: application/json" \
  -d '{ "email": "you@company.com", "code": "418302" }'

# 200 OK
# { "token": "sess_…", "expires_at": "2026-06-04T12:00:00Z" }

3. Call the API

curl https://api.agentos.dev/v1/agents \
  -H "Authorization: Bearer sess_…"

Builder overview

An agent is three things: a manifest (what it is and what it needs), the run logic (what it does each execution), and the tools it calls. You write the first two with the SDK; we run, scale, bill, and distribute.

You keep 70% of every subscription. See For Builders for the economics.

Install the SDK

npm install @agentos/sdk
# or
pip install agentos-sdk

Authenticate the CLI

npx agentos login
# Sends an OTP to your email, then stores a builder session locally.

The agent manifest

The manifest is the contract between your agent and the platform. It declares metadata, the trigger, required tool scopes, configurable inputs, and the outputs the agent promises to deliver.

{
  "slug": "weekly-blog-publisher",
  "name": "Weekly Blog Publisher",
  "category": "marketing",
  "tagline": "Researches, writes, and publishes a blog post every week.",
  "trigger": { "type": "scheduled", "cron": "0 9 * * MON" },
  "price": { "amount": 99, "interval": "month" },
  "tools": [
    { "provider": "wordpress", "scopes": ["posts.write"] },
    { "provider": "openai", "scopes": ["completions"] }
  ],
  "inputs": [
    { "key": "topics", "type": "string[]", "label": "Topic themes" },
    { "key": "tone", "type": "enum", "options": ["formal", "casual"], "default": "casual" }
  ],
  "outputs": ["Published post URL", "SEO meta description"]
}

Field reference

trigger.type is one of scheduled (with a cron), event (fires on a webhook/tool event), realtime (long-lived), or ondemand. toolslists every provider and the minimum scopes you need — keep this tight, it's reviewed. inputs become the configuration form the customer fills in at deploy time.

SDK & run loop

Your agent exports a runhandler. The platform calls it on each trigger, passing a context object with the customer's config, authenticated tool clients, a logger, and a key-value store for state between runs.

import { defineAgent } from "@agentos/sdk";

export default defineAgent(async (ctx) => {
  // 1. Read customer configuration (from manifest inputs)
  const { topics, tone } = ctx.config;

  // 2. Use injected, scoped tool clients — no raw credentials
  const idea = await ctx.tools.openai.complete({
    prompt: `Pick an unused topic from: ${topics.join(", ")}`,
  });

  // 3. Do the work
  const draft = await ctx.tools.openai.complete({
    prompt: `Write a ${tone} 800-word post about ${idea}`,
  });

  // 4. Act through a tool
  const post = await ctx.tools.wordpress.createPost({
    title: idea,
    content: draft,
    status: "publish",
  });

  // 5. Log a human-readable summary and return outputs
  ctx.log.info(`Published "${idea}" → ${post.url}`);
  return { outputs: { "Published post URL": post.url } };
});

The context object

ctx.config — typed customer inputs. ctx.tools — authenticated clients for each declared provider. ctx.log — structured logging surfaced to the customer. ctx.state — persistent KV store (e.g. to avoid repeating work). ctx.secrets— your own builder-level secrets, never the customer's.

Test locally

Run your agent on your machine against mock tool credentials before submitting.

1. 1
   Create a .agentos/dev.json with sample config values and mock tool responses.
2. 2
   Run npx agentos dev to execute the run loop locally with verbose logs.
3. 3
   Use npx agentos dev --watch to re-run on file changes.
4. 4
   Assert outputs with npx agentos test, which runs your run loop against fixtures.

npx agentos dev --config ./.agentos/dev.json
# ▸ trigger: scheduled (simulated)
# ▸ tools: openai (mock), wordpress (mock)
# ✓ run completed in 1.2s — 1 post published

Submit & publish

1. 1
   Run npx agentos validate to lint the manifest and check scope declarations.
2. 2
   Run npx agentos submit to upload your agent to the builder portal.
3. 3
   Automated security scans run immediately (dependency audit, scope analysis, sandbox checks).
4. 4
   A reviewer evaluates quality, accuracy, and safety. Typical turnaround is 2–3 business days.
5. 5
   On approval, set your price and publish. Your listing goes live in the marketplace and starts accepting subscribers.
6. 6
   Track installs, active subscribers, and earnings in the builder portal. Payouts are monthly.

Webhooks & events

Event-triggered agents subscribe to provider events. Declare the event in the manifest trigger; the platform delivers a verified payload to your run loop.

"trigger": {
  "type": "event",
  "source": "stripe",
  "event": "charge.disputed"
}

You can also receive platform lifecycle events (subscriber added, agent paused, payment failed) at a builder webhook endpoint. Every payload is signed; verify the signature before trusting it.

import { verifyWebhook } from "@agentos/sdk";

export async function POST(req: Request) {
  const sig = req.headers.get("agentos-signature")!;
  const body = await req.text();
  const event = verifyWebhook(body, sig, process.env.AGENTOS_WEBHOOK_SECRET!);
  // event is trusted from here
  return new Response("ok");
}

Product vision

AgentOS is the world's first outcome-driven AI agent marketplace — not a tool store, not a prompt library, but a living workforce platform where businesses subscribe to AI workers that perform real business functions autonomously.

The core insight: businesses don't want AI, they want results. AgentOS abstracts the AI entirely and sells the outcome — a blog published, a lead qualified, an invoice sent, an appointment booked.

Mission

Replace the first 10 hires of every SMB with AI workers that cost 95% less.

Long-term vision

Every business on earth runs a hybrid workforce of humans and AI agents through AgentOS — the operating system for the autonomous enterprise.

Market & opportunity

Why now

LLMs crossed the “reliable enough for production” threshold in 2024; agentic frameworks matured for non-PhD builders; SMBs are desperate to compete with AI-equipped enterprises; and no dominant marketplace has yet captured the category.

Market sizing

Competitive landscape

Adjacent platforms each leave the outcome-driven B2B agent category open.

The AgentOS moat

Outcome framing (“Marketing Department”, not “chatbot”); the full infrastructure stack (deploy, monitor, bill, share revenue); both sides of the marketplace; framework-agnostic execution; and vertical onboarding tailored per business type.

Business model

A three-sided marketplace: builders upload agents and earn recurring revenue, businesses subscribe and deploy outcomes, and the platform provides infrastructure, distribution, and billing.

Revenue streams

Pricing tiers

Starter agents $29–$99/mo (single-function); Pro agents $99–$299/mo (multi-step, connected workflows); Enterprise agents $500–$5,000/mo (custom SLA, dedicated compute); Workforce bundles $499–$4,999/mo (vertical-specific stacks).

Builder economics

Builders keep 70%+ of every subscription, rising with scale. The platform covers all LLM and compute costs from its share.

Platform architecture

The platform is layered: surfaces, shared services, runtime, and infrastructure.

┌─────────────────────────────────────────────────────────┐
│                    AgentOS Platform                      │
├──────────────┬──────────────┬──────────────┬────────────┤
│  Marketplace │  Agent Store │  Builder Hub │  Biz Portal│
├──────────────┴──────────────┴──────────────┴────────────┤
│                 Platform Services Layer                  │
│  Auth │ Billing │ Analytics │ Monitoring │ Notifications │
├──────────────────────────────────────────────────────────┤
│                  Agent Runtime Engine                    │
│  Execution │ Memory │ Tool Calls │ Orchestration │ Logs  │
├──────────────────────────────────────────────────────────┤
│                  Infrastructure Layer                    │
│  AWS EKS │ Lambda │ RDS │ Redis │ S3 │ OpenSearch        │
└──────────────────────────────────────────────────────────┘

Tenant isolation

Row-level security with a tenant_id on every table; namespace-per-tenant vector memory; per-tenant object-storage prefixes and secret paths; and shared vs dedicated execution namespaces by tier (Starter shared, Enterprise dedicated).

Execution runtime

Agents run in isolated pods with credential injection and full observability.

Framework adapters

Each supported framework (LangGraph, CrewAI, N8N, custom) has an adapter normalizing a single execute(inputs, tools, memory) interface. Builders reference tools by key; AgentOS injects authenticated clients at runtime via the tool proxy — builder code never handles OAuth tokens.

Fault handling

Exponential-backoff retries on tool failures, an LLM fallback chain (Claude → GPT-4o → Gemini), a dead-letter queue for failed executions, and alerts to both business and builder on systemic errors.

Ranking & discovery

Organic ranking blends quality, reliability, and trust signals.

Anti-gaming & search

Ratings count only from active subscribers (3+ uses); subscriber counts are age-normalized with a launch-boost window; sponsored slots are clearly labeled and excluded from organic signals. Search is hybrid — OpenSearch BM25 keyword plus semantic kNN over agent embeddings, fused with Reciprocal Rank Fusion and personalized by business type and existing subscriptions.

Data model

The relational core spans organizations, users, builders, agents and their tool requirements, subscriptions, deployments, tool connections, execution logs, usage events, reviews, and payouts. Below are the two anchor tables; the full schema lives in docs/WHITEPAPER.md.

CREATE TABLE agents (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  builder_id UUID REFERENCES builders(id),
  name TEXT NOT NULL,
  slug TEXT UNIQUE NOT NULL,
  category TEXT,
  runtime TEXT,            -- langraph | crewai | n8n | custom
  base_price_cents INTEGER,
  trigger_type TEXT,
  status TEXT DEFAULT 'pending',  -- pending|approved|live|suspended
  manifest JSONB,
  ranking_score DECIMAL(6,2) DEFAULT 0,
  subscriber_count INTEGER DEFAULT 0,
  avg_rating DECIMAL(3,2),
  created_at TIMESTAMPTZ DEFAULT now()
);

CREATE TABLE agent_deployments (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  subscription_id UUID REFERENCES subscriptions(id),
  org_id UUID REFERENCES organizations(id),
  agent_id UUID REFERENCES agents(id),
  config JSONB,            -- user-supplied inputs
  status TEXT DEFAULT 'running',
  last_run_at TIMESTAMPTZ,
  next_run_at TIMESTAMPTZ,
  created_at TIMESTAMPTZ DEFAULT now()
);

Go-to-market

Supply-first, then demand, then paid, then enterprise.

1. 1
   Phase 1 (Months 1–6) — Supply. Recruit 50 high-quality builders pre-launch with a 90/10 split for 12 months, featured placement, and co-marketing.
2. 2
   Phase 2 (Months 4–9) — Demand. Product Hunt launch, vertical SaaS partnerships, provocative content (“Fire your content agency, hire a Content Agent”), before/after demos.
3. 3
   Phase 3 (Months 6–18) — Paid + partnerships. LinkedIn ads, referral program, agency partner program (30% rev share), integration marketplace listings.
4. 4
   Phase 4 (Months 12+) — Enterprise. Dedicated sales team, conference presence, analyst relations to establish the “AI Agent Marketplace” category.

Roadmap & milestones

36-month arc

Year 1 — Foundation:core marketplace, 20 house agents, Stripe billing, builder self-serve upload, tool integrations, search & recommendations, enterprise SSO + audit logs, public API v1.
Year 2 — Scale: agent orchestration, visual workflow builder, white-label, mobile apps, A/B pricing, private marketplaces, agent-to-agent protocol, SDK, vertical marketplaces.
Year 3 — Platform: AI Workforce OS, outcome-based pricing, marketplace API for embedding, global expansion, $100M ARR target.

Milestone targets

Unit economics & financials

5-year projection

Troubleshooting

I didn't receive my OTP code

Wait 60 seconds, check spam, confirm the address, then click Resend code. Each resend invalidates older codes. Codes expire after 10 minutes.

An agent shows “Review needed”

The agent hit an approval gate or a rate limit. Open it, read the latest log entry, and approve the pending action or wait for the limit to reset.

A tool shows “Disconnected”

The OAuth token expired or was revoked at the provider. Go to Settings → Connections and reconnect.

My agent run failed

Open the Logs tab and expand the failed run to see the exact failing step and error. Builders can reproduce locally with npx agentos dev.