How to Integrate AI Agents with Monday.com

pip install requests langchain langchain-openai python-dotenv

export MONDAY_API_TOKEN="your-monday-api-token"

import os
import requests

MONDAY_API_URL = "https://api.monday.com/v2"
HEADERS = {
    "Authorization": os.getenv("MONDAY_API_TOKEN"),
    "Content-Type": "application/json"
}

def run_query(query: str, variables: dict = None) -> dict:
    """Execute a Monday.com GraphQL query."""
    payload = {"query": query}
    if variables:
        payload["variables"] = variables
    response = requests.post(MONDAY_API_URL, json=payload, headers=HEADERS)
    response.raise_for_status()
    return response.json()

# Test: Get your boards
result = run_query("{ boards { id name } }")
for board in result.get("data", {}).get("boards", []):
    print(f"Board: {board['name']} (ID: {board['id']})")

mutation CreateItem($boardId: ID!, $name: String!, $columnValues: JSON) {
  create_item(board_id: $boardId, item_name: $name, column_values: $columnValues) {
    id url
  }
}

import json
from langchain.tools import tool

MONDAY_API_URL = "https://api.monday.com/v2"


@tool
def list_boards() -> str:
    """List all accessible Monday.com boards with their IDs and item counts."""
    query = """
    {
      boards(limit: 20) {
        id
        name
        items_count
        state
      }
    }"""
    result = run_query(query)
    boards = result.get("data", {}).get("boards", [])
    if not boards:
        return "No boards found"
    lines = ["Available boards:"]
    for board in boards:
        if board.get("state") == "active":
            lines.append(f"  - {board['name']} (ID: {board['id']}, {board.get('items_count', 0)} items)")
    return "\n".join(lines)


@tool
def get_board_items(board_id: str, status_filter: str = None) -> str:
    """
    Get items from a Monday.com board. status_filter: filter by status label (e.g., 'In Progress').
    """
    query = """
    query GetItems($boardId: ID!) {
      boards(ids: [$boardId]) {
        items_page(limit: 30) {
          items {
            id
            name
            state
            column_values {
              id
              text
              type
            }
          }
        }
      }
    }"""
    result = run_query(query, {"boardId": board_id})
    board = result.get("data", {}).get("boards", [{}])[0]
    items = board.get("items_page", {}).get("items", [])

    if not items:
        return f"No items found on board {board_id}"

    lines = [f"Board items ({len(items)} shown):"]
    for item in items:
        if item.get("state") == "deleted":
            continue
        # Get status and date columns
        cols = {cv["id"]: cv["text"] for cv in item.get("column_values", []) if cv.get("text")}
        status = cols.get("status", "No status")
        if status_filter and status_filter.lower() not in status.lower():
            continue
        col_summary = " | ".join(f"{k}: {v}" for k, v in list(cols.items())[:3])
        lines.append(f"  [{item['id']}] {item['name']} | {col_summary}")
    return "\n".join(lines)


@tool
def create_item(board_id: str, item_name: str, group_id: str = None,
                column_values: dict = None) -> str:
    """
    Create a new item on a Monday.com board.
    column_values: dict mapping column IDs to values.
    Example: {"status": {"label": "In Progress"}, "date4": {"date": "2026-03-15"}}
    """
    mutation = """
    mutation CreateItem($boardId: ID!, $groupId: String, $name: String!, $values: JSON) {
      create_item(
        board_id: $boardId,
        group_id: $groupId,
        item_name: $name,
        column_values: $values
      ) {
        id name url
      }
    }"""
    variables = {
        "boardId": board_id,
        "name": item_name,
        "values": json.dumps(column_values or {})
    }
    if group_id:
        variables["groupId"] = group_id

    result = run_query(mutation, variables)
    item = result.get("data", {}).get("create_item", {})
    return f"Item created: '{item.get('name')}' (ID: {item.get('id')}) — {item.get('url', '')}"


@tool
def update_item_status(item_id: str, board_id: str, status_label: str,
                       column_id: str = "status") -> str:
    """
    Update the status of a Monday.com item.
    status_label: the label text (e.g., 'Done', 'In Progress', 'Blocked').
    """
    mutation = """
    mutation UpdateStatus($boardId: ID!, $itemId: ID!, $columnId: String!, $value: JSON!) {
      change_column_value(
        board_id: $boardId,
        item_id: $itemId,
        column_id: $columnId,
        value: $value
      ) {
        id
      }
    }"""
    variables = {
        "boardId": board_id,
        "itemId": item_id,
        "columnId": column_id,
        "value": json.dumps({"label": status_label})
    }
    run_query(mutation, variables)
    return f"Item {item_id} status updated to '{status_label}'"


@tool
def add_update_to_item(item_id: str, message: str) -> str:
    """Add an update/comment to a Monday.com item visible to the whole team."""
    mutation = """
    mutation AddUpdate($itemId: ID!, $body: String!) {
      create_update(item_id: $itemId, body: $body) {
        id
      }
    }"""
    result = run_query(mutation, {"itemId": item_id, "body": message})
    update_id = result.get("data", {}).get("create_update", {}).get("id")
    return f"Update added to item {item_id} (Update ID: {update_id})"

from langchain_openai import ChatOpenAI
from langchain.agents import create_tool_calling_agent, AgentExecutor
from langchain_core.prompts import ChatPromptTemplate

llm = ChatOpenAI(model="gpt-4o", temperature=0.1)
tools = [list_boards, get_board_items, create_item, update_item_status, add_update_to_item]

prompt = ChatPromptTemplate.from_messages([
    ("system", """You are an operations assistant with access to Monday.com.

When creating items:
1. List available boards first to find the right destination
2. Use clear, actionable item names
3. Set status and date columns when information is available

When reporting:
1. Fetch current board state before summarizing
2. Quantify items by status (not started, in progress, done, blocked)
3. Flag items that are overdue or blocked

Always add updates as comments rather than changing item names — comments preserve history."""),
    ("human", "{input}"),
    ("placeholder", "{agent_scratchpad}"),
])

agent = create_tool_calling_agent(llm, tools, prompt)
executor = AgentExecutor(agent=agent, tools=tools, verbose=True, max_iterations=6)