For Local Machine

Prerequisites

Ensure the following are installed and configured on your system:

1. Node.js (v16 or higher) Download Node.js

2. npm (Node Package Manager) Comes bundled with Node.js.

3. Firebase Service Account Key Required for local Firestore authentication.

4. OpenAI API Key Obtain an API key from OpenAI.

---

Dependencies

The project utilizes the following dependencies:

Dependency	Version	Purpose
express	^4.21.2	Web framework for building API endpoints.
cors	^2.8.5	Middleware to handle Cross-Origin Resource Sharing (CORS).
firebase-admin	^13.0.2	Firebase Admin SDK for Firestore integration.
dotenv	^16.4.7	Secure management of environment variables.
openai	^4.77.3	Integration with OpenAI’s GPT models for AI interactions.

Install all dependencies:

npm install

Setup

1. Clone the Repository

git clone https://github.com/qudeai/qudeframework-api.git
cd qudeframework-api

2. Install Dependencies

npm install

3. Configure Environment Variables

• Create a .env file in the root directory:

touch .env

• Add the following variables to your .env file:

OPENAI_API_KEY=your-openai-api-key
PORT=3000

4. Add Firebase Credentials

• Copy the sample file and replace placeholders with your Firebase credentials:

cp serviceAccountKey.example.json serviceAccountKey.json

• Edit: serviceAccountKey.json

{
  "type": "service_account",
  "project_id": "your-project-id",
  "private_key_id": "your-private-key-id",
  "private_key": "-----BEGIN PRIVATE KEY-----\\nYOUR_PRIVATE_KEY\\n-----END PRIVATE KEY-----\\n",
  "client_email": "[e-mail]",
  "client_id": "your-client-id",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/[e-mail]"
}

Running the API Locally

Start the server:

node index.js

Access the API locally:

http://localhost:3000

API Endpoints

1. Fetch Agent Details

• Retrieve metadata for an AI agent.

GET /api/agent/:name

• Request Example:

curl http://localhost:{your_port}/api/agent/Aura

• Response Example:

{
  "name": "Aura",
  "description": "An intelligent agent designed to assist with tasks.",
  "createdAt": "2025-01-01T12:00:00Z"
}

2. Interact with an Agent (GET Method)

• Interact with an AI agent using a query parameter.

GET /api/agent/:name/interact?message=YourMessage

• Request Example:

curl "http://localhost:3000/api/agent/Aura/interact?message=Hello!"

• Response Example:

{
  "agent": "Aura",
  "reply": "Hello! How can I assist you today?"
}

3. Interact with an Agent (POST Method)

• Interact with an AI agent using a JSON payload.

POST /api/agent/:name/interact

• Request Example:

curl -X POST "http://localhost:3000/api/agent/Aura/interact" \
-H "Content-Type: application/json" \
-d '{"message": "What is the weather today?"}'

• Response Example:

{
  "agent": "Aura",
  "reply": "I'm sorry, I cannot provide real-time weather updates."
}

Example Usage in Node.js

• Here’s how you can interact with the API programmatically:

const fetch = require("node-fetch");

async function interactWithAgent(agentName, message) {
  const response = await fetch(`http://localhost:3000/api/agent/${agentName}/interact`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ message }),
  });

  if (!response.ok) {
    console.error("Failed to interact with the agent:", response.statusText);
    return;
  }

  const data = await response.json();
  console.log("Agent Reply:", data.reply);
}

interactWithAgent("Aura", "Hello there!");