Ga naar hoofdinhoud
SEMANTISCHE KERNEL INTEGRATIE

Semantic Kernel betalingsintegratie.

Geen Semantic Kernel-pakket nodig. Wikkel de echte blockchain0x-client in een KernelFunction (Python of Java), of roep de REST API aan vanuit een C# KernelFunction. Hoe dan ook verplaatst de agent USDC op Base.

KORTE ANTWOORD

Er is geen Semantic Kernel-pakket. In Python wikkel je de echte blockchain0x-client in een methode versierd met @kernel_function; in C#, waar geen .NET SDK wordt verzonden, roept een [KernelFunction] de REST API rechtstreeks aan. Registreer het op jouw kernel, stel FunctionChoiceBehavior in op Auto, en de agent kan USDC verplaatsen op Base. De verzonden kern SDK's zijn Node, Python, Ruby, Go, en JVM.

WAAROM SEMANTISCHE KERNEL

Het enige enterprise-grade .NET agentframework.

Als je stack Microsoft-vormig is (Azure, .NET, SQL Server, Teams, Copilot Studio), is Semantic Kernel vrijwel zeker het juiste agentframework. Het is gebouwd door Microsoft, het integreert met Azure OpenAI, AKS en Entra, en het heeft eersteklas ondersteuning voor .NET, Python en Java op een manier die geen ander framework evenaart. En het geeft je al hetgene dat je nodig hebt: een KernelFunction is gewoon een methode, dus het inbedden van betalingen is een methode die je schrijft, niet een pakket waar je op wacht.

Dat is waarom er geen Semantic Kernel-adapter te installeren is. In Python en Java wikkel je de echte blockchain0x SDK in een KernelFunction; in C#, waar nog geen .NET SDK wordt geleverd, roept de KernelFunction de REST API rechtstreeks aan met HttpClient. Je behoudt idiomatische ergonomie - versierde methoden, async, op attributen gebaseerde parameter validatie - en er is geen adapterversie om bij te houden. De kern SDK's die vandaag bestaan zijn Node, Python, Ruby, Go en JVM.

INSTALLATIE

Installeer Semantic Kernel en, in Python, de kern SDK.

Er is geen blockchain0x Semantic Kernel-pakket om toe te voegen. Python installeert Semantic Kernel plus de echte blockchain0x SDK; C# installeert Microsoft.SemanticKernel en roept de REST API aan met de ingebouwde HttpClient. Java gebruikt Semantic Kernel voor Java plus de com.blockchain0x:sdk-jvm SDK.

INSTALLEREN - PYTHON
pip install semantic-kernel blockchain0x
INSTALLEREN - .NET (Alleen Semantic Kernel)
dotnet add package Microsoft.SemanticKernel
OMGEVINGSVARIABLES
BLOCKCHAIN0X_API_KEY=sk_test_...   # sk_test_ = Base Sepolia, sk_live_ = Base mainnet
BLOCKCHAIN0X_API_KEY=sk_test_...             # same key, the name the .NET REST example reads
OPENAI_API_KEY=sk-...

BLOCKCHAIN0X_API_KEY (de Python-client leest dit) is een sk_test_ testnet- of sk_live_ mainnet-sleutel uit je dashboard; het C# REST-voorbeeld leest dezelfde waarde uit BLOCKCHAIN0X_API_KEY. OPENAI_API_KEY (of AZURE_OPENAI_* voor op Azure gehoste modellen) is je LLM-sleutel. De webhook-handler heeft daarnaast BLOCKCHAIN0X_WEBHOOK_SECRET nodig.

VOLLEDIGE AGENT VOORBEELDEN

Een portemonnee KernelFunction, in Python en C#.

Python wikkelt de echte blockchain0x-client in een methode versierd met @kernel_function. C#, waar geen .NET SDK wordt geleverd, exposeert een [KernelFunction] die POST /v1/payments rechtstreeks aanroept met HttpClient. Beide registreren op de kernel als Wallet.send_usdc; alleen de omringende ceremonie verschilt.

PYTHON (plugin.py)
from semantic_kernel import Kernel
from semantic_kernel.functions import kernel_function
from blockchain0x import Client

blockchain0x = Client()  # reads BLOCKCHAIN0X_API_KEY from the environment

class WalletPlugin:
    @kernel_function(description="Send a USDC payment from an agent wallet.")
    def send_usdc(self, agent_id: str, to: str, amount_wei: str) -> str:
        # amount_wei is USDC base units (6 decimals): "10000" = 0.01 USDC
        return str(
            blockchain0x.payments.create(body={"agentId": agent_id, "to": to, "amountWei": amount_wei})
        )

