Skip to main content
Events are batched and sent to POST /v1/events. Each event has a type, agentKey, runId, sessionId, eventId, timestamp, and type-specific payload fields. Validate events before sending with validateEvents / validate_events (POST /v1/events/validate).

​
Tool and action events

Event typeWhen emitted
agent.tool.calledTool invocation completed
agent.action.requestedAction requested (pre-execution)
agent.action.completedAction completed successfully
agent.action.failedAction failed
agent.resource.touchedResource accessed

​
Guardrail and approval events

Event typeWhen emitted
agent.guardrail.evaluatedGuardrail policy evaluated
agent.approval.requestedHuman approval requested
agent.approval.resolvedApproval approved/rejected/expired

​
Workflow events

Event typeWhen emitted
agent.workflow.step.startedWorkflow step began
agent.workflow.step.completedWorkflow step finished
agent.workflow.step.failedWorkflow step failed

​
LLM events

Event typeWhen emitted
agent.llm.calledLLM invocation started
agent.llm.completedLLM invocation succeeded
agent.llm.failedLLM invocation failed

​
MCP events

Event typeWhen emitted
agent.mcp.calledMCP tool call started
agent.mcp.completedMCP tool call succeeded
agent.mcp.failedMCP tool call failed
agent.mcp.tools_listedMCP tools/list response

​
Handoff events

Event typeWhen emitted
agent.handoff.requestedHandoff to another agent requested
agent.handoff.acceptedHandoff accepted
agent.handoff.completedHandoff completed
agent.handoff.failedHandoff failed

​
Error events

Event typeWhen emitted
agent.errorUnhandled error captured

​
Common event fields

FieldDescription
agentKeyAgent identifier
agentIdRegistered agent ID
agentVersionIdRegistered version ID
runIdParent run ID
sessionIdParent session ID
eventIdUnique event UUID
sequenceNumberOrder within run
sessionSequenceNumberOrder within session
stepKeyWorkflow step key
stepNameWorkflow step name
stepIndexWorkflow step index
environmentEnvironment tag
payloadSummaryRedacted summary payload
timestampISO 8601 timestamp

​
Event builders (advanced)

Build events manually for custom integrations: 
import {
  buildToolCallEvent,
  buildActionRequestedEvent,
  buildGuardrailEvaluatedEvent,
  buildWorkflowEvent,
  buildErrorEvent,
  sendEvents,
} from "@apie-sh/sdk";

​
Wrappers vs builders

ApproachUse when
withTool, withRun, etc.Normal instrumentation — handles guard, telemetry, and lifecycle
track* methodsFine-grained events without wrapping execution
build* + sendEventsCustom integrations, non-standard agents
See Custom telemetry.