Traces and analysis

Inspect the result and tool calls from an agent run, or review the sandbox’s runtime and usage. Use Tangle Intelligence to investigate recorded agent activity across runs.

Set TANGLE_API_KEY and TANGLE_SANDBOX_ID to an existing sandbox. Install the TypeScript SDK, or pip install httpx for Python. These examples leave the sandbox available for further inspection.

Inspect an agent run

Use a running sandbox for this example. The agent checks installed tools and saves its actual result to agent-result.json on your computer.

import { writeFile } from "node:fs/promises";
import { Sandbox } from "@tangle-network/sandbox";

const apiKey = process.env.TANGLE_API_KEY;
const sandboxId = process.env.TANGLE_SANDBOX_ID;
if (!apiKey || !sandboxId) {
  throw new Error("Set TANGLE_API_KEY and TANGLE_SANDBOX_ID");
}
const client = new Sandbox({
  apiKey, baseUrl: "https://sandbox.tangle.tools",
});
const box = await client.get(sandboxId);
if (!box) throw new Error("Sandbox not found");

await box.waitFor("running");
const result = await box.prompt(
  "Report the Node.js, Python and Git versions. Do not edit files.",
  { sessionId: crypto.randomUUID() },
);
await writeFile("agent-result.json", JSON.stringify(result, null, 2));
console.log(result.status, result.traceId, result.response);
console.table(result.toolInvocations ?? []);

Inspect the returned status or outcome before treating the task as complete. The TypeScript result includes a traceId for correlating the run’s requests, plus usage and cost when reported. For live output and reconnecting to a specific execution, see agents and sessions.

Save runtime timings

box.trace() exports the sandbox’s observed lifecycle, runtime, and usage snapshots. Use agent results and session events for the conversation and tool-call history.

import { writeFile } from "node:fs/promises";
import { Sandbox } from "@tangle-network/sandbox";

const apiKey = process.env.TANGLE_API_KEY;
const sandboxId = process.env.TANGLE_SANDBOX_ID;
if (!apiKey || !sandboxId) {
  throw new Error("Set TANGLE_API_KEY and TANGLE_SANDBOX_ID");
}
const client = new Sandbox({
  apiKey, baseUrl: "https://sandbox.tangle.tools",
});
const box = await client.get(sandboxId);
if (!box) throw new Error("Sandbox not found");

const bundle = await box.trace({ includeIntelligence: true });
await writeFile("sandbox-trace.json", JSON.stringify(bundle, null, 2));
console.table(bundle.trace.criticalPath.phases);
console.log(bundle.intelligence?.recommendedActions);

The file is written to your computer before any sandbox cleanup. The reported phases can overlap; their durations do not describe a sequence of agent steps.

Send runtime traces to Intelligence

exportTrace() converts the runtime trace to OpenTelemetry JSON and posts it to the authenticated endpoint.

TypeScript

import { Sandbox } from "@tangle-network/sandbox";

const apiKey = process.env.TANGLE_API_KEY;
const sandboxId = process.env.TANGLE_SANDBOX_ID;
if (!apiKey || !sandboxId) {
  throw new Error("Set TANGLE_API_KEY and TANGLE_SANDBOX_ID");
}
const client = new Sandbox({
  apiKey, baseUrl: "https://sandbox.tangle.tools",
});
const box = await client.get(sandboxId);
if (!box) throw new Error("Sandbox not found");

const result = await box.exportTrace({
  url: "https://intelligence.tangle.tools/v1/otlp/v1/traces",
  headers: { Authorization: "Bearer " + apiKey },
  format: "otel-json",
  serviceName: "sandbox-runtime",
});
console.log(result.status);

To include agent prompts, responses, and tool details, follow Connect your agent.

Analyze runtime performance

Create a report from the sandbox’s runtime, resource, and usage records. The example waits for a completed or failed report before reading its result.

import { Sandbox } from "@tangle-network/sandbox";

const apiKey = process.env.TANGLE_API_KEY;
const sandboxId = process.env.TANGLE_SANDBOX_ID;
if (!apiKey || !sandboxId) {
  throw new Error("Set TANGLE_API_KEY and TANGLE_SANDBOX_ID");
}
const client = new Sandbox({
  apiKey, baseUrl: "https://sandbox.tangle.tools",
});
const box = await client.get(sandboxId);
if (!box) throw new Error("Sandbox not found");

const report = await box.createIntelligenceReport({
  mode: "deterministic",
});
const completed = await client.intelligence.waitForReport(report.jobId);
if (completed.status === "failed") throw new Error(completed.error);
console.log(completed.jobId, completed.result);

Use mode: "agentic" with budget: { billTo: "customer", maxUsd: 1 } to request paid analysis with a $1 ceiling. Call client.intelligence.estimateReport() before requesting paid analysis when your application needs a cost estimate.

Workflows Access, secrets & usage