---
title: "API-uri pregătite pentru agenți: acțiuni clare și repetări sigure"
description: "API-uri pentru agenți AI: validare, autorizare, idempotency și tratarea repetărilor fără duplicarea necontrolată a acțiunilor."
canonical: https://i8.ro/blog/api-uri-pregatite-pentru-agenti-actiuni-clare-si-repetari-sigure
---

# API-uri pregătite pentru agenți: acțiuni clare și repetări sigure

> API-uri pentru agenți AI: validare, autorizare, idempotency și tratarea repetărilor fără duplicarea necontrolată a acțiunilor.

Sursă: https://i8.ro/blog/api-uri-pregatite-pentru-agenti-actiuni-clare-si-repetari-sigure

**Seria II: De la infrastructură la proiecte agentice în producție. Episodul 16 din 20.**

Portalul B2B fictiv din serie poate fi monitorizat și recuperat. Mai rămâne o problemă de operare: ce face un agent când trimite o solicitare, dar nu primește răspunsul? Pentru un IMM, decizia utilă este să definească un contract verificabil al acțiunii înainte să ofere agentului acces la scriere. Reluarea trebuie proiectată în serviciu, nu lăsată la intuiția modelului.

## O conexiune întreruptă nu dovedește eșecul

Un **API**, interfață de programare a aplicației, permite unui program să ceară date sau să execute operații într-un alt sistem. În scenariul nostru ipotetic, agentul integrat în portal creează o solicitare asociată unui document, la cererea unui utilizator autorizat. Serverul o salvează, însă conexiunea se întrerupe înainte ca răspunsul să ajungă la agent.

Un **timeout** este expirarea timpului de așteptare. Un **retry** este repetarea încercării. Dacă agentul trimite imediat o nouă cerere de creare, poate produce două solicitări pentru aceeași intenție. Faptul că nu vede rezultatul nu înseamnă că prima operație nu a avut efect.

Această ambiguitate apare și în lucrarea Birrell și Nelson despre apeluri de proceduri la distanță, publicată în 1984: o eroare de comunicare poate lăsa clientul fără certitudinea execuției. Este un reper conceptual, nu o evaluare a agenților actuali.

## Contractul descrie o singură acțiune

Propunem acțiunea „creează solicitare”, separată de citire, modificare și aprobare. Contractul ei trebuie să poată fi înțeles de un dezvoltator, validat de server și folosit de agent fără să ghicească regulile.

| Element | Propunere pentru portal |
| --- | --- |
| Intrări | Titlu, documente existente și identificatorul intenției |
| Identitate | Utilizatorul și organizația verificate de server |
| Condiții | Documentele aparțin organizației și sunt accesibile utilizatorului |
| Rezultat | Identificator stabil al solicitării și starea operației |
| Repetare | Aceeași intenție și aceleași date nu creează o solicitare suplimentară |
| Verificare | O operație de citire arată starea, cu aceleași controale de acces |

Definim câmpurile obligatorii, limitele de lungime, valorile acceptate și erorile. **OpenAPI** este un format standardizat pentru descrierea API-urilor HTTP, protocolul folosit de serviciile web. Specificația 3.2.1 a fost publicată la 10 septembrie 2026. Alegem versiunea compatibilă cu instrumentele proiectului; descrierea nu implementează singură validarea sau securitatea.

## Cheia urmărește intenția, nu formularea agentului

**Idempotența** înseamnă că repetarea aceleiași operații are același efect intenționat ca o singură execuție. Nu cere ca fiecare jurnal sau răspuns să fie identic. RFC 9110 avertizează împotriva repetării automate a cererilor ne-idempotente fără dovezi că repetarea este sigură. Metoda HTTP `POST`, folosită frecvent pentru creare, nu oferă implicit această garanție.

Pentru portal propunem o cheie de idempotență generată înaintea primei încercări și păstrată pentru aceeași intenție. La întrerupere, clientul refolosește cheia și datele inițiale. Nu produce o cheie nouă doar pentru că agentul și-a reformulat explicația. O solicitare nouă, dorită separat de utilizator, primește altă cheie, chiar dacă documentul și titlul coincid.

Serverul asociază cheia cu apelantul, organizația și acțiunea și compară datele relevante. Aceeași cheie cu alte date este refuzată ca neconcordanță. Cheia nu este secret de autentificare și nu trebuie să conțină date personale.

În exemplu, după răspunsul pierdut, agentul verifică operația cunoscută sau repetă cererea conform contractului. Primește identificatorul solicitării deja create și îl prezintă utilizatorului. Dacă verificarea nu este disponibilă și protecția repetării nu poate fi confirmată, agentul raportează rezultatul ca necunoscut și cere verificare umană, fără să inventeze succesul sau eșecul.

## Concurența și durata protecției sunt explicite

Două încercări pot ajunge simultan. O simplă verificare „există cheia?” urmată de creare poate permite ambelor să continue. Propunem o constrângere de unicitate în baza de date și o **tranzacție**, un grup de modificări confirmate împreună sau deloc, pentru înregistrarea cheii, crearea solicitării și salvarea rezultatului.

Pentru o operație încă în curs, răspunsul indică starea și cum poate fi verificată, fără să pornească altă creare. Rezultatul final păstrează legătura cu aceeași solicitare. Separăm identificatorul intenției de identificatorul fiecărei încercări, util în jurnalele de execuție.

Contractul precizează cât timp păstrează serverul cheile. După expirare, repetarea poate fi tratată ca operație nouă; clientul verifică rezultatul anterior sau cere intervenție, nu retrimite orbește. Stripe API v1 documentează păstrarea rezultatului după începerea execuției, inclusiv pentru unele răspunsuri de eroare, și posibilitatea eliminării cheilor după cel puțin 24 de ore. Este politica acelui API, nu o regulă universală pentru portal.

