> Documentation index for m4trix: https://m4trix.dev/llms.txt. Every page is available as Markdown by appending `.md` to its URL.

# Agents (Logic + Lifecycle)

Source: https://m4trix.dev/docs/concepts/agents

Agents are units of work. You build them with the `AgentFactory` builder, declaring which events they listen to, which events they emit, and the async logic that runs when triggered.

## Basic Usage

```ts title="echo-agent.ts"
import { AgentFactory, AgentNetworkEvent, S } from '@m4trix/core/matrix';

const inputEvent = AgentNetworkEvent.of('user-input', S.Struct({ text: S.String }));
const outputEvent = AgentNetworkEvent.of('agent-output', S.Struct({ reply: S.String }));

const echoAgent = AgentFactory.run()
  .listensTo([inputEvent])
  .emits([outputEvent])
  .logic(async ({ triggerEvent, emit }) => {
    emit({
      name: 'agent-output',
      payload: { reply: `Echo: ${triggerEvent.payload.text}` },
    });
  })
  .produce({});
```

## Lifecycle

1. **Definition** — `AgentFactory.run()` starts the builder; `.listensTo()`, `.emits()`, `.logic()` configure the agent.
2. **Production** — `.produce(params)` finalizes and returns an `Agent` instance.
3. **Registration** — The agent is registered in a network via `registerAgent(agent).subscribe(...).publishTo(...)`.
4. **Execution** — When a matching event arrives on a subscribed channel, the logic runs. The agent can emit events to its publish channels.

## Type Safety

The builder provides end-to-end type inference:

* **Trigger events** — `triggerEvent` in `.logic()` is typed as a union of all `listensTo` event envelopes
* **Emit payloads** — The `emit()` function only accepts payloads matching declared `emits` events
* **Parameters** — `params` in `.logic()` matches the schema from `.params()` (validated by `.produce()`)
* **Runtime emit checks** — `emit` only publishes events declared with `.emits()` (or a tool's `.emits()`) whose payload passes the event's schema; anything else throws `EmitValidationError` and fails the invocation. An agent without `.emits()` may emit nothing

## Catch-All Agents

If you omit `.listensTo()`, the agent receives **every event** on its subscribed channels, except the runtime's own `m4trix:*` events. Useful for logging and monitoring.

```ts
const loggerAgent = AgentFactory.run()
  .logic(async ({ triggerEvent }) => {
    console.log('Event received:', triggerEvent);
  })
  .produce({});
```

See [AgentFactory API](https://m4trix.dev/docs/api-reference/agent-factory.md) for the full builder reference.