Agent API

Public API Server‑to‑Server Funktionale Agents

Was diese Seite abdeckt

Nutze diese Seite, wenn du einen Agent außerhalb der Webapp triggern möchtest – zum Beispiel aus einem Backend‑Service, einem Cronjob oder einer anderen Plattform.

• Unterstützter Einstiegspunkt: POST /api/agent/run
• Scope: funktionale Agents mit JSON‑Argument‑Schema
• Auth: JWT‑Bearer‑Token mit Admin‑Rechten für die Zielorganisation

Guter Use Case

Verwende die Agent API, wenn du einen einzelnen strukturierten Rückgabewert (Funktionsaufruf) brauchst – nicht eine längere Chatsession.

Voraussetzungen

1. Lege in der nara Webapp einen funktionalen Agent an und veröffentliche ihn für deine Organisation.
2. Konfiguriere den Arguments‑Typ (JSON‑Schema), damit Eingaben valide geprüft werden können.
3. Merke dir den Namen des Agents – dieser wird als agentName in der API übergeben.
4. Besorge dir ein Admin‑API‑Token (JWT) für die Organisation, in der der Agent laufen soll.

Endpoint-Übersicht

HTTP (empfohlen)

Der HTTP‑Endpoint steht über deine nara Webapp zur Verfügung:

POST https://app.nara.de/api/agent/run
Authorization: Bearer <ADMIN_JWT>
Content-Type: application/json

Request‑Body:

{
  "agentName": "support_triage",
  "args": {
    "ticketId": "TCK-12345",
    "priority": "high",
    "language": "en"
  }
}

Bei Erfolg enthält die Antwort das strukturierte Ergebnis des Agents sowie die interne Execution‑Spur:

{
  "success": true,
  "sessionId": "api-...",
  "agent": "support_triage",
  "output": {
    "category": "billing",
    "nextStep": "escalate_to_human",
    "summary": "Customer cannot update credit card."
  },
  "messages": [
    {
      "role": "assistant",
      "parts": [
        { "type": "text", "text": "…" }
      ]
    }
  ]
}

Bei Validierungs‑ oder Berechtigungsfehlern erhältst du einen Error‑Payload mit passendem HTTP‑Status (4xx oder 5xx).

Node.js via fetch

const baseUrl = 'https://app.nara.de'
const token = process.env.NARA_ADMIN_TOKEN ?? ''

type SupportTriageResult = {
  category: string
  nextStep: string
  summary: string
}

async function runSupportTriage(args: unknown): Promise<SupportTriageResult> {
  const response = await fetch(`${baseUrl}/api/agent/run`, {
    method: 'POST',
    headers: {
      'content-type': 'application/json',
      authorization: `Bearer ${token}`,
    },
    body: JSON.stringify({
      agentName: 'support_triage',
      args,
    }),
  })

  if (!response.ok) {
    throw new Error(`Agent call failed with status ${response.status}`)
  }

  const payload = (await response.json()) as {
    success?: boolean
    output?: unknown
    error?: string
  }

  if (!payload.success || !payload.output) {
    throw new Error(payload.error ?? 'Agent call failed')
  }

  return payload.output as SupportTriageResult
}

Dieses Muster funktioniert in jedem Node‑Service, der die Webapp‑URL erreichen und ein Admin‑Token mitsenden kann.

@nara/rpc (intern)

Für Dienste, die ohnehin im Umfeld der Webapp laufen, kannst du den typisierten RPC‑Client aus @nara/rpc nutzen, um dieselbe Funktionalität aufzurufen, während die Webapp die Authentifizierung übernimmt:

import { createRpcClient } from '@nara/rpc/client'

const rpc = createRpcClient()

const functionalAgents = await rpc.agent.list({ type: 'FUNCTIONAL' })

// Ausführung erfolgt entweder per HTTP-Endpoint oder über interne Flows.

Nutze dies in vertrauenswürdigen internen Services. Für Dritt‑Integrationen und klassische Server‑to‑Server‑Calls ist der HTTPS‑Endpoint aus dem HTTP‑Tab die richtige Wahl.

Authentifizierungsmodell

Nur Admins

Agent‑Ausführung benötigt einen Admin‑Kontext für die Zielorganisation. Das Token muss eine Admin‑Rolle für diese Organisation tragen.

JWT‑Tokens

Tokens werden von der Plattform verifiziert; du kannst entweder aus einer authentifizierten Admin‑Session heraus aufrufen oder ein Admin‑JWT als Bearer‑Token senden.

Organisations‑Scope

Der Agent muss zur gleichen Organisation gehören wie das Token. Cross‑Org‑Ausführung wird abgewiesen.

Richtiges Token wählen

Für dauerhafte Integrationen verwende bevorzugt ein dediziertes Service‑Token mit Admin‑Rolle statt interaktiver User‑Tokens.

Verfügbare funktionale Agents anzeigen

Du kannst ausführbare funktionale Agents abfragen:

GET https://app.nara.de/api/agent/run
Authorization: Bearer <ADMIN_JWT>

Antwort:

{
  "agents": [
    { "name": "support_triage" },
    { "name": "contract_summary" }
  ]
}

Nutze diese Namen als agentName, wenn du POST /api/agent/run aufrufst.

Nächste Schritte

Agents in Workflows integrieren

Typischerweise rufst du deinen funktionalen Agent aus einem Scheduler, Event‑Handler oder Ticket‑System auf und speicherst den output‑Payload in deinem eigenen System.

Edge Connector für On‑Prem‑Tools entdecken