Automations

Automations run cloud agents without a human kicking them off — on a schedule, or when something happens (a new issue, a failing build, a comment). Each automation stores a prompt template, trigger, and scope (repository, team, model) that the platform reuses on every invocation.

Trigger types

The platform supports four trigger kinds in the agents API. Additional sources (Slack, Linear, webhooks) appear in the UI roadmap; GitHub and schedule triggers are the most mature today.

Schedule examples

GitHub event examples

Trigger payload shape

Automations store triggers as JSON. Examples matching the platform contract:

{
  "kind": "schedule",
  "cron": "0 9 * * 1-5",
  "timezone": "America/New_York"
}

{
  "kind": "github",
  "event": "check_run",
  "action": "completed"
}

{
  "kind": "manual"
}

Built-in templates

The Agents workspace ships starter templates you can customize:

Defining an automation

1. Choose a trigger

   Pick a schedule or a GitHub event from a connected integration. For schedules, set cron, timezone, and confirm the next run time shown in the UI.

2. Describe the task

   Write the instruction the agent should follow each time it runs. Be specific about scope, severity thresholds, and what to do when nothing is found ("report no issues" vs. stay silent).

3. Set repository and branch

   Scope the automation to a single repository. The agent clones from your configured base branch unless the trigger provides a ref (for example, a PR head SHA).

4. Configure model and approvals

   Choose the model and approval policy. High-impact automations (auto-opening PRs) should use stricter approval settings than read-only triage.

5. Enable and monitor

   Start in draft, run manually once, then set status to enabled. Watch the first few runs in Sentinel before widening scope.

Create an automation via API

Automations are managed through the agents API. Requests require an authenticated session scoped to your organization.

curl -X POST "https://agents-api.4rged.ai/api/automations" \
  -H "Authorization: Bearer <session-access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "org_abc123",
    "repositoryId": "42",
    "name": "Fix failing CI",
    "promptTemplate": "When CI fails on a PR, inspect the failing check logs, implement a minimal fix, and open a PR if confident.",
    "status": "draft",
    "trigger": {
      "kind": "github",
      "event": "check_run",
      "action": "completed"
    },
    "agentKind": "cloud"
  }'

List automations for an organization:

curl "https://agents-api.4rged.ai/api/automations?organizationId=org_abc123" \
  -H "Authorization: Bearer <session-access-token>"

Automation lifecycle

API permissions and agent kinds

Creating automations through POST /api/automations on agents-api.4rged.ai requires an authenticated session with agent manager capability for the target organization. The handler persists records in x4rge_agent_automations with a required name and promptTemplate; new automations default to draft unless enabled: true is sent. The agentKind field accepts general, reviewer, tester, fixer, or pr_assistant — matching cloud run kinds in packages/platform-contracts. Each creation writes an audit event for operator review.

Best practices

• Start automations in a low-stakes repository and review their output before widening scope.
• Cap concurrent runs per automation to avoid duplicate PRs on the same failure.
• Pair automations with budget policies so runaway triggers can't exhaust allowance.
• Log automation IDs in run metadata so Sentinel can correlate runs to their source.