kernel = Kernel()
kernel.add_plugin(WalletPlugin(), plugin_name="Wallet")
# Add your chat service, then let the model call Wallet.send_usdc.
.NET (WalletPlugin.cs)
using System.ComponentModel;
using System.Net.Http.Json;
using Microsoft.SemanticKernel;

// There is no .NET SDK, so a C# KernelFunction calls the REST API directly.
public class WalletPlugin
{
    private static readonly HttpClient Http = new()
    {
        BaseAddress = new Uri("https://api.blockchain0x.com"),
    };

    [KernelFunction, Description("Send a USDC payment from an agent wallet. amountWei is USDC base units (6 decimals).")]
    public async Task<string> SendUsdc(string agentId, string to, string amountWei)
    {
        Http.DefaultRequestHeaders.Authorization =
            new("Bearer", Environment.GetEnvironmentVariable("BLOCKCHAIN0X_API_KEY"));
        var res = await Http.PostAsJsonAsync("/v1/payments", new { agentId, to, amountWei });
        return await res.Content.ReadAsStringAsync();
    }
}

// builder.Plugins.AddFromType<WalletPlugin>("Wallet");

Register the function on the kernel, set FunctionChoiceBehavior to Auto, and when the user's message implies a payment the model calls Wallet.send_usdc with the agent id, recipient, and amount. amountWei is base units, so 0.01 USDC is "10000". The Python path returns the SDK result; the C# path returns the REST response body.

WEBHOOK AFHANDELING

ASP.NET Core minimale API voor het ontvangen van betalingsgebeurtenissen.

Wanneer een betaling wordt afgehandeld, POST Blockchain0x een ondertekende gebeurtenis naar je webhook-URL. Er is geen geleverde .NET-verifier, dus de handler verifieert met de hand tegen de gedocumenteerde HMAC - wat een helper ook zou doen. .NET-voorbeeld hieronder; Python en Java verifiëren op dezelfde manier met hun eigen HMAC-bibliotheken.

WEBHOOK.CS
using System.Security.Cryptography;
using System.Text;
using Microsoft.AspNetCore.Builder;

var app = WebApplication.CreateBuilder(args).Build();
var secret = Environment.GetEnvironmentVariable("BLOCKCHAIN0X_WEBHOOK_SECRET")!;

app.MapPost("/webhooks/payment", async (HttpRequest req) =>
{
    using var reader = new StreamReader(req.Body);
    var raw = await reader.ReadToEndAsync(); // RAW body - verify before parsing
    var sig = req.Headers["X-Blockchain0x-Signature"].ToString();
    var ts = req.Headers["X-Blockchain0x-Timestamp"].ToString();

    var parts = sig.Split(',').Select(p => p.Split('=', 2))
        .Where(p => p.Length == 2).ToDictionary(p => p[0], p => p[1]);
    var t = parts.GetValueOrDefault("t", ts);
    var v1 = parts.GetValueOrDefault("v1", sig);

    var want = Convert.ToHexString(new HMACSHA256(Encoding.UTF8.GetBytes(secret))
        .ComputeHash(Encoding.UTF8.GetBytes($"{t}.{raw}"))).ToLowerInvariant();
    var fresh = Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - long.Parse(t)) <= 300;
    if (!fresh || !CryptographicOperations.FixedTimeEquals(
            Encoding.UTF8.GetBytes(want), Encoding.UTF8.GetBytes(v1)))
        return Results.Unauthorized();

    if (req.Headers["X-Blockchain0x-Event-Type"] == "payment.received")
        await RunFollowupAsync(); // USDC landed - do the next step
    return Results.Ok();
});

app.Run();

Het algoritme is HMAC-SHA256 over de string t.rawBody, een replayvenster van 300 seconden, en een constante tijdsvergelijking. Lees het ruwe lichaam via StreamReader zodat de handtekening intact blijft; deserialiseer niet en serializeer dan opnieuw. De verzonden evenementen zijn payment.received, payment.sent, wallet.deployed, en webhook.test. In productie draait de webhook vaak als een aparte ASP.NET Core-service die een database deelt met de agent, zodat de twee kunnen coördineren.

BRON EN DOCUMENTEN

De SDK's en het REST-oppervlak zijn open. Lees ze.

Er is geen Semantic Kernel starter package om te klonen - de bovenstaande recipes zijn de integratie. De core SDKs van blockchain0x (Node, Python, Ruby, Go) zijn open source op GitHub, en hun method surface plus de REST routes die het C# example aanroept zijn gedocumenteerd in de docs.

docs.blockchain0x.com/docs/overview

De methoden van de SDK en de REST routes zijn gedocumenteerd in de docs. Begin met een sk_test_ key op Base Sepolia en schakel daarna over naar sk_live_ wanneer de KernelFunction doet wat je verwacht.

GEMEENSCHAPPELIJKE VALKUILEN

