ai-agents-for-beginners

Configurarea cursului

Introducere

Această lecție va acoperi cum să rulați exemplele de cod din acest curs.

Alăturați-vă altor cursanți și primiți ajutor

Înainte de a începe să clonați repo-ul, alăturați-vă canalului AI Agents For Beginners Discord pentru a primi ajutor cu configurarea, orice întrebări legate de curs sau pentru a vă conecta cu alți cursanți.

Clonați sau faceți fork la acest repo

Pentru început, vă rugăm să clonați sau să faceți fork la Repositorul GitHub. Aceasta vă va crea propria versiune a materialului cursului astfel încât să puteți rula, testa și ajusta codul!

Acest lucru se poate face făcând clic pe linkul fork la repo

Acum ar trebui să aveți propria versiune fork-uită a acestui curs la linkul următor:

Forked Repo

Clonare superficială (recomandat pentru atelier / Codespaces)

Repositorio-ul complet poate fi mare (~3 GB) când descărcați istoricul complet și toate fișierele. Dacă participați doar la atelier sau aveți nevoie doar de câteva foldere de lecție, o clonare superficială (sau o clonare sparse) evită majoritatea acelei descărcări prin trunchierea istoricului și/sau sărind peste blob-uri.

Clonare superficială rapidă — istoric minimal, toate fișierele

Înlocuiți <your-username> în comenzile de mai jos cu URL-ul fork-ului dvs. (sau URL-ul upstream dacă preferați).

Pentru a clona doar istoricul ultimului commit (descărcare mică):

git clone --depth 1 https://github.com/<your-username>/ai-agents-for-beginners.git

Pentru a clona un branch specific:

git clone --depth 1 --branch <branch-name> https://github.com/<your-username>/ai-agents-for-beginners.git

Clonare parțială (sparse) — blob-uri minimale + doar folderele selectate

Aceasta folosește clonare parțială și sparse-checkout (necesită Git 2.25+ și se recomandă un Git modern cu suport pentru clonare parțială):

git clone --depth 1 --filter=blob:none --sparse https://github.com/<your-username>/ai-agents-for-beginners.git

Intrați în folderul repo:

cd ai-agents-for-beginners

Apoi specificați ce foldere doriți (exemplul de mai jos arată două foldere):

git sparse-checkout set 00-course-setup 01-intro-to-ai-agents

După clonare și verificarea fișierelor, dacă aveți nevoie doar de fișiere și doriți să eliberați spațiu (fără istoric git), vă rugăm să ștergeți meta-datele repository-ului (💀 ireversibil — veți pierde toate funcționalitățile Git: fără commit-uri, pull-uri, push-uri sau acces la istoric).

# zsh/bash
rm -rf .git

# PowerShell
Remove-Item -Recurse -Force .git

Folosind GitHub Codespaces (recomandat pentru a evita descărcări mari locale)

Creați un nou Codespace pentru acest repo prin GitHub UI.
În terminalul codespace-ului nou creat, rulați una din comenzile de clonare superficială/sparse de mai sus pentru a aduce doar folderele lecțiilor de care aveți nevoie în spațiul de lucru Codespace.
Opțional: după clonare în Codespaces, eliminați .git pentru a elibera spațiu suplimentar (vezi comenzile de eliminare de mai sus).
Notă: Dacă preferați să deschideți repo-ul direct în Codespaces (fără clonare suplimentară), rețineți că Codespaces va construi mediul devcontainer și este posibil să aprovisioneze mai mult decât aveți nevoie. Clonarea unei copii superficiale într-un Codespace proaspăt vă oferă mai mult control asupra utilizării discului.

Sfaturi

Întotdeauna înlocuiți URL-ul de clonare cu fork-ul dvs. dacă doriți să modificați/faceți commit.
Dacă aveți nevoie ulterior de mai mult istoric sau fișiere, le puteți aduce prin fetch sau puteți ajusta sparse-checkout pentru a include foldere suplimentare.

Rularea codului

Acest curs oferă o serie de Jupyter Notebooks pe care le puteți rula pentru a obține experiență practică în construirea de Agenți AI.

Exemplele de cod folosesc Microsoft Agent Framework (MAF) cu FoundryChatClient, care se conectează la Microsoft Foundry Agent Service V2 (API-ul Responses) prin Microsoft Foundry.

Toate notebook-urile Python sunt etichetate *-python-agent-framework.ipynb.

