Passer au contenu principal
Ceci est un notebook interactif. Vous pouvez l’exécuter localement ou utiliser les liens suivants :
Ce tutoriel montre comment créer un système multi-agent qui utilise la fonctionnalité de sorties structurées d’OpenAI, ainsi que comment tracer les interactions entre agents avec Weave. Au terme de ce tutoriel, vous disposerez d’un pipeline d’analyse de données à quatre agents, dont les entrées et sorties intermédiaires sont visibles dans l’interface Weave. OpenAI a lancé Structured Outputs pour que le modèle génère toujours des réponses conformes au schéma JSON que vous fournissez, sans avoir recours à des prompts formulés de manière très directive. Avec Structured Outputs, vous n’avez pas besoin de valider ou de relancer les réponses mal formatées. En utilisant le paramètre strict: true, vous pouvez garantir que la réponse respecte le schéma fourni. Dans un système multi-agent, les sorties structurées produisent des données cohérentes, traitées de façon prévisible d’un agent à l’autre. Elles prennent également en charge les refus explicites et éliminent la nécessité de relancer ou de valider les réponses.
Source : Ce cookbook est basé sur un exemple de code des sorties structurées d’OpenAI, avec quelques modifications pour améliorer la visualisation avec Weave.

​
Installation des dépendances

Commencez par installer les bibliothèques dont dépend ce tutoriel. Ce tutoriel utilise les bibliothèques suivantes :
  • OpenAI pour créer le système multi-agent.
  • Weave pour suivre le flux de travail avec les LLM et évaluer les stratégies de prompt.
!pip install -qU openai weave wandb
python
%%capture
# Solution temporaire pour corriger un bug dans openai :
# TypeError: Client.__init__() got an unexpected keyword argument 'proxies'
# Voir https://community.openai.com/t/error-with-openai-1-56-0-client-init-got-an-unexpected-keyword-argument-proxies/1040332/15
!pip install "httpx<0.28"
Ensuite, configurez les identifiants et initialisez Weave afin que les traces soient consignées dans votre projet W&B. Définissez WANDB_API_KEY dans votre environnement afin de pouvoir vous connecter avec wandb.login(). Fournissez-le à Colab en tant que secret. Définissez le projet dans W&B dans lequel vous souhaitez consigner les traces dans name_of_wandb_project.
name_of_wandb_project peut aussi être au format [YOUR-TEAM]/[YOUR-PROJECT] pour préciser l’équipe dans laquelle consigner les traces.
Nous récupérons ensuite un client Weave en appelant weave.init(). Puisque ce tutoriel utilise l’API OpenAI, vous avez également besoin d’une clé API OpenAI. Vous pouvez vous inscrire sur la plateforme OpenAI pour obtenir votre propre clé API. Fournissez-la aussi à Colab en tant que secret. 
import base64
import json
import os
from io import BytesIO, StringIO

import matplotlib.pyplot as plt
import numpy as np
import pandas as pd
import wandb
from google.colab import userdata
from openai import OpenAI

import weave
python
os.environ["WANDB_API_KEY"] = userdata.get("WANDB_API_KEY")
os.environ["OPENAI_API_KEY"] = userdata.get("OPENAI_API_KEY")

wandb.login()
name_of_wandb_project = "multi-agent-structured-output"
weave.init(name_of_wandb_project)

client = OpenAI()
MODEL = "gpt-4o-2024-08-06"

​
Configurer les agents

Une fois Weave initialisé, définissez les agents qui composent le système. Le cas d’usage de ce tutoriel est une tâche d’analyse de données. Commencez par configurer le système à quatre agents :
  • Agent de triage : décide quels agents appeler.
  • Agent de prétraitement des données : prépare les données pour l’analyse, par exemple en les nettoyant.
  • Agent d’analyse des données : effectue l’analyse des données.
  • Agent de visualisation des données : visualise les résultats de l’analyse afin d’en extraire des enseignements.
Commencez par définir les prompts système pour chacun de ces agents. Ces prompts définissent le rôle de chaque agent et les outils qu’il est autorisé à appeler. 
triaging_system_prompt = """You are a Triaging Agent. Your role is to assess the user's query and route it to the relevant agents. The agents available are:
- Data Processing Agent: Cleans, transforms, and aggregates data.
- Analysis Agent: Performs statistical, correlation, and regression analysis.
- Visualization Agent: Creates bar charts, line charts, and pie charts.

Use the send_query_to_agents tool to forward the user's query to the relevant agents. Also, use the speak_to_user tool to get more information from the user if needed."""

