Laat een agent een actie uitvoeren met een tool¶

Aan het eind van deze tutorial maakt de agent support een ticket aan in het ticketsysteem van Noordwind wanneer een klant daarom vraagt. Je hebt het endpoint van dat systeem als API-koppeling geregistreerd, de host toegestaan en de tool eerst zelf geprobeerd.

De voorbeelden gebruiken https://tickets.example.com/api/tickets als endpoint. Vervang dat door het adres van je eigen systeem; het voorbeeld gaat uit van een API die een POST met subject en description verwacht en 201 antwoordt met het nieuwe ticket.

Een API-koppeling is de kortste weg naar een bestaande HTTP-API: Core roept het endpoint aan met de argumenten van het model en bewaart het token. Moet je eigen applicatie de actie uitvoeren, bijvoorbeeld omdat ze een scherm bijwerkt, gebruik dan een functietool.

1. Registreer de API-koppeling¶

curl -s -X POST "$CORE_URL/api_connectors" \
    -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
    -d '{"name": "ticket_aanmaken",
         "http_url": "https://tickets.example.com/api/tickets",
         "description": "Maakt een supportticket aan. Gebruik dit alleen als de klant om een ticket vraagt of als je de vraag niet zelf kunt oplossen.",
         "parameters": {"type": "object",
                        "properties": {"onderwerp": {"type": "string", "description": "Korte titel van het probleem"},
                                       "omschrijving": {"type": "string", "description": "Wat de klant meldt, in zijn eigen woorden"}},
                        "required": ["onderwerp", "omschrijving"]},
         "request": {"method": "POST",
                     "body": {"subject": "{onderwerp}", "description": "{omschrijving}"}},
         "auth": {"type": "bearer", "secret": "Bearer <het token van het ticketsysteem>"}}'

Het antwoord is 201 (ingekort):

{
  "id": "tool_3Lm8...",
  "name": "ticket_aanmaken",
  "version": 1,
  "auth": { "type": "bearer", "header_name": "Authorization", "has_secret": true },
  "egress": [{ "host": "tickets.example.com", "allowed": false, "blocked": false }]
}

Vier keuzes in dit verzoek:

• name wordt de toolnaam api__ticket_aanmaken en wijzigt daarna niet meer.
• description en parameters zijn alles wat het model van de tool weet. Schrijf in de omschrijving wanneer de tool bedoeld is, en geef elk argument een eigen omschrijving.
• request vertaalt de argumenten naar de body die jouw API verwacht. Laat je request weg, dan stuurt Core een vaste body met tool, arguments, response_id en call_id.
• auth bewaart het token bij de koppeling. Het model en je applicatie krijgen het nooit te zien, en geen enkel antwoord geeft het terug. Een bearer-geheim gaat letterlijk mee, dus het voorvoegsel Bearer staat erin.

egress zegt dat de host nog niet is toegestaan. Dat los je in de volgende stap op.

2. Sta de host toe¶

Een organisatie bereikt geen enkele host tot ze die toestaat. Dat doet een beheerder in de console: open Instellingen, het tabblad Toegang & policy, en kies Host toevoegen op de kaart Toegestane hosts. Vul tickets.example.com in en kies Host toestaan.

Met een sleutel die de capability management heeft, doe je hetzelfde via de API:

curl -s -X POST "$CORE_URL/organisation/allowed-hosts" \
    -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
    -d '{"host": "tickets.example.com"}'

{
  "object": "allowed_hosts",
  "everywhere": false,
  "hosts": [{ "host": "tickets.example.com", "blocked": false }]
}

De lijst geldt voor de hele organisatie: elke sleutel bereikt de hosts die erop staan. Een sleutel kan dat met eigen regels over Bestemmingen versmallen en nooit verbreden. Zo bepaalt de organisatie, en niet één applicatie, waar haar gegevens heen mogen. Staat er blocked: true, dan blokkeert je installatie de host voor iedereen; vraag het dan je operator.

3. Probeer de tool zelf¶

curl -s -X POST "$CORE_URL/tools/api__ticket_aanmaken/call" \
    -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
    -d '{"arguments": {"onderwerp": "Test vanuit Core", "omschrijving": "Dit ticket mag weg."}}'

{
  "object": "tool_call",
  "name": "api__ticket_aanmaken",
  "status": "ok",
  "error_code": null,
  "text": "{\"id\": \"T-1042\", \"subject\": \"Test vanuit Core\"}"
}

text is wat een model zou lezen; de inhoud hier is een voorbeeld van wat een ticketsysteem antwoordt. Deze aanroep maakt een echt ticket aan. Je doet hem toch, omdat je zo de koppeling, het token en de host test zonder model ertussen. status is ok, denied, error of cancelled.

4. Geef de agent de tool¶

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. Zoek bij elke vraag over beleid eerst in het handboek en verwijs naar de passage met [n]. Maak alleen een ticket aan als de klant daarom vraagt of als je de vraag niet kunt oplossen. Noem daarna het ticketnummer.",
         "temperature": 0.2,
         "tools": [{"type": "tool", "name": "knowledge__handboek"},
                   {"type": "tool", "name": "api__ticket_aanmaken"}]}'

Heb je de tweede tutorial overgeslagen, laat dan knowledge__handboek en de zin over het handboek weg. De instructie zegt wanneer de agent een ticket mag aanmaken. Een tool die iets verandert, heeft zo'n grens nodig: zonder die zin maakt een model sneller een ticket dan je wilt.

5. Vraag om een ticket¶

curl -s -X POST "$CORE_URL/responses" \
    -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
    -d '{"agent": {"id": "support"},
         "input": "Mijn bestelling 88213 is beschadigd aangekomen. Wil je hier een ticket van maken?"}'

Controleer of het werkt¶

Het antwoord (ingekort) toont de toolaanroep en daarna de tekst van de agent:

{
  "id": "resp_0KQ2mR...",
  "status": "completed",
  "output": [
    { "type": "mcp_call", "name": "api__ticket_aanmaken", "server_label": "api",
      "arguments": "{\"onderwerp\": \"Beschadigde bestelling 88213\", \"omschrijving\": \"...\"}",
      "status": "completed", "output": "{\"id\": \"T-1043\", ...}" },
    { "type": "message", "role": "assistant",
      "content": [{ "type": "output_text", "text": "Ik heb ticket T-1043 voor je aangemaakt." }] }
  ]
}

Het ticket staat nu ook in je ticketsysteem. De trace van de beurt laat zien wat Core uitvoerde en wat het endpoint antwoordde:

curl -s "$CORE_URL/responses/resp_0KQ2mR.../trace" -H "Authorization: Bearer $CORE_KEY"

{
  "items": [
    { "id": "...", "round": 0, "status": "ok",
      "tool_calls": [
        { "tool_name": "api__ticket_aanmaken", "source": "http", "status": "ok", "vendor_status": 201 }
      ] }
  ]
}

vendor_status is de HTTP-status van je eigen endpoint. In de console staat dezelfde beurt onder Traces (Een trace lezen).

Als het niet werkt¶

Een mislukte toolaanroep laat de beurt niet mislukken: het model krijgt de melding en antwoordt daarmee.

Verder¶

• Tools: alle bronnen van tools en wanneer je welke kiest.
• API-koppelingen in de console en Tools via de API: authenticatie, eigen verzoeken en versies.
• De persoon logt zelf in: een tool die handelt namens de persoon voor wie de beurt is.
• Vertrouwen in toolresultaten: waarom een toolresultaat nooit een instructie is.

Volgende tutorial: Koppel een externe capability via MCP.