How SkyAIApp thinks

const agent = sky.createAgent({
  // Built-in + custom tools. Each is sandboxed unless you opt out.
  tools: [
    "web_search",
    "calculator",
    "code_exec",
    {
      name: "lookup_invoice",
      description: "Fetch invoice by ID from internal billing system.",
      parameters: { type: "object", properties: { id: { type: "string" } }, required: ["id"] },
      handler: async ({ id }) => billing.find(id),
    },
  ],
  maxSteps: 10,                         // hard upper bound — protects against runaway agents
  perStepTimeoutMs: 30_000,             // each tool/LLM call gets 30s max
  totalBudgetUsd: 0.50,                 // cumulative cost cap across all steps
  onStep: (step) => console.log(`[${step.number}] ${step.action} → ${step.tool ?? "llm"}`),
});

const result = await agent.run({
  task: "Find this month's overdue invoices and email a polite reminder to each.",
});

console.log(result.output);             // final agent response
console.log(result.steps.length);       // how many steps it actually took
console.log(result.totalCostUsd);       // cumulative spend
console.log(result.traceId);            // open in console for full span tree

const res = await sky.route({
  goal: "cost",
  messages: [...],
  cache: {
    enabled: true,
    similarity: 0.92,                 // threshold: lower = more hits, more risk of wrong-meaning hits
    ttlSeconds: 60 * 60 * 24,         // 24h — tune by content freshness needs
    namespace: "tenant_acme_summarize", // segregate caches per tenant + workflow
  },
});

if (res.routing.cacheHit) {
  console.log("Cache hit — saved", res.routing.savedCostUsd, "USD");
}

// Inspect a trace programmatically
const trace = await sky.traces.get("tr_01JFGYZ7K8M2N3P4Q5R6S7T8U9");

console.log(trace.routing.decisionReason);
//  → "balanced + cost: claude-haiku-4.5 wins on $/quality vs alternatives in this band."

console.log(trace.spans.length);                 // total span count
console.log(trace.summary.totalCostUsd);         // total cost (incl. retries + agent steps)
console.log(trace.summary.cacheHitRate);         // cache hit rate inside this trace

// Walk the span tree
for (const span of trace.spans) {
  console.log(`[${span.startedAtMs}] ${span.name} (${span.durationMs}ms) → ${span.status}`);
}