Get Started Beginner ⏱️ 10 min

Setup & Configuration

Before any agent runs, the Atlas team gates every environment through a readiness check. You'll provision the runtime, install the framework, wire up Azure credentials, and validate it all with a script that exits non-zero when something's missing.

The configuration surface

Three things must be true before an agent can start: a supported Python, the framework installed, and valid Azure credentials.

Configuration surface

flowchart TD
    P[Python 3.13+] --> R{Ready?}
    F[agent-framework 1.8.x] --> R
    C[Azure credentials] --> R
    C --> E1[AZURE_OPENAI_ENDPOINT]
    C --> E2[AZURE_OPENAI_API_KEY]
    C --> E3[AZURE_OPENAI_CHAT_DEPLOYMENT_NAME]
    R -->|yes| OK[Agent can run ✓]
    R -->|no| STOP[Blocked ✗]
    classDef hi fill:#6366f1,stroke:#4f46e5,color:#fff;
    class OK hi;

Optional: Foundry project endpoint and Application Insights for later lessons.

Provision the environment

Install Python 3.13+ (3.10 is the minimum; 3.13 recommended).
Create an isolated environment and add the framework with uv.
Provision an Azure OpenAI resource and deploy a chat model.
Export the required environment variables.

bash

uv venv
uv add agent-framework

Set the credentials Atlas requires (PowerShell):

PowerShell

$env:AZURE_OPENAI_ENDPOINT = "https://your-resource.openai.azure.com/"
$env:AZURE_OPENAI_API_KEY = "your-api-key"
$env:AZURE_OPENAI_CHAT_DEPLOYMENT_NAME = "gpt-4o"

The readiness validator

A small script makes the gate enforceable in CI — it returns a clear pass/fail and a non-zero exit code when blocked.

modules/01_setup_and_configuration/main.py

import os
import sys
from dataclasses import dataclass

MIN_PYTHON = (3, 10)
RECOMMENDED = (3, 13)
REQUIRED_VARS = (
    "AZURE_OPENAI_ENDPOINT",
    "AZURE_OPENAI_API_KEY",
    "AZURE_OPENAI_CHAT_DEPLOYMENT_NAME",
)


@dataclass
class CheckResult:
    name: str
    ok: bool
    detail: str


def check_env() -> list[CheckResult]:
    results: list[CheckResult] = []

    py = sys.version_info[:2]
    results.append(CheckResult(
        "python",
        py >= MIN_PYTHON,
        f"{py[0]}.{py[1]} (min {MIN_PYTHON[0]}.{MIN_PYTHON[1]}, rec {RECOMMENDED[0]}.{RECOMMENDED[1]})",
    ))

    for var in REQUIRED_VARS:
        present = bool(os.environ.get(var))
        results.append(CheckResult(var, present, "set" if present else "MISSING"))

    return results


def main() -> int:
    results = check_env()
    for r in results:
        mark = "✓" if r.ok else "✗"
        print(f"  {mark} {r.name:<38} {r.detail}")
    blocked = [r for r in results if not r.ok]
    if blocked:
        print(f"\nBlocked — {len(blocked)} check(s) failed.")
        return 1
    print("\nReady — environment passes the Atlas readiness gate.")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

Run the gate

python main.py — ready

  ✓ python                                 3.13 (min 3.10, rec 3.13)
  ✓ AZURE_OPENAI_ENDPOINT                   set
  ✓ AZURE_OPENAI_API_KEY                    set
  ✓ AZURE_OPENAI_CHAT_DEPLOYMENT_NAME       set

Ready — environment passes the Atlas readiness gate.
# exit code 0

python main.py — blocked

  ✓ python                                 3.13 (min 3.10, rec 3.13)
  ✓ AZURE_OPENAI_ENDPOINT                   set
  ✗ AZURE_OPENAI_API_KEY                    MISSING
  ✗ AZURE_OPENAI_CHAT_DEPLOYMENT_NAME       MISSING

Blocked — 2 check(s) failed.
# exit code 1

Enforce it in CI

.github/workflows/readiness.yml

name: readiness
on: [push, pull_request]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: '3.13' }
      - run: pip install agent-framework
      - run: python modules/01_setup_and_configuration/main.py
        env:
          AZURE_OPENAI_ENDPOINT: ${{ secrets.AZURE_OPENAI_ENDPOINT }}
          AZURE_OPENAI_API_KEY: ${{ secrets.AZURE_OPENAI_API_KEY }}
          AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ secrets.AZURE_OPENAI_CHAT_DEPLOYMENT_NAME }}

⚠️

Never commit keys

Keep credentials in environment variables or a secret store. The validator only checks presence — it never prints values.

✅

Green gate = go

Once this exits 0, every later lesson will run. Next, you'll build your first agent.