Agent

Scheduled agents

Scheduled agents let Brainbase run recurring work without putting product logic into the scheduler. The agent owns the durable instructions and credentials. The schedule owns timing and per-run configuration.

How schedules run

A schedule is a trigger node on an orchestration. When it fires, Brainbase creates a task for each trigger edge and sends the edge description plus the trigger payload as the initial user message.

Store standing behavior in the agent's instructions.
Store credentials in the agent's secrets.
Store per-schedule configuration in trigger configured_props.
Keep new schedules inactive until a manual dry run has been reviewed.

Cron expressions are evaluated in UTC

Use standard five-field cron syntax. If you need a local business time, convert it to UTC before writing cron_expression.

Create the agent

Create a normal agent with the runtime, tools, and instructions it should use for every scheduled task. Pass group_id if the orchestration will live inside a group.

bash

curl --request POST \
  --url "$BRAINBASE_MAS_URL/v2/agents" \
  --header "Authorization: Bearer $BRAINBASE_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "title": "Daily repository digest",
    "group_id": "11111111-2222-3333-4444-555555555555",
    "runtime_kind": "codex_cloud",
    "machine_kind": "daytona",
    "instructions": "Review the configured repositories, summarize meaningful changes, and take only the actions allowed by the trigger payload."
  }'

Store secrets

Secrets are planted into every task sandbox as environment variables. Do not put token values in instructions, trigger descriptions, or configured_props.

Secrets use whole-replace semantics

When updating secrets, send the full desired secret object. Omitted keys are removed.

bash

curl --request PATCH \
  --url "$BRAINBASE_MAS_URL/v2/agents/$AGENT_ID" \
  --header "Authorization: Bearer $BRAINBASE_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "secrets": {
      "GITHUB_TOKEN": "github_pat_...",
      "SLACK_WEBHOOK_URL": "https://hooks.slack.com/services/..."
    }
  }'

Create the schedule

Add the agent as an orchestration member, then add a schedule trigger with an edge to that agent. The edge description should say what to do when the trigger fires. The JSON payload is appended automatically.

bash

curl --request POST \
  --url "$BRAINBASE_MAS_URL/v2/orchestrations" \
  --header "Authorization: Bearer $BRAINBASE_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "group_id": "11111111-2222-3333-4444-555555555555",
    "name": "Daily repository digest",
    "description": "Scheduled repo review and digest generation.",
    "members": ["22222222-3333-4444-5555-666666666666"],
    "triggers": [
      {
        "trigger_type": "schedule",
        "cron_expression": "30 1 * * 2-6",
        "is_active": false,
        "configured_props": {
          "watched_repos": [
            "acme/web",
            "acme/api"
          ],
          "scan_overlap_hours": 2,
          "target": {
            "repo": "acme/web",
            "path": "content/changelog.ts"
          }
        },
        "edges": [
          {
            "to_agent_id": "22222222-3333-4444-5555-666666666666",
            "description": "Run the scheduled repository digest using the trigger payload."
          }
        ]
      }
    ]
  }'

On each scheduled run, the agent receives a payload with _source: "schedule", schedule metadata, and your opaque configured_props.

json

{
  "_source": "schedule",
  "schedule": {
    "trigger_id": "trigger-id",
    "node_id": "node-id",
    "orchestration_id": "orchestration-id",
    "cron_expression": "30 1 * * 2-6",
    "fired_at": "2026-05-28T01:30:00+00:00",
    "window_start": "2026-05-27T01:30:00+00:00",
    "window_end": "2026-05-28T01:30:00+00:00"
  },
  "configured_props": {
    "watched_repos": ["acme/web", "acme/api"],
    "scan_overlap_hours": 2
  }
}

Activate after a dry run

Before activating the schedule, create a manual task against the same agent with a representative trigger payload. Confirm the output, side effects, and credential access. Then patch the orchestration with the same trigger and is_active: true.