Cortex Tool Integration Guide

A simple guide to connect your tool with Cortex.

Visit Cortex on https://cortex.lyzr.app

Step 1: Create Your Tool in Platform

1.1 Go to Developer Settings

Open Settings → Developer Settings

1.2 Click "Register Tool"

1.3 Fill the Form

Field	What to Enter
Display Name	Your tool name (e.g., Meeting Intelligence)
Tool ID	Auto-generated (e.g., meeting-intelligence)
Description	What your tool does

1.4 Select What Your Tool Can Do

Check the boxes:

• ✅ Push Documents - Send data to Cortex
• ✅ Query - Search the knowledge graph
• ✅ Get Context - Get user info

1.5 Select Document Types

Pick what your tool will send:

• meeting_transcript
• voice_note
• document
• note

1.6 Click Register

You'll see a popup with:

• Your API Key (masked)
• Download buttons

1.7 Download Your Files

Click both buttons:

• cortex.yaml - Your config file
• .env.cortex - Your API key

⚠️ Important: Save these files! You won't see the API key again.

---

Step 2: Setup Your Project

2.1 Create Project Folder

my-tool/
├── cortex.yaml      ← Put downloaded file here
├── .env             ← Rename .env.cortex to .env
└── app.py           ← Your code

2.2 Your cortex.yaml

name: meeting-intelligence
display_name: Meeting Intelligence
description: AI-powered meeting transcription
version: 1.0.0

documents:
  - meeting_transcript
  - voice_note

2.3 Your .env

CORTEX_ENABLED=true
CORTEX_API_URL=http://localhost:5000/api/tools
CORTEX_API_KEY=ctx_meeting-intelligence_abc123xyz...
CORTEX_TOOL_ID=meeting-intelligence

---

Step 3: Connect with Python

3.1 Install

pip install requests python-dotenv

3.2 Basic Setup

import os
import requests
from dotenv import load_dotenv

# Load your .env file
load_dotenv()

# Your credentials
API_URL = os.getenv("CORTEX_API_URL")
API_KEY = os.getenv("CORTEX_API_KEY")
TOOL_ID = os.getenv("CORTEX_TOOL_ID")

# Headers for all requests
headers = {
    "X-Cortex-Tool-ID": TOOL_ID,
    "X-API-Key": API_KEY,
    "Content-Type": "application/json"
}

3.3 Push a Document

# Send a meeting transcript to Cortex
data = {
    "external_id": "meeting_001",
    "document_type": "meeting_transcript",
    "content": "John: Let's discuss the roadmap. Sarah: I think we should...",
    "name": "Team Standup",
    "access_scope": "global"
}

response = requests.post(
    f"{API_URL}/documents",
    headers=headers,
    json=data
)

print(response.json())

Output:

{
  "id": "abc-123-def",
  "status": "indexed",
  "external_id": "meeting_001"
}

3.4 Search the Knowledge Graph

# Ask a question
data = {
    "query": "What did we discuss in the standup?",
    "max_results": 5
}

response = requests.post(
    f"{API_URL}/query",
    headers=headers,
    json=data
)

print(response.json())

Output:

{
  "answer": "In the standup, John discussed the roadmap and Sarah shared her thoughts...",
  "sources": [
    {
      "name": "Team Standup",
      "type": "meeting_transcript"
    }
  ]
}

3.5 Get User Info

# Get user's teams and permissions
email = "john@company.com"

response = requests.get(
    f"{API_URL}/context/{email}",
    headers=headers
)

print(response.json())

Output:

{
  "id": "user-123",
  "email": "john@company.com",
  "name": "John Doe",
  "teams": [{"id": "team-1", "name": "Engineering"}],
  "role": "member"
}

---

Step 4: Connect with TypeScript

4.1 Install

npm install axios dotenv

4.2 Basic Setup

import axios from 'axios';
import dotenv from 'dotenv';

dotenv.config();

const client = axios.create({
  baseURL: process.env.CORTEX_API_URL,
  headers: {
    'X-Cortex-Tool-ID': process.env.CORTEX_TOOL_ID,
    'X-API-Key': process.env.CORTEX_API_KEY,
  },
});

4.3 Push a Document

const response = await client.post('/documents', {
  external_id: 'meeting_001',
  document_type: 'meeting_transcript',
  content: 'Meeting transcript content...',
  name: 'Team Standup',
  access_scope: 'global',
});

console.log(response.data);
// { id: "abc-123", status: "indexed", external_id: "meeting_001" }

4.4 Search

const response = await client.post('/query', {
  query: 'What were the action items?',
  max_results: 5,
});

console.log(response.data.answer);
// "The action items were..."

---

Step 5: Using the CLI (Optional)

The CLI helps you create new tool projects quickly.

5.1 Install CLI

cd sdk/cli
npm install
npm run build
npm link

5.2 Create New Project

mkdir my-new-tool
cd my-new-tool
cortex init

Output:

  Cortex Tool Initializer

? Tool name (lowercase, hyphens only): my-new-tool
? Display name: My New Tool
? Description: A tool that does amazing things
? Document types (comma-separated): meeting_transcript,voice_note

✔ Created cortex.yaml
  Created backend/
  Created frontend/
  Created .env.example

  Tool initialized successfully!

  Next steps:
  1. Edit cortex.yaml with your tool configuration
  2. Implement your backend and frontend
  3. Run `cortex validate` to check your manifest
  4. Run `cortex dev` to start local development

5.3 Validate Your Config

cortex validate

Output:

  Validating cortex.yaml...

  ✓ Manifest is valid!

  Summary:
    Name: my-new-tool
    Display Name: My New Tool
    Version: 1.0.0
    Documents: meeting_transcript, voice_note
    Backend Port: 8000
    Frontend Port: 3000

5.4 Generated Files

my-new-tool/
├── cortex.yaml
├── .env.example
├── backend/
└── frontend/

cortex.yaml:

name: my-new-tool
display_name: My New Tool
description: A tool that does amazing things
version: 1.0.0

documents:
  - meeting_transcript
  - voice_note

ui:
  embed_path: /
  menu:
    label: My New Tool
    position: tools

build:
  backend:
    dockerfile: backend/Dockerfile
    port: 8000
    health_check: /health
  frontend:
    dockerfile: frontend/Dockerfile
    port: 3000

secrets: []

---

Quick Reference

API Endpoints

What	Method	URL
Push document	POST	/api/tools/documents
Search	POST	/api/tools/query
Get user	GET	/api/tools/context/{email}

Required Headers

X-Cortex-Tool-ID: your-tool-id
X-API-Key: ctx_your-tool-id_xxxxx
Content-Type: application/json

Document Types

• meeting_transcript - Meeting notes
• voice_note - Voice memos
• document - General docs
• note - Text notes
• email - Emails
• task - Tasks

---