Runs and events

Two records: a run and the events inside it.

Run

One execution of an agent.

Field	Notes
`id`	Client-generated, `run_<region>_...`. See Identifiers.
`agent`	Slug.
`started_at` / `received_at`	Client clock / server clock.
`status`	`running`, `success`, `failed`, `timeout`, `cancelled`.
`finished_at`	Set on close.
`customer_id`, `feature`	Optional attribution tags.
`parent_run_id`	Optional, for cross-agent traces.

Runs are immutable once finished. Re-finishing a terminal run returns the existing record idempotently.

Event

A discrete observation inside a run. SDKs emit events automatically; you can append your own.

Type	Source
`llm_call`	Auto-captured for Anthropic, OpenAI, Bedrock, Gemini, Mistral, Cohere, LiteLLM
`tool_call`	Auto-captured for LangChain, LlamaIndex, Vercel AI SDK, Pydantic AI, CrewAI, OpenAI Agents SDK
`log`	`run.log("message")`
`decision`	Explicit branching points
`score`	`run.score(name, value)`, self-reported quality

Each event has a client-generated id (evt_<region>_...), timestamp, type, and JSON data payload.

Lifecycle

run start  ─►  event  ─►  event  ─►  event  ─►  run finish
   │                                                │
   └────── server stamps received_at ───────────────┘

The SDK constructs run.id locally before any network call. Log it, pass it to child processes, include it in your own errors immediately. Events can be sent in any order.

with agentping.run("support-triage", customer_id="acme-corp") as run:
    run.log("classifying ticket")
    decision = classify(ticket)
    run.score("confidence", decision.confidence)
    return decision

const run = agentping.run("support-triage", { customerId: "acme-corp" });
run.log("classifying ticket");
const decision = await classify(ticket);
run.score("confidence", decision.confidence);
await run.finish({ status: "success" });

run := agentping.Run("support-triage",
    agentping.WithCustomerID("acme-corp"),
)
run.Log("classifying ticket")
decision := classify(ticket)
run.Score("confidence", decision.Confidence)
run.Finish(agentping.RunStatusSuccess)

Parent runs

When agent A spawns agent B, set the parent so traces link across processes:

AGENTPING_PARENT_RUN=run_eu_018f3a2b9c1d7e8fa4b9c2d7e8f1a3b6 (env var, read on init)
parent_run_id parameter on the child run

A failure on a child surfaces the root run too: a five-step pipeline that breaks at step four shows up as one incident, not four.

Heartbeats

A heartbeat is a run with started_at == finished_at and no events. Same table, same dashboard, same alerts. See Heartbeats.