Notifications
The runtime publishes notifications on every meaningful transition: agent lifecycle, task progress, coordination events, and derived signals like repeated failures or approaching iteration limits. Subscribe to the stream to observe agent execution from outside.
See Agent notifications for how to subscribe.
This page is a catalog of all notification types. Two distinct families exist:
-
Autonomous agent notifications: the
Notificationsealed interface and its records, emitted by an agent instance and observed by subscribing to its notification stream. -
Task entity notifications: the
TaskNotificationsealed interface inakka.javasdk.agent.task, published by the task entities themselves.
Each link below points at the JavaDoc for the exact field set.
Autonomous agent notifications
Every autonomous agent notification implements the Notification sealed interface and exactly one capability-grouped marker sub-interface. Pattern-match on a marker to handle a whole family generically.
Lifecycle
Notification.LifecycleNotification: agent activation, iteration boundaries, and suspend/resume/stop transitions.
| Notification | Description |
|---|---|
Agent transitioned from idle to processing. |
|
No more work, back to idle. |
|
Model call beginning. |
|
Iteration completed successfully, with token usage. |
|
Iteration failed, optionally tied to a task and iteration number. |
|
Agent suspended, with the source of the suspend. |
|
Agent resumed, with the source of the resume. |
|
Agent stopped, distinguishing operator terminate from auto-stop on queue drain. |
Task
Notification.TaskNotification: assignment, start, completion, failure, cancellation, and dependency events.
| Notification | Description |
|---|---|
A task was accepted or queued, fires before the agent starts working on it. |
|
Agent started working on a task. |
|
Result rejected by a task rule. |
|
Task completed successfully. |
|
Task failed during execution, either by the model’s decision or because the iteration limit was reached. |
|
Task terminated before execution began, for example by a dependency failure or orphan cleanup. |
|
Task is blocked waiting for dependencies. |
|
A specific dependency resolved, with success or failure. |
Handoff
Notification.HandoffNotification: source-side and target-side of cross-agent handoffs.
| Notification | Description |
|---|---|
Source side. This agent handed off a task to a target. |
|
Target side. This agent received a handed-off task from a source. |
Delegation
Notification.DelegationNotification: orchestrator-side and worker-side of subtask delegation.
| Notification | Description |
|---|---|
Orchestrator side. A batch of subtasks was dispatched to one or more workers. |
|
Orchestrator side. Aggregate resolution of a delegation batch. |
|
Worker side. This agent accepted a delegated subtask. |
|
Worker side. Delegated subtask finished. |
Team
Notification.TeamNotification: team formation, member lifecycle, and disbanding.
| Notification | Description |
|---|---|
Lead side. A new team was formed. |
|
Lead side. A member’s setup chain completed. |
|
Lead side. A member’s setup chain failed. |
|
Lead side. A member has stopped. |
|
Lead side. Team disbanded. |
|
Member side. This agent joined a team. |
Conversation
Notification.ConversationNotification: conversation creation, turns, and participation lifecycle.
| Notification | Description |
|---|---|
Moderator side. A new conversation was created with a set of participants. |
|
Moderator side. A participant’s setup completed. |
|
Moderator side. A participant’s setup failed. |
|
Moderator side. The conversation ended. |
|
Moderator side. A turn was received from a participant. |
|
Participant side. This agent joined a conversation. |
|
Participant side. This agent submitted its turn. |
Messaging
Notification.MessagingNotification: contact introductions and message delivery.
| Notification | Description |
|---|---|
A message was received from another agent. |
|
A new contact was introduced. |
Struggle
Notification.StruggleNotification: derived signals for repeated failures, stuck dependencies, and approaching limits. The runtime tracks counters and emits these once per detection. Notifications are deduplicated until the underlying counter resets, for example on task termination or successful recovery. Thresholds are configurable in reference.conf under akka.runtime.autonomous-agent.struggle.
| Notification | Description |
|---|---|
Repeated iteration failures or repeated rule rejections on the same task. |
|
A task has been waiting on dependencies past the configured threshold; re-fires periodically. |
|
A task has reached the configured fraction (default 80%) of its max iterations. |
|
Repeated iteration failures in flows not tied to a specific task (pre-task setup, request-based delegation). |
Task entity notifications
akka.javasdk.agent.task.TaskNotification is published by the task entity itself on every terminal transition. This is the persistent, entity-level event used by the runtime for TaskClient.resultAsync and similar deliver-on-completion APIs.
Non-terminal transitions (created, assigned, started, reassigned) do not publish a notification. They are observable through event-sourced history or by reading the task snapshot.
| Notification | Description |
|---|---|
Task completed successfully, carrying the JSON-encoded result. |
|
A task rule rejected the result. |
|
Task failed. |
|
Task was cancelled. |