Remind me in three days

The simplest thing an agent can outsource to AIGears is its own memory of when. An agent finishes a piece of work, decides it should follow up in a few days, and — rather than staying resident for seventy-two hours — hands us a one-shot schedule. At the appointed moment we POST a webhook back, and a fresh agent instance picks the thread up. This is the first rung of the ladder: one primitive, one fire, no recurrence.

The story

A support agent has just replied to a customer and promised to check back if they don't hear anything. It doesn't want to poll, and it certainly doesn't want to sit in memory for three days. So it registers a schedule to fire in three days carrying enough context to resume, then exits. When the webhook arrives, a new instance reads the payload and continues the follow-up.

Solve it

Go to Schedules → New schedule, choose One-shot, and pick a date and time three days out. Paste the webhook_url the callback should POST to, and (optionally) a small JSON payload to carry context. Save, and the schedule shows up in the list as pending with its fire time.

POST /v1/schedules/ with a single fire_at timestamp and a webhook_url. The payload is echoed back to you when the webhook fires, so use it to carry whatever the resuming agent needs.

curl https://aigears.example.com/v1/schedules/ \
  -H "Authorization: Bearer aigears_live_..." \
  -H "Idempotency-Key: followup-ticket-8412" \
  -H "Content-Type: application/json" \
  -d '{
    "fire_at": "2026-07-06T09:00:00Z",
    "webhook_url": "https://hooks.example.com/aigears",
    "payload": {"ticket_id": "8412", "step": "follow-up"}
  }'

The runnable version lives in examples/python/schedules_agent.py (and examples/typescript/schedulesAgent.ts), which walks the whole lifecycle through the generated client. The create step is the same call as above:

one_shot = create_one_shot_schedule(
    client,
    fire_at=fire_at,
    webhook_url=webhook_url,
    payload={"kind": "reminder", "note": "schedules tracer bullet"},
)

Ask the agent in plain language; it translates the phrasing into a schedule_create call and keeps the returned id.

"Remind me in three days to follow up on ticket 8412."

schedule_create(
  fire_at="2026-07-06T09:00:00Z",
  webhook_url="https://hooks.example.com/aigears",
  payload={"ticket_id": "8412", "step": "follow-up"},
  idempotency_key="followup-ticket-8412",
)
  → { "id": "01J9Z8XKQR...", "status": "pending",
      "fire_at": "2026-07-06T09:00:00Z" }

(If the session hasn't selected a Team yet, the tool returns a no_team_selected error — call teams_list then set_current_team first. See Getting started.)

What happens next

Three days later, at fire_at, we POST a schedule.fired event to your webhook_url. Inside the standard signed envelope, the data is small — the schedule's id and the exact payload you registered:

{
  "event_type": "schedule.fired",
  "data": {
    "schedule_id": "01J9Z8XKQR...",
    "payload": {"ticket_id": "8412", "step": "follow-up"}
  }
}

Your receiver reads the payload and spins up a fresh agent to do the follow-up. The delivery shows up in the dashboard Activity feed with its status code. For how to stand up and verify a receiver, see Receiving webhooks; the signing and retry/dead-letter contract is owned by Webhooks & signing.

Variations

Carry more context. The payload is the resuming agent's whole memory of why it was called. Put the ticket id, the customer, the next step — anything it needs to act without re-deriving state.
Make retries safe. Pass an Idempotency-Key (HTTP) or idempotency_key (MCP) so an agent that retries the create after a dropped connection gets the original schedule back instead of double-booking the reminder. See Idempotency.

Next rung

Send the weekly report — the same primitive, but recurring.