### Install Development Prerequisites

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/README.md

Install required development tools using Homebrew.

```bash
brew install uv bun
```

--------------------------------

### GET /api/tracing_experiment Examples

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/endpoints.md

cURL commands to retrieve experiment information and open the UI link.

```bash
curl http://localhost:8000/api/tracing_experiment
```

```bash
curl -s http://localhost:8000/api/tracing_experiment | jq '.link' | xargs open
```

--------------------------------

### Start Vite dev server

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/errors.md

Command to start the Vite development server.

```bash
./watch.sh
```

--------------------------------

### Run development server

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/client/README.md

Starts the application in development mode with hot reloading.

```bash
npm start
```

--------------------------------

### Import and use shadcn/ui components

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/README.md

Example of importing and implementing installed UI components within a React component.

```tsx
import { Button } from "@/components/ui/button"
import { Dialog } from "@/components/ui/dialog"
import { Card, CardContent, CardHeader } from "@/components/ui/card"

function MyComponent() {
  return (
    <Card>
      <CardHeader>My Card</CardHeader>
      <CardContent>
        <Button variant="outline">Click me</Button>
      </CardContent>
    </Card>
  )
}
```

--------------------------------

### Setup Development Environment

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/README.md

Run the interactive script to generate the local environment configuration file.

```bash
./setup.sh
```

--------------------------------

### Sync dependencies

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/errors.md

Command to install missing project dependencies.

```bash
uv sync  # Install dependencies
```

--------------------------------

### Agent Execution Examples

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/endpoints.md

Various cURL commands demonstrating different agent interaction scenarios.

```bash
curl -X POST http://localhost:8000/api/agent \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "messages": [
        {"role": "user", "content": "What catalogs are available?"}
      ]
    }
  }'
```

```bash
curl -X POST http://localhost:8000/api/agent \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "messages": [
        {"role": "user", "content": "List schemas in the main catalog"}
      ]
    }
  }'
```

```bash
curl -X POST http://localhost:8000/api/agent \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "messages": [
        {"role": "user", "content": "What catalogs exist?"},
        {"role": "assistant", "content": "Available catalogs: main, samples"},
        {"role": "user", "content": "List tables in the main catalog"}
      ]
    }
  }'
```

--------------------------------

### GET /api/health Examples

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/endpoints.md

cURL commands to verify service health and extract the status field.

```bash
curl http://localhost:8000/api/health
```

```bash
curl -s http://localhost:8000/api/health | jq '.status'
```

--------------------------------

### Basic Agent Usage

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/api-reference-backend.md

Example of invoking the agent and extracting the content from the response.

```python
from server.agents.databricks_assistant import databricks_agent

# Call the agent
response = databricks_agent(
    messages=[
        {"role": "user", "content": "List all catalogs"}
    ]
)

# Extract the response
agent_response = response["choices"][0]["message"]["content"]
print(agent_response)
```

--------------------------------

### GET /redoc

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/endpoints.md

Provides access to the ReDoc interactive API documentation.

```APIDOC
## GET /redoc

### Description
Serves the ReDoc interactive API documentation, providing organized endpoint sections and detailed type definitions.

### Method
GET

### Endpoint
/redoc
```

--------------------------------

### 404 Not Found cURL Example

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/errors.md

Example request triggering a 404 error by referencing a non-existent endpoint.

```bash
curl -X POST http://localhost:8000/api/invoke_endpoint \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint_name": "nonexistent-endpoint",
    "messages": [{"role": "user", "content": "test"}]
  }'
# Error: Endpoint not found or 404
```

--------------------------------

### GET /docs

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/endpoints.md

Provides access to the interactive Swagger UI documentation.

```APIDOC
## GET /docs

### Description
Serves the interactive Swagger UI documentation for testing and exploring the API.

### Method
GET

### Endpoint
/docs
```

--------------------------------

### AppSidebar Usage Example

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/api-reference-frontend.md

Initializes the AppSidebar with required state callbacks and experiment data.

```typescript
<AppSidebar
  selectedAgent="default"
  setSelectedAgent={setSelectedAgent}
  setMessages={setMessages}
  experiment={experiment}
  experimentIsLoading={false}
/>
```

--------------------------------

### Add shadcn/ui components

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/README.md

Commands to install UI components into the project using the Bun package manager.

```bash
# Add a new component (run from project root)
bunx --bun shadcn@latest add button
bunx --bun shadcn@latest add dialog
bunx --bun shadcn@latest add form

# Browse available components
bunx --bun shadcn@latest add
```

--------------------------------

### POST /api/agent Request

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/endpoints.md

Example of the HTTP request structure for executing the agent.

```http
POST /api/agent HTTP/1.1
Host: localhost:8000
Content-Type: application/json

{
  "inputs": {
    "messages": [
      {
        "role": "user",
        "content": "List all catalogs in my workspace"
      }
    ]
  }
}
```

--------------------------------

### 400 Bad Request cURL Example

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/errors.md

Example request triggering a 400 error due to a missing required field.

```bash
curl -X POST http://localhost:8000/api/agent \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {}  # Missing 'messages' field
  }'
# Error: "detail": "Field required"
```

--------------------------------

### 401 Unauthorized Troubleshooting Examples

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/errors.md

Common authentication error scenarios in development and production environments.

```python
# Development: Missing token
Error: Unable to authenticate with Databricks
# Solution: Set DATABRICKS_TOKEN in .env.local

# Production: Missing OAuth credentials
Error: Unable to authenticate with Databricks
# Solution: Ensure DATABRICKS_CLIENT_ID and DATABRICKS_CLIENT_SECRET are set
```

