# `Sycophant.Agent.Telemetry`

Telemetry events for the agent lifecycle.

Emits `:telemetry` events at key points during agent execution,
following the standard span pattern.

## Agent Events

  * `[:sycophant, :agent, :start]` - Agent starts.
    Measurements: `%{}`.
    Metadata: caller-provided (e.g. `%{model: ...}`).

  * `[:sycophant, :agent, :stop]` - Agent stops.
    Measurements: caller-provided (e.g. `%{duration: integer}`).
    Metadata: caller-provided (e.g. `%{reason: atom}`).

## Turn Events

  * `[:sycophant, :agent, :turn, :start]` - A turn begins.
    Measurements: `%{}`.
    Metadata: caller-provided (e.g. `%{turn_number: integer}`).

  * `[:sycophant, :agent, :turn, :stop]` - A turn completes.
    Measurements: caller-provided (e.g. `%{duration: integer, input_tokens: integer}`).
    Metadata: caller-provided.

## Tool Events

  * `[:sycophant, :agent, :tool, :start]` - Tool execution begins.
    Measurements: `%{}`.
    Metadata: caller-provided (e.g. `%{tool_name: string}`).

  * `[:sycophant, :agent, :tool, :stop]` - Tool execution completes.
    Measurements: caller-provided (e.g. `%{duration: integer}`).
    Metadata: caller-provided.

## Other Events

  * `[:sycophant, :agent, :error]` - An error occurs.
    Measurements: `%{}`.
    Metadata: caller-provided (e.g. `%{error: term}`).

  * `[:sycophant, :agent, :state_change]` - Agent state transition.
    Measurements: `%{}`.
    Metadata: `%{from_state: atom, to_state: atom}`.

## Attaching Handlers

    :telemetry.attach_many("agent-logger", Sycophant.Agent.Telemetry.events(), &handle_event/4, nil)

# `agent_start`

```elixir
@spec agent_start(map()) :: :ok
```

Emits agent start event.

# `agent_stop`

```elixir
@spec agent_stop(map(), map()) :: :ok
```

Emits agent stop event with measurements.

# `error`

```elixir
@spec error(map()) :: :ok
```

Emits error event.

# `events`

```elixir
@spec events() :: [[atom(), ...]]
```

Returns the list of telemetry event names emitted by the agent.

# `state_change`

```elixir
@spec state_change(atom(), atom()) :: :ok
```

Emits state change event.

# `tool_start`

```elixir
@spec tool_start(map()) :: :ok
```

Emits tool start event.

# `tool_stop`

```elixir
@spec tool_stop(map(), map()) :: :ok
```

Emits tool stop event with measurements.

# `turn_start`

```elixir
@spec turn_start(map()) :: :ok
```

Emits turn start event.

# `turn_stop`

```elixir
@spec turn_stop(map(), map()) :: :ok
```

Emits turn stop event with measurements.

---

*Consult [api-reference.md](api-reference.md) for complete listing*