Skip to main content
Last updated on
Tags:
Options
Open in ChatGPTAsk ChatGPT about this pageOpen in ClaudeAsk Claude about this page

Event Model

OpenBox receives both governed middleware events and operational telemetry from the LangChain SDK. Understanding that model is necessary for writing policy, configuring guardrails, and interpreting the dashboard correctly.

Top-Level Event Types​

Event typeEmitted byPrimary use
WorkflowStartedbefore_agent middleware hookStart-of-run governance
WorkflowCompletedafter_agent middleware hookFinal outcome and summary telemetry
SignalReceivedUser prompt extraction before the agent startsPrompt-level context and auditability
LLMStartedwrap_model_call before model executionInput-time model governance and prompt guardrails
LLMCompletedwrap_model_call after model executionOutput-time model governance, token usage, and response metadata
ToolStartedwrap_tool_call before tool executionInput-time tool governance and approvals
ToolCompletedwrap_tool_call after tool executionOutput-time tool governance and tool result telemetry

Business Events Versus Internal Telemetry​

In the LangChain SDK, business events are the middleware boundaries:

  • agent run start and completion
  • model call start and completion
  • tool call start and completion

These are not separate business events:

  • internal HTTP telemetry
  • internal database telemetry
  • internal file telemetry
  • internal traced-function telemetry

Those appear as operational spans associated with the active model call, tool call, or agent run.

How Agent Runs Appear​

LangChain agent runs are represented as workflow-like entities in OpenBox.

The middleware creates a run identity at before_agent time and uses the configured agent_name as the workflow type when present.

Important implications:

  • A LangChain agent run can appear as a workflow run in OpenBox.
  • The initiating prompt is emitted as SignalReceived(user_prompt).
  • Model work is represented by LLMStarted and LLMCompleted, not as a tool activity.

Model Payload Shape Guidance​

LLMStarted​

Use LLMStarted to inspect prompt-side data.

Common fields:

  • prompt
  • activity_input[0].prompt
  • activity_type = "llm_call"

LLMCompleted​

Use LLMCompleted to inspect model response metadata.

Common fields:

  • completion
  • llm_model
  • input_tokens
  • output_tokens
  • total_tokens
  • has_tool_calls

Tool Payload Shape Guidance​

ToolStarted​

Use ToolStarted to inspect tool inputs and require approval before a tool executes.

Common fields:

  • tool_name
  • tool_type
  • activity_type
  • activity_input

ToolCompleted​

Use ToolCompleted to inspect the tool output and final status.

Common fields:

  • tool_name
  • tool_type
  • activity_output
  • status
  • duration_ms

Typical Event Sequences​

Agent Run With A Model Call​

SignalReceived(user_prompt)
-> WorkflowStarted
-> LLMStarted
-> zero or more telemetry spans during model execution
-> LLMCompleted
-> WorkflowCompleted

Tool Call​

ToolStarted
-> zero or more telemetry spans during tool execution
-> ToolCompleted

Model Usage And Tool Health In The UI​

  • Model and token usage come from LLMCompleted metadata when the underlying model provider returns it.
  • Tool health populates for agents that actually execute tools.
  • An agent run that only generates text without tools may show model usage but no tool health.

Policy And Guardrail Guidance​

Recommended approach:

  1. Use LLMStarted for prompt-side model governance.
  2. Use LLMCompleted for response-side model governance.
  3. Use ToolStarted for tool-input guardrails and approval policies.
  4. Use ToolCompleted for tool-output guardrails and result review.
  5. Treat hook-triggered telemetry as internal by default.