Sitecore Marketer MCP a deep dive - Agent API - Part 2

-

In our previous article , we explored the various tools available in the Sitecore Marketer MCP server. In this article, we will take a closer look at the Agent API, which serves as the core foundation behind the MCP server.

The Agent API enables AI agents to interact with a connected Sitecore instance and perform various operations through secure REST endpoints. These endpoints allow agents to execute actions such as retrieving information, updating content, or triggering specific actions within Sitecore.

When a marketer or developer interacts with a Large Language Model (LLM) that is connected to Sitecore through the MCP server, the LLM processes the request and then interacts with the Agent API, which in turn performs the required operations on the Sitecore instance.


Marketers usually interact with Sitecore using prompts through tools integrated with their IDE or marketing interfaces, while developers use the Agent API to build agentic workflows, automations, and integrations.

Getting started with Agent API:

To get started with the Agent API as a developer, the first step is to generate a JWT token, which is required to authenticate all REST API requests.
Follow the steps below to generate the token:

  • Goto SitecoreAI Deploy portal  SitecoreAI Deploy 
  • Create an automation credential for the project we like to connect with the Agent API




  • Once the credentials are created, let's generate the JWT token using the client Id and Client secret, which we got from the above steps.
    To generate the token, call the following REST endpoint:
    • Http POST: https://auth.sitecorecloud.io/oauth/token
    • Content-type:application/x-www-form-urlencoded


  • During this request, make sure the required scope for the Agent API is included. This scope is important for accessing the Agent API endpoints. If the required scope is not present in the generated token, you may need to contact Sitecore Support to enable the appropriate scope for your project.
  • Now that we have the JWT token ready, we can use it to execute the REST API in our agentic application or any custom application, like below.

The example above demonstrates how developers can directly connect to the Agent API using REST endpoints. However, there are other approaches developers can use when building agentic applications.

For example, when developing a Sitecore Marketplace application, a developer may need to create pages or upload any assets, etc. In such cases, developers can either call the Agent API directly using REST endpoints or use the Marketplace SDK, which already provides built-in capabilities for calling these APIs, as shown below.

 



Currently, the Agent API provides around 39 REST endpoints that developers can use to build applications interacting with a connected Sitecore instance. These APIs allow developers to perform various actions.

If a marketer interacts with Sitecore using prompts, the LLM will internally determine the appropriate tool to execute. That tool then calls the relevant Agent API endpoint to perform the required action in the Sitecore instance.

The table below lists the available Agent API endpoints details along with their corresponding Marketplace SDK Types for calling the Agent Api.