processing_system_prompt = """You are a Data Processing Agent. Your role is to clean, transform, and aggregate data using the following tools:
- clean_data
- transform_data
- aggregate_data"""

analysis_system_prompt = """You are an Analysis Agent. Your role is to perform statistical, correlation, and regression analysis using the following tools:
- stat_analysis
- correlation_analysis
- regression_analysis"""

visualization_system_prompt = """You are a Visualization Agent. Your role is to create bar charts, line charts, and pie charts using the following tools:
- create_bar_chart
- create_line_chart
- create_pie_chart"""
Ensuite, définissez les outils de chaque agent. À l’exception de l’agent de triage, chaque agent dispose d’outils spécifiques à son rôle : Agent de prétraitement des données : nettoyer les données, transformer les données et agréger les données. Agent d’analyse des données : analyse statistique, analyse de corrélation et analyse de régression. Agent de visualisation des données : créer un graphique à barres, créer un graphique en courbes et créer un diagramme circulaire. 
triage_tools = [
    {
        "type": "function",
        "function": {
            "name": "send_query_to_agents",
            "description": "Sends the user query to relevant agents based on their capabilities.",
            "parameters": {
                "type": "object",
                "properties": {
                    "agents": {
                        "type": "array",
                        "items": {"type": "string"},
                        "description": "An array of agent names to send the query to.",
                    },
                    "query": {
                        "type": "string",
                        "description": "The user query to send.",
                    },
                },
                "required": ["agents", "query"],
            },
        },
        "strict": True,
    }
]

preprocess_tools = [
    {
        "type": "function",
        "function": {
            "name": "clean_data",
            "description": "Cleans the provided data by removing duplicates and handling missing values.",
            "parameters": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "string",
                        "description": "The dataset to clean. Should be in a suitable format such as JSON or CSV.",
                    }
                },
                "required": ["data"],
                "additionalProperties": False,
            },
        },
        "strict": True,
    },
    {
        "type": "function",
        "function": {
            "name": "transform_data",
            "description": "Transforms data based on specified rules.",
            "parameters": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "string",
                        "description": "The data to transform. Should be in a suitable format such as JSON or CSV.",
                    },
                    "rules": {
                        "type": "string",
                        "description": "Transformation rules to apply, specified in a structured format.",
                    },
                },
                "required": ["data", "rules"],
                "additionalProperties": False,
            },
        },
        "strict": True,
    },
    {
        "type": "function",
        "function": {
            "name": "aggregate_data",
            "description": "Aggregates data by specified columns and operations.",
            "parameters": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "string",
                        "description": "The data to aggregate. Should be in a suitable format such as JSON or CSV.",
                    },
                    "group_by": {
                        "type": "array",
                        "items": {"type": "string"},
                        "description": "Columns to group by.",
                    },
                    "operations": {
                        "type": "string",
                        "description": "Aggregation operations to perform, specified in a structured format.",
                    },
                },
                "required": ["data", "group_by", "operations"],
                "additionalProperties": False,
            },
        },
        "strict": True,
    },
]

analysis_tools = [
    {
        "type": "function",
        "function": {
            "name": "stat_analysis",
            "description": "Performs statistical analysis on the given dataset.",
            "parameters": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "string",
                        "description": "The dataset to analyze. Should be in a suitable format such as JSON or CSV.",
                    }
                },
                "required": ["data"],
                "additionalProperties": False,
            },
        },
        "strict": True,
    },
    {
        "type": "function",
        "function": {
            "name": "correlation_analysis",
            "description": "Calculates correlation coefficients between variables in the dataset.",
            "parameters": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "string",
                        "description": "The dataset to analyze. Should be in a suitable format such as JSON or CSV.",
                    },
                    "variables": {
                        "type": "array",
                        "items": {"type": "string"},
                        "description": "List of variables to calculate correlations for.",
                    },
                },
                "required": ["data", "variables"],
                "additionalProperties": False,
            },
        },
        "strict": True,
    },
    {
        "type": "function",
        "function": {
            "name": "regression_analysis",
            "description": "Performs regression analysis on the dataset.",
            "parameters": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "string",
                        "description": "The dataset to analyze. Should be in a suitable format such as JSON or CSV.",
                    },
                    "dependent_var": {
                        "type": "string",
                        "description": "The dependent variable for regression.",
                    },
                    "independent_vars": {
                        "type": "array",
                        "items": {"type": "string"},
                        "description": "List of independent variables.",
                    },
                },
                "required": ["data", "dependent_var", "independent_vars"],
                "additionalProperties": False,
            },
        },
        "strict": True,
    },
]

