Quickstart - Maitai

Getting started

The fastest path is to authenticate the CLI, then ask your coding agent to do the integration.

Install the CLI
Log in
Prompt your agent

Install the CLI

pip install maitai-cli

Log in

maitai login

This opens a browser to authenticate, then saves an API key to ~/.maitai/config so the CLI (and agent tooling that uses it) can call the Maitai API. For CI or headless environments, create a key in the Portal under Settings > API Keys, then run:

maitai login --api-key YOUR_MAITAI_API_KEY

See Authentication and the CLI Reference for other options.

Prompt your agent

In Cursor, Claude Code, Codex, or whichever agent you use, ask it to integrate Maitai for you. Pick the prompt that matches what you want: Switch OpenAI calls to Maitai

Switch my OpenAI client calls over to use Maitai client

Add traces to agent runs

Implement Maitai traces on my agent runs

Build and wire a workflow

Build a Maitai workflow for xyz and wire it into my code

Your agent can use the CLI and docs to install the SDK, update your client calls, create Applications/Intents/Workflows, and verify traffic in the Portal.

See it in the Portal

Once your agent finishes and your app makes a request (or a workflow/agent run), open portal.trymaitai.com to inspect the new Application/Intent resources, requests, and sessions.

Prefer to do it yourself?

You can also install the SDK and send a chat completion manually:

pip install maitai-python

npm install maitai

export MAITAI_API_KEY="<YOUR_MAITAI_API_KEY>"

import maitai

maitai_client = maitai.MaitaiAsync()

messages = [
    {"role": "system", "content": "You are a helpful ordering assistant..."},
    {"role": "user", "content": "Generate a response to the customer..."},
]

response = await maitai_client.chat.completions.create(
    messages=messages,
    model="llama3-70b-8192",  # Optional: omit to use your Portal config
    application="YOUR_APPLICATION",  # Groups traffic in the Portal (auto-created on first use)
    intent="CONVERSATION",  # Also called action_type (auto-created on first use)
    session_id="YOUR_SESSION_ID",  # Recommended for grouping requests into sessions
    metadata={},  # Optional: custom tags for filtering/debugging
)

import maitai

messages = [
    {"role": "system", "content": "You are a helpful ordering assistant..."},
    {"role": "user", "content": "Generate a response to the customer..."},
]

maitai_client = maitai.Maitai()

response = maitai_client.chat.completions.create(
    messages=messages,
    model="llama3-70b-8192",  # Optional: omit to use your Portal config
    application="YOUR_APPLICATION",  # Groups traffic in the Portal (auto-created on first use)
    intent="CONVERSATION",  # Also called action_type (auto-created on first use)
    session_id="YOUR_SESSION_ID",  # Recommended for grouping requests into sessions
    metadata={},  # Optional: custom tags for filtering/debugging
)

import Maitai from "maitai";

const maitai = new Maitai();

const messages = [
    {role: "system", content: "You are a helpful ordering assistant..."},
    {role: "user", content: "Generate a response to the customer..."},
];

const response = await maitai.chat.completions.create({
    messages: messages,
    model: "llama3-70b-8192",  // Optional: omit to use your Portal config
    application: "YOUR_APPLICATION", // Groups traffic in the Portal (auto-created on first use)
    intent: "CONVERSATION", // Also called action_type (auto-created on first use)
    session_id: "YOUR_SESSION_ID", // Recommended for grouping requests into sessions
    metadata: {}, // Optional: custom tags for filtering/debugging
});

session_id is optional (the SDK will generate one if you omit it), but you’ll get the best Portal experience if you provide a stable session id per user/session.

Full chat reference: Chat. Already on an OpenAI-compatible SDK? See Base URL integration.

Next Steps

Tune configuration in the Portal: Configuration
Add domain context to improve responses: upload application context entries in the Portal (Application > Edit > Add Context Entry)
Build a regression suite: Test Sets
Optional: set up alerts in the Portal (Settings > Notifications)

​Getting started

​Install the CLI

​Log in

​Prompt your agent

​See it in the Portal

​Prefer to do it yourself?

​Next Steps

Getting started

Install the CLI

Log in

Prompt your agent

See it in the Portal

Prefer to do it yourself?

Next Steps