Bouw je eerste agent¶

Aan het eind van deze tutorial heb je een agent support die vragen van klanten beantwoordt, en roept je applicatie hem aan met alleen zijn naam en de vraag. Je hebt ook een tweede versie gemaakt en gezien hoe een applicatie op een versie blijft staan.

De voorbeelden in de tutorials volgen één geval: je bent partner en bouwt een supportassistent voor je klant Noordwind, een handelsbedrijf. In deze tutorial bouw je de agent in je eigen organisatie.

1. Controleer wat je sleutel mag¶

curl -s "$CORE_URL/key" -H "Authorization: Bearer $CORE_KEY"

In het antwoord (ingekort) moet agents onder capabilities staan:

{
  "id": "key_7Hn2...",
  "tenant_id": "ten_4Kd9...",
  "capabilities": { "agents": {} }
}

Je kijkt eerst, omdat een ontbrekende capability er later uitziet als een pad dat niet bestaat: de routes onder /agents antwoorden dan 404.

2. Kies een model¶

curl -s "$CORE_URL/models" -H "Authorization: Bearer $CORE_KEY"

De lijst data bevat de chatmodellen die je sleutel mag aanroepen. Neem het id van een ervan over; de voorbeelden schrijven <een model-id>.

Welke modellen er zijn, verschilt per installatie en per sleutel. Een model-id overnemen uit deze lijst voorkomt dat je een agent vastlegt op een model dat je sleutel niet bereikt.

3. Leg de agent vast¶

curl -s -X POST "$CORE_URL/agents" \
    -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
    -d '{"name": "support",
         "description": "Beantwoordt vragen van klanten over bestellingen en retouren.",
         "model": "<een model-id>",
         "instructions": "Je bent de supportassistent van Noordwind. Antwoord kort en in het Nederlands. Weet je iets niet zeker, zeg dat dan.",
         "temperature": 0.2}'

Het antwoord is 201 met de agent en zijn eerste versie (ingekort):

{
  "id": "agt_5Nj2...",
  "object": "agent",
  "name": "support",
  "latest_version": {
    "version": 1,
    "model": "<een model-id>",
    "instructions": "Je bent de supportassistent van Noordwind. ...",
    "temperature": 0.2
  }
}

Bewaar het id voor de volgende stappen:

export AGENT_ID=agt_5Nj2...

Alleen name is verplicht. Je legt hier het model, de instructie en de temperatuur vast, omdat je die later wilt kunnen aanpassen zonder je applicatie opnieuw uit te rollen. De naam kies je met zorg: je applicatie en de policy van een sleutel verwijzen ernaar.

In de console doe je hetzelfde onder Agents.

4. Roep de agent aan¶

curl -s -X POST "$CORE_URL/responses" \
    -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
    -d '{"agent": {"id": "support"},
         "input": "Kan ik een bestelling nog wijzigen nadat ik heb betaald?"}'

Het antwoord heeft dezelfde vorm als bij een verzoek zonder agent (ingekort):

{
  "id": "resp_0KQ2mR...",
  "status": "completed",
  "model": "<een model-id>",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [{ "type": "output_text", "text": "Dat hangt af van ..." }]
    }
  ]
}

Het verzoek noemt geen model en geen instructie: die komen uit de agent. Je applicatie hoeft dus alleen de naam support te kennen.

5. Maak een tweede versie¶

Je wilt dat de agent altijd afsluit met een vraag. Dat is een nieuwe versie:

curl -s -X POST "$CORE_URL/agents/$AGENT_ID/versions" \
    -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
    -d '{"model": "<een model-id>",
         "instructions": "Je bent de supportassistent van Noordwind. Antwoord kort en in het Nederlands. Weet je iets niet zeker, zeg dat dan. Sluit af met de vraag of je nog ergens mee kunt helpen.",
         "temperature": 0.2}'

Een versie is de hele definitie. Wat je niet opnieuw meestuurt, staat er in de nieuwe versie niet meer in; daarom staan het model en de temperatuur er weer bij. Versies veranderen na het aanmaken niet meer, dus je kunt altijd terugvinden wat er op een bepaald moment draaide.

Een verzoek zonder versienummer gebruikt vanaf nu versie 2. De aanroep uit stap 4 hoeft niet te veranderen.

6. Zet je applicatie vast op een versie¶

curl -s -X POST "$CORE_URL/responses" \
    -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
    -d '{"agent": {"id": "support", "version": 1},
         "input": "Kan ik een bestelling nog wijzigen nadat ik heb betaald?"}'

Met version blijft een verzoek op die versie, ook nadat er nieuwe zijn gemaakt. Gebruik dat in productie als je een nieuwe versie eerst wilt proberen: je testomgeving laat version weg, je productieomgeving noemt het nummer dat je hebt goedgekeurd.

Controleer of het werkt¶

Drie dingen laten zien dat de agent doet wat je hebt vastgelegd:

1. De aanroep uit stap 4 eindigt nu met een vraag, en die uit stap 6 niet. Beide versies bestaan naast elkaar.
2. GET /agents/$AGENT_ID/versions geeft twee versies terug.

3. Een verzoek dat een vastgelegd veld wil overschrijven, wordt geweigerd:

   curl -s -X POST "$CORE_URL/responses" \
       -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
       -d '{"agent": {"id": "support"}, "temperature": 0.9, "input": "Hallo"}'
   

   Dit antwoordt 400 met temperature in error.param. Zo weet je bij elke beurt welke definitie er draaide.

Als het niet werkt¶

De volledige lijst staat in Agents via de API.

Verder¶

• Agents: wat een agent vastlegt en wanneer je er een gebruikt.
• Agents via de API: alle velden, en wat een verzoek mag aanvullen.
• Prompts via de API: een sjabloon met variabelen dat een agent vastzet.
• Een modelaanroep doen: de velden van een verzoek en streaming.

Volgende tutorial: Geef een agent kennis uit eigen bedrijfsinformatie.