diff --git a/authors.yaml b/authors.yaml index b164a40e2a..fa27074e33 100644 --- a/authors.yaml +++ b/authors.yaml @@ -472,3 +472,8 @@ heejingithub: name: "Heejin Cho" website: "https://www.linkedin.com/in/heejc/" avatar: "https://avatars.githubusercontent.com/u/169293861" + +blazstojanovic: + name: "Blaz Stojanovic" + website: "https://www.linkedin.com/in/blazstojanovic/" + avatar: "https://avatars.githubusercontent.com/u/22046931" \ No newline at end of file diff --git a/examples/agents_sdk/predictive_agents/README.md b/examples/agents_sdk/predictive_agents/README.md new file mode 100644 index 0000000000..fe6d99d556 --- /dev/null +++ b/examples/agents_sdk/predictive_agents/README.md @@ -0,0 +1,38 @@ +# Predictive Insurance Agent + +Multi-agent system that predicts customer churn and generates retention strategies using KumoRFM and OpenAI's Agents SDK. + +## What it does + +Analyzes insurance customers with expiring policies to: +- Predict churn risk +- Recommend additional products +- Generate personalized retention emails + +## Setup + +1. **Install dependencies**: + ```bash + pip install -r requirements.txt + ``` + +2. **Set API keys**: + ```bash + export KUMO_API_KEY='your-kumo-api-key-here' + export OPENAI_API_KEY='your-openai-api-key-here' + ``` + +## Run + +```bash +python predictive_insurance_agent.py +``` + +## How it works + +Three specialized agents work together: +- **Assessment Agent**: Checks if predictions are possible with available data +- **Prediction Agent**: Runs ML models to predict churn and recommend products +- **Business Action Agent**: Creates personalized emails and business recommendations + +An orchestrator coordinates the agents using handoffs for a seamless workflow. \ No newline at end of file diff --git a/examples/agents_sdk/predictive_agents/bridging-the-predictive-gap-in-agents.ipynb b/examples/agents_sdk/predictive_agents/bridging-the-predictive-gap-in-agents.ipynb new file mode 100644 index 0000000000..a9078cffca --- /dev/null +++ b/examples/agents_sdk/predictive_agents/bridging-the-predictive-gap-in-agents.ipynb @@ -0,0 +1,704 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "f62246f4-e574-4499-bfe0-fc2ff1d3a2a6", + "metadata": {}, + "source": [ + "# Bridging the predictive gap in agents with the KumoRFM MCP\n", + "Agents today are fundamentally reactive, they excel at responding to what's happening right now. Commonplace agentic tools like RAG and (web)search allow agents to retrieve information from databases, process documents, and otherwise compile available information in order to facilitate the agents' actions, be it responding to a customer inqury or performing a sequence of actions with available tools. But the most valuable business decisions require anticipating what will happen next.\n", + "\n", + "Consider a customer service agent that can instantly lookup a customer's policy details and transaction history. It's incredibly helpful for handling current inquiries, but what if that same agent could predict which customers are about to churn and proactively suggest retention strategies? Or an underwriting agent that doesn't just process applications, but predicts which applicants represent the best long-term value? The difference between reactive and predictive agents is the difference between managing problems and preventing them." + ] + }, + { + "cell_type": "markdown", + "id": "be72d5f4-64a7-48d2-9633-2a8952b65e28", + "metadata": {}, + "source": [ + "## Why Agents Need Predictive Capabilities\n", + "For agents to make truly informed decisions about what actions to take, they must go beyond simple data retrieval and synthesis. Agents need to be able to take the available enterprise data and produce quantitative predictions in which they will ground their future actions. \n", + "\n", + "Just like executives in large organizations rely on human analysts to guide their strategic decisions and enterprises rely on **predictive machine learning models** to optimize customer experience (recommender systems, personalization, etc.) and improve their operations (fraud detection, demand forecasting, etc.), agents too will need to rely on predictive tools to operate optimally.\n", + "\n", + "## How agents predict today\n", + "When organizations attempt to add predictive capabilities to their agents, they typically pursue one of two approaches, each with significant limitations.\n", + "\n", + "### Approach 1: Pre-Built Predictive Services\n", + "The most common approach involves implementing dedicated predictive services or integrating with existing ML platforms, then connecting agents to these rigid prediction endpoints.\n", + "\n", + "```{python}\n", + "@tool\n", + "def churn_risk(customer_id):\n", + " # call to service\n", + " return churn_probability\n", + "\n", + "@ tool \n", + "def recommendation(customer_id):\n", + " # call to service\n", + " return recommendations\n", + "```\n", + "\n", + "#### Core Issues with Pre-Built Services\n", + "* **Development Time and Expertise Requirements:** Each prediction service requires months of specialized development with data scientists, ML engineers, and infrastructure teams. A simple churn prediction service may take many months from conception to production.\n", + "* **Rigid Agentic Flows:** Agents become constrained to pre-determined prediction types. If a customer interaction reveals an unexpected need like predicting optimal policy renewal timing, the agent cannot adapt.\n", + "* **Inflexibility/Maintenance cost**: Any change to business requirements or data schemas requires rebuilding the entire ML pipeline from feature engineering to model retraining. Traditional model services are also expensive and difficult to maintain, requiring subsantial knowledge to keep running.\n", + "\n", + "### Approach 2: MLE-Agent (or Agent-as-a-Data-Scientist)\n", + "The second approach attempts to make agents themselves responsible for building and maintaining predictive models using SQL, Python, and other ML tools. While it is amazing to see the latest LLMs perform well on the core task of training ML models from scratch [1], deploying ML models goes far beyond training - reliability of the tool across diverse tasks, and deployment scenarios becomes the core issue for agent builders to overcome.\n", + "\n", + "#### Core Issues with MLE-Agents\n", + "* **Extremely Difficult Tool Development**: Machine Learning Engineering requires deep knowledge, building an agent or sub-agent/tool which reliably performs well on MLE tasks is difficult and adds much complexity to the already difficult task of developing useful agents.\n", + "* **Reliability Issues** : Agents can make critical errors in data preprocessing, feature selection, or model validation that lead to poor prediction performance. ML pipelines have many decision points where agent judgment can go wrong.\n", + "* **Doesn't Solve Fundamental Problems**: MLE-Agents still need to train individual models for each prediction task they want to solve, this nullifies the promised advantage of grounding agentic actions in many diverse predictions in a single (short) sequence." + ] + }, + { + "cell_type": "markdown", + "id": "15e44f57-a095-445d-b008-b9492a615468", + "metadata": {}, + "source": [ + "## Agentic predictions of the future\n", + "Both traditional approaches treat prediction as a separate, specialized capability that must be explicitly built for each use case. This paradigm fundamentally misaligns with how agents work best: through flexible, conversational reasoning that adapts to the current context.\n", + "\n", + "### The In-Context Prediction Paradigm\n", + "What if predictive capabilities worked more like large language models? LLMs don't require task-specific training to understand new domains or generate relevant text. They adapt through in-context learning, using examples and context to understand what's needed.\n", + "\n", + "Consider how an LLM handles a new task:\n", + "```\n", + "Human: \"Write a product launch email for insurance\"\n", + "LLM: [Adapts to context, generates relevant content without specific training]\n", + "```\n", + "\n", + "Now imagine prediction working the same way:\n", + "```\n", + "Human: \"Predict if customer XYZ will cancel their auto insurance in 30 days?\" \n", + "Model: [Adapts to prediction context, generates forecasts without task-specific training]\n", + "```\n", + "\n", + "### Relational In-Context Learning: The Missing Piece\n", + "A new paradigm is emerging in machine learning: in-context learning for predictive tasks. Relational (or multi-table) in-context learning solves many fundamental problems we discussed in previous sections. Relational Foundation Models (RFMs) work with relational data (databases) directly and can make predictions without task-specific training, learning patterns from contextual examples similar to how LLMs handle new text generation tasks. These approaches enable:\n", + "\n", + "* **Zero feature engineering:** The model learns predictive patterns from raw relational data.\n", + "* **Multi-table reasoning:** Reason across various entities (e.g. Customers, Policies) and their interactions (Claims, Cancellations) natively.\n", + "* **Schema adaptation:** Instantly working with new data structures without preprocessing pipelines.\n", + "* **Rich business context:** Leveraging the full complexity of enterprise data relationships.\n", + "\n", + "### KumoRFM: Foundation Model Intelligence for Relational Data\n", + "**Kumo Relational Foundation Model (KumoRFM)** [2] brings this vision to reality as the world's first Relational Foundation Model, extending in-context learning principles to multi-table enterprise data. By representing databases as temporal heterogeneous graphs, KumoRFM can generate predictions directly from existing database schemas without feature engineering or model training.\n", + "\n", + "For agents, this means predictions become as natural as text generation: conversational, adaptive, and instantly available across any prediction task your business data can support.\n", + "\n", + "![image](img/Kumo2.svg)" + ] + }, + { + "cell_type": "markdown", + "id": "645bee4e-0ead-485f-a03c-7803fd6c393a", + "metadata": {}, + "source": [ + "## Solution Overview: Building Predictive Agents with KumoRFM MCP\n", + "\n", + "### The Predictive Agent Architecture Pattern\n", + "**KumoRFM MCP** [3, 4] enables a new architectural pattern for building intelligent agents that seamlessly integrate predictions into business workflows. Instead of treating prediction as a separate service or complex ML pipeline, predictions become natural agent capabilities accessible through conversational interfaces.\n", + "\n", + "This pattern consists of three specialized agents working together under an **Orchestrator agent**:\n", + "\n", + "* **Assessment Agent:** Analyzes available data and determines prediction feasibility given KumoRFM capabilities.\n", + "* **Prediction Agent:** Executes the desired predictions with available data.\n", + "* **Action Agent:** Processes prediction results into business actions.\n", + "\n", + "The key insight is that KumoRFM's in-context learning capabilities enable agents to make sophisticated predictions using only natural language and PQL (predictive query language) understanding, eliminating the need for ML expertise, feature engineering, or model training. Just as LLMs democratized text generation through simple prompting, KumoRFM democratizes prediction through **predictive-prompting** in combination with a relational foundation model interface that any agent can master." + ] + }, + { + "cell_type": "markdown", + "id": "1ed0da00-3074-4859-88f3-47e0fdf84030", + "metadata": {}, + "source": [ + "```mermaid\n", + "graph TD\n", + " A[Business User] -->|Natural Language Request| B[Orchestrator Agent]\n", + " \n", + " B --> C[Assessment Agent]\n", + " B --> D[Graph & Prediction Agent]\n", + " B --> E[Action Agent]\n", + " \n", + " C -->|Data Feasibility Analysis| F[KumoRFM MCP Server]\n", + " D -->|Graph Setup & PQL Queries| F\n", + " E -->|Data Enrichment| F\n", + " \n", + " F --> G[(Multi-Table Database)]\n", + " F --> H[KumoRFM Engine]\n", + " \n", + " C -->|Assessment Results| B\n", + " D -->|Prediction Results| B\n", + " E -->|Business Actions| B\n", + " \n", + " B -->|Orchestrated Response| I[Business Outputs]\n", + " \n", + " I --> J[Personalized Emails]\n", + " I --> K[Risk Assessments]\n", + " I --> L[Product Recommendations]\n", + " I --> M[Retention Strategies]\n", + " \n", + " style B fill:#e1f5fe\n", + " style D fill:#e8f5e8\n", + " style F fill:#f3e5f5\n", + " style H fill:#e8f5e8\n", + " style G fill:#fff3e0\n", + "```" + ] + }, + { + "cell_type": "markdown", + "id": "4505ef6a-af14-47b5-b50b-7be748398122", + "metadata": {}, + "source": [ + "### Implementation: Insurance Renewal & Cross-Selling Workflow\n", + "Let's implement this pattern for a common insurance scenario: identifying customers at risk of churning and generating personalized retention offers with product recommendations.\n", + "\n", + "1. **OpenAI Agents SDK**: Provides agent orchestration, conversation management, and tool integration.\n", + "2. **KumoRFM MCP Server**: Delivers in-context prediction capabilities for structured data.\n", + "3. **Specialized Agent Roles**: Each agent handles a specific aspect of the prediction workflow.\n", + "\n", + "To run the full example simply install requirements:\n", + "```\n", + "pip install requirements.txt\n", + "```\n", + "and run the main script:\n", + "```\n", + "python predictive_insurance_agent.py\n", + "```\n", + "\n", + "Let's walk through the key implementation steps below!" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "644a38b3-f372-4d87-a502-7538e78d8dc6", + "metadata": {}, + "outputs": [], + "source": [ + "# imports\n", + "import asyncio\n", + "import os\n", + "from datetime import datetime, timedelta\n", + "from typing import List, Dict\n", + "\n", + "from agents import Agent, Runner, gen_trace_id, trace\n", + "from agents.mcp import MCPServer, MCPServerStdio\n", + "\n", + "import kumo_rfm_mcp" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "afe3f1d2-7988-4c41-aae8-da32866aa00b", + "metadata": {}, + "outputs": [], + "source": [ + "## Data configuration \n", + "\n", + "# Insurance Data Configuration\n", + "DATA_DIR = \"s3://kumo-sdk-public/rfm-datasets/insurance/\"\n", + "FILE_NAMES = [\"agents.csv\", \"policies.csv\", \"customers.csv\", \"pets.csv\", \n", + " \"products.csv\", \"properties.csv\", \"vehicles.csv\"]\n", + "\n", + "# Sample customer IDs with policies expiring in next 30 days\n", + "EXPIRING_CUSTOMER_IDS = [13, 402, 14, 329, 375, 239, 493, 319]\n", + "\n", + "def get_expiring_customers() -> List[int]:\n", + " \"\"\"\n", + " Get customer IDs with policies expiring in the next 30 days.\n", + " In a real scenario, this would query your policy database.\n", + " \"\"\"\n", + " print(f\"πŸ” Found {len(EXPIRING_CUSTOMER_IDS)} customers with policies expiring in next 30 days\")\n", + " print(f\"πŸ“‹ Customer IDs: {EXPIRING_CUSTOMER_IDS}\")\n", + " return EXPIRING_CUSTOMER_IDS\n", + "\n", + "CUSTOMER_IDs = get_expiring_customers()" + ] + }, + { + "cell_type": "markdown", + "id": "eeeedd12-7bc2-4b11-bf4b-ef042f8e3ef5", + "metadata": {}, + "source": [ + "#### MCP Server integration\n", + "KumoRFM integrates as an MCP server, providing prediction tools to all agents:\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "3c7c0441-8a4a-4c73-bc83-7e0de9e400bb", + "metadata": {}, + "outputs": [], + "source": [ + "async with MCPServerStdio(\n", + " name=\"KumoRFM Server\",\n", + " params={\n", + " \"command\": \"python\",\n", + " \"args\": [\"-m\", \"kumo_rfm_mcp.server\"],\n", + " \"env\": {\n", + " \"KUMO_API_KEY\": KUMO_API_KEY,\n", + " }\n", + " },\n", + ") as server:\n", + " # Agents can now access KumoRFM prediction capabilities\n", + " results = await run_predictive_workflow(server, user_request)" + ] + }, + { + "cell_type": "markdown", + "id": "710fe8d6-5c71-4f35-8877-f1de1712a431", + "metadata": {}, + "source": [ + "**The MCP server exposes several specialized tools that agents can use:**\n", + "\n", + "**Data Discovery & Inspection Tools:**\n", + "* `find_table_files`: Discovers tables (csv, parquet) in provided path.\n", + "* `inspect_table_files`: Examines table schemas and sample data to understand structure.\n", + "* `get_docs`: Retrieves KumoRFM documentation for graph setup and predictive queries.\n", + "\n", + "**Graph Management Tools:**\n", + "* `inspect_graph_metadata`: Views current graph structure, relationships, and semantic types.\n", + "* `update_graph_metadata`: Configures table relationships, primary keys, time columns, and semantic types.\n", + "* `materialize_graph`: Builds the graph structure ready for predictions.\n", + "* `get_mermaid`: Generates visual entity-relationship diagrams of the graph.\n", + "\n", + "**Prediction Execution Tools:**\n", + "* `predict`: Executes PQL queries to generate predictions.\n", + "* `lookup_table_rows`: Retrieves specific rows by primary key for data enrichment.\n", + "\n", + "**Authentication:**\n", + "* `authenticate`: Handles OAuth2 authentication flow if API key not set.\n", + "\n", + "These tools are enough to build out our proposed architecture, and unlock predictive flows for agents! However, our sub-agents require different tools from the same server so we need to be careful to filter them accordingly. We can do this very easily with `ToolFilterContext`:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "7b419fc0-721d-4f0e-a997-10c994b34a2c", + "metadata": {}, + "outputs": [], + "source": [ + "from agents.mcp import ToolFilterContext\n", + "\n", + "def dynamic_tool_filter(context: ToolFilterContext, tool) -> bool:\n", + " \"\"\"\n", + " Dynamic tool filtering based on agent context.\n", + " Each agent gets only the tools they need for their specific role.\n", + " \"\"\"\n", + " agent_name = context.agent.name\n", + " tool_name = tool.name\n", + " \n", + " # Define tool access patterns for each agent\n", + " agent_tool_mapping = {\n", + " \"Assessment Agent\": {\n", + " \"get_docs\",\n", + " \"inspect_table_files\",\n", + " },\n", + " \"Prediction Agent\": {\n", + " \"get_docs\",\n", + " \"inspect_table_files\",\n", + " \"inspect_graph_metadata\",\n", + " \"update_graph_metadata\",\n", + " \"materialize_graph\",\n", + " \"predict\",\n", + " },\n", + " \"Business Action Agent\": {\n", + " \"lookup_table_rows\",\n", + " \"inspect_graph_metadata\",\n", + " },\n", + " \"Predictive Insurance Orchestrator\": {\n", + " }\n", + " }\n", + " \n", + " allowed_tools = agent_tool_mapping.get(agent_name, set())\n", + " is_allowed = tool_name in allowed_tools\n", + " \n", + " return is_allowed" + ] + }, + { + "cell_type": "markdown", + "id": "3e151607-4315-4b59-a1a9-e774365a00bf", + "metadata": {}, + "source": [ + "#### Assessment Agent: Feasibility Validation\n", + "The Assessment Agent serves as the gatekeeper, ensuring prediction requests are realistic given available data." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "f5eeab64-5e98-41b3-86b1-54dd18d3e166", + "metadata": {}, + "outputs": [], + "source": [ + "from agents.extensions.handoff_prompt import RECOMMENDED_PROMPT_PREFIX" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "6061c46a-cbfe-4eab-be67-518813a01a6f", + "metadata": {}, + "outputs": [], + "source": [ + "# Assessment Agent - Determines prediction feasibility\n", + "assessment_agent = Agent(\n", + " name=\"Assessment Agent\",\n", + " model=\"gpt-5\",\n", + " instructions=f\"\"\"{RECOMMENDED_PROMPT_PREFIX}\n", + " \n", + " You are an expert data analyst who assesses whether predictive \n", + " tasks are feasible given available data.\n", + " \n", + " Your responsibilities:\n", + " 1. Use the `get_docs` tool to understand KumoRFM capabilities, data requrements, and pql syntax\n", + " 2. Use the `inspect_table_files` tool to understand the data in the files\n", + " 3. Determine if the data is sufficient to answer the business request(s)\n", + " \n", + " Be specific about what predictions are possible and why. If data is insufficient,\n", + " explain exactly what's missing and what would be needed. For predictions that are possible provide \n", + " predictive queries that can be used to answer the business request(s).\n", + " \n", + " After completing your assessment, hand off back to the Orchestrator with your findings\n", + " and recommendations for next steps.\"\"\",\n", + " mcp_servers=[mcp_server]\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "b5a218b0-0df6-48ea-8e26-6a03b60b6ce9", + "metadata": {}, + "source": [ + "**Key Capabilities:**\n", + "\n", + "* **Data Source Analysis:** Uses inspect_table_files to understand available data.\n", + "* **Requirement Breakdown:** Decomposes complex business requests into specific prediction tasks.\n", + "* **Feasibility Assessment:** Validates whether available data supports requested predictions.\n", + "* **Gap Identification:** Highlights missing data or relationships needed for predictions." + ] + }, + { + "cell_type": "markdown", + "id": "548c297d-3f96-442e-a08f-da5e5ddbcca4", + "metadata": {}, + "source": [ + "#### Prediction Agent: The Quantitative Reasoning Engine\n", + "This agent combines graph setup and prediction execution, intelligently managing data preparation and generating insights." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "bd351184-0435-4412-92fa-e544e2bae463", + "metadata": {}, + "outputs": [], + "source": [ + "# Prediction Agent - Sets up data and executes predictions\n", + "prediction_agent = Agent(\n", + " name=\"Prediction Agent\", \n", + " model=\"gpt-5\",\n", + " instructions=f\"\"\"{RECOMMENDED_PROMPT_PREFIX}\n", + " \n", + " You are a comprehensive prediction specialist who handles both \n", + " data preparation and prediction execution using KumoRFM.\n", + "\n", + " Your responsibilities:\n", + " 1. Use the `get_docs` tool to understand KumoRFM capabilities, data requrements, and pql syntax\n", + " 2. Use the `inspect_graph_metadata` tool to see if a suitable graph already exists for the requested predictions\n", + " 3. Use the `inspect_table_files` tool to understand the data in the files if needed to answer the business request(s)\n", + " 4. Use the `update_graph_metadata` tool to update the graph metadata if needed\n", + " 5. Use the `materialize_graph` tool to materialize the graph\n", + " 6. Use the `predict` tool to execute the predictions\n", + " 7. Summarize the key prediction results in a structured format\n", + "\n", + " After completing predictions successfully, hand off back to the Orchestrator\n", + " with your prediction results and analysis. If the predictions are not possible,\n", + " explain why and hand off back to the Orchestrator with your findings and recommendations.\"\"\",\n", + " mcp_servers=[mcp_server]\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "621feab3-9ac5-4ec8-a27d-f1f3a78cdecd", + "metadata": {}, + "source": [ + "**Key Capabilities:**\n", + "\n", + "* **Intelligent Graph Management:** Checks existing graph suitability before rebuilding.\n", + "* **Schema Discovery:** Uses `inspect_table_files` for data exploration.\n", + "* **Graph Materialization:** Configures relationships with `update_graph_metadata` and `materialize_graph`.\n", + "* **Natural Language to PQL:** Converts business requests into executable predictive queries.\n", + "* **Prediction Execution:** Uses `predict` tool with optimal parameters for accuracy." + ] + }, + { + "cell_type": "markdown", + "id": "727e2e88-026b-4da5-bc50-adc683ee05ee", + "metadata": {}, + "source": [ + "#### Action Agent: Business Output Generation\n", + "The Action Agent transforms prediction results into actionable business communications - this agent is purposfully left simple to spark the reader's imagination, in our case it's role is to simply write email offers, but the action agent could automatically send emails to customers, follow-up, alert relevant stakeholders or perform any array of possible actions to achieve the desired business outcome!" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "0078c445-15cb-4862-9c23-6a4a562b9f62", + "metadata": {}, + "outputs": [], + "source": [ + "# Business Action Agent - Converts predictions to business actions\n", + "action_agent = Agent(\n", + " name=\"Business Action Agent\", \n", + " model=\"gpt-5\",\n", + " instructions=f\"\"\"{RECOMMENDED_PROMPT_PREFIX}\n", + " \n", + " You are a business operations specialist who converts \n", + " prediction results into actionable business communications.\n", + "\n", + " Your responsibilities:\n", + " 1. Take the User Request and understand the business intent\n", + " 2. Use the results provided by the Prediction Agent to create a personalized business communication and/or recommendations\n", + "\n", + " Think about the prediction results and what they mean in the context of the insurance business. You can write an email, with recommendation + discount offer, to the user\n", + " if you see a high risk of churn and good opportunity to cross-sell.\n", + " \n", + " After creating the business actions, return the results to the Orchestrator.\"\"\",\n", + " mcp_servers=[mcp_server]\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "56081df1-0eb8-4ab9-baca-acbfaac318ca", + "metadata": {}, + "source": [ + "**Key Capability:**\n", + "* **Act**: Takes the prediction output and imbues it with additional context in order to perform meaningful actions.\n" + ] + }, + { + "cell_type": "markdown", + "id": "cfa81d6a-ab45-4ff3-888c-eca680d653c6", + "metadata": {}, + "source": [ + "#### Orchestrator Agent: Pulling it all together\n", + "The orchestrator is responsible for the e2e flow, it hands-off tasks to the sub-agents and receives their responses. In the end it summarizes the progress to the user." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "fa041fe5-563b-4a64-83b8-0d3403e53d7d", + "metadata": {}, + "outputs": [], + "source": [ + "# Orchestrator Agent - Manages the overall workflow\n", + "orchestrator_agent = Agent(\n", + " name=\"Predictive Insurance Orchestrator\",\n", + " model=\"gpt-5\",\n", + " instructions=f\"\"\"{RECOMMENDED_PROMPT_PREFIX}\n", + " \n", + " You are the orchestrator for predictive insurance workflows. Your role is to:\n", + " \n", + " 1. Understand the business request and context\n", + " 2. Coordinate with specialized agents to fulfill the request\n", + " 3. Ensure the workflow progresses logically through assessment β†’ prediction β†’ action\n", + " 4. Provide status updates and manage the overall process\n", + " \n", + " Available context:\n", + " - Data location: {DATA_DIR}\n", + " - Available files: {', '.join(FILE_NAMES)}\n", + " - Sample expiring customer IDs: {EXPIRING_CUSTOMER_IDS}\n", + " \n", + " Workflow:\n", + " 1. For prediction requests, start by handing off to the Assessment Agent\n", + " 2. When Assessment Agent returns, evaluate their findings and decide next steps:\n", + " - If feasible, hand off to Prediction Agent\n", + " - If not feasible, provide alternative recommendations\n", + " 3. When Prediction Agent returns with results, hand off to Business Action Agent\n", + " 4. When Business Action Agent returns, compile and present final results\n", + " \n", + " Each sub-agent will return to you with their results. Coordinate the workflow\n", + " by deciding which agent to involve next based on the current state and results.\"\"\",\n", + " mcp_servers=[mcp_server],\n", + " handoffs=[handoff(assessment_agent), handoff(prediction_agent), handoff(action_agent)]\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "53b9f016-12b7-4ab2-9afc-638b07563995", + "metadata": {}, + "source": [ + "We also need to configure handoffs from other agents back to the orchestrator:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "9808d2a0-45d1-4012-87f8-588263f89876", + "metadata": {}, + "outputs": [], + "source": [ + "# Configure handoffs\n", + "assessment_agent.handoffs = [handoff(orchestrator_agent)]\n", + "prediction_agent.handoffs = [handoff(orchestrator_agent)]\n", + "action_agent.handoffs = [handoff(orchestrator_agent)]" + ] + }, + { + "cell_type": "markdown", + "id": "603fad2a-362c-4db0-afb9-2d4febf8f88b", + "metadata": {}, + "source": [ + "And with that our multi-agent system is complete! We simply need to run the system on the provided user input." + ] + }, + { + "cell_type": "markdown", + "id": "9d8d45c6-d933-4b12-8ae5-27eec6be92a8", + "metadata": {}, + "source": [ + "#### Agent orchestration with `Runner`\n", + "We can easily manage the ochestration of the agents with the `Runner` class which automatically takes care of the multi-turn conversation and agent coordination:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "eadd4e62-f2c3-49f4-b25a-fe2f8dd3df22", + "metadata": {}, + "outputs": [], + "source": [ + "# Execute agent workflow with conversation management\n", + "result = await Runner.run(\n", + " starting_agent=orchestrator_agent,\n", + " input=orchestrator_request,\n", + " max_turns=5 # Allows for back-and-forth clarification\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "e0e5a9bb-1f78-48d5-99ac-cd3fe010d188", + "metadata": {}, + "source": [ + "#### Observability with Tracing\n", + "The SDK provides comprehensive workflow observability:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "f2793a18-95cf-419d-b82f-fe75f83a242e", + "metadata": {}, + "outputs": [], + "source": [ + "trace_id = gen_trace_id()\n", + "with trace(workflow_name=\"Predictive Insurance Workflow\", trace_id=trace_id):\n", + " print(f\"πŸ“Š View trace: https://platform.openai.com/traces/trace?trace_id={trace_id}\")\n", + " results = await run_predictive_workflow(server, user_request)" + ] + }, + { + "cell_type": "markdown", + "id": "652478ac-f50b-41fe-8acf-f5079cf5ae8c", + "metadata": { + "jp-MarkdownHeadingCollapsed": true + }, + "source": [ + "### Generalization to Other Industries\n", + "This same pattern applies across industries by supplying domain-specific context and action tools to the agents:\n", + "\n", + "* **E-commerce:** Customer lifetime value prediction β†’ Product recommendation β†’ Marketing campaign generation.\n", + "* **Financial Services:** Credit risk assessment β†’ Investment recommendation β†’ Client communication.\n", + "* **Healthcare:** Patient risk scoring β†’ Risk score prediction β†’ Treatment recommendation β†’ Care plan generation β†’ PCP handoff.\n", + "* **Manufacturing:** Demand forecasting β†’ Inventory optimization β†’ Supplier communication.\n", + "\n", + "The core architecture remains the same while agents adapt to industry-specific data, predictions, and business actions." + ] + }, + { + "cell_type": "markdown", + "id": "fbf1984d-79f8-48de-ab31-032d6dd1ba4c", + "metadata": {}, + "source": [ + "### Key Architecture Benefits\n", + "This predictive agent pattern provides several advantages over traditional ML approaches:\n", + "* **Natural Language Interface:** Business users can request complex predictions in plain English without knowing PQL syntax or ML terminology.\n", + "* **Automatic Feasibility Assessment:** The system validates whether predictions are possible before attempting them, preventing failed workflows.\n", + "* **Schema Adaptability:** New data sources and relationship types are discovered and integrated automatically without code changes.\n", + "* **Composable Predictions:** Complex business scenarios are broken down into manageable prediction tasks that can be orchestrated flexibly.\n", + "* **Business Context Integration:** Predictions are automatically enriched with business logic and converted into actionable outputs." + ] + }, + { + "cell_type": "markdown", + "id": "b94134d4", + "metadata": { + "vscode": { + "languageId": "plaintext" + } + }, + "source": [ + "# References\n", + "- [1] [MLAgentBench: Evaluating Language Agents on Machine Learning Experimentation](https://arxiv.org/abs/2310.03302)\n", + "- [2] [KumoRFM: A Foundation Model for In-Context Learning on Relational Data](https://kumo.ai/research/kumo_relational_foundation_model.pdf)\n", + "- [3] [Model Context Protocol](https://modelcontextprotocol.io/docs/getting-started/intro)\n", + "- [4] [kumo-rfm-mcp](https://github.com/kumo-ai/kumo-rfm-mcp)" + ] + }, + { + "cell_type": "markdown", + "id": "4dc2b61d", + "metadata": {}, + "source": [ + "## We'd love to hear from you! ❀️\n", + "\n", + "1. **Found a bug or have a feature request?** \n", + " Submit issues directly on [GitHub](https://github.com/kumo-ai/kumo-rfm). Your feedback helps us improve RFM for everyone.\n", + "\n", + "2. **Built something cool with RFM? We'd love to see it!** \n", + " Share your project on LinkedIn and tag @kumo. We regularly spotlight on our official channelsβ€”yours could be next!\n", + "\n", + "
\n", + " \n", + "
" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.10.18" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/examples/agents_sdk/predictive_agents/img/Kumo2.svg b/examples/agents_sdk/predictive_agents/img/Kumo2.svg new file mode 100644 index 0000000000..0935bcccb9 --- /dev/null +++ b/examples/agents_sdk/predictive_agents/img/Kumo2.svg @@ -0,0 +1 @@ +RawRelational DataData Preparation & Feature EngineeringModel Selection, Training, and OptimizationModel Evaluation & ValidationModel Serving & MonitoringModel Maintenance & RetrainingAI Prediction 1AI Prediction 2…AI Prediction NAI Prediction 1AI Prediction 2AI Prediction N…RawRelational DataWithout KumoWith Kumo \ No newline at end of file diff --git a/examples/agents_sdk/predictive_agents/predictive_insurance_agent.py b/examples/agents_sdk/predictive_agents/predictive_insurance_agent.py new file mode 100644 index 0000000000..9c78968fae --- /dev/null +++ b/examples/agents_sdk/predictive_agents/predictive_insurance_agent.py @@ -0,0 +1,293 @@ +import asyncio +import os +# Instructions: +# KUMO_API_KEY and OPENAI_API_KEY need to be set as environment variables +# export KUMO_API_KEY='your-kumo-api-key-here' +# export OPENAI_API_KEY='your-openai-api-key-here' + +from datetime import datetime, timedelta +from typing import List, Dict + +from agents import Agent, Runner, gen_trace_id, trace, handoff +from agents.mcp import MCPServer, MCPServerStdio, ToolFilterContext +from agents.extensions.handoff_prompt import RECOMMENDED_PROMPT_PREFIX + +# Insurance Data Configuration +DATA_DIR = "s3://kumo-sdk-public/rfm-datasets/insurance/" +# FILE_NAMES = ["agents.csv", "policies.csv", "customers.csv", "pets.csv", +# "products.csv", "properties.csv", "vehicles.csv"] +FILE_NAMES = ["agents.csv", "policies.csv", "customers.csv", "products.csv"] # simpler example +# FILE_NAMES = ["customers.csv", "pets.csv"] # failing example (not enough data) + +# Sample customer IDs with policies expiring in next 30 days +# EXPIRING_CUSTOMER_IDS = [13, 402, 14, 329, 375, 239, 493, 319] +EXPIRING_CUSTOMER_IDS = [13, 402, 14] # shorter example + + +def get_expiring_customers() -> List[int]: + """ + Get customer IDs with policies expiring in the next 30 days. + """ + print(f"πŸ” Found {len(EXPIRING_CUSTOMER_IDS)} customers with policies expiring in next 30 days") + print(f"πŸ“‹ Customer IDs: {EXPIRING_CUSTOMER_IDS}") + return EXPIRING_CUSTOMER_IDS + + +def dynamic_tool_filter(context: ToolFilterContext, tool) -> bool: + """ + Dynamic tool filtering based on agent context. + Each agent gets only the tools they need for their specific role. + """ + agent_name = context.agent.name + tool_name = tool.name + + # Define tool access patterns for each agent + agent_tool_mapping = { + "Assessment Agent": { + "get_docs", + "inspect_table_files", + }, + "Prediction Agent": { + "get_docs", + "inspect_table_files", + "inspect_graph_metadata", + "update_graph_metadata", + "materialize_graph", + "predict", + }, + "Business Action Agent": { + "lookup_table_rows", + "inspect_graph_metadata", + }, + "Predictive Insurance Orchestrator": { + } + } + + allowed_tools = agent_tool_mapping.get(agent_name, set()) + is_allowed = tool_name in allowed_tools + + return is_allowed + +async def setup_predictive_agents(mcp_server: MCPServer): + """ + Initialize the predictive agent architecture with handoffs and tool filtering. + """ + + # Assessment Agent - Determines prediction feasibility + assessment_agent = Agent( + name="Assessment Agent", + model="gpt-5", + instructions=f"""{RECOMMENDED_PROMPT_PREFIX} + + You are an expert data analyst who assesses whether predictive + tasks are feasible given available data. + + Your responsibilities: + 1. Use the `get_docs` tool to understand KumoRFM capabilities, data requrements, and pql syntax + 2. Use the `inspect_table_files` tool to understand the data in the files + 3. Determine if the data is sufficient to answer the business request(s) + + Be specific about what predictions are possible and why. If data is insufficient, + explain exactly what's missing and what would be needed. For predictions that are possible provide + predictive queries that can be used to answer the business request(s). + + After completing your assessment, hand off back to the Orchestrator with your findings + and recommendations for next steps.""", + mcp_servers=[mcp_server] + ) + + # Prediction Agent - Sets up data and executes predictions + prediction_agent = Agent( + name="Prediction Agent", + model="gpt-5", + instructions=f"""{RECOMMENDED_PROMPT_PREFIX} + + You are a comprehensive prediction specialist who handles both + data preparation and prediction execution using KumoRFM. + + Your responsibilities: + 1. Use the `get_docs` tool to understand KumoRFM capabilities, data requrements, and pql syntax + 2. Use the `inspect_graph_metadata` tool to see if a suitable graph already exists for the requested predictions + 3. Use the `inspect_table_files` tool to understand the data in the files if needed to answer the business request(s) + 4. Use the `update_graph_metadata` tool to update the graph metadata if needed + 5. Use the `materialize_graph` tool to materialize the graph + 6. Use the `predict` tool to execute the predictions + 7. Summarize the key prediction results in a structured format + + After completing predictions successfully, hand off back to the Orchestrator + with your prediction results and analysis. If the predictions are not possible, + explain why and hand off back to the Orchestrator with your findings and recommendations.""", + mcp_servers=[mcp_server] + ) + + # Business Action Agent - Converts predictions to business actions + action_agent = Agent( + name="Business Action Agent", + model="gpt-5", + instructions=f"""{RECOMMENDED_PROMPT_PREFIX} + + You are a business operations specialist who converts + prediction results into actionable business communications. + + Your responsibilities: + 1. Take the User Request and understand the business intent + 2. Use the results provided by the Prediction Agent to create a personalized business communication and/or recommendations + + Think about the prediction results and what they mean in the context of the insurance business. You can write an email, with recommendation + discount offer, to the user + if you see a high risk of churn and good opportunity to cross-sell. + + After creating the business actions, return the results to the Orchestrator.""", + mcp_servers=[mcp_server] + ) + + # Orchestrator Agent - Manages the overall workflow + orchestrator_agent = Agent( + name="Predictive Insurance Orchestrator", + model="gpt-5", + instructions=f"""{RECOMMENDED_PROMPT_PREFIX} + + You are the orchestrator for predictive insurance workflows. Your role is to: + + 1. Understand the business request and context + 2. Coordinate with specialized agents to fulfill the request + 3. Ensure the workflow progresses logically through assessment β†’ prediction β†’ action + 4. Provide status updates and manage the overall process + + Available context: + - Data location: {DATA_DIR} + - Available files: {', '.join(FILE_NAMES)} + - Sample expiring customer IDs: {EXPIRING_CUSTOMER_IDS} + + Workflow: + 1. For prediction requests, start by handing off to the Assessment Agent + 2. When Assessment Agent returns, evaluate their findings and decide next steps: + - If feasible, hand off to Prediction Agent + - If not feasible, provide alternative recommendations + 3. When Prediction Agent returns with results, hand off to Business Action Agent + 4. When Business Action Agent returns, compile and present final results + + Each sub-agent will return to you with their results. Coordinate the workflow + by deciding which agent to involve next based on the current state and results. + + Make sure to hand off to the next agent with the results of the previous agent.""", + mcp_servers=[mcp_server], + handoffs=[handoff(assessment_agent), handoff(prediction_agent), handoff(action_agent)] + ) + + # Configure handoffs + assessment_agent.handoffs = [handoff(orchestrator_agent,)] + prediction_agent.handoffs = [handoff(orchestrator_agent)] + action_agent.handoffs = [handoff(orchestrator_agent)] + + return orchestrator_agent, assessment_agent, prediction_agent, action_agent + + +async def run_predictive_workflow(mcp_server: MCPServer, user_request: str): + """ + Run the predictive workflow using the orchestrator agent with handoffs + """ + + # Initialize agents + orchestrator_agent, assessment_agent, prediction_agent, action_agent = await setup_predictive_agents(mcp_server) + + print("🏒 Starting Predictive Insurance Workflow") + print("=" * 60) + + # Create comprehensive request for orchestrator + orchestrator_request = f""" + Handle this predictive insurance business request: + + "{user_request}" + + Context: + - Available data: {DATA_DIR} with files {FILE_NAMES} + - Customers with expiring policies: {EXPIRING_CUSTOMER_IDS} + + Please coordinate the complete workflow: + 1. Assess the feasibility of the requested predictions + 2. Set up the data graph and execute predictions if feasible + 3. Generate actionable business communications and recommendations + + Use handoffs to specialized agents as appropriate to ensure each step is handled by the right expert. + """ + + # Execute the workflow + result = await Runner.run( + starting_agent=orchestrator_agent, + input=orchestrator_request, + max_turns=25 + ) + + print("=" * 60) + print("πŸŽ‰ Workflow Complete!") + print("βœ… Insurance retention and cross-selling analysis finished") + + return result + + +async def main(): + """ + Main function for the predictive insurance workflow + """ + print("🏒 Predictive Insurance Agent") + print("🎯 Customer Retention & Cross-Selling Analysis") + print() + + # Business request in natural language + user_request = """ + I need to identify customers whose insurance policies are expiring in the next 30 days + and are at risk of not renewing. For high-risk customers, I want to: + + 1. Predict their likelihood of churning + 2. Recommend additional insurance products they might purchase + 3. Generate personalized retention emails with discount offers and product bundles + + The goal is to proactively retain customers and increase cross-selling. + """ + + # Get expiring customers + expiring_customers = get_expiring_customers() + + # Environment setup + kumo_api_key = os.getenv("KUMO_API_KEY") + if not kumo_api_key: + print("❌ KUMO_API_KEY environment variable not set") + print("πŸ“ Please set your KumoRFM API key: export KUMO_API_KEY='your-key-here'") + return + + print("πŸ”Œ Connecting to KumoRFM...") + + # try: + async with MCPServerStdio( + name="KumoRFM Server", + params={ + "command": "python", + "args": ["-m", "kumo_rfm_mcp.server"], + "env": { + "KUMO_API_KEY": kumo_api_key, + "KUMO_API_URL": "https://kumorfm.ai/api" + } + }, + tool_filter=dynamic_tool_filter + ) as server: + + # Enable tracing + trace_id = gen_trace_id() + with trace(workflow_name="Predictive Insurance Workflow", trace_id=trace_id): + print(f"πŸ“Š View trace: https://platform.openai.com/traces/trace?trace_id={trace_id}\n") + print("βœ… Connected to KumoRFM successfully!") + print() + + # Execute the workflow + results = await run_predictive_workflow(server, user_request) + + print("\nπŸ“‹ RESULTS:") + print("=" * 40) + print(results) + print("=" * 40) + + return results + + +if __name__ == "__main__": + asyncio.run(main()) \ No newline at end of file diff --git a/examples/agents_sdk/predictive_agents/requirements.txt b/examples/agents_sdk/predictive_agents/requirements.txt new file mode 100644 index 0000000000..805694ef74 --- /dev/null +++ b/examples/agents_sdk/predictive_agents/requirements.txt @@ -0,0 +1,2 @@ +openai-agents-sdk>=1.0.0 +kumo-rfm-mcp>=1.0.0 diff --git a/registry.yaml b/registry.yaml index 7e2c5a2606..36f4abf321 100644 --- a/registry.yaml +++ b/registry.yaml @@ -2501,3 +2501,14 @@ - katiagg tags: - images + +- title: Bridging the Predictive Gap in Agents with KumoRFM MCP + path: examples/agents_sdk/predictive_agents/bridging-the-predictive-gap-in-agents.ipynb + date: 2025-09-04 + authors: + - blazstojanovic + tags: + - agents + - agents-sdk + - mcp + - tracing \ No newline at end of file