Agents
Follow-up
Scheduled forum nudge when the agent was last to speak — defineFollowUpActor and assistant.follow_up_due.
The follow-up actor schedules a delayed forum message when the agent speaks last, and cancels when a human replies. It prevents conversations from going stale without blocking the processor.
Behavior
Agent posts to forum
│
▼
followUp actor: schedule assistant.follow_up_due (delayMs)
│
├─ Human posts before fire → cancel schedule
│
└─ Timer fires → post follow-up message (meta.followUp: true)Follow-up messages carry meta.followUp: true so they do not re-arm another timer.
defineFollowUpActor
import {
defineFollowUpActor,
followUpConfigSchema,
followUpStateSchema,
} from "@yoke/sdk";
followUp: actor(
defineFollowUpActor({
configSchema: followUpConfigSchema,
stateSchema: followUpStateSchema,
}),
),Config schema
const followUpConfigSchema = z.object({
sourceConversationId: z.string(), // forum id
forumParticipantId: z.string(),
agentActorId: z.string(),
delayMs: z.number().int().positive().default(30_000),
followUpText: z.string().default("Following up — still there?"),
});State schema
const followUpStateSchema = z.object({
lastScheduledAt: z.number().optional(),
followUpsSent: z.number().int().default(0),
});Filter logic
The follow-up actor subscribes to:
conversation.message.postedwherepayload.conversationId === sourceConversationId(forum)assistant.follow_up_duewherepayload.forumId === sourceConversationId
On forum message:
- If author is the agent (and not
meta.followUp) → schedule timer - If author is human → cancel timer
On assistant.follow_up_due:
- Post
followUpTextas forum message fromforumParticipantId
Schedule key
function scheduleKey(forumId: string) {
return `follow-up:${forumId}`;
}Uses ctx.schedules.schedule / cancel — see Schedules.
Join with follow-up
await joinConversation(ctx, agent, forumId, {
model: "gpt-4o",
followUp: true,
// or:
followUp: { delayMs: 60_000, text: "Still need help?" },
});joinConversation creates a follow-up instance alongside ingestion and processor.
Queue policy
queue: { mode: "fifo", concurrency: 1 },FIFO preserves forum message ordering for schedule arm/cancel decisions.
E2E verification
Test the full timer flow via portal /agents routes and a follow-up schedule.