## Efectele externe cer protecție proprie

Tranzacția bazei de date nu include automat e-mailul trimis de un furnizor extern. Propunem înregistrarea durabilă a notificării de trimis împreună cu solicitarea, apoi procesarea separată și verificabilă. Serviciul care preia notificarea trebuie să recunoască repetările, iar integrarea externă să prevină duplicatele sau să reconcilieze rezultatele cu starea reală.

Nu promitem execuție „exact o dată” pentru toate sistemele implicate. Piesa sigură este limita concretă testată: o singură solicitare creată pentru aceeași intenție, în condițiile și intervalul contractului. Notificarea și alte efecte se urmăresc separat.

Legăm acest registru și de recuperarea din episodul anterior. Restaurarea unei baze mai vechi poate elimina evidența unei operații deja executate în alt sistem. După un astfel de incident, reconciliem stările înainte să repornim automat lucrările; existența cheii într-o copie pierdută nu mai protejează reluarea.

## Erori care indică următorul pas

Răspunsul oferă o categorie stabilă de eroare, câmpurile de corectat și identificatorul operației, fără credențiale sau detalii interne sensibile. Datele invalide cer corectare; lipsa drepturilor cere oprire sau clarificare, nu repetare continuă. O operație acceptată pentru prelucrare nu este prezentată ca finalizată.

Pentru erorile tranzitorii prevăzute de contract, folosim încercări limitate și pauze progresive, cu o mică variație aleatoare, numită **jitter**, pentru a evita reluările simultane. Respectăm indicația `Retry-After`, când este furnizată și aplicabilă. Stabilim și termenul după care agentul oprește reluarea și raportează incertitudinea.

Serverul limitează frecvența apelurilor și numărul operațiilor simultane pentru fiecare client. Aceste limite protejează capacitatea și bugetul, dar nu înlocuiesc verificarea duplicatelor.

## Autorizarea rămâne la server

Serverul verifică accesul la fiecare document și solicitare, inclusiv la citirea unui rezultat salvat. Identificatorul organizației trimis de agent nu reprezintă dovadă de apartenență. Dacă folosim OAuth, mecanism de delegare a accesului, limităm tokenurile la resursele și acțiunile necesare, conform reperelor RFC 9700.

Un **dry-run** este o simulare proiectată explicit să arate validările și efectele propuse fără a executa modificarea. Nu este disponibil implicit în orice API și nu rezervă automat starea verificată. Pentru operații cu impact mare, confirmarea umană trebuie legată de datele exacte, iar condițiile reverificate înaintea execuției.

## Proba de acceptare înaintea accesului agentului

Testăm răspuns pierdut după salvare, încercări concurente, aceeași cheie cu date schimbate, acces din altă organizație și cheie expirată. Verificăm numărul solicitărilor și starea efectelor externe, nu doar mesajul de succes. Contractul și aceste teste sunt rezultatul utilizabil al episodului.

Agentul de dezvoltare poate implementa contractul; agentul integrat în portal îl consumă cu identitate distinctă. Un adaptor MCP (Model Context Protocol) conectează instrumente, fără să înlocuiască aceste controale. Episodul următor verifică dacă și interfața website-ului poate fi folosită corect de agenți, nu doar API-ul.

## Surse

Surse verificate la 17 octombrie 2026:

- [RFC 9110, HTTP Semantics, iunie 2022, secțiunea 9.2.2](https://www.rfc-editor.org/rfc/rfc9110.html#section-9.2.2), pentru idempotență și repetarea cererilor.
- [Stripe, Idempotent requests](https://docs.stripe.com/api/idempotent_requests), pentru politica API v1, chei, rezultate și expirare; pagina diferențiază comportamentul API v2.
- [AWS Builders' Library, Making retries safe with idempotent APIs](https://aws.amazon.com/builders-library/making-retries-safe-with-idempotent-APIs/), pentru identificarea intenției și concurență, și [Transactional outbox pattern](https://docs.aws.amazon.com/prescriptive-guidance/latest/cloud-design-patterns/transactional-outbox.html), pentru notificări durabile și consumatori idempotenți.
- [PostgreSQL 18, Transactions](https://www.postgresql.org/docs/18/tutorial-transactions.html) și [Unique Constraints](https://www.postgresql.org/docs/18/ddl-constraints.html#DDL-CONSTRAINTS-UNIQUE-CONSTRAINTS), pentru confirmarea atomică și unicitate în baza de date.
- [OpenAPI Specification 3.2.1, 10 septembrie 2026](https://spec.openapis.org/oas/v3.2.1.html), pentru descrierea contractului.
- [RFC 9700, ianuarie 2025, secțiunea 2.3](https://www.rfc-editor.org/rfc/rfc9700.html#section-2.3) și [OWASP API1:2023, Broken Object Level Authorization](https://api-security.owasp.org/editions/2023/en/0xa1-broken-object-level-authorization/), pentru limitarea accesului și verificarea obiectelor.
- [Birrell și Nelson, Implementing Remote Procedure Calls, ACM Transactions on Computer Systems, februarie 1984](https://www.microsoft.com/en-us/research/publication/implementing-remote-procedure-calls/), în special secțiunea 3.1; [textul lucrării](https://www.cl.cam.ac.uk/teaching/0708/DigiCommI/birrell1984rpc.pdf).

Vrei API-uri pe care agenții să le folosească cu efecte controlate? [Discută cu i8 despre integrare, contracte verificabile și repetări sigure.](https://i8.ro/contact)