Stately Agent

You can emit custom domain events from within your machine using enq.emit(...). To ensure type safety, declare the emitted event schemas in setupAgent.

Emitted events are 'fire-and-forget' observations; they do not affect the machine's control flow or state transitions. They are ideal for triggering UI updates, SSE streams, or logging.

Workflow:

1. Define the event schema in the emitted property of setupAgent using Zod.
2. Emit the event inside the machine (e.g., in an onDone handler) using enq.emit({ type: 'EVENT_NAME', ... }).
3. Handle the event in the runAgent configuration using the on property.

const agentSetup = setupAgent({
  context: z.object({ /* ... */ }),
  emitted: {
    EVALUATED: z.object({ qualityScore: z.number(), iteration: z.number() }),
  },
  // ...
});

// In the machine, from any transition or entry function:
onDone: ({ context, output }, enq) => {
  enq.emit({ type: 'EVALUATED', qualityScore: output.score, iteration: context.iteration });
  return { target: 'checking', context: { evaluation: output } };
},

Implement reliability, safety, and human oversight using these patterns:

Durable Threads and Long Pauses

For workflows requiring long-running processes or persistence across different environments:

• Long-running onboarding: Use a multi-day coordinator with durable typed state and dormancy gates.
• File-backed snapshot store: Use a file-based store to maintain durable threads across different processes.

For more on pausing and resuming, see Human in the loop.

When using an LLM to generate agent machines, be aware of the following technical constraints:

• Host-Resolved Guards and Actions: A configuration cannot contain actual functions. It can only contain string names (e.g., guard: "isReady"). The actual implementation must be provided in the guards object passed to setupAgent.fromConfig(...). You should list the available names in your prompt to guide the model.
• Schema vs. Semantic Validity: Ajv validates the shape of the JSON, but not the meaning. A config might be schema-valid but logically broken (e.g., referencing a non-existent request). Use lintAgentMachine and simulateAgent to catch these semantic errors.
• Simulation Coverage: simulateAgent follows a specific script and only covers one path. If you need to verify that a generated branch structure is sound, use explorePaths.
• Unchecked String References: Model references and tool names are treated as unchecked strings in the config. They are resolved at runtime by the host. When using generated machines, ensure you pass createAiSdkExecutors({ resolveModel }) to handle these string-based model references.

An AgentMessage is a parts-based, discriminated union representing a single conversation turn. It is designed to mirror the Vercel AI SDK's ModelMessage structure without requiring a dependency on the ai package.

Messages are categorized by role, which determines the allowed structure of the content field:

• system: content must be a string.
• user: content can be a string, or an array of TextPart, ImagePart, or FilePart.
• assistant: content can be a string, or an array of TextPart, FilePart, ToolCallPart, or ToolResultPart.
• tool: content must be an array of ToolResultPart.

Note on Serialization: ImagePart and FilePart can contain binary data (Uint8Array, ArrayBuffer) or URL instances. These are not JSON-serializable. If you plan to persist messages (e.g., to a database), you must convert binary data to base64 strings and URL instances to strings manually.

type AgentMessage = SystemMessage | UserMessage | AssistantMessage | ToolMessage;

In Stately Agent, conditional logic is handled via guarded transitions rather than router functions.

Instead of a node returning a string that a router function uses to pick the next node, the model selects from a set of allowedEvents. The transition is then governed by a guard (a function attached to an event). If the guard returns undefined, that transition is considered illegal for the current state.

**Key differences:

• Model interaction: The model picks a named event. If the guard rejects it, the attempt is recorded as rejected-by-guard and the model is prompted again with that feedback.
• Safety: Constraints are enforced by the machine's guards, meaning they hold regardless of what the prompt instructs the model to do.
• Typo prevention: The model picks from defined event names rather than generating arbitrary routing strings.

// Example of a guarded transition in a machine definition
grading: {
  invoke: {
    src: "agent.decide",
    input: ({ context }) => ({
      model: "grader",
      system: "GENERATE if the documents answer the question, else REWRITE.",
      prompt: `Question:\n${context.question}\n\nDocuments:\n${context.docs}`,
      allowedEvents: ["GENERATE", "REWRITE"],
    }),
  },
  on: {
    GENERATE: { target: "generating" },
    // The guard: returns undefined if the condition isn't met, making the transition illegal
    REWRITE: ({ context }) =>
      context.rewrites < 2
        ? { target: "rewriting", context: { rewrites: context.rewrites + 1 } }
        : undefined,
  },
}

Stately Agent supports several architectural patterns for coordinating multiple agents or specialized workers. These patterns allow you to manage complexity by delegating tasks to typed child actors or specialized machines.

Available Patterns

For detailed implementation of sub-agents and child actors, see the Multi-agent documentation.