Cerințe

Python 3.12+
- NOTĂ: Dacă nu aveți Python3.12 instalat, asigurați-vă că îl instalați. Apoi creați-vă mediul virtual folosind python3.12 pentru a vă asigura că sunt instalate versiunile corecte din fișierul requirements.txt.
  
  Exemplu
  
  Creați directorul pentru mediul virtual Python:
```
python -m venv venv
```
  Apoi activați mediul virtual pentru:
```
# zsh/bash
source venv/bin/activate
```
```
# Command Prompt for Windows
venv\Scripts\activate
```
.NET 10+: Pentru codurile de exemplu care folosesc .NET, asigurați-vă că instalați .NET 10 SDK sau o versiune ulterioară. Apoi verificați versiunea SDK instalată:
```
  dotnet --list-sdks
```
Azure CLI — Este necesar pentru autentificare. Instalați de la aka.ms/installazurecli.
Abonament Azure — Pentru acces la Microsoft Foundry și Microsoft Foundry Agent Service.
Proiect Microsoft Foundry — Un proiect cu un model implementat (ex., gpt-4.1-mini). Vezi Pasul 1 mai jos.

Am inclus un fișier requirements.txt în rădăcina acestui repo care conține toate pachetele Python necesare pentru a rula exemplele de cod.

Le puteți instala rulând comanda următoare în terminal, în directorul rădăcină al repository-ului:

pip install -r requirements.txt

Recomandăm crearea unui mediu virtual Python pentru a evita conflictele și problemele.

Configurarea VSCode

Asigurați-vă că utilizați versiunea corectă de Python în VSCode.

Configurarea Microsoft Foundry și Microsoft Foundry Agent Service

Pasul 1: Creați un Proiect Microsoft Foundry

Aveți nevoie de un hub și proiect Microsoft Foundry cu un model implementat pentru a rula notebook-urile.

Accesați ai.azure.com și conectați-vă cu contul Azure.
Creați un hub (sau folosiți unul existent). Vezi: Prezentare generală resurse Hub.
În cadrul hub-ului, creați un proiect.
Implementați un model (ex., gpt-4.1-mini) din Models + Endpoints → Deploy model.

Pasul 2: Obțineți Endpoint-ul proiectului și numele implementării modelului

Din proiectul dvs. în portalul Microsoft Foundry:

Project Endpoint — Accesați pagina Overview și copiați URL-ul endpoint-ului.

Project Connection String

Model Deployment Name — Accesați Models + Endpoints, selectați modelul implementat și rețineți Deployment name (ex., gpt-4.1-mini).

Pasul 3: Autentificați-vă în Azure cu `az login`

Toate notebook-urile folosesc AzureCliCredential pentru autentificare — fără chei API de gestionat. Aceasta necesită să fiți autentificat prin Azure CLI.

Instalați Azure CLI dacă nu l-ați instalat deja: aka.ms/installazurecli
Conectați-vă rulând:
```
 az login
```
Sau dacă sunteți într-un mediu remote/Codespace fără browser:
```
 az login --use-device-code
```
Selectați abonamentul dacă vi se solicită — alegeți-l pe cel care conține proiectul Foundry.
Verificați că sunteți autentificat:
```
 az account show
```

De ce az login? Notebook-urile se autentifică folosind AzureCliCredential din pachetul azure-identity. Aceasta înseamnă că sesiunea dvs. Azure CLI furnizează credențialele — fără chei API sau secrete în fișierul .env. Aceasta este o practică de securitate recomandată.

Pasul 4: Creați fișierul `.env`

Copiați fișierul exemplu:

# zsh/bash
cp .env.example .env

# PowerShell
Copy-Item .env.example .env

Deschideți .env și completați aceste două valori:

AZURE_AI_PROJECT_ENDPOINT=https://<your-project>.services.ai.azure.com/api/projects/<your-project-id>
AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4.1-mini

Variabilă	Unde să o găsiți
`AZURE_AI_PROJECT_ENDPOINT`	Portal Foundry → proiectul dvs. → pagina Overview
`AZURE_AI_MODEL_DEPLOYMENT_NAME`	Portal Foundry → Models + Endpoints → numele modelului implementat

Acesta este tot pentru cele mai multe lecții! Notebook-urile se vor autentifica automat prin sesiunea dvs. az login.

