Run Locally

Run Locally

Start Development Servers

Start both agent and UI servers:

npm run dev

This starts:

• Agent server on port 5001 (provides /invocations)
• UI server on port 3001 (provides /api/chat and React frontend)
• Hot-reload enabled for both

Or start individually:

# Terminal 1: Agent only
npm run dev:agent

# Terminal 2: UI only
npm run dev:ui

Servers will be available at:

• Agent: http://localhost:5001/invocations
• UI frontend: http://localhost:3000
• UI backend: http://localhost:3001/api/chat

Start Production Build

# Build first
npm run build

# Then start
npm start

Testing the Agent

1. Test /invocations Endpoint (Responses API)

curl -X POST http://localhost:5001/invocations \
  -H "Content-Type: application/json" \
  -d '{
    "input": [
      {"role": "user", "content": "What is the weather in San Francisco?"}
    ],
    "stream": true
  }'

Expected response (Server-Sent Events):

data: {"type":"response.output_item.added","item":{"type":"message",...}}
data: {"type":"response.output_text.delta","delta":"The weather..."}
...
data: {"type":"response.completed"}
data: [DONE]

2. Test /api/chat Endpoint (useChat Format)

Requires both servers running (npm run dev)

curl -X POST http://localhost:3001/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "role": "user",
      "parts": [{"type": "text", "text": "Calculate 15 * 32"}]
    },
    "selectedChatModel": "chat-model"
  }'

Expected response (AI SDK format):

data: {"type":"text-delta","delta":"Let me calculate..."}
data: {"type":"tool-call",...}
...
data: [DONE]

3. Test UI Frontend

Open browser: http://localhost:3000

Should see chat interface with:

• Message input
• Send button
• Chat history
• Tool call indicators

Environment Variables

Make sure .env is configured (see quickstart skill):

# Required
DATABRICKS_HOST=https://your-workspace.cloud.databricks.com
DATABRICKS_TOKEN=dapi...
DATABRICKS_MODEL=databricks-claude-sonnet-4-5
MLFLOW_TRACKING_URI=databricks
MLFLOW_EXPERIMENT_ID=123

# Optional
PORT=8000
TEMPERATURE=0.1
MAX_TOKENS=2000
ENABLE_SQL_MCP=false

View MLflow Traces

See MLflow Tracing Guide for viewing traces in your workspace.

Development Tips

Watch Mode

npm run dev uses tsx watch which:

• Auto-restarts on file changes
• Preserves type checking
• Fast compilation

TypeScript Compilation

Manual compilation:

npm run build

Output in dist/ directory.

Debugging

Add console.log() statements and view in terminal:

console.log("Tool invoked:", toolName);
console.log("Result:", result);

For deeper debugging, use VS Code debugger:

1. Set breakpoints in .ts files
2. Press F5 or use Run > Start Debugging
3. Select "Node.js" as runtime

Testing Tools

Test Basic Tools

# Weather tool
curl -X POST http://localhost:5001/invocations \
  -H "Content-Type: application/json" \
  -d '{"input": [{"role": "user", "content": "What is the weather in Tokyo?"}], "stream": false}'

# Calculator tool
curl -X POST http://localhost:5001/invocations \
  -H "Content-Type: application/json" \
  -d '{"input": [{"role": "user", "content": "Calculate 123 * 456"}], "stream": false}'

# Time tool
curl -X POST http://localhost:5001/invocations \
  -H "Content-Type: application/json" \
  -d '{"input": [{"role": "user", "content": "What time is it in London?"}], "stream": false}'

Test MCP Tools

MCP tools are configured in src/mcp-servers.ts. See add-tools skill for details.

Example test:

curl -X POST http://localhost:5001/invocations \
  -H "Content-Type: application/json" \
  -d '{"input": [{"role": "user", "content": "Query my database"}], "stream": false}'

Running Tests

Unit Tests (No Server Required)

Pure tests with no dependencies:

npm run test:unit

Runs tests/agent.test.ts - tests agent initialization, tool usage, multi-turn conversations.

Integration Tests (Requires Local Servers)

Tests that need local servers running:

# Terminal 1: Start servers
npm run dev

# Terminal 2: Run tests
npm run test:integration

Tests: /invocations, /api/chat, streaming, error handling.

E2E Tests (Requires Deployed App)

Tests that need a deployed Databricks app:

# 1. Deploy app
npm run build
databricks bundle deploy --profile your-profile
databricks bundle run agent_langchain_ts --profile your-profile

# 2. Set APP_URL
export APP_URL=$(databricks apps get agent-lc-ts-dev --profile your-profile --output json | jq -r '.url')

# 3. Run E2E tests
npm run test:e2e

See tests/e2e/README.md for detailed setup instructions.

All Non-E2E Tests

npm run test:all

Runs unit + integration tests (not E2E).

Troubleshooting

See Troubleshooting Guide for common issues.

Quick Fixes

Port already in use:

lsof -ti:5001 | xargs kill -9  # Agent
lsof -ti:3001 | xargs kill -9  # UI backend
lsof -ti:3000 | xargs kill -9  # UI frontend

Authentication failed:

Verify credentials:

databricks auth profiles
databricks auth env --host
databricks auth env --token

Re-run quickstart:

npm run quickstart

"Module not found"

Install dependencies:

npm install

"MLflow traces not appearing"

Check:

1. MLFLOW_EXPERIMENT_ID is set in .env
2. Experiment exists: databricks experiments get --experiment-id $MLFLOW_EXPERIMENT_ID
3. Server logs show "MLflow tracing initialized"

Create experiment if missing:

databricks experiments create \
  --experiment-name "/Users/$(databricks current-user me --output json | jq -r .userName)/agent-langchain-ts"

"Tool not working"

Check tool invocation in response intermediateSteps:

curl -s http://localhost:8000/api/chat \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "What is 2+2?"}]}' | jq '.intermediateSteps'

Should show tool name and observation.

Performance Monitoring

Monitor server logs for:

• Request timing
• Tool execution time
• Error rates
• Token usage

Add logging in src/server.ts:

console.log(`Request completed in ${duration}ms`);