--------------------------------

### Invoke model_serving_endpoint

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/api-reference-backend.md

Example usage showing how to call the endpoint and extract content and usage statistics from the response.

```python
from server.agents.model_serving import model_serving_endpoint

response = model_serving_endpoint(
    endpoint_name="databricks-claude-sonnet-4",
    messages=[
        {"role": "user", "content": "Explain Unity Catalog"}
    ]
)

content = response["choices"][0]["message"]["content"]
usage = response["usage"]
print(f"Response: {content}")
print(f"Tokens used: {usage['total_tokens']}")
```

--------------------------------

### Interact with Log Assessment Endpoint

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/api-reference-backend.md

Examples for logging feedback and handling errors during the process.

```python
response = await client.post(
    "http://localhost:8000/api/log_assessment",
    json={
        "trace_id": "trace_abc123",
        "assessment_name": "good_response0",
        "assessment_value": True
    }
)
print(response.json())  # {"status": "success"}
```

```python
try:
    response = await client.post(
        "http://localhost:8000/api/log_assessment",
        json={
            "trace_id": trace_id,
            "assessment_name": "good_response0",
            "assessment_value": False
        }
    )
    if response.status_code != 200:
        print(f"Failed to log feedback: {response.text}")
except Exception as e:
    print(f"Error logging feedback: {e}")
```

--------------------------------

### POST /api/agent Response

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/endpoints.md

Example of a successful 200 OK response from the agent.

```json
{
  "response": {
    "choices": [
      {
        "message": {
          "role": "assistant",
          "content": "Available catalogs: main, samples, demo_catalog"
        }
      }
    ]
  },
  "trace_id": "trace_xyz123abc"
}
```

--------------------------------

### Interact with Agent Endpoint

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/api-reference-backend.md

Examples for calling the agent endpoint and handling potential errors.

```python
import httpx

async with httpx.AsyncClient() as client:
    response = await client.post(
        "http://localhost:8000/api/agent",
        json={
            "inputs": {
                "messages": [
                    {"role": "user", "content": "List all catalogs"}
                ]
            }
        }
    )
    data = response.json()
    print(f"Response: {data['response']}")
    print(f"Trace ID: {data['trace_id']}")
```

```python
try:
    response = await client.post(
        "http://localhost:8000/api/agent",
        json={"inputs": {"messages": [{"role": "user", "content": "test"}]}}
    )
    if response.status_code == 200:
        result = response.json()
    else:
        print(f"Error: {response.status_code}")
except Exception as e:
    print(f"Request failed: {e}")
```

--------------------------------

### NavDocuments Usage Example

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/api-reference-frontend.md

Initializes the NavDocuments component with current agent and experiment state.

```typescript
<NavDocuments
  selectedAgent={selectedAgent}
  setSelectedAgent={setSelectedAgent}
  setMessages={setMessages}
  experiment={experiment}
  experimentIsLoading={experimentIsLoading}
/>
```

--------------------------------

### Spinner Component Usage

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/api-reference-frontend.md

Example of implementing the Spinner component with a required size prop.

```typescript
<Spinner size={16} />
```

--------------------------------

### MessageContent Usage Example

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/api-reference-frontend.md

Renders markdown content using the MessageContent component.

```typescript
<MessageContent
  content="# Welcome\n\nThis is **bold** and this is *italic*\n\n- Item 1\n- Item 2"
/>
```

--------------------------------

### GET /openapi.json

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/endpoints.md

Retrieves the OpenAPI 3.0 specification for the API in JSON format.

```APIDOC
## GET /openapi.json

### Description
Returns the OpenAPI 3.0 specification for the API, describing all endpoints, parameters, and response types.

### Method
GET

### Endpoint
/openapi.json

### Response
#### Success Response (200)
- **schema** (JSON) - JSON schema describing the API.
```

--------------------------------

### Invoke Endpoint via cURL

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/endpoints.md

Examples of using cURL to invoke specific model endpoints.

```bash
curl -X POST http://localhost:8000/api/invoke_endpoint \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint_name": "databricks-claude-sonnet-4",
    "messages": [
      {"role": "user", "content": "Hello, how are you?"}
    ]
  }'
```

```bash
curl -X POST http://localhost:8000/api/invoke_endpoint \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint_name": "databricks-llama-4-maverick",
    "messages": [
      {"role": "user", "content": "Write a poem about data"}
    ]
  }'
```

--------------------------------

### Resolve port conflicts

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/errors.md

Commands to identify and terminate processes using port 8000 or to start Uvicorn on a different port.

```bash
# Kill process on port 8000
lsof -i :8000  # Find PID
kill -9 PID    # Kill it

# Or use different port
UVICORN_PORT=8001 python -m uvicorn server.app:app --reload
```

--------------------------------

### Log Feedback via cURL

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/endpoints.md

Examples of using cURL to send positive, negative, or custom metric feedback to the assessment endpoint.

```bash
curl -X POST http://localhost:8000/api/log_assessment \
  -H "Content-Type: application/json" \
  -d '{
    "trace_id": "trace_abc123",
    "assessment_name": "good_response0",
    "assessment_value": true
  }'
```

```bash
curl -X POST http://localhost:8000/api/log_assessment \
  -H "Content-Type: application/json" \
  -d '{
    "trace_id": "trace_abc123",
    "assessment_name": "good_response0",
    "assessment_value": false
  }'
```