#GroupEndpoint URLSDK CallHTTP MethodEndpoint URLx-sc-job-id HeaderPath ParamsQuery ParamsBody FieldsResponse TypeType Name (from types.gen.d.ts)SDK Key (xmc.agent.*)
1Sites/api/v1/sitesqueryGET/api/v1/sitesOptional—sitecoreContextId?—ListSitesResponse
→ sites: SiteBasicModel[]
(id, name, targetHostname, rootPath)		SitesGetSitesListxmc.agent.sitesGetSitesList
2Sites/api/v1/sites/{siteId}queryGET/api/v1/sites/{siteId}OptionalsiteId: stringsitecoreContextId?—SiteInformationResponse
→ itemId, name, brand_information, rootPath
page_locations[], non_visual_content_locations[]		SitesGetSiteDetailsxmc.agent.sitesGetSiteDetails
3Sites/api/v1/sites/{siteName}/pagesqueryGET/api/v1/sites/{siteName}/pagesOptionalsiteName: stringlanguage?
sitecoreContextId?		—PageModel[]
→ id: string, path: string		SitesGetAllPagesBySitexmc.agent.sitesGetAllPagesBySite
4Sites/api/v1/sites/site-id-from-item/{itemId}queryGET/api/v1/sites/site-id-from-item/{itemId}OptionalitemId: stringsitecoreContextId?—SiteIdFromItemResponse
→ siteRootItemId, siteRootDisplayName, siteRootName		SitesGetSiteIdFromItemxmc.agent.sitesGetSiteIdFromItem
5Pages/api/v1/pages/createmutatePOST/api/v1/pages/createOptional—sitecoreContextId?templateId: string (required)
name: string (required)
parentId: string (required)
language?: string
fields?: Array<{[key]: unknown}>		CreatePageResponse
→ itemId: string, name: string		PagesCreatePagexmc.agent.pagesCreatePage
6Pages/api/v1/pages/{pageId}/add-languagemutatePOST/api/v1/pages/{pageId}/add-languageOptionalpageId: stringsitecoreContextId?language?: stringAddLanguageResponse
→ success: boolean		PagesAddLanguageToPagexmc.agent.pagesAddLanguageToPage
7Pages/api/v1/pages/{pageId}queryGET/api/v1/pages/{pageId}OptionalpageId: stringlanguage?
sitecoreContextId?		—GetPageResponse
→ itemId, name, templateId, locationPath
insertOptions: PageInsertOptionModel[]		PagesGetPagexmc.agent.pagesGetPage
8Pages/api/v1/pages/{pageId}/componentsqueryGET/api/v1/pages/{pageId}/componentsOptionalpageId: stringlanguage?: string | null
version?: number | null
sitecoreContextId?		—GetPageComponentsResponse
→ pageId, pageName, pagePath, version, language
components: ComponentModel[]		PagesGetComponentsOnPagexmc.agent.pagesGetComponentsOnPage
9Pages/api/v1/pages/{pageId}/componentsmutatePOST/api/v1/pages/{pageId}/componentsOptionalpageId: stringsitecoreContextId?componentRenderingId: string (required)
placeholderPath: string (required)
componentItemName: string (required)
language?: string
fields?: {[key]: unknown}		AddComponentResponse
→ componentId, pageId, placeholderId?, datasourceId?		PagesAddComponentOnPagexmc.agent.pagesAddComponentOnPage
10Pages/api/v1/pages/{pageId}/components/{componentId}/datasourcemutatePUT/api/v1/pages/{pageId}/components/{componentId}/datasourceOptionalpageId: string
componentId: string		sitecoreContextId?datasourceId: string (required)
language?: string | null		SetComponentDatasourceResponse
→ success, message, componentId, pageId, datasourceId		PagesSetComponentDatasourcexmc.agent.pagesSetComponentDatasource
11Pages/api/v1/pages/searchqueryGET/api/v1/pages/searchOptional—search_query: string (required)
site_name: string (required)
language?
sitecoreContextId?		—PageSearchItemModel[]
→ itemId, name, path, templateId, fields: FieldModel[]		PagesSearchSitexmc.agent.pagesSearchSite
12Pages/api/v1/pages/path-by-urlqueryGET/api/v1/pages/path-by-urlOptional—live_url: string (required)
sitecoreContextId?		—PagePathByLiveUrlResponse
→ itemId, name, hasPresentation, template, insertOptions[]		PagesGetPagePathByLiveUrlxmc.agent.pagesGetPagePathByLiveUrl
13Pages/api/v1/pages/{pageId}/screenshotqueryGET/api/v1/pages/{pageId}/screenshotOptionalpageId: stringversion: number (required)
language?
width?
height?
sitecoreContextId?		—PageScreenshotResponse
→ type, fullPage, encoding, timestamp, screenshot_base64		PagesGetPageScreenshotxmc.agent.pagesGetPageScreenshot
14Pages/api/v1/pages/{pageId}/htmlqueryGET/api/v1/pages/{pageId}/htmlOptionalpageId: stringlanguage: string (required)
version?: number | null
sitecoreContextId?		—PageHtmlResponse
→ pageId: string, html: string		PagesGetPageHtmlxmc.agent.pagesGetPageHtml
15Pages/api/v1/pages/{pageId}/preview-urlqueryGET/api/v1/pages/{pageId}/preview-urlOptionalpageId: stringlanguage?
version?: number | null
sitecoreContextId?		—GetPagePreviewUrlResponse
→ pageId: string, previewUrl: string		PagesGetPagePreviewUrlxmc.agent.pagesGetPagePreviewUrl
16Pages/api/v1/pages/template-by-idqueryGET/api/v1/pages/template-by-idOptional—templateId: string (required)
sitecoreContextId?		—PageTemplateResponse
→ templateId, name, fields: PageTemplateFieldModel[]		PagesGetPageTemplateByIdxmc.agent.pagesGetPageTemplateById
17Pages/api/v1/pages/{pageId}/placeholders/{placeholderName}/allowed-componentsqueryGET/api/v1/pages/{pageId}/placeholders/{placeholderName}/allowed-componentsOptionalpageId: string
placeholderName: string		language?: string | null
sitecoreContextId?		—ComponentShortInfo[]
→ id: string, name: string		PagesGetAllowedComponentsByPlaceholderxmc.agent.pagesGetAllowedComponentsByPlaceholder
18Content/api/v1/content/createmutatePOST/api/v1/content/createOptional—sitecoreContextId?templateId: string (required)
name: string (required)
parentId: string (required)
language?: string
fields?: {[key]: unknown}		CreateContentItemResponse
→ itemId, name, path, templateId, version		ContentCreateContentItemxmc.agent.contentCreateContentItem
19Content/api/v1/content/{itemId}queryGET/api/v1/content/{itemId}OptionalitemId: stringlanguage?: string | null
sitecoreContextId?		—ContentItemResponse
→ itemId, name, path, workflow?, children?, version?, template, fields?, created_at?, updated_at?		ContentGetContentItemByIdxmc.agent.contentGetContentItemById
20Content/api/v1/content/{itemId}mutatePUT/api/v1/content/{itemId}OptionalitemId: stringsitecoreContextId?fields?: {[key]: unknown}
language?: string
createNewVersion?: boolean
siteName?: string | null		UpdateContentResponse
→ itemId, name, path, updatedFields: {[key]: unknown}		ContentUpdateContentxmc.agent.contentUpdateContent
21Content/api/v1/content/{itemId}mutateDELETE/api/v1/content/{itemId}OptionalitemId: stringlanguage?
sitecoreContextId?		—DeleteContentResponse
→ success: boolean, deletedId: string		ContentDeleteContentxmc.agent.contentDeleteContent
22Content/api/v1/contentqueryGET/api/v1/contentOptional—item_path: string (required)
failOnNotFound?: boolean | null
language?: string | null
sitecoreContextId?		—ContentItemResponse | {[key]: unknown}ContentGetContentItemByPathxmc.agent.contentGetContentItemByPath
23Content/api/v1/content/{itemId}/insert-optionsqueryGET/api/v1/content/{itemId}/insert-optionsOptionalitemId: stringlanguage?
sitecoreContextId?		—InsertOptionModel[]
→ name: string, templateId: string		ContentListAvailableInsertoptionsxmc.agent.contentListAvailableInsertoptions
24Components/api/v1/componentsqueryGET/api/v1/componentsOptional—site_name: string (required)
sitecoreContextId?		—ComponentsResponse
→ components: Components
(groups: ComponentGroup[], ungrouped?: ComponentInfo[])		ComponentsListComponentsxmc.agent.componentsListComponents
25Components/api/v1/components/{componentId}queryGET/api/v1/components/{componentId}OptionalcomponentId: stringsitecoreContextId?—ComponentResponse
→ id, name, datasourceTemplateId, datasourceLocations[]
datasourceFields[], datasourceAutoGenerated, datasourceRequired		ComponentsGetComponentxmc.agent.componentsGetComponent
26Components/api/v1/components/{componentId}/datasourcesmutatePOST/api/v1/components/{componentId}/datasourcesOptionalcomponentId: stringsitecoreContextId?siteName: string (required)
dataFields: {[key]: unknown} (required)
children?: Array<{[key]: unknown}>
language?: string		CreateComponentDatasourceResponse
→ datasourceId: string, datasourceLocation: string		ComponentsCreateComponentDatasourcexmc.agent.componentsCreateComponentDatasource
27Components/api/v1/components/{componentId}/datasources/searchqueryGET/api/v1/components/{componentId}/datasources/searchOptionalcomponentId: stringterm: string (required)
sitecoreContextId?		—SearchResponse
→ results?: SearchResult[]
(itemId, templateId, name)		ComponentsSearchComponentDatasourcesxmc.agent.componentsSearchComponentDatasources
28Assets/api/v1/assets/uploadmutatePOST/api/v1/assets/uploadOptional—sitecoreContextId?file: Blob | File (required)
upload_request: string (required)
JSON with: name, itemPath, language, extension, siteName		UploadAssetResponse
→ success: boolean, mediaItem: MediaItem
(id, embedUrl, size, dimensions, extension)		AssetsUploadAssetxmc.agent.assetsUploadAsset
29Assets/api/v1/assets/searchqueryGET/api/v1/assets/searchOptional—query?: string | null
language?: string | null
type?: string | null
sitecoreContextId?		—AssetSearchResultModel[]
→ itemId, path, name, displayName?, type?, templateId, templateName, innerItem?		AssetsSearchAssetsxmc.agent.assetsSearchAssets
30Assets/api/v1/assets/{assetId}queryGET/api/v1/assets/{assetId}OptionalassetId: stringsitecoreContextId?—AssetInformationResponse
→ id, name?, type?, url?, size?, metadata?, innerItem?		AssetsGetAssetInformationxmc.agent.assetsGetAssetInformation
31Assets/api/v1/assets/{assetId}mutatePATCH/api/v1/assets/{assetId}OptionalassetId: stringsitecoreContextId?fields: {[key]: unknown} (required)
language: string (required)
name?: string | null
altText?: string | null		UpdateAssetResponse
→ itemId, name, path, updatedFields: {[key]: unknown}		AssetsUpdateAssetxmc.agent.assetsUpdateAsset
32Environments/api/v1/environments/languagesqueryGET/api/v1/environments/languagesOptional—sitecoreContextId?—LanguageModel[]
→ displayName: string, iso: string, name: string		EnvironmentsListLanguagesxmc.agent.environmentsListLanguages
33Personalization/api/v1/personalization/{pageId}/versionsmutatePOST/api/v1/personalization/{pageId}/versionsOptionalpageId: stringsitecoreContextId?name: string (required)
variant_name: string (required)
audience_name: string (required)
condition_template_id: string (required)
condition_params: {[key]: unknown} (required)
language?: string | null		FlowDefinitionResponse
→ clientKey, href, ref, name, status, type, subtype
traffic: FlowDefinitionTraffic, variants?, siteId		PersonalizationCreatePersonalizationVersionxmc.agent.personalizationCreatePersonalizationVersion
34Personalization/api/v1/personalization/by-page/{pageId}queryGET/api/v1/personalization/by-page/{pageId}OptionalpageId: stringlanguage?: string | null
sitecoreContextId?		—PersonalizationVariantDetailModel[]
→ page_id, variant_name, audience_name, template, condition_groups?		PersonalizationGetPersonalizationVersionsByPagexmc.agent.personalizationGetPersonalizationVersionsByPage
35Personalization/api/v1/personalization/condition-templatesqueryGET/api/v1/personalization/condition-templatesOptional—sitecoreContextId?—ConditionTemplate[]
→ href, ref, name, type, status, friendlyId, tags[]
templateElements[], additionalFields		PersonalizationGetConditionTemplatesxmc.agent.personalizationGetConditionTemplates
36Personalization/api/v1/personalization/condition-templates/{template_id}queryGET/api/v1/personalization/condition-templates/{template_id}Optionaltemplate_id: stringsitecoreContextId?—ConditionTemplatePersonalizationGetConditionTemplateByIdxmc.agent.personalizationGetConditionTemplateById
37Jobs/api/v1/jobs/{jobId}queryGET/api/v1/jobs/{jobId}—jobId: stringsitecoreContextId?—unknown (response schema not yet defined)JobsGetJobxmc.agent.jobsGetJob
38Jobs/api/v1/jobs/{jobId}/operationsqueryGET/api/v1/jobs/{jobId}/operations—jobId: stringsitecoreContextId?—unknown (response schema not yet defined)JobsListOperationsxmc.agent.jobsListOperations
39Jobs/api/v1/jobs/{jobId}/revertmutatePOST/api/v1/jobs/{jobId}/revert—jobId: stringsitecoreContextId?—unknown (response schema not yet defined)JobsRevertJobxmc.agent.jobsRevertJob
Let's learn and grow together, happy programming 😊

