Core Concepts

Understanding The One Agents requires understanding five things: Events, Agents, Steps, Executions, and Credits. Everything else is built on these.

Events

Events are the heartbeat of the platform. Every product in The One Stack publishes structured events to The One Bus as things happen — a ticket is opened, an alert fires, an invoice goes overdue, an employee is offboarded. The One Agents subscribes to all of them.

Event Schema

Every Bus event has the same outer structure:

{
  "id": "evt_01HXYZ...",
  "event_type": "ticket.created",
  "source_product": "psa",
  "org_id": "org_abc123",
  "client_id": "client_xyz",
  "payload": {
    "ticket_id": "tkt_abc123",
    "priority": "p2",
    "subject": "Server unreachable",
    "type": "incident",
    "created_by": "user_abc",
    "created_at": "2026-03-09T14:23:00Z"
  },
  "metadata": {
    "agent_triggered": false
  },
  "published_at": "2026-03-09T14:23:01Z"
}

The payload is product-specific — each event type has its own documented payload structure in the Event Catalog.

Filterable Fields

Each event type exposes a set of filterable fields — specific payload paths you can use to filter which events actually trigger your agent. For example, psa:ticket.created exposes priority, type, and client_id as filterable fields.

Operator	Applies To	Behavior
`eq`	string, number, boolean, enum	Exact match
`ne`	string, number, boolean	Not equal
`gt`	number	Greater than
`lt`	number	Less than
`contains`	string	Substring match
`in`	enum, string	Value is in array
`not_in`	enum, string	Value is not in array

Trigger filters are evaluated before agent conditions — they're an efficient first pass. Conditions (see below) run after the trigger matches and can access richer context.

Deduplication

Events are deduplicated within a 5-minute window per agent. If the same trigger event fires your agent twice within 5 minutes (e.g., a rapid ticket-updated loop), the second execution is suppressed and logged as a duplicate. This prevents runaway execution loops.

Agents

An agent is a persistent, named definition that says: "When this event happens, check these conditions, then execute these steps."

Agent Types

Type	Description
`system`	Pre-built by The One Stack team. Runs for all orgs. Cannot be deleted. Can be paused or overridden at the org level.
`template`	A read-only definition in the template library. Cannot be executed directly — must be cloned first.
`cloned`	A clone of a system agent or template. Fully owned by the org. Customizable.
`custom`	Built from scratch by the org. Fully owned. Counts against the active agent limit.

Agent Status

Status	Meaning
`active`	Running — will fire on matching events
`paused`	Defined but not running
`draft`	Being built — not yet deployed
`error`	Failed configuration validation

Conditions

Conditions are evaluated after the trigger filter passes. They support the same operators as trigger filters, plus exists, and can reference both the event payload (context: 'event') and enriched client context (context: 'client_context').

Example: "Fire only if the ticket client has an active Defend subscription" — this requires checking the client context, not just the event payload.

Conflict Behavior

When a system agent and a custom agent both match the same trigger, conflict_behavior controls what happens:

Value	Behavior
`additive`	Both agents run (default for system agents)
`override_system`	This custom agent runs; the system agent is suppressed for this event
`exclusive`	This agent runs; all other agents for this trigger are suppressed

Execution Limits

Agents support rate limiting to prevent abuse or unexpected loops:

"execution_limit": {
  "max_per_hour": 10,
  "max_per_day": 50,
  "cooldown_minutes": 5
}

When a limit is reached, executions are queued and processed after the cooldown or the next hour/day window.

Client Scope

Agents can be scoped to all clients or a specific subset:

"client_scope": "all"          // fires for all managed clients
"client_scope": ["client_abc", "client_xyz"]  // fires only for these clients

Steps

Steps are the actions an agent takes when it runs. There are six step types.

AI Reason

Calls an AI model with a prompt you define. The full client context (if the Context Builder has a profile for this client) is injected automatically alongside the event payload.

{
  "type": "ai_reason",
  "id": "classify",
  "model": "standard",
  "prompt": "Classify this ticket for routing.\n\nSubject: {{event_payload.subject}}\nType: {{event_payload.type}}\n\nReturn JSON with: priority, category, required_skill",
  "output_var": "classification",
  "output_schema": { "type": "object", "properties": { "priority": { "type": "string" } } },
  "estimated_credits": 20,
  "on_error": "continue"
}

The model's output is stored in output_var and is available to all subsequent steps via template syntax: {{classification.priority}}.

Model tiers:

Tier	Model	Credits/Step	Best For
`quick`	GPT-4o mini (~2K tokens)	5	Simple classification, routing decisions
`standard`	GPT-4o mini (~8K tokens)	20	Triage, draft responses, moderate reasoning
`premium`	GPT-4o (~8K tokens)	100	Complex analysis, QBR narratives, security reasoning
`expert`	Claude Sonnet (~8K tokens)	200	Highest-quality reasoning, compliance analysis, nuanced judgment

Product Action

Calls any product API to take action. Uses a service-level integration key — not tied to any individual user's permissions.