```bash
curl -X POST http://localhost:8000/api/log_assessment \
  -H "Content-Type: application/json" \
  -d '{
    "trace_id": "trace_abc123",
    "assessment_name": "relevance_score",
    "assessment_value": 8.5
  }'
```

--------------------------------

### Initialize the project

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/README.md

Commands to clone the repository and initialize the development environment.

```bash
git clone <this-repo>
./setup.sh                 # Interactive environment setup
./watch.sh                 # Start development server
```

--------------------------------

### Run frontend tests

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/README.md

Navigates to the client directory and executes tests using bun.

```bash
cd client && bun test
```

--------------------------------

### Project file structure

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/README.md

Overview of the backend and frontend directory layout.

```text
server/                              # Backend
├── app.py                           # FastAPI app + endpoints
├── tracing.py                       # MLflow setup
└── agents/
    ├── databricks_assistant/        # Main agent
    │   ├── __init__.py
    │   ├── agent.py                 # Agent logic
    │   ├── tools.py                 # Catalog tools
    │   └── auth.py                  # Auth helpers
    └── model_serving.py             # Endpoint caller

client/                              # Frontend
├── src/
│   ├── App.tsx                      # Main component
│   ├── index.tsx                    # Entry point
│   ├── index.css                    # Global styles
│   ├── endpoints.ts                 # Endpoint config
│   ├── lib/
│   │   └── utils.ts                 # Utilities
│   ├── queries/                     # React Query hooks
│   │   ├── useQueryAgent.tsx
│   │   └── useQueryTracing.tsx
│   ├── components/
│   │   ├── MessageContent.tsx       # Markdown renderer
│   │   ├── Spinner.tsx              # Loading indicator
│   │   ├── app-sidebar.tsx          # Main sidebar
│   │   ├── nav-documents.tsx        # Config section
│   │   ├── nav-main.tsx
│   │   ├── nav-secondary.tsx
│   │   ├── nav-user.tsx
│   │   └── ui/                      # shadcn/ui components
│   ├── fastapi_client/              # Auto-generated
│   └── react-app-env.d.ts
├── build/                           # Production build output
├── package.json
├── tsconfig.json
└── vite.config.ts

Configuration files:
├── pyproject.toml                   # Python dependencies
├── requirements.txt
├── uv.lock
├── .env.local                       # Environment (not in git)
├── app.yaml                         # Databricks Apps manifest
└── .python-version
```

--------------------------------

### GET /api/tracing_experiment

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/INDEX.md

Retrieves MLflow experiment information.

```APIDOC
## GET /api/tracing_experiment

### Description
Retrieves information regarding the current MLflow experiment used for tracing.

### Method
GET

### Endpoint
/api/tracing_experiment
```

--------------------------------

### Build for production

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/client/README.md

Bundles the application into the build folder with production optimizations.

```bash
npm run build
```

--------------------------------

### Add UI Components

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/configuration.md

Use the shadcn CLI to add new components to the project from the client directory.

```bash
cd client
bunx shadcn@latest add <component-name>
```

--------------------------------

### GET /api/health

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/INDEX.md

Performs a system health check.

```APIDOC
## GET /api/health

### Description
Checks the health status of the application.

### Method
GET

### Endpoint
/api/health
```

--------------------------------

### Initialize FastAPI Application

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/api-reference-backend.md

The main entry point for the FastAPI application instance.

```python
app = FastAPI()
```

--------------------------------

### setup_mlflow_tracing()

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/api-reference-backend.md

Configures MLflow tracing and enables LangChain autologging for the application.

```APIDOC
## setup_mlflow_tracing()

### Description
Configures MLflow tracing by setting the tracking URI to Databricks and enabling LangChain autologging with specific logging configurations.

### Signature
`def setup_mlflow_tracing()`
```

--------------------------------

### POST /api/agent Error Response

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/endpoints.md

Example of a 500 error response structure.

```json
{
  "detail": "Error in agent execution: ..."
}
```

--------------------------------

### Build client application

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/errors.md

Commands to resolve build directory errors by navigating to the client directory and running the build script.

```bash
cd client
bun run build
```

--------------------------------

### Initialize Catalog Tools

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/api-reference-backend.md

Factory function to generate a list of Tool and StructuredTool instances for the agent.

```python
from server.agents.databricks_assistant.tools import create_catalog_tools

tools = create_catalog_tools()
# tools = [Tool(list_catalogs), StructuredTool(list_schemas), ...]
```

--------------------------------

### Configure React QueryClient

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/api-reference-frontend.md

Initializes the QueryClient and wraps the application with the QueryClientProvider.

```typescript
const queryClient = new QueryClient()

<QueryClientProvider client={queryClient}>
  <Chat />
</QueryClientProvider>
```

--------------------------------

### Configure Databricks Host

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/errors.md

Instructions for setting the DATABRICKS_HOST in the .env.local file.

```bash
# Set in .env.local
DATABRICKS_HOST="your-workspace.cloud.databricks.com"
```

--------------------------------

### Project directory structure

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/README.md

Overview of the project file organization for the FastAPI backend and React frontend.

```text
├── server/                 # FastAPI backend
│   ├── agents/            # Agent implementations
│   │   ├── databricks_assistant.py  # Main agent (customize this!)
│   │   └── model_serving.py         # Direct model endpoint calls
│   ├── app.py             # FastAPI routes and setup
│   └── tracing.py         # MLflow integration
├── client/                # React frontend
│   ├── src/components/    # UI components (shadcn/ui based)
│   ├── src/queries/       # API client and React Query hooks
│   └── build/             # Production build output
├── scripts/               # Build and utility scripts
├── *.sh                   # Development automation scripts
└── .env.local            # Environment configuration (create with ./setup.sh)
```