Comments

Post a Comment

Popular posts from this blog

Sitecore Search - API Crawler with Edge Pagination

-
Image
Sitecore Search provides different ways to index the items from 3rd party systems with the help of Source Connectors. There are different types of Source Connectors available: API Crawler API Push Feed Crawler Web Crawler Web Crawler(Advanced) I have provided more details here about the different sources for crawling different types of documents to get indexed into Sitecore Search. In this article, I would like to share the details about API Crawler in more real-time querying data and adding to the index. We have a scenario where I need to index all the items along with their placeholder components based on a specific template that has a layout assigned to it. I decided to utilize the Experience EDGE GraphQL Query to get the data and index it to Sitecore Search. We can use this for non-layout items as well. This article covers the following: GraphQL - Layout Query with Components GraphQL - Item Query GraphQL - Item Query with Pagination GraphQL - Search Query with Pagination Graph...
Read more

Sitecore Upgrade from 8.1 XP to 10.4 XM Scaled - Part 1

-
Image
 I have seen many questions about upgrading Sitecore from 8.1 to 10.4. I will share my experience upgrading Sitecore with tips and tricks that will help the upgrade process go smoothly. This contains multiple parts to get started with the upgrade activity. Steps for Sitecore and Solution Upgrade Checklist Sitecore 8.1 Local instance setup with Solr and verification Sitecore 10.4 Code upgrade issues and resolution Steps for Sitecore and Solution Upgrade Checklist: Solution Upgrade Checklist:   Task Comments / Findings Comments 1 .Net 4.8 upgrade to all the projects in the solution   2 Install SQL Server 2022   3 .NET Core 6.0 Windows Hosting Bundle   4 Install Compatible Solr version for 8.1 and 10.4   5 Update the Nuget package of Sitecore from 8.1 to 10.4 ...
Read more

Seamless Media Migration to XM Cloud: A Step-by-Step Guide from Sitecore XP 10.4 and Content Hub Integration - Part 1

-
Image
 We have been working with Sitecore and the media library for a long time. Now if the requirement comes from the client to use Sitecore Content Hub instead of Sitecore media library, and they are also planning to move  from Sitecore XP to XMCloud, then the following questions will pop up How to connect Sitecore Content Hub How to make sure all the Images in the Sitecore Media library are added to the Sitecore content hub  How can we add the Sitecont Content Hub assets public link to all the Images from the Media library referenced How to migrate all content from Sitecore XP to XM Cloud Let's explore the migration step by step as follows Connect Sitecore XP with Sitecore Content Hub Migrate all the Sitecore XP Media Items to Sitecore Content Hub Configure public link creation for all the assets migrated from the Sitecore media library Replace all the media item references with the public link of the assets Sitecore Content Hub integration with XM Cloud Migration of content...
Read more