Vijf Semantic Kernel-specifieke valkuilen om te vermijden.

Het pluginmodel van Semantic Kernel is schoon, maar heeft valkuilen met betrekking tot taaloverstijging en gedragsstandaarden. Dit van tevoren weten bespaart tijd.

PITFALL 1

Er is geen Semantic Kernel-pakket, in welke taal dan ook

Er is geen NuGet-, PyPI- of Maven-adapter. De verzonden kern SDK's zijn Node, Python, Ruby, Go, en JVM - niet .NET. Dus een Python-kernel wikkelt de blockchain0x Python-client in een @kernel_function, een Java-kernel gebruikt de com.blockchain0x:sdk-jvm SDK, en een C#-kernel roept de REST API rechtstreeks aan vanuit een KernelFunction (hierboven getoond). Alle drie zijn het een paar regels.

PITFALL 2

FunctionChoiceBehavior moet Auto zijn

Semantic Kernel roept alleen pluginfuncties aan wanneer FunctionChoiceBehavior is ingesteld op Auto in de instellingen voor prompt-uitvoering. De standaardinstelling is Geen, dus het model roept nooit je walletfunctie aan, ongeacht hoe duidelijk de gebruiker vraagt. Als de agent de functie volledig negeert, controleer dit dan eerst.

PITFALL 3

Bedragen zijn USDC basis eenheden, als strings

The payments call takes amountWei: a string of USDC base units (6 decimals), so 0.01 USDC is "10000" and 5 USDC is "5000000". Type the function argument as a string in any language. payments.create also does not retry by default and can answer 503 until the chain adapter is wired for your network - return a clear message rather than letting the agent loop.

PITFALL 4

Plugin scope over agents

Registreer de walletfunctie alleen op de kernel van de agent die de uitgavenautoriteit moet hebben. De plugin is niet globaal - een agent wiens kernel het niet heeft, kan het niet aanroepen. Geef een beoordelingsagent een kernel zonder de walletfunctie, of beperk de toegestane functies per agent, zodat geld bij één rol blijft.

PITFALL 5

Verifieer webhooks tegen de ruwe body

Lees het ruwe aanvraaglichaam en verifieer voordat je deserialiseert - de HMAC dekt de exacte bytes, dus een parse-then-reserialize rondreis breekt het. De .NET-handler hieronder implementeert het gedocumenteerde algoritme: HMAC-SHA256 over t.rawBody, een venster van 300 seconden en een constante tijdsvergelijking. Python en Java verifiëren op dezelfde manier met hun eigen HMAC-bibliotheken.

VAKANT VRAAG

Drie Semantic Kernel-specifieke vragen.

Is er een Semantic Kernel-pakket om te installeren (NuGet, PyPI of Maven)?

Nee. Het eerlijke pad hangt af van uw taal. Python Semantic Kernel wikkelt de echte blockchain0x Python-client in een @kernel_function, zoals hierboven weergegeven. Java Semantic Kernel gebruikt de com.blockchain0x:sdk-jvm SDK binnen een KernelFunction. C# en de andere .NET-talen hebben geen blockchain0x SDK - de verzonden kern-SDK's zijn Node, Python, Ruby, Go en JVM - dus een .NET KernelFunction roept de REST API rechtstreeks aan, ook hierboven weergegeven. De enige verzonden framework-pakketten zijn blockchain0x-langchain en blockchain0x-crewai (beide Python) plus de @blockchain0x/mcp-server.

Waarom is er een .NET SDK-kloof, en is dat een probleem?

Het is gewoon waar de SDK-roadmap vandaag is: Node, Python, Ruby, Go en JVM worden geleverd, .NET nog niet. Het is geen blokkade. De REST API is gewone JSON over HTTPS met bearer-token-authenticatie, en een C# KernelFunction die POST /v1/payments (hierboven) aanroept, is een handvol regels met HttpClient. Als een eersteklas .NET SDK belangrijk voor je is, laat het ons weten en we zullen het afwegen tegen de vraag.

Werkt dit met het Agent Framework en Microsoft 365 Copilot?

Ja. De portemonnee functie is een gewone Semantic Kernel functie, dus het werkt in enkele ChatCompletionAgent runs en in AgentGroupChat orchestraties - registreer het alleen op de kernel van de factureringsagent en laat de anderen werk doen nadat de betaling is afgehandeld. Microsoft 365 Copilot extensies die Semantic Kernel onder de motorkap draaien kunnen het op dezelfde manier registreren; breng de betaling naar de gebruiker met je eigen UI. Er is geen Copilot-specifiek pakket; het is hetzelfde recept.

Voeg facturering toe aan je SK-agent.

Een KernelFunction over de echte client of de REST API, geen pakket om te installeren. Gratis om te beginnen.