--------------------------------

### Check logs

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/errors.md

Instructions for accessing logs in development and production environments.

```bash
# uvicorn logs in console
# Check stdout/stderr for error messages
```

```bash
# View at https://{app-url}/logz
# Or query via dashboard
```

--------------------------------

### GET /api/health Request

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/endpoints.md

Standard HTTP request for the system health check endpoint.

```http
GET /api/health HTTP/1.1
Host: localhost:8000
```

--------------------------------

### Reset environment

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/errors.md

Commands to clear Python cache files and reinstall dependencies using uv.

```bash
# Clear Python cache
find . -type d -name __pycache__ -exec rm -r {} +
find . -name "*.pyc" -delete

# Reinstall dependencies
rm uv.lock
uv sync
```

--------------------------------

### Initialize React Query Client

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/configuration.md

Instantiate the QueryClient for managing server state in the React application.

```typescript
const queryClient = new QueryClient()
```

--------------------------------

### GET /api/tracing_experiment Response

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/endpoints.md

JSON response body containing the experiment ID and UI link.

```json
{
  "experiment_id": "123456789",
  "link": "https://workspace.databricks.com/ml/experiments/123456789?compareRunsMode=TRACES"
}
```

--------------------------------

### create_catalog_tools() -> List[Tool]

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/api-reference-backend.md

Factory function that creates all catalog exploration tools for the agent.

```APIDOC
## create_catalog_tools() -> List[Tool]

### Description
Factory function that creates all catalog exploration tools for the agent.

### Returns
- **List[Tool]** - List containing Tool and StructuredTool instances for list_catalogs, list_schemas, list_tables, and list_volumes.
```

--------------------------------

### GET /api/health Responses

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/endpoints.md

JSON response bodies for successful and failed health check requests.

```json
{
  "status": "healthy",
  "timestamp": 1693478400000,
  "mlflow_experiment_id": "123456789",
  "environment": "development"
}
```

```json
{
  "status": "unhealthy",
  "error": "MLflow connection failed",
  "timestamp": 1693478400000
}
```

--------------------------------

### Initialize Databricks WorkspaceClient

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/api-reference-backend.md

Initializes an authenticated client using environment variables for OAuth or token-based authentication.

```python
from server.agents.databricks_assistant.auth import get_workspace_client

w = get_workspace_client()
# Use the client to query workspace resources
catalogs = w.catalogs.list()
```

--------------------------------

### Configure .env.local Variables

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/README.md

Manual configuration of environment variables required for local development and agent monitoring.

```text
DATABRICKS_HOST="e2-dogfood.staging.cloud.databricks.com"
DATABRICKS_TOKEN="..."
DATABRICKS_CONFIG_PROFILE="..."

# Your LHA name here:
DATABRICKS_APP_NAME="nikhil-chatbot-fastapi"

# The agents monitoring destination. See external trace logging SDK for configuration of this param. If not defined, will not monitor the traces in mlflow.
DATABRICKS_AGENTS_MONITORING_DESTINATION="rag.external_agent_monitoring.nikhil_chatbot_fastapi"

# The source code path is only necessary for local dev:
LHA_SOURCE_CODE_PATH="/Workspace/Users/nikhil.thorat@databricks.com/nikhil-chatbot-fastapi"
```

--------------------------------

### GET /api/health

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/endpoints.md

Retrieves the current system health status, including environment details and MLflow experiment connectivity.

```APIDOC
## GET /api/health

### Description
System health check endpoint for monitoring.

### Method
GET

### Endpoint
/api/health

### Response
#### Success Response (200)
- **status** (string) - "healthy" or "unhealthy"
- **timestamp** (number) - Unix timestamp in milliseconds
- **mlflow_experiment_id** (string|null) - Active experiment ID
- **environment** (string) - "development" or "production"

#### Error Response (500)
- **status** (string) - "unhealthy"
- **error** (string) - Error message
- **timestamp** (number) - Unix timestamp in milliseconds

### Response Example
{
  "status": "healthy",
  "timestamp": 1693478400000,
  "mlflow_experiment_id": "123456789",
  "environment": "development"
}
```

--------------------------------

### Initialize ChatDatabricks LLM

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/configuration.md

Configures the LLM endpoint, token limits, and temperature settings within the databricks_agent function.

```python
llm = ChatDatabricks(
    endpoint='databricks-claude-sonnet-4',
    max_tokens=1000,
    temperature=0.1,
)
```

--------------------------------

### Configure Python Logging

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/configuration.md

Sets up standard logging to stdout for Databricks Apps monitoring.

```python
logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
    handlers=[
        logging.StreamHandler(),
    ],
)
```

--------------------------------

### Capture and View Server Logs

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/CLAUDE.md

Captures the current screen session output to a file and displays the last 30 lines for debugging.

```bash
screen -S lha-dev -X hardcopy /tmp/server_logs.txt && tail -30 /tmp/server_logs.txt
```

--------------------------------

### 502 Bad Gateway Fix Commands

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/errors.md

Commands to restart the development server.

```bash
# Ensure Vite dev server is running
./watch.sh
# Or manually
cd client && bun start
```

--------------------------------

### useQueryExperiment()

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/api-reference-frontend.md

React Query hook for fetching MLflow experiment information.

