Integration af Karla AI Søgning via API

Log ind på Karla platformen og tilgå Karlas udviklerindstillinger, og opret et sæt OAuth 2.0 credentials. Gem jeres client_id og client_secret et sikkert sted. Credentials skal tilhøre den organisation, som agenten ligger i.

1. Åbn API-dokumentationen, og log ind, hvis I bliver bedt om det.
2. Indtast Client ID og Client Secret fra trin 1 i felterne øverst, og klik på Authorize.
3. Vent, til dokumentationen viser ✓ Authorized, før I tester endpoints med Try it out og Execute.

Vælg den search agent, I vil integrere med, og brug dens model-id. Agenten skal tilhøre jeres organisation og have en publiceret version. Kontakt Karla, hvis I mangler agentens id.

Find GET /v1/models/{model_id}/published under Models. Klik på Try it out, indsæt jeres agents id som model_id, og klik på Execute.

GET https://api.getkarla.ai/v1/models/{model_id}/published
Authorization: Bearer <access_token>

Ved succes indeholder svaret type: "success" og den publicerede search agents konfiguration under response. De relevante felter er:

I behøver ikke angive en version i det første søgekald: uden model_version_id bruger API'et agentens aktuelt publicerede version.

Find POST /v1/search/query under Search, og klik på Try it out. Brug følgende request body med jeres OAuth-credentials, og erstat MODEL_ID med samme agent-id som i trin 3:

{
  "model_id": "MODEL_ID",
  "message": {
    "role": "user",
    "content": "Skriv jeres søgeforespørgsel her"
  },
  "stream": false,
  "conversation_id": null
}

Felterne skal ligge direkte i JSON-objektet ved OAuth-kald. Brug Content-Type: application/json. Eksemplet bruger stream: false, så I kan læse det samlede svar direkte i dokumentationen uden at opsætte en socket-forbindelse.

Klik på Execute, og kontrollér svaret:

• type er "success" ved et gennemført kald.
• response.messages indeholder beskederne. Vis content fra beskeder med role: "assistant" som AI-svar.
• response.search_query_hits indeholder søgeresultaterne. Brug title og, når det findes, url til kildelisten.
• response.id er samtalens id. Send det som conversation_id ved et opfølgende spørgsmål. Brug null ved en ny samtale.

Se endpointets schema og eksempler i API-dokumentationen for øvrige felter og mulige fejlsvar.

Når model- og søgekaldet virker i dokumentationen, kan I bruge præcis samme URL'er, headers og request bodies i jeres egen integration. Kopiér eventuelt dokumentationens genererede cURL-request som udgangspunkt.

Backend: credentials og access token

Lad jeres backend hente og opbevare access tokenet og videresende model- og søgekald til Karla API. Frontend kalder jeres backend, som tilføjer Bearer-tokenet.

Tokenet hentes med følgende request. Erstat pladsholderne med jeres credentials, og send body som URL-encoded form-data:

POST https://api.getkarla.ai/v1/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>

Læs access_token og expires_in fra token-svaret. Den nuværende API-implementering udsteder OAuth-tokens med en levetid på 3600 sekunder. Genbrug tokenet, mens det er gyldigt, og hent et nyt med samme client-credentials-kald ved udløb. Dette flow udsteder ikke et refresh token.

Frontend: svar og kilder

• Byg et responsivt søgefelt, inline eller popup.
• Vis en tydelig loading-tilstand, mens søgningen kører, og en forståelig fejlbesked, hvis kaldet fejler.
• Vis AI-svaret med understøttelse af Markdown, herunder overskrifter, lister og fed tekst.
• Vis kilder med titel og link til originalkilden, når et link findes.
• Gem samtalens id, hvis brugeren skal kunne stille opfølgende spørgsmål. Tilføj eventuelt foreslåede spørgsmål som knapper.

Når det almindelige request fungerer, kan I tilføje løbende visning af svaret. Forbind via Socket.IO til namespace /v1/search/query, tilmeld jer et entydigt room med join_room, og send samme room i søgerequesten sammen med stream: true.

Kontrollér først, at dokumentationen viser Authorized, at jeres credentials tilhører den rigtige organisation, og at agenten har en publiceret version. Kontrollér derefter request body mod endpointets schema, og læs HTTP-status samt fejlbeskeden i svaret.

Skriv endelig, hvis I støder på noget undervejs. Så hjælper vi jer videre.