> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://dev.neurologyca.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://dev.neurologyca.com/_mcp/server.

# Overview

> Session-based integration flow for the Agent backend

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

| Endpoint                                    | Used for                               | Notes                                                                                                                                                                  |
| ------------------------------------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `POST /api/v1/auth/firebase`                | Recommended backend user sync          | New client integrations should use it to provision the backend user record after sign-in.                                                                              |
| `POST /api/v1/sessions`                     | Create a new agent chat session        | The web integration sends `channel: "web"` plus a `client_info` object with browser metadata.                                                                          |
| `GET /api/v1/sessions`                      | Load the user's recent chat sessions   | Used to build the session list and restore prior conversations.                                                                                                        |
| `GET /api/v1/sessions/{session_id}/history` | Load turns for a specific chat session | The client maps returned turns into chat messages and restores the selected conversation.                                                                              |
| `POST /api/v1/adk/message`                  | Generate the assistant response        | This is the main chat endpoint. The response includes `content`, `agent_traces`, `context`, `sentiment`, `query_analysis`, `total_latency_ms`, `success`, and `error`. |

## Example integration

```ts
const token = await getBearerToken();

const createSessionResponse = await fetch("https://your-agent-backend.example.com/api/v1/sessions", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${token}`,
  },
  body: JSON.stringify({
    channel: "web",
    client_info: {
      userAgent: navigator.userAgent,
      language: navigator.language,
    },
  }),
});

const session = await createSessionResponse.json();

const replyResponse = await fetch("https://your-agent-backend.example.com/api/v1/adk/message", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${token}`,
  },
  body: JSON.stringify({
    session_id: session.id,
    content: "Help me prepare for a difficult conversation with my manager.",
    conversation_history: [],
    user_preferences: {},
  }),
});

const reply = await replyResponse.json();
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.