```APIDOC
## useQueryExperiment()

### Description
React Query hook for fetching MLflow experiment information.

### Signature
`export function useQueryExperiment(): UseQueryResult<ExperimentInfo>`

### Response Shape
- **experiment_id** (string | null)
- **link** (string | null)
```

--------------------------------

### Deploy to LHA

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/README.md

Execute the deployment script to deploy the application to the Lakehouse App environment.

```bash
./deploy.sh
```

--------------------------------

### Run test runner

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/client/README.md

Launches the test runner in interactive watch mode.

```bash
npm test
```

--------------------------------

### Logging and Debugging

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/README.md

Standard logging practices for backend and frontend environments to facilitate troubleshooting.

```python
logger.info(f"Message: {info}")
logger.error(f"Error: {error}")
# Appears in uvicorn console or Databricks Apps /logz
```

```typescript
console.log("Debug info:", data)
console.error("Error:", error)
// Appears in browser console
```

--------------------------------

### Backend Import Patterns

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/INDEX.md

Standard imports for backend services, including agents, model serving, and MLflow tracing utilities.

```python
from server.app import app
from server.agents.databricks_assistant import databricks_agent
from server.agents.model_serving import model_serving_endpoint
from server.agents.databricks_assistant.auth import get_workspace_client
from server.agents.databricks_assistant.tools import create_catalog_tools
from server.tracing import setup_mlflow_tracing, get_mlflow_experiment_id
```

--------------------------------

### list_schemas(catalog_name: str) -> str

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/api-reference-backend.md

Lists all schemas in a specific catalog.

```APIDOC
## list_schemas(catalog_name: str) -> str

### Description
Lists all schemas in a specific catalog.

### Parameters
- **catalog_name** (str) - Required - Name of the catalog to query

### Returns
- **str** - Formatted string listing schema names or error message
```

--------------------------------

### Configure MLflow Tracing

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/api-reference-backend.md

Enables MLflow tracing and LangChain autologging with specific logging configurations.

```python
from server.tracing import setup_mlflow_tracing

# Called automatically when app.py loads
setup_mlflow_tracing()
```

--------------------------------

### useQueryExperiment Hook Usage

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/api-reference-frontend.md

Fetch and display MLflow experiment information.

```typescript
const { data: experiment, isLoading: experimentIsLoading } = useQueryExperiment()

// Display experiment link
{!experimentIsLoading && experiment?.link && (
  <a href={experiment.link} target="_blank">
    View traces
  </a>
)}
```

--------------------------------

### list_tables(catalog_name: str, schema_name: str) -> str

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/api-reference-backend.md

Lists all tables in a specific schema.

```APIDOC
## list_tables(catalog_name: str, schema_name: str) -> str

### Description
Lists all tables in a specific schema.

### Parameters
- **catalog_name** (str) - Required - Name of the catalog
- **schema_name** (str) - Required - Name of the schema

### Returns
- **str** - Formatted string listing table names with types or error message
```

--------------------------------

### Handle Catalog Not Found Error

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/errors.md

Verify catalog existence by listing available catalogs before performing operations.

```python
response = databricks_agent(
    messages=[{"role": "user", "content": "List all catalogs"}]
)
# First list available catalogs to get valid names
```

--------------------------------

### List Tables in a Schema

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/api-reference-backend.md

Requires both catalog_name and schema_name to retrieve table information.

```python
from server.agents.databricks_assistant.tools import list_tables

result = list_tables("main", "default")
print(result)  # "Tables in main.default: users (TABLE), events (TABLE), ..."
```

--------------------------------

### Define Main App Components

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/modules.md

Exports for the primary application components including Chat and Feedback functionality.

```typescript
export function Chat(): JSX.Element
export function Feedback({ traceId }: { traceId: string }): JSX.Element
export default function App(): JSX.Element
```

--------------------------------

### Project Directory Structure

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/INDEX.md

Visual representation of the project's file organization.

```text
Output Directory Structure:
├── README.md                      [START HERE]
├── INDEX.md                       [This file]
├── api-reference-backend.md       [Backend API reference]
├── api-reference-frontend.md      [Frontend API reference]
├── configuration.md               [Settings and environment]
├── endpoints.md                   [HTTP endpoints with examples]
├── types.md                       [Data types and schemas]
├── errors.md                      [Error catalog]
└── modules.md                     [Architecture and organization]
```

--------------------------------

### Backend Absolute Imports

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/modules.md

Use absolute paths for importing core application components and utility functions from the server package.

```python
from server.app import app
from server.agents.databricks_assistant import databricks_agent
from server.agents.model_serving import model_serving_endpoint
from server.tracing import setup_mlflow_tracing, get_mlflow_experiment_id
```

--------------------------------

### Manual API testing with curl

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/README.md

Sends a POST request to the local agent endpoint to verify functionality.

```bash
curl -X POST http://localhost:8000/api/agent \
  -H "Content-Type: application/json" \
  -d '{"inputs": {"messages": [{"role": "user", "content": "list catalogs"}]}}'
```

--------------------------------

### Run unit tests with pytest

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/README.md

Executes unit tests for backend agents and utilities using uv.

```bash
uv run pytest server/agents/
```

--------------------------------

### get_workspace_client()

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/api-reference-backend.md

Initializes and returns an authenticated Databricks WorkspaceClient using environment-based credentials.

```APIDOC
## get_workspace_client()

### Description
Initializes a Databricks WorkspaceClient with proper authentication. Supports OAuth for production (Databricks Apps) and token-based authentication for development.

### Signature
`def get_workspace_client() -> WorkspaceClient`

### Returns
- **WorkspaceClient** - Authenticated Databricks SDK client
```

