Een agent definiëren en gebruiken¶

Machinevertaling van het Franse origineel.

Drie objecten om te plaatsen, in deze volgorde. Geen van hen is optioneel: het overslaan van het tweede object resulteert in een agent waarvan de kosten niet aan iemand kunnen worden toegerekend.

flowchart TD
    e["1 · Équipe<br/>budget commun, un projet"] --> c["2 · Clé virtuelle<br/>une par agent = imputation"]
    c --> a["3 · Agent<br/>carte + limites + contrat"]
    a --> u["Consommation<br/>script · workflow · chat · autre agent"]

1. Het team¶

Dit beheert het budget van een project en bevat de relevante gegevens. Een enkele agent heeft geen team nodig; twee agents van hetzelfde project, als — anders worden hun budgetten niet gecombineerd.

curl -sX POST "$PROXY/team/new" -H "Authorization: Bearer $CLE_ADMIN" \
  -H 'Content-Type: application/json' \
  -d '{"team_alias":"<projet>","max_budget":0.5,"budget_duration":"1d"}'

2. De virtuele sleutel — één per agent¶

Dit is het hele mechanisme van toerekening. Zonder dit, besteedt iedereen uitgaven onder dezelfde naam, en de dashboard-weergave toont getallen die geen antwoord geven.

curl -sX POST "$PROXY/key/generate" -H "Authorization: Bearer $CLE_ADMIN" \
  -H 'Content-Type: application/json' \
  -d '{"key_alias":"<projet>-<agent>","team_id":"<id>",
       "models":["<alias1>","<alias2>"],
       "max_budget":0.5,"budget_duration":"1d",
       "metadata":{"role":"agent-projet","agent":"<agent>"}}'

De sleutel wordt in de kluis geplaatst, direct, nooit in een bestand in de repository: zie Een geheim uit de kluis lezen.

Een budget snijdt

Als het budget bereikt is, wordt de sleutel geweigerd. Voor een basisagent waarvan niemand de output bekijkt, biedt dit een dienst die niet meer werkt. Kalibreer boven het piekgetal, en configureer de budgetwaarschuwing (Een notificatie instellen).

3. De agent¶

curl -sX POST "$PROXY/v1/agents" -H "Authorization: Bearer $CLE_ADMIN" \
  -H 'Content-Type: application/json' -d '{
    "agent_name": "<nom>",
    "agent_card_params": {
      "protocolVersion": "0.3",
      "name": "<Nom affiché>",
      "description": "<ce qu'"'"'il fait, et ce qu'"'"'il ne fera jamais>",
      "url": "http://<hôte>:<port>/a2a/<nom>",
      "version": "1.0.0",
      "defaultInputModes": ["text/plain"],
      "defaultOutputModes": ["text/markdown"],
      "skills": [{
        "id": "<verbe>", "name": "<verbe — ce qu'"'"'il établit>",
        "description": "<ce que cette compétence rend, et ce qu'"'"'elle ne rend pas>",
        "tags": ["<axe>"], "examples": ["<appel typique>"]
      }]
    },
    "object_permission": { "models": ["<alias1>","<alias2>"] },
    "rpm_limit": 6
  }'

Veld	Wat het bepaalt
`agent_name`	De stabiele identifier. Dit is wat gekoppeld wordt, nooit de `agent_id`: een agent die opnieuw wordt aangemaakt via de UI, krijgt een nieuwe ID en behoudt zijn naam
`agent_card_params`	De A2A-kaart voor de aanvragers — naam, beschrijving, vaardigheden, formaten
`agent_card_params.url`	Waar de proxy typ.. Als er niets achter zit, liegt de kaart
`object_permission.models`	De lijst met goedgekeurde modellen. Een tweede veiligheidsmaatregel, apart van die van de sleutel
`rpm_limit`, `tpm_limit`	De doorvoersnelheid. `session_*` beperkt een gesprek, niet de hele agent

Een agent consumeren¶

Vier manieren, van het meest algemene naar het meest specifieke.

A. Als een standaardmodel — de methode die voor 90% van de gevallen werkt¶

curl -sX POST "$PROXY/v1/chat/completions" -H "Authorization: Bearer $CLE" \
  -H 'Content-Type: application/json' \
  -d '{"model":"a2a/<nom>","messages":[{"role":"user","content":"<consigne>"}]}'

De proxy herkent het prefix a2a/, lost het agent op in zijn register, vertaalt het naar message/send en vertaalt de reactie terug. Elk systeem dat al met een model communiceert, communiceert dan met de agent: de chat-interface ziet het in zijn lijst, ook de workflow-engine, en een script van drie regels heeft hier niets bijzonders voor nodig.

Met een belangrijke kanttekening: deze oplossing leest het register in geheugen van de proxy. Na een herstart, lukt dit niet voor iedereen, zolang de agents niet opnieuw zijn toegepast – zie val 4.

B. In A2A, voor een klant die het protocol { #b-en-a2a-pour-un-client-qui-connait-le-protocole } kent¶

curl -s "$PROXY/a2a/<id>/.well-known/agent-card.json" -H "Authorization: Bearer $CLE"

curl -sX POST "$PROXY/a2a/<id>/message/send" -H "Authorization: Bearer $CLE" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":"1","method":"message/send","params":{"message":{
       "role":"user","parts":[{"kind":"text","text":"<consigne>"}],"messageId":"<uuid>"}}}'