{
  "type": "product_action",
  "id": "create_ticket",
  "product": "psa",
  "action": "create_ticket",
  "params": {
    "org_id": "{{org_id}}",
    "client_id": "{{event_payload.client_id}}",
    "subject": "{{analysis.ticket_subject}}",
    "priority": "{{analysis.severity}}"
  },
  "on_error": "fail"
}

The on_error field controls behavior when the action fails:

fail — Stop execution, mark as failed
continue — Log the error, continue to next step
retry — Retry up to 3 times with exponential backoff, then fail

Notification

Sends an email, SMS, or push notification. Recipients can be hardcoded or interpolated from context variables.

{
  "type": "notification",
  "id": "alert_oncall",
  "channel": "sms",
  "recipients": ["+15551234567"],
  "body": "P1 security incident: {{analysis.ticket_subject}}. Ticket: {{ticket.id}}"
}

Notification steps cost zero credits. SMS delivery uses The One Voice infrastructure.

Approval Gate

Pauses the workflow and waits for a human decision. The agent sends a notification to the specified recipients with an approve/deny link. If no decision is made before timeout_hours, the on_timeout default is applied.

{
  "type": "approval_gate",
  "id": "confirm_isolation",
  "message": "Confirm device isolation for {{event_payload.hostname}} (Client: {{event_payload.client_id}}). Ransomware confidence: {{event_payload.detection_confidence}}",
  "notify_channel": "sms",
  "notify_recipients": ["+15551234567"],
  "timeout_hours": 2,
  "on_timeout": "deny"
}

Approval gates cost zero credits. Executions in waiting_approval status remain open until the gate resolves. All approval decisions are logged with the deciding user and timestamp.

Branch

Evaluates a JavaScript expression against accumulated context variables and routes to one of two step lists.

{
  "type": "branch",
  "id": "check_severity",
  "condition": "analysis.should_page_oncall === true",
  "true_steps": [
    { "type": "product_action", "id": "page_oncall", ... }
  ],
  "false_steps": [
    { "type": "notification", "id": "log_only", ... }
  ]
}

Branch expressions can reference any variable in the execution context: event_payload, org_id, client_id, and any output_var from preceding AI Reason steps.

Wait

Pauses execution for a fixed duration before continuing to the next step. Useful for rate-limiting follow-up actions or building sequential workflows.

{
  "type": "wait",
  "id": "pause_30min",
  "duration_minutes": 30
}

Wait steps cost zero credits. The execution remains in running status during the wait.

Executions

An execution is a single run of an agent, triggered by a specific Bus event. Each execution has a complete, immutable log.

Execution Status

Status	Meaning
`pending`	Queued, not yet started
`running`	Actively executing steps
`completed`	All steps finished successfully
`failed`	A step failed with `on_error: fail` or an unrecoverable error occurred
`cancelled`	Manually cancelled via API or UI
`waiting_approval`	Paused at an Approval Gate step, awaiting a human decision

Step Results

Each step in an execution produces a StepResult:

{
  "step_id": "classify_ticket",
  "step_type": "ai_reason",
  "status": "completed",
  "output": { "priority": "p1", "category": "security", "required_skill": "senior" },
  "credits_used": 20,
  "duration_ms": 843,
  "started_at": "2026-03-09T14:23:02Z",
  "completed_at": "2026-03-09T14:23:02Z"
}

Step output is available to subsequent steps via the output_var name defined in the step config.

Retry and Cancel

Running or failed executions can be retried or cancelled via the UI or API:

Retry — Re-executes the agent from the beginning using the original trigger event. Credits are consumed again.
Cancel — Stops a running or waiting execution. Pending steps are skipped. Cannot be undone.

Credits

Credits are the currency for AI reasoning steps. One credit equals approximately $0.001 retail.

Non-AI steps — Product Action, Notification, Approval Gate, Branch, Wait — cost zero credits. You only pay for intelligence.

Monthly Allocation

Tier	Credits/mo	Typical Usage (50-client MSP)
Starter	20,000	~2 months of system agent traffic
Growth	100,000	Comfortable headroom for system + 10 custom agents
Scale	300,000	Large MSPs, aggressive automation, unlimited custom agents

A typical 50-client MSP running only system agents consumes roughly 10,000–12,000 credits per month — well within the Starter allocation.

Usage Monitoring

Navigate to Credits to see:

This month's usage — credits used vs. allocation, with a breakdown by agent and by model tier
12-month history — month-over-month trend
80% threshold alert — automatic notification when you reach 80% of your monthly allocation

Credits do not roll over month to month.

Overages

If your organization exhausts its monthly allocation, AI Reason steps begin failing. Executions that reach a depleted credit balance are logged as failed with a credit_insufficient error. Non-AI steps continue to run unaffected.

Top-up packs are available to cover overages mid-month. See Credits & Billing for details.

Events​

Event Schema​

Filterable Fields​

Deduplication​

Agents​

Agent Types​

Agent Status​

Conditions​

Conflict Behavior​

Execution Limits​

Client Scope​

Steps​

AI Reason​

Product Action​

Notification​

Approval Gate​

Branch​

Wait​

Executions​

Execution Status​

Step Results​

Retry and Cancel​

Credits​

Monthly Allocation​

Usage Monitoring​

Overages​