visualization_tools = [
    {
        "type": "function",
        "function": {
            "name": "create_bar_chart",
            "description": "Creates a bar chart from the provided data.",
            "parameters": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "string",
                        "description": "The data for the bar chart. Should be in a suitable format such as JSON or CSV.",
                    },
                    "x": {"type": "string", "description": "Column for the x-axis."},
                    "y": {"type": "string", "description": "Column for the y-axis."},
                },
                "required": ["data", "x", "y"],
                "additionalProperties": False,
            },
        },
        "strict": True,
    },
    {
        "type": "function",
        "function": {
            "name": "create_line_chart",
            "description": "Creates a line chart from the provided data.",
            "parameters": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "string",
                        "description": "The data for the line chart. Should be in a suitable format such as JSON or CSV.",
                    },
                    "x": {"type": "string", "description": "Column for the x-axis."},
                    "y": {"type": "string", "description": "Column for the y-axis."},
                },
                "required": ["data", "x", "y"],
                "additionalProperties": False,
            },
        },
        "strict": True,
    },
    {
        "type": "function",
        "function": {
            "name": "create_pie_chart",
            "description": "Creates a pie chart from the provided data.",
            "parameters": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "string",
                        "description": "The data for the pie chart. Should be in a suitable format such as JSON or CSV.",
                    },
                    "labels": {
                        "type": "string",
                        "description": "Column for the labels.",
                    },
                    "values": {
                        "type": "string",
                        "description": "Column for the values.",
                    },
                },
                "required": ["data", "labels", "values"],
                "additionalProperties": False,
            },
        },
        "strict": True,
    },
]

​
Activer le suivi multi-agent avec Weave

Une fois les agents et leurs outils définis, l’étape suivante consiste à les faire fonctionner ensemble et à activer le tracing de Weave. Écrivez la logique nécessaire pour :
  • Gérer la transmission de la requête de l’utilisateur au système multi-agent.
  • Gérer le fonctionnement interne du système multi-agent.
  • Exécuter les appels d’outil.
# Exemple de requête

user_query = """
Below is some data. I want you to first remove the duplicates then analyze the statistics of the data as well as plot a line chart.

house_size (m3), house_price ($)
90, 100
80, 90
100, 120
90, 100
"""
À partir de la requête de l’utilisateur, vous pouvez déduire que les outils à appeler sont clean_data, start_analysis et use_line_chart. Commencez par définir la fonction d’exécution chargée d’exécuter les appels d’outils. En décorant les fonctions Python avec @weave.op(), vous pouvez consigner et déboguer les entrées, les sorties et les traces du modèle de langage. Un système multi-agent implique de nombreuses fonctions, mais il suffit d’ajouter @weave.op() au-dessus de chacune d’elles. 
@weave.op()
def clean_data(data):
    data_io = StringIO(data)
    df = pd.read_csv(data_io, sep=",")
    df_deduplicated = df.drop_duplicates()
    return df_deduplicated

@weave.op()
def stat_analysis(data):
    data_io = StringIO(data)
    df = pd.read_csv(data_io, sep=",")
    return df.describe()

@weave.op()
def plot_line_chart(data):
    data_io = StringIO(data)
    df = pd.read_csv(data_io, sep=",")

    x = df.iloc[:, 0]
    y = df.iloc[:, 1]

    coefficients = np.polyfit(x, y, 1)
    polynomial = np.poly1d(coefficients)
    y_fit = polynomial(x)

    plt.figure(figsize=(10, 6))
    plt.plot(x, y, "o", label="Data Points")
    plt.plot(x, y_fit, "-", label="Best Fit Line")
    plt.title("Line Chart with Best Fit Line")
    plt.xlabel(df.columns[0])
    plt.ylabel(df.columns[1])
    plt.legend()
    plt.grid(True)

    # Enregistrer le graphique dans un buffer BytesIO avant de l'afficher
    buf = BytesIO()
    plt.savefig(buf, format="png")
    buf.seek(0)

    # Afficher le graphique
    plt.show()

    # Encoder l'image en base64 pour l'URL de données
    image_data = buf.getvalue()
    base64_encoded_data = base64.b64encode(image_data)
    base64_string = base64_encoded_data.decode("utf-8")
    data_url = f"data:image/png;base64,{base64_string}"

    return data_url

