Actors

An actor is the entry point of work in Yoke. It subscribes to the event bus, performs its own filtering, and acts when an event passes.

Actors can do anything: send a message to an agent, spawn an agent, call a tool, publish another event, or write to the store. They are the glue between the stream and the agents.

Defining an actor

runtime.actor({
  name: "message-forwarder",
  topics: ["messages.incoming"],
  act: async (env, ctx) => {
    await ctx.agents.counter("default").sendMessage(env.payload);
  },
});

• topics — which topics to subscribe to.
• filter? — an optional predicate run against each envelope; the actor only acts when it returns true.
• act(env, ctx) — the handler. env is the event envelope, ctx is the runtime context.

Filtering

runtime.actor({
  name: "orders-only",
  topics: ["orders.*"],
  filter: (env) => env.type === "order.placed" && env.payload.customerId != null,
  act: async (env, ctx) => {
    // only high-value orders
    if (env.payload.total < 100) return;
    await ctx.agents.triage("default").sendMessage(env.payload);
  },
});

Typed actors

Because Runtime() accumulates types as you register, .actor(...) gets a ctx whose agents / tools are exactly the registered ones — with their input and output types. Reference an unregistered agent or tool and it's a compile-time error.

Use .actorTyped(...) when you also want ctx.inference's model to be the union of registered model ids:

runtime
  .withInference(stack)
  .actorTyped({
    name: "replier",
    topics: ["messages.incoming"],
    act: async (env, ctx) => {
      // ctx.inference.model is now the union of registered model ids
      const reply = await ctx.inference.chat({
        model: "gpt-4o", // type-checked against registered models
        messages: [userMessage(env.payload.text)],
      });
    },
  });

The actor lifecycle

Actors are started when the runtime serves:

1. runtime.actor(def) registers the actor.
2. runtime.serve() begins the actor's subscription.
3. For each event matching topics (and passing filter), act runs.

The runtime emits actor.started, actor.stopped, and actor.failed standard events around this lifecycle.