> ## Documentation Index
> Fetch the complete documentation index at: https://snowglobe.so/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Install the snowglobe-sdk for TypeScript and use it to create an agent, launch a simulation, and download simulation results.

<Warning>
  For a better experience, we strongly recommend utilizing [`snowglobe simulate`](/snowglobe/docs/connect/launch-a-simulation) for launching and monitoring simulations end-to-end.
</Warning>

## Prerequisites

* Node.js v20.x+ or similar (e.g. Bun v1.x+)
* macOS, Linux, or Windows

## Installation

Install the package using your preferred package manager:

```bash theme={null}
npm install @guardrails-ai/snowglobe-sdk
# or
yarn add @guardrails-ai/snowglobe-sdk
# or
bun add @guardrails-ai/snowglobe-sdk
```

## Code Sample

```typescript theme={null}
import * as fs from "fs";
import { SnowglobeClient } from "@guardrails-ai/snowglobe-sdk";

function sleep(ms: number): Promise<void> {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

async function runAgentSimulation() {
  /// Step 1: Initialize the Snowglobe Client
  const client = new SnowglobeClient({
    apiKey: process.env.SNOWGLOBE_API_KEY!,
    organizationId: process.env.SNOWGLOBE_ORG_ID,
  });

  try {
    /// Step 2: Create Agent
    const agent = await client.agents.createAgent({
      name: "customer_support_agent",
      description: "Customer support agent for Amatto's pizza restaurant",
      icon: "pizza",
    });
    const agentId = agent.id;

    /// Step 3: Create and Launch Simulation
    const simulation = await client.simulations.create({
      name: "continuous integration simulation",
      agent_id: agentId,
      max_conversation_length: 5,
      max_personas: 10,
      max_conversations: 50,
    });
    const simulationId = simulation.id;

    /// Step 4: Poll simulation until completion or timeout
    const timeoutMinutes = 20;
    const maxAttempts = timeoutMinutes * 6; // poll every 10 seconds
    let completed = false;

    for (let i = 0; i < maxAttempts; i++) {
      const sim = await client.simulations.getSimulation(simulationId);
      const stateNum = sim.state_num;
      console.log(`Simulation state: ${stateNum}`);

      // state_num >= 17 indicates completion (see Simulation States below)
      if (stateNum != null && stateNum >= 17) {
        console.log("Simulation completed successfully");
        completed = true;
        break;
      }

      await sleep(10_000);
    }

    if (!completed) {
      throw new Error("Simulation timed out before completion");
    }

    /// Step 5: Download simulation results for analysis
    const data = await client.simulations.downloadSimulationData(simulationId);

    const filename = `${simulationId}_results.json`;
    fs.writeFileSync(filename, JSON.stringify(data, null, 2));
    console.log(`Results saved to ${filename}`);

    return {
      success: true,
      agentId,
      simulationId,
      resultsFile: filename,
    };
  } catch (err) {
    console.error("Simulation failed:", err);
    return { success: false, error: String(err) };
  }
}

runAgentSimulation();
```