--------------------------------

### Run integration tests

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/README.md

Executes the integration test script for API endpoints.

```bash
./test_agent.sh
```

--------------------------------

### list_volumes(catalog_name: str, schema_name: str) -> str

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/api-reference-backend.md

Lists all volumes in a specific schema.

```APIDOC
## list_volumes(catalog_name: str, schema_name: str) -> str

### Description
Lists all volumes in a specific schema.

### Parameters
- **catalog_name** (str) - Required - Name of the catalog
- **schema_name** (str) - Required - Name of the schema

### Returns
- **str** - Formatted string listing volume names or error message
```

--------------------------------

### Frontend Import Patterns

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/INDEX.md

Standard imports for frontend components and query hooks used in the application.

```typescript
import { Chat } from "@/App"
import { useQueryAgent, useModelServing, useLogFeedback } from "@/queries/useQueryAgent"
import { useQueryExperiment } from "@/queries/useQueryTracing"
import { MessageContent } from "@/components/MessageContent"
import { ENDPOINTS } from "@/endpoints"
```

--------------------------------

### Define a Databricks Agent with MLflow Tracing

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/README.md

Uses the @mlflow.trace decorator to monitor LLM interactions and initializes a LangChain tool-calling agent for Unity Catalog exploration.

```python
@mlflow.trace(span_type='LLM')
def databricks_agent(messages):
  """A LangChain agent that can explore Databricks catalogs and answer questions."""
  # Initialize ChatDatabricks LLM
  llm = ChatDatabricks(
    endpoint='databricks-claude-sonnet-4',
    max_tokens=1000,
    temperature=0.1,
  )
  
  # Create catalog exploration tools
  tools = create_catalog_tools()  # list_catalogs, list_schemas, list_tables, list_volumes
  
  # Create tool-calling agent with custom prompt
  agent = create_tool_calling_agent(llm=llm, tools=tools, prompt=prompt)
  
  # Execute agent with AgentExecutor for tool orchestration
  agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)
  result = agent_executor.invoke({'input': user_query})
  
  return formatted_response  # Formatted for UI compatibility
```

--------------------------------

### list_catalogs(query: str = '') -> str

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/api-reference-backend.md

Lists all available catalogs in the Databricks workspace.

```APIDOC
## list_catalogs(query: str = '') -> str

### Description
Lists all available catalogs in the Databricks workspace.

### Parameters
- **query** (str) - Optional - Optional query parameter (not used in current implementation)

### Returns
- **str** - Formatted string listing catalog names or error message
```

--------------------------------

### List Schemas in a Catalog

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/api-reference-backend.md

Requires the catalog_name parameter to fetch schemas within a specific catalog.

```python
from server.agents.databricks_assistant.tools import list_schemas

result = list_schemas("main")
print(result)  # "Schemas in catalog \"main\": default, system, ..."
```

--------------------------------

### useQueryAgent()

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/api-reference-frontend.md

React Query mutation hook for calling the built-in Databricks agent.

```APIDOC
## useQueryAgent()

### Description
React Query mutation hook for calling the built-in Databricks agent.

### Signature
`export function useQueryAgent(): UseMutationResult<{ response: AgentResponse } & QueryAgentResponse, unknown, AgentRequestOptions>`
```

--------------------------------

### Define Agent Request and Response Schemas

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/api-reference-backend.md

Pydantic models for the agent request and response structures.

```python
class AgentRequestOptions(BaseModel):
    inputs: dict[str, Any]
```

```python
class QueryAgentResponse(BaseModel):
    response: Any
    trace_id: Optional[str]
```

--------------------------------

### Define LangChain Tool

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/types.md

Configures a simple LangChain tool for listing Databricks catalogs.

```python
Tool(
    name='list_catalogs',
    func=list_catalogs,
    description='List all available catalogs in the Databricks workspace.',
)
```

--------------------------------

### List Volumes in a Schema

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/api-reference-backend.md

Requires both catalog_name and schema_name to retrieve volume information.

```python
from server.agents.databricks_assistant.tools import list_volumes

result = list_volumes("main", "default")
print(result)  # "Volumes in main.default: data_lake, backups, ..."
```

--------------------------------

### Configure Ruff Formatter

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/configuration.md

Defines linting and formatting rules for Python code within the pyproject.toml file.

```toml
[tool.ruff]
line-length = 100
indent-width = 2
quote-style = "single"
target-version = "py312"
```

--------------------------------

### Workspace Client Error Message

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/errors.md

Displays the error message triggered when WorkspaceClient initialization fails during catalog listing.

```text
Error listing catalogs: ...
```

--------------------------------

### Eject project configuration

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/client/README.md

Permanently removes build dependencies and exposes configuration files. This is a one-way operation.

```bash
npm run eject
```

--------------------------------

### List Databricks Catalogs

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/api-reference-backend.md

Retrieves a list of all available catalogs in the workspace.

```python
from server.agents.databricks_assistant.tools import list_catalogs

result = list_catalogs()
print(result)  # "Available catalogs: main, samples, ..."
```

--------------------------------

### Configure CORS Middleware

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/configuration.md

Sets up CORS middleware for the application. Ensure allow_origins is restricted to specific domains in production environments.

```python
app.add_middleware(
    CORSMiddleware,
    allow_origins=['*'],
    allow_credentials=True,
    allow_methods=['*'],
    allow_headers=['*'],
)
```

