Skip to main content
Start agents on a schedule or from your product’s events, let them work to completion, and bring the results back.

On a schedule

agent is optional; without it, runs use the workspace defaults (Configure the agent). runMode picks a new session per run, one reusable session, or an existing session. Select tools by id from a workspace OpenAPI Integration or MCP connection. Manage tasks with listScheduledTasks, updateScheduledTask, pauseScheduledTask, resumeScheduledTask, triggerScheduledTask, and deleteScheduledTask. To continue an existing conversation, schedule a message for that session:
Each run uses that chat’s own model and tools and runs as the schedule owner. Updates keep fields you omit; expectedExecutionDigest rejects a conflicting edit. If moving targetSessionId would change the run’s settings, the API returns a conflict; repeat with adoptSessionSettings: true to accept. overlapPolicy decides what a run into a chat does when the chat is still busy:
  • steer (the default): if the busy turn is this task’s own earlier run, the new run reaches it at its next model step, like a person’s Steer. The tool calls of that step finish, and the agent then reads the new run together with the work so far, so a burst of events is handled as one conversation instead of a queue of separate replies. A turn anyone else started still finishes first, and the run follows it.
  • buffer_one (allow_concurrent is the same in a chat): the run waits and starts when the current turn finishes.
  • skip: the run is dropped, and the next one runs as normal.
Runs in a new chat (new_session_per_run) never wait, so the choice only matters for tasks that continue a chat.

From your product’s events

A scheduled task can also run when something happens: give it events, and each event that matches one of its triggers starts a run. Events come from an event source: Event triggers are on when clientConfig.eventTriggers.enabled is true (OPENGENI_EVENT_TRIGGERS_ENABLED on the deployment).
Your backend sends { "type": "ticket.created", "timestamp": "…", "data": { … } } with the webhook-id, webhook-timestamp and webhook-signature headers; any Standard Webhooks library signs it. Each run gets the events that started it. Redelivered events (same webhook-id) are ignored, and the agent treats event data as untrusted input. An app with its own webhook format needs no code: describe the format on a custom source and paste the app’s secret. signature.scheme is one of:
  • standard_webhooks.
  • hmac_sha256: the body’s HMAC in a header, hex or base64, after an optional prefix. Add signedContent, such as "v0:{header:X-Request-Timestamp}:{body}", when the app signs more than the body.
  • timestamped_hmac_sha256: t=<unix seconds>,v1=<hex> over "<t>.<body>".
  • token: a shared secret in a header.
  • ed25519: the app’s signature, checked with its public key as the secret. It also takes signedContent.
  • url_token: for apps that can’t sign. The secret goes in the address as ?token=<secret>, and it must be at least 24 letters, digits, -, _, . or ~.
The other fields are dot paths into each event, or headers. summary, subject, url, actor, eventId and occurredAt also take a list of paths, where the first with text wins. type can join parts, freshness refuses old deliveries, and actorKind says which actors are people. eventId can also join parts with a separator: an alert’s status, fingerprint and startsAt name one firing episode, so an alert sent again runs automations once, and an event missing a part has no id. Linear, Sentry and Tailscale have presets that Automations and agents offer by name. Agents add webhook sources with the event_sources_create_webhook tool. Tailscale, spelled out:
  • events.once: true finishes the task after its first run, for “tell me when this happens”. A once-task that continues a chat belongs to it: archiving that chat with Pause removes the task if it has not run yet.
  • events.maxRunsPerHour (default 30) holds back a burst; held events are batched into the next run, and the owner is told once.
  • Events made by Opengeni’s own bots don’t fire a trigger unless it sets includeOwnEvents: true.
  • listEventDeliveries, replayEventDelivery and sendTestEvent show what arrived, process a delivery again, and send a test event. listEventSourceTypes lists the event types a trigger can name.

Events from your own MCP server

If your product already gives the agent an MCP server, that server can publish events too, and nothing has to sign webhooks. Opengeni implements the client side of the MCP Events extension (SEP-3415, io.modelcontextprotocol/events):
  • Advertise the extension in initialize and answer events/list with each event type’s name, description, delivery modes, inputSchema (the subscription arguments) and payloadSchema.
  • Offer poll (events/poll), webhook (events/subscribe and events/unsubscribe), or both. Opengeni prefers a webhook, refreshes it before its TTL runs out, and polls instead when your server can’t reach Opengeni’s address. push (events/stream) is not used yet.
  • Return a cursor with each page or delivery. Opengeni resumes from it and treats truncated: true as missed events, which the run says. Repeated eventIds are ignored.
  • Errors use the extension’s codes. Servers built for ChatGPT’s earlier sketch of the extension (capabilities.events and errors -32011 to -32015) work as well.
Each trigger names one event type and its arguments, checked against the type’s inputSchema. Opengeni subscribes as the event source’s owner, through their connection to your server, so your server decides which events that person may see just as it does for their tool calls. When no automation listens any more, Opengeni unsubscribes.

Automations in your UI

AutomationsPanel from @opengeni/react/automations lists, creates and edits automations inside your own dialog or page. Given a sessionId, new automations continue that chat; without one, each run starts a new chat with the workspace’s defaults and the owner’s access. It offers event triggers whenever the deployment runs them; pass eventTriggers={false} to offer schedules only.
Its words come from the automations.* message keys, so OpenGeniMessagesProvider translates it. Sessions and session list entries carry automationWait: the next run, or the event and source the chat waits for. sessionAutomationWaitWords(t, session, { now }) turns it into “Waiting for project.updated from Acme” or “Next run: Tomorrow, 09:00” for your own chat list.

Work until done

Give a session a goal and it keeps working across turns until the goal is met or it pauses with a reason:
See Goals.

Nobody watching

A run that a schedule or event starts is unattended: no person answers while it works. The agent is told so, settles open choices with the most conventional option instead of asking, and ends with its result, the assumptions it made and any steps left for a person. A call that needs someone’s approval is not run and not approved; the agent gets an error result and works around it. Your tool permissions stay as you set them. Set agentConfig.unattended: false for a schedule whose runs someone answers (for example approvals with approvalTimeoutSeconds, which also keeps runs attended). For a session your backend starts with no person behind it, pass unattended: true to createSession; with an initialMessage and no goal, it also gets a goal to complete that message, so it keeps working until the agent completes or pauses it (pass goal: null to opt out). People can switch any chat with Work without me in its Settings tab; your code can do the same with updateSessionUnattended. Switching changes only whether the agent waits for a person: the agent’s instructions and tools stay as the chat started, so a question in a chat switched to unattended gets an immediate “no one will answer” result instead. Explicit choices stay until someone changes them. Only the default for scheduled and event-triggered chats ends by itself: when someone writes in that chat from the web app, Slack or a call, it runs attended from that message on.

Bring results back

  • Write back through your tools. The agent calls your API to update a ticket, post a comment, or store a report. This is the most direct path.
  • Webhooks. Get notified when a turn completes or fails, a session’s status changes, or the agent waits for approval or an answer. Deliveries are signed, at least once, and unordered; read the session through the API when one arrives. See Webhooks and credentials.
  • Read the full output. listEvents returns a summary view that can truncate long answers. For the complete result, call listEventPage with mode: "forensic" and payloadMode: "full", follow nextAfter while hasMore, and read payload.output from the turn’s turn.completed event.
Using a coding agent? The opengeni-client skill covers this.