Skip to main content
ODAI requires Python 3.11+. Make sure you have a compatible version installed before proceeding.
1

Clone the repository

git clone https://github.com/sibblegp/ODAI.git
cd ODAI
2

Create and activate a virtual environment

python -m venv venv
source venv/bin/activate
3

Install dependencies

Install production and testing dependencies:
pip install -r requirements.txt
pip install -r test_requirements.txt
The production requirements.txt contains 173 packages including FastAPI, the OpenAI Agents SDK, Firebase Admin, and all third-party service SDKs.
4

Configure environment variables

Create a .env file in the project root. At minimum you need:
.env
# Required: set local development mode
LOCAL=true

# Required: your OpenAI API key
OPENAI_API_KEY=sk-...

# Required: Firebase service account JSON (as a single-line string)
FIREBASE_SERVICE_ACCOUNT_KEY='{"type":"service_account","project_id":"...","private_key_id":"...","private_key":"-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n","client_email":"...","client_id":"...","auth_uri":"https://accounts.google.com/o/oauth2/auth","token_uri":"https://oauth2.googleapis.com/token"}'

# Optional: add keys for the services you want to enable
PLAID_CLIENT_ID=your_plaid_client_id
PLAID_SECRET=your_plaid_secret
TWILIO_ACCOUNT_SID=your_twilio_sid
TWILIO_AUTH_TOKEN=your_twilio_token
SERPAPI_API_KEY=your_serpapi_key
With LOCAL=true, ODAI reads all secrets from the .env file. In production (Google App Engine), secrets are fetched from Google Secret Manager and LOCAL is not set.
To use Google integrations (Gmail, Calendar, Docs) locally, you also need a credentials.json file from the Google Cloud Console placed in the project root. In production, Google OAuth credentials are stored in Google Secret Manager under the key google_oauth_credentials.
Never commit your .env file. It is already listed in .gitignore. Use Google Secret Manager for production credentials.
5

Start the server

uvicorn api:APP --reload --host 0.0.0.0 --port 8080
The API is now available at http://localhost:8080. Visit http://localhost:8080/test to confirm the server is running:
{
  "status": "success",
  "service": "ODAI API",
  "environment": "development",
  "connections": 0
}
6

Connect over WebSocket

ODAI’s primary interface is a WebSocket endpoint. Obtain a Firebase ID token for your user, then connect:
WSS /chats/{chat_id}?token={auth_token}
Here is a minimal working example in Python:
import asyncio
import json
import websockets

CHAT_ID = "my-chat-session-1"
AUTH_TOKEN = "your-firebase-id-token"

async def chat():
    uri = f"ws://localhost:8080/chats/{CHAT_ID}?token={AUTH_TOKEN}"

    async with websockets.connect(uri) as ws:
        # Send a message
        await ws.send(json.dumps({
            "message": "What is the weather like in San Francisco?",
            "thread_id": "thread-abc123"
        }))

        # Stream the response events
        async for raw in ws:
            event = json.loads(raw)
            event_type = event.get("type")

            if event_type == "raw_response_event":
                # Character-by-character text delta
                print(event["delta"], end="", flush=True)
            elif event_type == "tool_call":
                print(f"\n[Tool] {event['description']}")
            elif event_type == "agent_updated":
                print(f"\n[Agent] Handed off to {event['new_agent']}")
            elif event_type == "end_of_stream":
                print("\n[Done]")
                break

asyncio.run(chat())
The server streams several event types as the agent processes your request:
Event typeDescription
raw_response_eventText delta — append delta to build the full response
tool_callThe orchestrator is invoking a tool; description is a human-readable status
agent_updatedThe orchestrator handed off to a specialist agent
tool_outputResult from a tool call (when display_response is true)
llm_responseCompleted text response from an agent turn
suggested_promptsFollow-up prompt suggestions
end_of_streamSignals the response is complete

​
Next steps

Architecture

Understand the layered system design and component relationships.

WebSocket API

Full reference for the WebSocket protocol and event schema.

Integrations

Browse the 35+ services ODAI can connect to.

Running tests

Run the 700+ test suite with the custom test runner.

Build docs developers (and LLMs) love

Get started for freeTalk to us