--------------------------------

### Frontend Alias Imports

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/modules.md

Use the @ alias to import components and hooks from the project root, which is the recommended practice for frontend modules.

```typescript
import { Button } from "@/components/ui/button"
import { useQueryAgent } from "@/queries/useQueryAgent"
import { ENDPOINTS } from "@/endpoints"
```

--------------------------------

### 404 Not Found JSON Response

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/errors.md

Standard JSON structure for missing resources.

```json
{
  "detail": "Not Found"
}
```

--------------------------------

### Agent System Prompt

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/api-reference-backend.md

The system prompt used to define the agent's behavior and tool access.

```text
You are a helpful Databricks assistant that can explore Unity Catalog.

You have access to tools that let you:
- List all catalogs in the workspace
- List schemas within a specific catalog
- List tables within a specific schema
- List volumes within a specific schema

Use these tools to help users understand their data structure and find the information they need.
When listing items, present them in a clear, organized format.

Always be helpful and provide context about what you find. If a user asks about data,
start by exploring the catalog structure to understand what's available.
```

--------------------------------

### Restart server process

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/errors.md

Commands to terminate the existing uvicorn process and restart the server.

```bash
# Kill existing process
pkill -f "uvicorn server.app:app"

# Restart
python -m uvicorn server.app:app --reload --port 8000
```

--------------------------------

### Provide User Message

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/errors.md

Ensure the message list contains at least one entry with the role 'user' to avoid empty response errors.

```python
response = databricks_agent(
    messages=[
        {"role": "user", "content": "What catalogs exist?"}
    ]
)
```

--------------------------------

### Verify Uvicorn Process

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/CLAUDE.md

Use this command to check if the uvicorn server process is running.

```bash
ps aux | grep uvicorn
```

--------------------------------

### Agent Function Signature

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/api-reference-backend.md

The primary entry point for the Databricks assistant, decorated with MLflow tracing.

```python
@mlflow.trace(span_type='LLM')
def databricks_agent(messages: List[ChatCompletionMessageParam]) -> Dict[str, Any]
```

--------------------------------

### Agent Response Format

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/endpoints.md

The application uses the standard OpenAI chat completion format for agent responses.

```json
{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "Response text"
      }
    }
  ]
}
```

--------------------------------

### useLogFeedback()

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/api-reference-frontend.md

React Query mutation hook for logging user feedback to MLflow.

```APIDOC
## useLogFeedback()

### Description
React Query mutation hook for logging user feedback to MLflow.

### Signature
`export function useLogFeedback(): UseMutationResult<unknown, unknown, LogAssessmentRequestOptions>`
```

--------------------------------

### Define App Sidebar Component

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/modules.md

Sidebar component definition accepting navigation and experiment state props.

```typescript
export function AppSidebar({
  selectedAgent,
  setSelectedAgent,
  setMessages,
  experiment,
  experimentIsLoading,
  ...props
}: React.ComponentProps<typeof Sidebar> & {...})
```

--------------------------------

### Check Port Availability

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/CLAUDE.md

Verify if the server is listening on port 8000 to troubleshoot connection issues.

```bash
lsof -i :8000
```

--------------------------------

### Define Python version requirement

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/configuration.md

Specifies the minimum Python version required for the project.

```toml
requires-python = ">=3.12"
```

--------------------------------

### Define model_serving_endpoint return structure

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/api-reference-backend.md

The expected JSON structure of the OpenAI-compatible chat completion response.

```python
{
    "choices": [
        {
            "message": {"role": str, "content": str},
            "index": int,
            "finish_reason": str
        }
    ],
    "usage": {
        "prompt_tokens": int,
        "completion_tokens": int,
        "total_tokens": int
    },
    "model": str,
    "id": str,
    "object": "chat.completion",
    "created": int
}
```

--------------------------------

### POST /api/agent

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/endpoints.md

Executes the Databricks LangChain agent with catalog exploration tools.

```APIDOC
## POST /api/agent

### Description
Executes the Databricks LangChain agent with catalog exploration tools.

### Method
POST

### Endpoint
/api/agent

### Request Body
- **inputs** (object) - Required - Container for agent inputs
- **inputs.messages** (array) - Required - Message history
- **inputs.messages[].role** (string) - Required - "user", "assistant", or "system"
- **inputs.messages[].content** (string) - Required - Message text

### Request Example
{
  "inputs": {
    "messages": [
      {
        "role": "user",
        "content": "List all catalogs in my workspace"
      }
    ]
  }
}

### Response
#### Success Response (200)
- **response** (object) - Agent response in OpenAI format
- **response.choices** (array) - List of generated responses
- **response.choices[].message** (object) - Assistant message
- **response.choices[].message.role** (string) - "assistant"
- **response.choices[].message.content** (string) - Response text
- **trace_id** (string) - MLflow trace ID for monitoring

#### Response Example
{
  "response": {
    "choices": [
      {
        "message": {
          "role": "assistant",
          "content": "Available catalogs: main, samples, demo_catalog"
        }
      }
    ]
  },
  "trace_id": "trace_xyz123abc"
}
```

--------------------------------

### Define Log Assessment Schema and Response

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/api-reference-backend.md

Pydantic model for feedback logging and the expected success response.

```python
class LogAssessmentRequestOptions(BaseModel):
    trace_id: str
    assessment_name: str
    assessment_value: Union[str, int, float, bool]
```

```python
{"status": "success"}
```

--------------------------------

### Define ExperimentInfo model

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/types.md

Defines the structure for MLflow experiment metadata.

