dotfiles/dot_claude/skills/agents-sdk/references/server-driven-messages.md

Server-Driven Messages (Trigger Patterns)

Fetch https://developers.cloudflare.com/agents/api-reference/trigger-patterns/ for complete documentation.

Patterns for server-initiated LLM turns in AIChatAgent — from schedules, webhooks, email, or other agents.

saveMessages — Trigger an LLM Turn

await this.saveMessages((existingMessages) => [
  ...existingMessages,
  { role: "user", content: "Check for new notifications" }
]);

saveMessages persists the messages AND triggers onChatMessage.

persistMessages — Save Without Triggering

await this.persistMessages([
  ...this.messages,
  { role: "assistant", content: "System note: checked at " + new Date() }
]);

waitUntilStable

Always call before saveMessages from non-chat contexts (schedules, webhooks, email):

async checkNotifications(payload: unknown, schedule: Schedule) {
  await this.waitUntilStable({ timeout: 30_000 });
  await this.saveMessages((msgs) => [
    ...msgs,
    { role: "user", content: "Run scheduled notification check" }
  ]);
}

onChatResponse

Runs after each LLM turn completes. Use for chaining:

async onChatResponse(result: ChatResponseResult) {
  if (result.type === "finish" && needsFollowUp(result)) {
    await this.saveMessages((msgs) => [
      ...msgs,
      { role: "user", content: "Continue with next step" }
    ]);
  }
}

Client Status

const { isStreaming, isServerStreaming } = useAgentChat({ agent });

• isStreaming — true during any streaming (user-initiated or server-initiated)
• isServerStreaming — true only during server-initiated streams