---
title: "Quickstart"
description: "Get started with Arksim in minutes. This guide walks you through your first agent evaluation using pre-built scenarios and a config for your agent."
---

## Prerequisites

- Python 3.10–3.13
- An API key from a supported provider (e.g. [OpenAI](https://developers.openai.com/api/docs), [Anthropic](https://platform.claude.com/docs/en/home), or [Gemini](https://ai.google.dev/gemini-api/docs/api-key))

## Get started

<Steps>
  <Step title="Install Arksim">
    ```bash
    pip install arksim
    ```
  </Step>
  <Step title="Set your API key">
    Set the key for the provider your config uses (e.g. OpenAI):

    ```bash
    export OPENAI_API_KEY="your-api-key"
    ```

    For other providers:

    ```bash
    export ANTHROPIC_API_KEY="your-api-key"
    export GEMINI_API_KEY="your-api-key"
    ```
  </Step>
  <Step title="Run Simulation & Evaluation">
    You can simulate conversations with your agent and evaluate them via the CLI, Python, or the web UI.

    <Tabs>
      <Tab title="CLI">
        This command simulates conversations against your agent, evaluates them, and saves results to the specified output location.

        ```bash
        arksim simulate-evaluate <path/to/config.yaml>
        ```

        Example:

        ```bash
        arksim simulate-evaluate ./config.yaml
        ```

        Your config should define:

        **Agent Configuration**

        ```yaml
        agent_config:
          agent_type: chat_completions
          agent_name: my-agent
          api_config:
            endpoint: https://api.openai.com/v1/chat/completions
            headers:
              Content-Type: application/json
              Authorization: "Bearer ${OPENAI_API_KEY}"
            body:
              model: gpt-5.1
              messages:
                - role: system
                  content: "You are a helpful assistant."
        ```

        **Pre-built Scenario**

        ```yaml
        scenario_file_path: ./path/to/scenario/scenario.json
        ```

        Path to the `scenario.json` file used to simulate conversations.

        **Simulation Output**

        ```yaml
        output_file_path: ./path/to/results/conversations.json
        ```

        Where the simulated conversation transcripts will be saved.

        **Evaluation Output**

        ```yaml
        output_dir: ./path/to/results/evaluation/
        ```

        Directory where evaluation scores, metrics, and reports will be written.
      </Tab>
      <Tab title="Python">
        You can also simulate and evaluate conversations programmatically inside your own codebase.

        ```python
        from arksim.simulation_engine import run_simulation, SimulationInput
        from arksim.evaluator import run_evaluation, EvaluationInput
        from arksim.config import AgentConfig

        # Define your agent configuration
        agent_config = AgentConfig(
            agent_type="chat_completions",
            agent_name="my-agent",
            api_config={
                "endpoint": "https://api.openai.com/v1/chat/completions",
                "headers": {
                    "Content-Type": "application/json",
                    "Authorization": "Bearer ${OPENAI_API_KEY}",
                },
                "body": {
                    "model": "gpt-5.1",
                    "messages": [
                        {"role": "system", "content": "You are a helpful assistant."}
                    ],
                },
            },
        )

        # Run simulation
        simulation = run_simulation(SimulationInput(
            agent_config=agent_config,
            scenario_file_path="examples/path/to/scenario.json",
            num_conversations_per_scenario=30,
            max_turns=10,
            num_workers="auto",
            output_file_path="./simulation.json",
        ))

        # Evaluate simulated agent conversations
        evaluation = run_evaluation(EvaluationInput(
            simulation_file_path="./simulation.json",
            scenario_file_path="examples/path/to/scenario.json",
            output_dir="./evaluation",
            model="gpt-5.1",
            provider="openai",
            num_workers="auto",
            generate_html_report=True,
        ))

        print("Simulation and evaluation complete.")
        print(f"Simulated {len(simulation.conversations)} conversations.")
        print("Evaluation results saved to ./evaluation")
        ```
      </Tab>
      <Tab title="UI">
        Run simulation and evaluation from your browser with the arksim web UI.

        ```bash
        arksim ui
        ```

        Your browser opens at [**http://localhost:8080**](http://localhost:8080).

        <Tip>
          Set your API key in the environment before starting `arksim ui` (e.g. `OPENAI_API_KEY`).
        </Tip>
      </Tab>
    </Tabs>
  </Step>
  <Step title="View Results">
    - **Conversations:** Open `conversations.json` in your simulation output directory for full transcripts.
    - **Evaluation:** Open `final_report.html` or `final_report.md` and the CSV files in your evaluation output directory for metrics and failure analysis.

    Use these to see how your agent performed and where it failed or could be improved.
  </Step>
</Steps>

---

## Next Steps

Now that you've run your first simulation and evaluation, here's where to go next.

- **Explore the core concepts:** Dive deeper into [Scenarios](/build-scenario), [Simulation](/simulate-conversation), and [Evaluation](/evaluate-conversation) to understand how each piece works and how to configure them for your agent.

<CardGroup cols={2}>
  <Card icon="cart-shopping" href="/e-commerce-customer-service-agent-evaluation" title="E-commerce customer service">
    Run scenarios and evaluation for a retail/support agent with OpenAI or LangGraph RAG.
  </Card>
  <Card icon="shield" href="/insurance-customer-service-agent-evaluation" title="Insurance customer service">
    Bank/insurance agent with custom compliance metrics, disclosures, and escalation behavior.
  </Card>
</CardGroup>