```python
from pydantic import BaseModel
from typing import Optional

class ExperimentInfo(BaseModel):
    experiment_id: Optional[str]
    link: Optional[str]
```

```json
{
    "experiment_id": "123456789",
    "link": "https://workspace.databricks.com/ml/experiments/123456789?compareRunsMode=TRACES"
}
```

--------------------------------

### Agent Error Handling

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/api-reference-backend.md

Implementation pattern for safely calling the agent and handling potential exceptions.

```python
try:
    response = databricks_agent(messages=[{"role": "user", "content": "test"}])
    if response and "choices" in response:
        message = response["choices"][0]["message"]["content"]
    else:
        print("Unexpected response format")
except Exception as e:
    print(f"Agent error: {e}")
```

--------------------------------

### POST /api/agent

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/INDEX.md

Queries the Databricks agent for responses.

```APIDOC
## POST /api/agent

### Description
Queries the Databricks agent to retrieve responses based on user input.

### Method
POST

### Endpoint
/api/agent
```

--------------------------------

### Define Databricks Apps Deployment Manifest

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/configuration.md

Specifies the application name and source code path for deployment via app.yaml.

```yaml
name: [DATABRICKS_APP_NAME]
source_code_path: [LHA_SOURCE_CODE_PATH]
```

--------------------------------

### Regenerate TypeScript Client

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/README.md

Run this command after modifying API signatures or Pydantic models in server/app.py to update the frontend client.

```bash
uv run python -m scripts.make_fastapi_client
```

--------------------------------

### Success Format

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/endpoints.md

The standard JSON structure returned upon successful operation completion.

```json
{
  "status": "success"
}
```

--------------------------------

### Configure MLflow Experiment ID

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/errors.md

Set the environment variable in .env.local to resolve experiment configuration errors.

```bash
# Set in .env.local
MLFLOW_EXPERIMENT_ID="123456789"
```

--------------------------------

### Feedback(traceId)

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/api-reference-frontend.md

Renders feedback buttons (thumbs up/down) for agent responses.

```APIDOC
## Feedback(traceId)

### Description
Renders feedback buttons (thumbs up/down) for agent responses.

### Signature
`export function Feedback({ traceId }: { traceId: string }): JSX.Element`

### Parameters
- **traceId** (string) - Required - MLflow trace ID from the agent response
```

--------------------------------

### Check health endpoint

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/errors.md

Use curl to verify the application health status.

```bash
curl http://localhost:8000/api/health

# Healthy: status = "healthy"
# Unhealthy: status = "unhealthy" with error details
```

--------------------------------

### Define Endpoint Configuration

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/modules.md

Interface and constant array for managing available model serving endpoints.

```typescript
interface Endpoint {
  displayName: string
  endpointName: string
}

export const ENDPOINTS: Endpoint[]
```

--------------------------------

### Debug MLflow Connection

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/errors.md

Verify the experiment ID and connectivity to the MLflow tracking server using the MlflowClient.

```python
from server.tracing import get_mlflow_experiment_id
import mlflow

exp_id = get_mlflow_experiment_id()
print(f"Experiment ID: {exp_id}")

# Try to get experiment
client = mlflow.tracking.MlflowClient()
try:
    exp = client.get_experiment(exp_id)
    print(f"Experiment found: {exp.name}")
except Exception as e:
    print(f"Experiment error: {e}")
```

--------------------------------

### Define EndpointRequestOptions model

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/types.md

Defines the structure for invoking model serving endpoints.

```python
from pydantic import BaseModel
from typing import List

class EndpointRequestOptions(BaseModel):
    endpoint_name: str
    messages: list[dict[str, str]]
```

```json
{
    "endpoint_name": "databricks-claude-sonnet-4",
    "messages": [
        {"role": "user", "content": "What is Databricks?"}
    ]
}
```

--------------------------------

### Module import error message

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/errors.md

Displays the error message for missing Python modules.

```text
ModuleNotFoundError: No module named 'databricks'
```

--------------------------------

### Define Navigation Documents Component

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/modules.md

Component for rendering agent selection and experiment status in the sidebar.

```typescript
export function NavDocuments({
  selectedAgent,
  setSelectedAgent,
  setMessages,
  experiment,
  experimentIsLoading,
})
```

--------------------------------

### Test API Endpoint with curl

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/CLAUDE.md

Use this command to send a POST request to the agent endpoint with a JSON payload.

```bash
curl -X POST http://localhost:8000/api/agent \
  -H "Content-Type: application/json" \
  -d '{"inputs": {"messages": [{"role": "user", "content": "What is Databricks?"}]}}'
```

--------------------------------

### list_catalogs()

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/modules.md

Lists catalogs based on a search query.

```APIDOC
## list_catalogs()

### Description
Lists catalogs matching the provided query.

### Signature
(query: str) -> str
```

--------------------------------

### Define Query Hooks

Source: https://github.com/databricks-solutions/agent-monitoring-demo-app/blob/main/_autodocs/modules.md

Interface definitions and mutation hooks for interacting with the backend API.

```typescript
interface AgentResponse
interface AgentRequestOptions (re-export from fastapi_client)
interface EndpointRequestOptions (re-export from fastapi_client)
interface LogAssessmentRequestOptions (re-export from fastapi_client)
interface QueryAgentResponse (re-export from fastapi_client)

export function useQueryAgent(): UseMutationResult<...>
export function useModelServing(): UseMutationResult<...>
export function useLogFeedback(): UseMutationResult<...>
```