Pearl Vet Phone Agent

AI-powered veterinary phone agent built with React, OpenAI GPT-4o, and Pearl MCP. Routes pet owners to real veterinarians via chat and phone callbacks.

Architecture

flowchart TD
    A[User — Pet Owner] -->|types message| B[React Chat UI]
    B -->|full conversation| C[GPT-4o Agent — ai-agent.ts]
    C -->|respond directly| B
    C -->|call a tool| D[Pearl MCP Client — pearl-mcp-client.ts]
    D -->|POST /mcp| E[Pearl MCP Server]
    E -->|tool result| D
    D -->|answer + expert info| C

Loading

The user chats with a friendly veterinary assistant. GPT-4o receives every message and decides whether to respond from its own knowledge or route the question to a Pearl expert via MCP tool calls. When the situation warrants it, the agent offers to arrange a phone callback with a real veterinarian.

Prerequisites

• Node.js 18+
• An OpenAI API key
• Access to a Pearl MCP server (and its API key)

Setup

1. Clone the repo and install dependencies:

git clone <repo-url>
cd pearl-vet-phone-agent
npm install

2. Copy the environment template and fill in your keys:

cp .env.example .env

Edit .env with your actual values:

VITE_OPENAI_API_KEY=your-openai-api-key
VITE_MCP_API_KEY=your-pearl-mcp-api-key
VITE_PEARL_MCP_URL=https://mcp.pearl.com/mcp

3. Start the dev server:

npm run dev

How It Works

1. The user describes their pet's issue in the chat interface.
2. GPT-4o asks clarifying questions and then offers a phone callback.
3. If the user provides a phone number, it's passed along in subsequent Pearl tool calls so a vet can call them back.
4. The agent routes the question to the appropriate Pearl MCP tool (askPearlExpert, askPearlAi, askExpert, or verifyAnswer) depending on complexity and urgency.
5. Pearl's response is streamed back to the chat — including the assigned expert's name and credentials.

Tech Stack

• React 18 + TypeScript — UI framework
• Vite — build tooling and dev server
• Tailwind CSS — styling
• OpenAI GPT-4o — conversation routing and triage
• Pearl MCP — communication with Pearl's expert platform via MCP SDK