---
title: ".on()"
description: "Subscribe to typed agent lifecycle and execution events."
---

> Documentation Index
> Fetch the complete documentation index at: https://xsaf.ilha.build/llms.txt
> Use this file to discover all available pages before exploring further.

# .on()

## Signature

```ts
agent.on(type: EventType, handler: EventHandler): XsafAgent
```

## Usage

```ts
agent
  .on("tool.called", (event) => {
console.log(event.sessionId, event.tool);
  })
  .on("tool.failed", (event) => {
reportError(event.error);
  });
```

Handlers can be registered before or after the agent is sealed. `.on()` returns the agent, so subscriptions can stay in the configuration chain.

## Privacy boundary

Public telemetry intentionally excludes validated tool arguments and tool results. Use [`.approve()`](/xsaf/approve) for privileged argument inspection, and publish tool results explicitly only when your application permits it.

Available events cover lifecycle, model calls, tools, delegates, schedules, heartbeats, and errors. See [Types and events](/reference#events) for the complete event union.

Source: https://xsaf.ilha.build/xsaf/on/index.mdx