Track agent runs

Use run() to create the execution context for one agent run. Events recorded inside the callback are connected to the same run and session.

When to use this

Use run tracking when you want to inspect the full path from user input to final outcome.

How it works

run() creates an async context. The SDK attaches runId, sessionId, workspaceId, agentId, spanId, and parentSpanId to events recorded inside that context. Nested run() calls inherit the parent run and create child span relationships. When a root run() callback returns or throws without an explicit outcome(), the SDK records a technical COMPLETED or FAILED outcome automatically. Call outcome() when you also know whether the business task succeeded, partially succeeded, or failed; the SDK will not add a duplicate automatic outcome.

Example

await lynx.run(
  {
    agentName: "SupportAgent",
    workspaceId: "workspace_123",
    agentId: "agent_support",
    sessionId: "session_123",
  },
  async () => {
    lynx.userInput("Where is my order?", { userId: "usr_123" });
    lynx.setAttributes({ orderId: "order_123" });

    lynx.context("account-state", {
      plan: "pro",
      renewalDate: "2026-07-01",
    });

    lynx.decision({
      name: "choose_support_path",
      selected: "lookup_order",
      alternatives: ["ask_clarifying_question", "handoff"],
      confidence: 0.81,
      reason: "The user is asking about a specific order",
    });

    lynx.memory("read", {
      key: "usr_123",
      hit: true,
      store: "customer-profile",
    });

    lynx.outcome({
      status: "COMPLETED",
      businessStatus: "SUCCEEDED",
      reason: "The order status was returned to the user",
    });
  },
);

You can also pass only an agent name.

await lynx.run("SupportAgent", async () => {
  lynx.userInput("Where is my order?");
});

Semantic helpers

Helper	Use it for
`userInput(input, metadata?)`	The user request or command that influenced the run.
`context(label, data, metadata?)`	RAG results, loaded records, summaries, or selected context.
`decision(reasonOrDecision, options?)`	A workflow choice, tool choice, branch, or reasoning step.
`memory(operation, data, metadata?)`	Memory read, write, search, hit, or miss information.
`outcome(options)`	An explicit technical and business result. Optional for technical run closure.
`setAttributes(attributes)`	IDs and metadata that should be attached to later events.
`annotate(label, payload)`	A custom breadcrumb for debugging.
`log(label, payload)`	A custom context event when no semantic helper fits.

What you can see in Lynx

Run tracking powers:

Session timelines
Agent decision history
Context and memory snapshots
Error and slow-step analysis
Root cause candidates with evidence

Notes

Keep stable identifiers stable. Use the same agentId for the same agent across deployments. Use appVersion, deploymentId, and promptVersion when you need to compare behavior before and after a change.

Getting started

TypeScript SDK

OpenAPI

Track agent runs

When to use this

How it works

Example

Semantic helpers

What you can see in Lynx

Notes

Next steps

​When to use this

​How it works

​Example

​Semantic helpers

​What you can see in Lynx

​Notes

​Next steps

When to use this

How it works

Example

Semantic helpers

What you can see in Lynx

Notes

Next steps