Overview

The Agent API provides a session-based conversational backend for Neurologyca chat experiences. A typical integration creates a session, reloads session history when needed, and sends each user message to the ADK orchestrator to receive the assistant reply plus per-agent execution traces.

Integration pattern

• Authentication: Send a bearer token with agent framework requests using Authorization: Bearer <token>.
• Base URL resolution: The web client reads VITE_AGENT_CHAT_BACKEND_SERVER first, then falls back to VITE_WEBSOCKET_SERVER or VITE_BACKEND_SERVER. If the configured URL uses ws: or wss:, the client normalizes it to http: or https: for API requests. If the configured URL does not already end with /api/v1, the client appends that path automatically.
• Session endpoints: POST /api/v1/sessions, GET /api/v1/sessions, and GET /api/v1/sessions/{session_id}/history
• Primary message endpoint: POST /api/v1/adk/message

Recommended integration flow

1. Authenticate the user in your client application.
2. Read the auth token and send it on agent API requests as Authorization: Bearer <token>.
3. For a new client integration, call POST /api/v1/auth/firebase after sign-in so the backend can create or sync the user record. If the user is not already provisioned, the session endpoints return 401 User not found. Please sync your account first.
4. Create a chat session with POST /api/v1/sessions.
5. Load existing sessions with GET /api/v1/sessions and hydrate a specific conversation with GET /api/v1/sessions/{session_id}/history.
6. Send each message to POST /api/v1/adk/message with session_id, content, and the client-side conversation_history array.
7. Render the returned content as the assistant message and optionally use agent_traces to show progress, latency, or per-agent summaries in the UI.

Core endpoints

Example integration

1
const token = await getBearerToken();
2
3
const createSessionResponse = await fetch("https://your-agent-backend.example.com/api/v1/sessions", {
4
  method: "POST",
5
  headers: {
6
    "Content-Type": "application/json",
7
    "Authorization": `Bearer ${token}`,
8
  },
9
  body: JSON.stringify({
10
    channel: "web",
11
    client_info: {
12
      userAgent: navigator.userAgent,
13
      language: navigator.language,
14
    },
15
  }),
16
});
17
18
const session = await createSessionResponse.json();
19
20
const replyResponse = await fetch("https://your-agent-backend.example.com/api/v1/adk/message", {
21
  method: "POST",
22
  headers: {
23
    "Content-Type": "application/json",
24
    "Authorization": `Bearer ${token}`,
25
  },
26
  body: JSON.stringify({
27
    session_id: session.id,
28
    content: "Help me prepare for a difficult conversation with my manager.",
29
    conversation_history: [],
30
    user_preferences: {},
31
  }),
32
});
33
34
const reply = await replyResponse.json();
35
console.log(reply.content, reply.agent_traces);

Notes

• The Agent Framework endpoints use bearer auth. This is separate from the public SoftSkills API flow documented elsewhere in these docs, which currently uses API keys.
• Current web integrations use POST /api/v1/adk/message instead of POST /api/v1/conversation/message because the ADK route returns the multi-agent traces used for the chat UI.
• The backend exposes additional routes in agents-backend, but this page and the Agent API reference focus on the core session and messaging contract used by the current web integrations.