Pasul 5: Instalați dependențele Python

pip install -r requirements.txt

Recomandăm să rulați acest lucru în mediul virtual creat anterior.

Configurare suplimentară pentru Lecția 5 (Agentic RAG)

Lecția 5 folosește Azure AI Search pentru generare augmentată cu recuperare. Dacă intenționați să rulați acea lecție, adăugați aceste variabile în fișierul .env:

Variabilă	Unde să o găsiți
`AZURE_SEARCH_SERVICE_ENDPOINT`	Portal Azure → resursa dvs. Azure AI Search → Overview → URL
`AZURE_SEARCH_API_KEY`	Portal Azure → resursa dvs. Azure AI Search → Settings → Keys → cheia principală admin

Configurare suplimentară pentru lecțiile care apelează Azure OpenAI direct (Lecțiile 6 și 8)

Unele notebook-uri din lecțiile 6 și 8 apelează Azure OpenAI direct (folosind Responses API) în loc să treacă printr-un proiect Microsoft Foundry. Aceste exemple foloseau anterior GitHub Models, care este învechit (se retrage în iulie 2026) și nu suportă Responses API. Dacă intenționați să rulați acele exemple, adăugați aceste variabile în fișierul .env:

Variabilă	Unde să o găsiți
`AZURE_OPENAI_ENDPOINT`	Portal Azure → resursa dvs. Azure OpenAI → Keys and Endpoint → Endpoint (ex. `https://<resursa-dvs>.openai.azure.com`)
`AZURE_OPENAI_DEPLOYMENT`	Numele modelului implementat (ex. `gpt-4.1-mini`) care suportă Responses API
`AZURE_OPENAI_API_KEY`	Opțional — doar dacă folosiți autentificare bazată pe cheie în loc de `az login` / Entra ID

Responses API folosește endpoint-ul stabil /openai/v1/, deci nu este necesar api-version. Autentificați-vă cu az login pentru a folosi autentificarea fără cheie Entra ID.

Furnizor alternativ: MiniMax (compatibil OpenAI)

MiniMax oferă modele cu context mare (până la 204K tokeni) printr-un API compatibil OpenAI. Deoarece OpenAIChatClient din Microsoft Agent Framework funcționează cu orice endpoint compatibil OpenAI, puteți folosi MiniMax ca alternativă directă la Azure OpenAI sau OpenAI.

Adăugați aceste variabile în fișierul .env:

Variabilă	Unde să o găsiți
`MINIMAX_API_KEY`	Platforma MiniMax → API Keys
`MINIMAX_BASE_URL`	Folosiți `https://api.minimax.io/v1` (valoare implicită)
`MINIMAX_MODEL_ID`	Numele modelului de folosit (ex., `MiniMax-M3`)

Modele exemplu: MiniMax-M3 (recomandat), MiniMax-M2.7, MiniMax-M2.7-highspeed (răspunsuri mai rapide). Numele modelelor și disponibilitatea pot varia în timp, iar accesul la un model depinde de contul sau regiunea dvs. — verificați Platforma MiniMax pentru lista curentă. Dacă MiniMax-M3 nu este disponibil pentru contul dvs., setați MINIMAX_MODEL_ID la un model la care aveți acces (ex. MiniMax-M2.7).

Exemplele de cod care folosesc OpenAIChatClient (ex., fluxul de lucru pentru rezervarea hotelului din Lecția 14) vor detecta automat și utiliza configurația MiniMax dacă este setată MINIMAX_API_KEY.

Furnizor alternativ: Foundry Local (Rulează modele local)

Foundry Local este un runtime ușor care descarcă, gestionează și servește modele de limbaj în întregime pe propriul dvs. calculator printr-un API compatibil OpenAI — fără cloud, fără abonament Azure și fără chei API. Este o opțiune excelentă pentru dezvoltare offline, experimentare fără costuri cloud sau păstrarea datelor local.

Deoarece OpenAIChatClient din Microsoft Agent Framework funcționează cu orice endpoint compatibil OpenAI, Foundry Local este o alternativă locală directă la Azure OpenAI.

1. Instalați Foundry Local

# Windows
winget install Microsoft.FoundryLocal

# macOS
brew install foundrylocal

2. Descărcați și rulați un model (aceasta pornește și serviciul local):

foundry model list          # vezi modelele disponibile
foundry model run phi-4-mini

