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:
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_concurrentis 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.
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 itevents, 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).
{ "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. AddsignedContent, 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 takessignedContent.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~.
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: truefinishes 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,replayEventDeliveryandsendTestEventshow what arrived, process a delivery again, and send a test event.listEventSourceTypeslists 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
initializeand answerevents/listwith each event type’sname,description,deliverymodes,inputSchema(the subscription arguments) andpayloadSchema. - Offer
poll(events/poll),webhook(events/subscribeandevents/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: trueas missed events, which the run says. RepeatedeventIds are ignored. - Errors use the extension’s codes. Servers built for ChatGPT’s earlier sketch of the extension (
capabilities.eventsand errors -32011 to -32015) work as well.
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.
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: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. SetagentConfig.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.
listEventsreturns a summary view that can truncate long answers. For the complete result, calllistEventPagewithmode: "forensic"andpayloadMode: "full", follownextAfterwhilehasMore, and readpayload.outputfrom the turn’sturn.completedevent.