Dit wordt gebruikt wanneer je het taakproces wilt uitvoeren – een taak die lang duurt, een statusvolging, en artefacten die geleverd worden tijdens het proces.

C. Vanuit een script in de omgeving, zonder A2A¶

Dit is het geval van een agent die een commandoregelprogramma is op een machine, niet een server. Het script leest de definitie van de agent uit het register, en start vervolgens het programma zelf:

agent, provenance, contrat = charge(AGENT_DE_SECOURS)   # GET /v1/agents
print(f"définition : {provenance}")                      # litellm | cache | code

Er zijn drie dingen die je moet onthouden, en die allemaal duur zijn om opnieuw te ontdekken:

Het lezen gebeurt met de sleutel van de agent zelf. Het register reageert op een normale sleutel: er hoeft geen beheer-sleutel op de machine te draaien die het programma uitvoert.
Een lokaal cache, en de bron van de informatie. Een agent die op een back-up draait, geeft dezelfde output, op hetzelfde moment, voor dezelfde kosten: dit is het enige verschil dat je ziet tussen "up-to-date" en "proxy is sinds drie dagen stil".
Een label voor de aanroep (x-litellm-tags), anders wordt de kosten toegewezen aan de sleutel, maar niet aan het werk.

D. Tussen agents¶

Een agent kan een andere agent aanroepen via dezelfde methode, met zijn sleutel. Dit is waar object_permission.agents voor dient: om te bepalen wie welke agent kan aanroepen.

De val, allemaal gemeten¶

1. De administratieve interface overschrijft litellm_params

Het formulier vervangt dit veld met alleen zijn eigen velden. Alle gegevens die een script hierin opslaat – een uitvoeringscontract, metadata – verdwijnen wanneer de eerste gebruiker de agent opent en opslaat. Er is geen melding, geen spoor, behalve in updated_by.

Gemeten: 21 velden, ingesteld op 07:52, verwijderd op 08:13 dezelfde dag. De kaart, de grenzen en de lijst met templates, waren wel intact.

Belangrijk: Wat moet blijven, komt in de kaart. Wat je in litellm_params opslaat, heeft een andere bron en een handeling nodig om het te herstellen.

2. De kaart verwijdert wat hij niet kent, en geeft 200 terug

capabilities.extensions – de normatieve plek voor metadata – wordt gefilterd bij het opslaan. Alleen streaming, pushNotifications en stateTransitionHistory blijven over. Het aanmaken is succesvol, de kaart komt terug met een gebrek, er wordt niets gemeld.

3. Een herlezen van de kaart is geen geldige actie

Het herlezen van een kaart en het terugsturen zoals het is, mislukt met 422, op velden die de proxy zelf heeft aangemaakt. Het verwijderen van deze velden is voldoende: ze worden opnieuw aangemaakt. Alle acties lezen / wijzigen / herschrijven moeten deze verwijderen.

4. Het register leeft in het geheugen: een herstart van de proxy leegt het

De lijst met agenten wordt niet opnieuw gelezen vanaf de basis bij het opstarten: deze bevat alleen de agenten die zijn aangemaakt of gewijzigd sinds het proces is gestart. Na een herstart bestaan ze nog steeds – ze kunnen nog steeds worden bereikt via hun identificatie – maar de lijst is leeg, en vooral a2a/<nom> stopt met werken: het oplossen leest hetzelfde register. Alles wat de agent als een model gebruikte, stopt zonder waarschuwing, terwijl de proxy healthy en de modellen reageren.

Gemeten twee keer in dezelfde uur, op 13 september 2026, bij zes agenten.

Drie stappen, in deze volgorde: het identificatie van elke agent bewaren in de definitie (wanneer de lijst vergeten is, is dit de enige manier om er toegang toe te krijgen); ervoor zorgen dat de conditie wordt aangegeven door de controle, in plaats van "afwezig" te zeggen, wat een poging tot creatie zou veroorzaken en "bestaat al" zou betekenen; en herstellen – een eenvoudige terugschrijfoperatie brengt het terug in het register.

Het herstellen gebeurt automatisch zonder risico, omdat het verschil onjuist is: zowel de basis als de bron zeggen hetzelfde, er is niets om te arbitreren. Maar alleen in dit geval – zodra een ander type verschil zich voordoet, wordt dit opgemerkt en wordt er niets aan gedaan, anders wordt het werk van iemand anders overschreven.

5. Een gedeeltelijke wijziging vervangt

Een PATCH fuseert niet: de ontbrekende velden in het object worden verloren. Het is altijd belangrijk om het volledige object terug te geven. En een contract met ontbrekende elementen gedraagt zich precies als een gezond contract, omdat de ontbrekende elementen terugvallen op de standaardwaarden van de code – waardoor het nuttig is voor een gebruiker die aangeeft wat hij daadwerkelijk heeft gelezen.

Controles¶

# La définition telle que le registre la sert, et rien d'autre
curl -s "$PROXY/v1/agents" -H "Authorization: Bearer $CLE" | jq '.[] | {agent_name, rpm_limit}'

# Ce que l'exécutant a réellement chargé, à son dernier run
<commande de l'agent> 2>&1 >/dev/null | head -1

# Qui a modifié l'agent en dernier — un humain dans l'UI s'y voit
curl -s "$PROXY/v1/agents/<id>" -H "Authorization: Bearer $CLE_ADMIN" \
  | jq '{updated_at, updated_by}'

Dernière vérification de cette page : 2026-09-13