Intégrations IA

Trois façons d'intégrer Paylet dans un agent autonome : en appel HTTP direct, via le function calling d'OpenAI, ou comme outil LangChain. Chaque exemple est complet et exécutable.

Prérequis

  • Une clé API Paylet avec le scope write:payment (variable d'environnement PAYLET_API_KEY).
  • Pour les exemples b et c : une clé OPENAI_API_KEY.
  • Dépendances : pip install openai langchain langchain-openai (Python) ou npm install openai langchain @langchain/openai @langchain/core zod (TypeScript).

Méthode A — Appel HTTP direct, sans framework

La méthode la plus simple : un script qui paie une ressource à la volée, sans passer par un orchestrateur d'agent. Le SDK gère le flux 402 de bout en bout.

import os
from paylet import Paylet

# Agent minimal : paie un appel API à la volée, sans framework d'agent.
client = Paylet(os.environ["PAYLET_API_KEY"])

def call_paid_api(url: str):
    # Le 402 est géré automatiquement : challenge réglé + rejeu avec reçu.
    return client.fetch_paid("GET", url)

if __name__ == "__main__":
    data = call_paid_api("https://vendor.example.com/data/42")
    print(data)

Résultat : l'agent reçoit directement le contenu payant (200 OK) sans intervention humaine.

Méthode B — Function calling OpenAI

On expose le paiement comme une fonction que le modèle peut appeler quand il estime avoir besoin d'une ressource payante. L'agent décide lui-même du moment du paiement.

import json
import os
from openai import OpenAI
from paylet import Paylet

paylet = Paylet(os.environ["PAYLET_API_KEY"])
openai_client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

def pay_for_resource(url: str) -> dict:
    """Paie l'accès à une ressource payante (flux x402) et renvoie son contenu."""
    return paylet.fetch_paid("GET", url)

tools = [
    {
        "type": "function",
        "function": {
            "name": "pay_for_resource",
            "description": "Paie l'accès à une ressource API payante via Paylet et renvoie son contenu.",
            "parameters": {
                "type": "object",
                "properties": {
                    "url": {"type": "string", "description": "URL de la ressource payante"}
                },
                "required": ["url"],
            },
        },
    }
]

def run_agent(prompt: str) -> str:
    messages = [{"role": "user", "content": prompt}]
    response = openai_client.chat.completions.create(
        model="gpt-4o",
        messages=messages,
        tools=tools,
        tool_choice="auto",
    )
    message = response.choices[0].message

    if message.tool_calls:
        messages.append(message)
        for call in message.tool_calls:
            if call.function.name == "pay_for_resource":
                args = json.loads(call.function.arguments)
                result = pay_for_resource(args["url"])
                messages.append({
                    "role": "tool",
                    "tool_call_id": call.id,
                    "content": json.dumps(result),
                })
        response = openai_client.chat.completions.create(
            model="gpt-4o",
            messages=messages,
        )
        return response.choices[0].message.content

    return message.content

if __name__ == "__main__":
    print(run_agent("Récupère les données du jeu de données 42 et résume-les."))

Gardez le contrôle de la dépense

Avec le function calling, le modèle décide de déclencher un paiement. Ajoutez systématiquement un garde-fou : budget maximum, liste blanche d'URL, ou confirmation humaine au-delà d'un seuil. Le solde est prépayé, donc le risque est plafonné, mais il reste réel.

Méthode C — Outil LangChain

Enfin, Paylet s'intègre naturellement comme outil dans un agent LangChain, pour un agent capable de raisonner, d'appeler des outils et de payer dans la même boucle.

import os
from langchain_openai import ChatOpenAI
from langchain_core.tools import tool
from langchain.agents import AgentExecutor, create_tool_calling_agent
from langchain_core.prompts import ChatPromptTemplate
from paylet import Paylet

paylet = Paylet(os.environ["PAYLET_API_KEY"])

@tool
def pay_for_resource(url: str) -> dict:
    """Paie l'accès à une ressource API payante via Paylet (flux x402) et renvoie son contenu."""
    return paylet.fetch_paid("GET", url)

llm = ChatOpenAI(model="gpt-4o", temperature=0)

prompt = ChatPromptTemplate.from_messages([
    ("system", "Tu es un agent capable de payer des ressources API via Paylet."),
    ("human", "{input}"),
    ("placeholder", "{agent_scratchpad}"),
])

agent = create_tool_calling_agent(llm, [pay_for_resource], prompt)
executor = AgentExecutor(agent=agent, tools=[pay_for_resource], verbose=True)

result = executor.invoke({"input": "Récupère les données du jeu de données 42 et résume-les."})
print(result["output"])

Résultat attendu

Dans les trois méthodes, la mécanique de paiement est identique : la ressource payante renvoie d'abord un 402, le challenge est réglé via POST /v1/payments, puis la requête est rejouée avec le reçu signé. L'agent obtient finalement le contenu, et chaque transaction est traçable dans votre grand livre.