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

# SDK Reference

> Install and use the Agent Simulation Engine Python SDK to run simulations, evaluations, and agent hardening programmatically.

## Installation

```bash theme={null}
pip install git+https://github.com/LyzrCore/agent-simulation-engine.git#subdirectory=sdk
```

**Requirements:** Python 3.8 or higher, `requests >= 2.28.0`, `pydantic >= 2.0.0`.

## Initialize the SDK

```python theme={null}
from agent_simulation_engine import ASIMEngine

engine = ASIMEngine(
    api_key="<YOUR_STUDIO_API_KEY>",
    base_url="https://agent.api.lyzr.ai",  # optional, this is the default
    timeout=30                              # optional, seconds
)
```

Get your API key from [Lyzr Studio](https://studio.lyzr.ai).

## Complete workflow

The example below runs a full simulation and hardening cycle for an agent.

```python theme={null}
from agent_simulation_engine import ASIMEngine
import time

engine = ASIMEngine(api_key="<YOUR_STUDIO_API_KEY>")

# Step 1: Create an environment for the agent you want to test
env = engine.environments.create(
    agent_id="<YOUR_AGENT_ID>",
    name="Customer Support Tests"
)

# Step 2: Generate personas and scenarios using AI
personas = engine.personas.generate(env.environment_id)
scenarios = engine.scenarios.generate(env.environment_id)

# Step 3: Generate test simulations
job = engine.simulations.generate(env.environment_id)

while True:
    status = engine.jobs.get_status(env.environment_id, job.job_id)
    if status.summary.completed + status.summary.failed == status.summary.total:
        break
    time.sleep(3)

# Step 4: Run evaluations
eval_run = engine.evaluations.create(
    environment_id=env.environment_id,
    evaluation_run_name="Round 1",
    metrics=["task_completion", "hallucinations", "answer_relevancy"]
)

while True:
    status = engine.jobs.get_evaluation_status(env.environment_id, eval_run.job_id)
    if status.summary.completed + status.summary.failed == status.summary.total:
        break
    time.sleep(3)

# Step 5: Review results
results = engine.evaluations.list(env.environment_id)
pass_count = sum(1 for e in results.evaluations if e.judgment == "PASS")
fail_count = sum(1 for e in results.evaluations if e.judgment == "FAIL")
print(f"Results: {pass_count} PASS | {fail_count} FAIL")

# Step 6: Harden the agent if any simulations failed
if fail_count > 0:
    hardening = engine.hardening.harden_agent(
        environment_id=env.environment_id,
        run_id=eval_run.evaluation_run_id,
        round_number=1
    )
    print("Original instructions:", hardening.original_config.agent_instructions)
    print("Improved instructions:", hardening.improved_config.agent_instructions)

    # Step 7: Continue with the improved config
    engine.hardening.continue_run(
        environment_id=env.environment_id,
        run_id=eval_run.evaluation_run_id,
        round_number=1,
        agent_config=hardening.improved_config.model_dump()
    )
```

## Resources

Each resource is accessible as a property on the `ASIMEngine` instance.

| Resource                 | Description                                     | Key methods                                                         |
| ------------------------ | ----------------------------------------------- | ------------------------------------------------------------------- |
| `engine.environments`    | Manage isolated test environments               | `create()`, `get()`, `list_by_agent()`, `delete()`                  |
| `engine.personas`        | Define or generate user archetypes              | `create()`, `list()`, `generate()`, `delete()`                      |
| `engine.scenarios`       | Define or generate task types                   | `create()`, `list()`, `generate()`, `delete()`                      |
| `engine.simulations`     | Manage synthetic test conversations             | `create()`, `list()`, `get()`, `update()`, `delete()`, `generate()` |
| `engine.evaluations`     | Run evaluations and retrieve scores             | `create()`, `list()`, `get()`                                       |
| `engine.jobs`            | Track the status of async operations            | `get_status()`, `list()`, `cancel()`, `get_evaluation_status()`     |
| `engine.evaluation_runs` | Access RL training rounds                       | `get()`, `list()`, `get_round()`, `sync_round()`                    |
| `engine.hardening`       | Analyze failures and improve agent instructions | `harden_agent()`, `continue_run()`                                  |

## Agent hardening

`harden_agent()` analyzes failures from a completed evaluation round and returns the original and improved agent configurations. Pass `evaluation_ids` to target specific failures, or omit it to analyze all failures from the round.

```python theme={null}
hardening = engine.hardening.harden_agent(
    environment_id=env.environment_id,
    run_id=eval_run.evaluation_run_id,
    round_number=1,
    evaluation_ids=["eval-id-1", "eval-id-2"]  # optional
)

# Apply the improved config and start a new round
engine.hardening.continue_run(
    environment_id=env.environment_id,
    run_id=eval_run.evaluation_run_id,
    round_number=1,
    agent_config=hardening.improved_config.model_dump()
)
```

`continue_run()` starts a new evaluation round (round number + 1) using the improved instructions. Repeat until all simulations pass.

## Error handling

The SDK raises typed exceptions for each failure mode.

```python theme={null}
from agent_simulation_engine import (
    ASIMEngine,
    ASIMError,
    AuthenticationError,
    NotFoundError,
    ValidationError,
    RateLimitError,
    ServerError,
)

try:
    env = engine.environments.get("<environment-id>")
except AuthenticationError:
    print("Invalid API key.")
except NotFoundError:
    print("Environment not found.")
except ValidationError as e:
    print(f"Invalid request: {e.message}")
except RateLimitError:
    print("Rate limit exceeded. Retry after a short wait.")
except ServerError:
    print("Server error. Try again shortly.")
except ASIMError as e:
    print(f"API error {e.status_code}: {e.message}")
```