# Définir la fonction pour exécuter les outils
@weave.op()
def execute_tool(tool_calls, messages):
    for tool_call in tool_calls:
        tool_name = tool_call.function.name
        tool_arguments = json.loads(tool_call.function.arguments)

        if tool_name == "clean_data":
            # Simuler le nettoyage des données
            cleaned_df = clean_data(tool_arguments["data"])
            cleaned_data = {"cleaned_data": cleaned_df.to_dict()}
            messages.append(
                {"role": "tool", "name": tool_name, "content": json.dumps(cleaned_data)}
            )
            print("Cleaned data: ", cleaned_df)
        elif tool_name == "transform_data":
            # Simuler la transformation des données
            transformed_data = {"transformed_data": "sample_transformed_data"}
            messages.append(
                {
                    "role": "tool",
                    "name": tool_name,
                    "content": json.dumps(transformed_data),
                }
            )
        elif tool_name == "aggregate_data":
            # Simuler l'agrégation des données
            aggregated_data = {"aggregated_data": "sample_aggregated_data"}
            messages.append(
                {
                    "role": "tool",
                    "name": tool_name,
                    "content": json.dumps(aggregated_data),
                }
            )
        elif tool_name == "stat_analysis":
            # Simuler l'analyse statistique
            stats_df = stat_analysis(tool_arguments["data"])
            stats = {"stats": stats_df.to_dict()}
            messages.append(
                {"role": "tool", "name": tool_name, "content": json.dumps(stats)}
            )
            print("Statistical Analysis: ", stats_df)
        elif tool_name == "correlation_analysis":
            # Simuler l'analyse de corrélation
            correlations = {"correlations": "sample_correlations"}
            messages.append(
                {"role": "tool", "name": tool_name, "content": json.dumps(correlations)}
            )
        elif tool_name == "regression_analysis":
            # Simuler l'analyse de régression
            regression_results = {"regression_results": "sample_regression_results"}
            messages.append(
                {
                    "role": "tool",
                    "name": tool_name,
                    "content": json.dumps(regression_results),
                }
            )
        elif tool_name == "create_bar_chart":
            # Simuler la création d'un graphique en barres
            bar_chart = {"bar_chart": "sample_bar_chart"}
            messages.append(
                {"role": "tool", "name": tool_name, "content": json.dumps(bar_chart)}
            )
        elif tool_name == "create_line_chart":
            # Simuler la création d'un graphique en courbes
            line_chart = {"line_chart": plot_line_chart(tool_arguments["data"])}
            messages.append(
                {"role": "tool", "name": tool_name, "content": json.dumps(line_chart)}
            )
        elif tool_name == "create_pie_chart":
            # Simuler la création d'un graphique en secteurs
            pie_chart = {"pie_chart": "sample_pie_chart"}
            messages.append(
                {"role": "tool", "name": tool_name, "content": json.dumps(pie_chart)}
            )
    return messages
Ensuite, créez les gestionnaires d’outils pour chacun des sous-agents. Chacun reçoit un prompt et un ensemble d’outils qui lui sont propres, transmis au modèle. Le résultat est ensuite transmis à une fonction d’exécution qui exécute les appels d’outil. 
# Définir les fonctions pour gérer le traitement de chaque agent
@weave.op()
def handle_data_processing_agent(query, conversation_messages):
    messages = [{"role": "system", "content": processing_system_prompt}]
    messages.append({"role": "user", "content": query})

    response = client.chat.completions.create(
        model=MODEL,
        messages=messages,
        temperature=0,
        tools=preprocess_tools,
    )

    conversation_messages.append(
        [tool_call.function for tool_call in response.choices[0].message.tool_calls]
    )
    execute_tool(response.choices[0].message.tool_calls, conversation_messages)

@weave.op()
def handle_analysis_agent(query, conversation_messages):
    messages = [{"role": "system", "content": analysis_system_prompt}]
    messages.append({"role": "user", "content": query})

    response = client.chat.completions.create(
        model=MODEL,
        messages=messages,
        temperature=0,
        tools=analysis_tools,
    )

    conversation_messages.append(
        [tool_call.function for tool_call in response.choices[0].message.tool_calls]
    )
    execute_tool(response.choices[0].message.tool_calls, conversation_messages)

@weave.op()
def handle_visualization_agent(query, conversation_messages):
    messages = [{"role": "system", "content": visualization_system_prompt}]
    messages.append({"role": "user", "content": query})

    response = client.chat.completions.create(
        model=MODEL,
        messages=messages,
        temperature=0,
        tools=visualization_tools,
    )

    conversation_messages.append(
        [tool_call.function for tool_call in response.choices[0].message.tool_calls]
    )
    execute_tool(response.choices[0].message.tool_calls, conversation_messages)
