PINGWorks.SitecoreExperienceEdge.AgentSDK 1.1.0

PINGWorks.SitecoreExperienceEdge.AgentSDK

This is a .NET SDK for working with Sitecore's Experience Edge Agent API.<br /> More information about Sitecore's API is at Agent API Doc (official)

Features

• Typed, DI-friendly services for interacting with the Sitecore Agent API
• Async-first APIs with CancellationToken support and full XML documentation comments
• NetStandard 2.1 for wide compatibility
• Automatic token maintenance using client credentials flow
• x-sc-job-id header support on all operations for tracing and reverting agent actions

Getting started

Prerequisites

To work with the SDK you will require credentials which are created in the SitecoreAI Deployment Portal.

Create an Environment credential of type Automation for the project and environment combination for which you wish to grant access.

Install

From your project directory:

dotnet add package PINGWorks.SitecoreExperienceEdge.AgentSDK

AppSettings

Properties are available to configure the SDK through configuration binding. The snippet below shows all options along with their default values. You do not need to include values where you wish to use the defaults.

{
	/* The base URL of the Agent API */
	"ServiceEndpoint": "https://edge-platform.sitecorecloud.io/stream/ai-agent-api/",

	/* The URL of the Token Request API */
	"TokenEndpoint": "https://auth.sitecorecloud.io/oauth/token",

	/* The auth audience */
	"Audience": "https://api.sitecorecloud.io",

	/* The auth grant type */
	"GrantType": "client_credentials",

	/* The value of ClientID from the SitecoreAI Deploy Portal */
	"ClientID": "[Created in SitecoreAI Deploy portal's Credentials pane]",

	/* The value of ClientSecret from the SitecoreAI Deploy Portal */
	"ClientSecret": "[Created in SitecoreAI Deploy portal's Credentials pane]"
}

We recommend the use of Visual Studio's User Secrets feature to store sensitive information such as ClientId and ClientSecret during development.

Register services

Register the SDK in Program.cs, e.g. when using the minimal hosting model:

// Program.cs
var builder = WebApplication.CreateBuilder(args);

// Register SDK services - set options through binding or manually
builder.Services.AddSitecoreEEAgentApi( opt => config.GetSection( "mySettings" ).Bind( opt ) );

HttpClient defaults. This call (via AddSitecoreEECommon) applies AddStandardResilienceHandler() and a DEBUG-only console request/response logger to every HttpClient in your container — not just the SDK's own. See the PINGWorks.SitecoreExperienceEdge.Common README for how to customize the resilience options per-client.

This library uses Json serialization through System.Text.Json.

Using job IDs

The Agent API supports a x-sc-job-id header on all operations. When provided, the job ID is used by Sitecore to group operations so they can be traced, audited, and reverted as a unit.

var jobId = $"job-{Guid.NewGuid()}";

// All operations with the same jobId can be reverted together
await sdk.CreatePage( request, jobId );
await sdk.AddComponentToPage( pageId, componentRequest, jobId );

// Undo everything in the job
await sdk.RevertJob( jobId );

Available services

The SDK exposes a composite interface ISitecoreAgentSdk as well as 10 focused resource-group interfaces. Inject the composite for full API access, or inject individual interfaces for narrower dependencies.

Composite interface ISitecoreAgentSdk

Extends all 10 resource interfaces. Use when a single component needs access to multiple API groups.

ISitecoreAgentSitesSdk

ISitecoreAgentPagesSdk

ISitecoreAgentContentSdk

ISitecoreAgentComponentsSdk

ISitecoreAgentAssetsSdk

ISitecoreAgentEnvironmentsSdk

ISitecoreAgentPersonalizationSdk

ISitecoreAgentJobsSdk

ISitecoreAgentBrandKitsSdk

ISitecoreAgentBriefsSdk