Skip to main content

​
Installation

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

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.

​
Complete workflow

The example below runs a full simulation and hardening cycle for an agent. 
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.
ResourceDescriptionKey methods
engine.environmentsManage isolated test environmentscreate(), get(), list_by_agent(), delete()
engine.personasDefine or generate user archetypescreate(), list(), generate(), delete()
engine.scenariosDefine or generate task typescreate(), list(), generate(), delete()
engine.simulationsManage synthetic test conversationscreate(), list(), get(), update(), delete(), generate()
engine.evaluationsRun evaluations and retrieve scorescreate(), list(), get()
engine.jobsTrack the status of async operationsget_status(), list(), cancel(), get_evaluation_status()
engine.evaluation_runsAccess RL training roundsget(), list(), get_round(), sync_round()
engine.hardeningAnalyze failures and improve agent instructionsharden_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. 
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. 
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}")