Enfin, créez l’outil principal qui gère le traitement de la requête de l’utilisateur. Cette fonction prend la requête de l’utilisateur, obtient une réponse du modèle, puis la transmet aux autres agents pour qu’ils l’exécutent. 
# Fonction pour gérer les entrées utilisateur et le triage
@weave.op()
def handle_user_message(user_query, conversation_messages=None):
    if conversation_messages is None:
        conversation_messages = []
    user_message = {"role": "user", "content": user_query}
    conversation_messages.append(user_message)

    messages = [{"role": "system", "content": triaging_system_prompt}]
    messages.extend(conversation_messages)

    response = client.chat.completions.create(
        model=MODEL,
        messages=messages,
        temperature=0,
        tools=triage_tools,
    )

    conversation_messages.append(
        [tool_call.function for tool_call in response.choices[0].message.tool_calls]
    )

    for tool_call in response.choices[0].message.tool_calls:
        if tool_call.function.name == "send_query_to_agents":
            agents = json.loads(tool_call.function.arguments)["agents"]
            query = json.loads(tool_call.function.arguments)["query"]
            for agent in agents:
                if agent == "Data Processing Agent":
                    handle_data_processing_agent(query, conversation_messages)
                elif agent == "Analysis Agent":
                    handle_analysis_agent(query, conversation_messages)
                elif agent == "Visualization Agent":
                    handle_visualization_agent(query, conversation_messages)

    outputs = extract_tool_contents(conversation_messages)

    return outputs

functions = [
    "clean_data",
    "transform_data",
    "stat_analysis",
    "aggregate_data",
    "correlation_analysis",
    "regression_analysis",
    "create_bar_chart",
    "create_line_chart",
    "create_pie_chart",
]

@weave.op()
def extract_tool_contents(data):
    contents = {}
    contents["all"] = data
    for element in data:
        if (
            isinstance(element, dict)
            and element.get("role") == "tool"
            and element.get("name") in functions
        ):
            name = element["name"]
            content_str = element["content"]
            try:
                content_json = json.loads(content_str)
                if "chart" not in element.get("name"):
                    contents[name] = [content_json]
                else:
                    first_key = next(iter(content_json))
                    second_level = content_json[first_key]
                    if isinstance(second_level, dict):
                        second_key = next(iter(second_level))
                        contents[name] = second_level[second_key]
                    else:
                        contents[name] = second_level
            except json.JSONDecodeError:
                print(f"Error decoding JSON for {name}")
                contents[name] = None

    return contents

​
Exécutez le système multi-agent et visualisez-le dans Weave

Une fois tous les agents, outils et gestionnaires en place, le système est prêt à être exécuté. Enfin, exécutez la fonction principale handle_user_message à partir de l’entrée de l’utilisateur’ et observez les résultats. 
handle_user_message(user_query)
Lorsque vous cliquez sur l’URL Weave, vous pouvez voir la trace d’exécution. Sur la page Traces, vous pouvez consulter l’entrée et la sortie. Pour plus de clarté, l’illustration inclut des captures d’écran des résultats affichés lorsque vous cliquez sur chaque sortie. Weave s’intègre à l’API OpenAI et calcule automatiquement les coûts. Le coût et la latence sont également affichés pour chaque trace. Page Weave Traces montrant l’exécution multi-agent avec le coût et la latence Cliquez sur une ligne pour voir les processus intermédiaires exécutés au sein du système multi-agent. Par exemple, l’entrée et la sortie de analysis_agent apparaissent sous forme de sorties structurées. Les sorties structurées d’OpenAI aident les agents à collaborer, mais à mesure que le système gagne en complexité, le format de ces interactions devient plus difficile à suivre. Weave vous permet d’inspecter en détail ces processus intermédiaires ainsi que leurs entrées et sorties.
Détail d’une trace Weave montrant l’entrée et la sortie structurées de l’agent d’analyse
Examinez de plus près comment le tracing est géré dans Weave.

​
Conclusion

Dans ce tutoriel, vous avez appris à développer un système multi-agent à l’aide des sorties structurées d’OpenAI et de Weave pour suivre les entrées, les sorties finales et les formats de sortie intermédiaires. Vous disposez maintenant d’un exemple fonctionnel que vous pouvez enrichir avec des agents, des outils ou des schémas de réponse structurée supplémentaires.