Observability
Observer hooks let plugins reconstruct agent execution without changing runtime behavior.
Contract
Plugins can register hooks such as:
def register(ctx):
ctx.register_hook("pre_api_request", on_pre_api_request)
ctx.register_hook("post_api_request", on_post_api_request)
ctx.register_hook("pre_tool_call", on_pre_tool_call)
ctx.register_hook("post_tool_call", on_post_tool_call)Callbacks should accept **kwargs so additive fields remain backward-compatible.
Correlation fields
Important fields include:
| Field | Meaning |
|---|---|
session_id | Conversation identity. |
turn_id | User-turn identity. |
api_request_id | Provider attempt identity. |
tool_call_id | Provider tool-call identity when available. |
task_id | Task identity for subagents and isolated execution. |
Event families
Observer events cover session lifecycle, turn-scoped LLM hooks, request-scoped API hooks, tool lifecycle, delegation, and budget or interruption events.
Behavior
Observer hooks should be fail-open. If a telemetry plugin fails, Arcen logs a warning and keeps the agent loop running.