VS Code + Kumo Agent

Overview

This guide walks you through setting up the KumoRFM SDK and Kumo Coding Agent for use with KumoRFM in a VS Code project workflow.

Unlike the notebook-based setup, this guide focuses on working with regular Python files, the VS Code integrated terminal, and coding-agent workflows that edit scripts, configuration, and project files directly.

This guide assumes minimal prior experience with VS Code, Python virtual environments, and coding agents. If you already have a preferred local setup, you can jump directly to the relevant sections.

Prerequisites

Make sure you have:

1. VS Code installed (Download)
2. Python installed at the system level
3. Access to a KumoRFM environment, including an API key and any required API URL
4. An OpenAI or Anthropic subscription (recommended if you plan to use the Kumo Coding Agent)
   • OpenAI Codex (Subscribe)
   • Anthropic Claude Code (Subscribe)
5. Homebrew (macOS package manager) (Install)
6. GitHub CLI installed and authenticated (required for installing coding-agent skills and some GitHub-powered workflows)

🖥 Terminal

$
brew install gh
$
gh auth status
$
gh auth login

Part 1: Setup for VS Code + KumoRFM SDK

Step 1: Create or Open a Project Folder

Start with a normal VS Code project folder rather than a notebook file.

1. Open VS Code
2. Choose File -> Open Folder
3. Create or open a project directory such as kumo-demo

A simple starter structure works well:

kumo-demo/
├── .venv/
├── data/
├── scripts/
├── models/
└── README.md

Step 2: Create a Python Virtual Environment

Open the VS Code integrated terminal:

• Use Terminal -> New Terminal
• Or press Ctrl + backtick

Then create a virtual environment inside the project:

🖥 Terminal

$
python3 -m venv .venv
$
source .venv/bin/activate

If VS Code prompts you to select a Python interpreter, choose the one from your local .venv directory.

You can also manually choose it:

1. Open the Command Palette (Cmd + Shift + P)
2. Search for Python: Select Interpreter
3. Select the interpreter inside .venv

Step 3: Install the KumoRFM SDK

Install the SDK inside the active virtual environment:

🖥 Terminal

$
pip install kumoai

Verify the installation:

🖥 Terminal

$
python -c "import kumoai.rfm as rfm; print('Kumo SDK loaded successfully')"

Step 4: Authenticate the KumoRFM SDK

You need an API key before you can make calls to KumoRFM.

There are two common approaches:

• use interactive authentication
• set KUMO_API_KEY manually

Interactive authentication

Create a small setup script such as scripts/setup_kumo.py:

1
import os
2
import kumoai.rfm as rfm
3
4
if not os.environ.get("KUMO_API_KEY"):
5
    rfm.authenticate()
6
7
rfm.init(api_key=os.environ.get("KUMO_API_KEY"))
8
print("Kumo SDK initialized successfully")

Run it from the integrated terminal:

🖥 Terminal

$
python scripts/setup_kumo.py

Manual authentication

1
import os
2
import kumoai.rfm as rfm
3
4
os.environ["KUMO_API_KEY"] = "YOUR_API_KEY_HERE"
5
rfm.init(api_key=os.environ.get("KUMO_API_KEY"))

Step 5: Optional Dependencies

Install Graphviz if you want to visualize graphs from a script-based workflow.

Install the system dependency:

🖥 Terminal

$
brew install graphviz

Install the Python package:

🖥 Terminal

$
pip install graphviz

Test that a simple graph renders:

1
from graphviz import Digraph
2
3
g = Digraph()
4
g.edge("Users", "Orders")
5
g

Part 2: Using the VS Code CLI Workflow

The VS Code integrated terminal is one of the easiest ways to work with the KumoRFM SDK in an editor-based workflow.

Instead of switching between separate apps, you can keep all of the following in one place:

• your Python scripts
• your terminal commands
• your coding agent chat panel
• project files such as README.md, config files, and sample queries

Common tasks you can run directly from the integrated terminal include:

🖥 Terminal

$
source .venv/bin/activate
$
python scripts/setup_kumo.py
$
python scripts/run_prediction.py

This workflow works especially well when:

• you want reproducible scripts instead of interactive notebook cells
• you want Codex or Claude Code to edit source files directly
• you want to commit your work to Git as normal Python code
• you want to run the same setup locally, in CI, or on another machine

Part 3: Add a Coding Agent (Optional)

Choose one of the following to add an AI coding agent to your workflow:

$
cd your-project
$
git clone https://github.com/kumo-ai/kumo-coding-agent.git kumo-coding-agent

$skill-installer install https://github.com/kumo-ai/kumo-coding-agent

Create a scripts/run_prediction.py file that loads the RelBench F1 dataset,
builds a Kumo graph, and predicts whether each driver will finish in the
top 3 in the next race.

$
pip install --upgrade kumoai

$
cd kumo-coding-agent && git pull

Step 4: Verify the Setup

Create a minimal script such as scripts/run_prediction.py:

1
import os
2
import kumoai.rfm as rfm
3
4
if not os.environ.get("KUMO_API_KEY"):
5
    raise RuntimeError("KUMO_API_KEY is not set")
6
7
rfm.init(api_key=os.environ.get("KUMO_API_KEY"))
8
print("Kumo SDK initialized successfully")

Run it:

🖥 Terminal

$
python scripts/run_prediction.py

Run Your First Example

Once the SDK and coding agent are set up, ask the agent to help you scaffold a simple project-based workflow.

Examples:

• create a LocalGraph from local data files
• draft a first predictive query in Python
• create a reusable script instead of a one-off notebook
• add logging, comments, and lightweight validation

If you prefer to start from a guided SDK example first, continue with:

• SDK Getting Started
• Coding Agent Quick Start

Troubleshooting

VS Code cannot find the interpreter

• Re-run Python: Select Interpreter
• Make sure .venv exists in the project folder
• Restart VS Code after creating the environment

The SDK will not import

🖥 Terminal

$
source .venv/bin/activate
$
pip install kumoai

Then rerun your script.

The API key is missing

Export the API key before running a script:

🖥 Terminal

$
export KUMO_API_KEY="YOUR_API_KEY_HERE"

Then rerun:

$
python scripts/run_prediction.py

The coding agent edited files, but the workflow still fails

• Re-run the script from the integrated terminal
• Check that the active terminal is using .venv
• Review the modified files before rerunning commands
• Ask the agent to fix the error using the exact terminal output

Next Steps

• Setup for SDK fundamentals
• Make Predictions for PQL query reference
• Kumo Coding Agent for agent source and skills