3. Instalați SDK-ul Python folosit pentru a descoperi endpoint-ul local:

pip install foundry-local-sdk

4. Indicați Microsoft Agent Framework către modelul dvs. local:

from foundry_local import FoundryLocalManager
from agent_framework.openai import OpenAIChatClient

# Descarcă (dacă este necesar) și servește modelul local, apoi descoperă endpoint-ul/portul.
manager = FoundryLocalManager("phi-4-mini")

chat_client = OpenAIChatClient(
    base_url=manager.endpoint,      # de ex. http://localhost:<port>/v1
    api_key=manager.api_key,        # întotdeauna "nu este necesar" pentru Foundry Local
    model_id=manager.get_model_info("phi-4-mini").id,
)

agent = chat_client.as_agent(
    name="LocalAgent",
    instructions="You are a helpful assistant running fully on-device.",
)

Notă: Foundry Local expune un endpoint compatibil OpenAI pentru Chat Completions. Folosiți-l pentru dezvoltare locală și scenarii offline. Pentru setul complet de funcționalități Responses API (conversații stateful, orchestrare complexă de unelte și dezvoltare de tip agent), țintiți către Azure OpenAI sau un proiect Microsoft Foundry așa cum este arătat în lecții. Consultați documentația Foundry Local pentru catalogul curent de modele și suport platformă.

Configurare suplimentară pentru Lecția 8 (Flux de lucru Bing Grounding)

Notebook-ul de flux condiționat din lecția 8 folosește Bing grounding prin Microsoft Foundry. Dacă intenționați să rulați acel exemplu, adăugați această variabilă în fișierul vostru .env:

Variabilă	Unde o găsiți
`BING_CONNECTION_ID`	Portal Microsoft Foundry → proiectul vostru → Management → Resurse conectate → conexiunea Bing → copiați ID-ul conexiunii

Depanare

Erori la verificarea certificatului SSL pe macOS

Dacă folosiți macOS și întâmpinați o eroare ca acesta:

ssl.SSLCertVerificationError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self-signed certificate in certificate chain

Aceasta este o problemă cunoscută cu Python pe macOS unde certificatele SSL ale sistemului nu sunt acceptate automat. Încercați următoarele soluții în ordine:

Opțiunea 1: Rulați scriptul Install Certificates al Python (recomandat)

# Înlocuiți 3.XX cu versiunea dvs. Python instalată (de ex., 3.12 sau 3.13):
/Applications/Python\ 3.XX/Install\ Certificates.command

Opțiunea 2: Folosiți connection_verify=False în notebook-ul vostru (doar pentru notebook-urile GitHub Models)

În notebook-ul Lecția 6 (06-building-trustworthy-agents/code_samples/06-system-message-framework.ipynb), un workaround comentat este deja inclus. Decomentați connection_verify=False când creați clientul:

client = ChatCompletionsClient(
    endpoint=endpoint,
    credential=AzureKeyCredential(token),
    connection_verify=False,  # Dezactivați verificarea SSL dacă întâmpinați erori de certificat
)

⚠️ Atenție: Dezactivarea verificării SSL (connection_verify=False) reduce securitatea prin sărirea validării certificatului. Folosiți asta doar ca soluție temporară în medii de dezvoltare, niciodată în producție.

Opțiunea 3: Instalați și folosiți truststore

pip install truststore

Apoi adăugați următorul cod la începutul notebook-ului sau scriptului vostru înainte de a face orice apel de rețea:

import truststore
truststore.inject_into_ssl()

Blocată undeva?

Dacă aveți probleme cu această configurare, intrați în Azure AI Community Discord sau creați o problemă.

Lecția următoare

Acum sunteți gata să rulați codul pentru acest curs. Spor la învățat mai multe despre lumea Agenților AI!

Introducere în Agenții AI și Cazuri de utilizare a Agenților

Declinare a responsabilității: Acest document a fost tradus folosind serviciul de traducere AI Co-op Translator. În timp ce ne străduim pentru acuratețe, vă rugăm să rețineți că traducerile automate pot conține erori sau inexactități. Documentul original în limba sa nativă trebuie considerat sursa autorizată. Pentru informații critice, se recomandă traducerea profesională realizată de un om. Nu ne asumăm responsabilitatea pentru eventualele neînțelegeri sau interpretări greșite care decurg din utilizarea acestei traduceri.

This site is open source. Improve this page.