feat: add agents and agent runs [PIC-828]

README.md

@@ -162,7 +162,7 @@ const client = contentful.createClient(
     // This is the access token for this space. Normally you get the token in the Contentful web app
     accessToken: 'YOUR_ACCESS_TOKEN',
   },
-  { type: 'plain' }
+  { type: 'plain' },
 )
 //....
 ```
@@ -177,7 +177,7 @@ const plainClient = contentful.createClient(
   {
     accessToken: 'YOUR_ACCESS_TOKEN',
   },
-  { type: 'plain' }
+  { type: 'plain' },
 )
 
 const environment = await plainClient.environment.get({
@@ -205,7 +205,7 @@ const scopedPlainClient = contentful.createClient(
       spaceId: '<space_id>',
       environmentId: '<environment_id>',
     },
-  }
+  },
 )
 
 // entries from '<space_id>' & '<environment_id>'
@@ -232,18 +232,19 @@ The benefits of using the "plain" version of the client, over the legacy version
 Cursor-based pagination is supported on collection endpoints for content types, entries, and assets. To use cursor-based pagination, use the related entity methods `getAssetsWithCursor`, `getContentTypesWithCursor`, and `getEntriesWithCursor`
 
 ```js
-const response = await environment.getEntriesWithCursor({ limit: 10 });
-console.log(response.items); // Array of items
-console.log(response.pages?.next); // Cursor for next page
+const response = await environment.getEntriesWithCursor({ limit: 10 })
+console.log(response.items) // Array of items
+console.log(response.pages?.next) // Cursor for next page
 ```
+
 Use the value from `response.pages.next` to fetch the next page.
 
 ```js
 const secondPage = await environment.getEntriesWithCursor({
   limit: 2,
   pageNext: response.pages?.next,
-});
-console.log(secondPage.items); // Array of items
+})
+console.log(secondPage.items) // Array of items
 ```
 
 ## Legacy Client Interface
@@ -298,7 +299,7 @@ contentfulApp.init((sdk) => {
         environmentId: sdk.ids.environmentAlias ?? sdk.ids.environment,
         spaceId: sdk.ids.space,
       },
-    }
+    },
   )
 
   // ...rest of initialization code
@@ -444,9 +445,11 @@ To download a build that has features that are not yet released, you can use the
 npm install contentful-management@canary
 ```
 
+In addition, there may be some experimental features in the main build of this SDK that are subject to breaking changes without notice, which are listed below:
+
 ### Current experimental features
 
-Currently there are no features in experimental status.
+- **AI Agents**: The Agent and Agent Run APIs (`getAgent`, `getAgents`, `getAgentRun`, `getAgentRuns`, `generateWithAgent`) are experimental and subject to breaking changes without notice.
 
 ## Reach out to us
 

lib/adapters/REST/endpoints/agent-run.ts

@@ -0,0 +1,45 @@
+import type { RawAxiosRequestHeaders } from 'axios'
+import type { AxiosInstance } from 'contentful-sdk-core'
+import type { CollectionProp, GetSpaceEnvironmentParams } from '../../../common-types'
+import type { AgentRunProps, AgentRunQueryOptions } from '../../../entities/agent-run'
+import type { RestEndpoint } from '../types'
+import * as raw from './raw'
+
+const AgentRunAlphaHeaders = {
+  'x-contentful-enable-alpha-feature': 'agents',
+}
+
+export const get: RestEndpoint<'AgentRun', 'get'> = (
+  http: AxiosInstance,
+  params: GetSpaceEnvironmentParams & { runId: string },
+  headers?: RawAxiosRequestHeaders,
+) => {
+  return raw.get<AgentRunProps>(
+    http,
+    `/spaces/${params.spaceId}/environments/${params.environmentId}/ai_agents/runs/${params.runId}`,
+    {
+      headers: {
+        ...AgentRunAlphaHeaders,
+        ...headers,
+      },
+    },
+  )
+}
+
+export const getMany: RestEndpoint<'AgentRun', 'getMany'> = (
+  http: AxiosInstance,
+  params: GetSpaceEnvironmentParams & { query?: AgentRunQueryOptions },
+  headers?: RawAxiosRequestHeaders,
+) => {
+  return raw.get<CollectionProp<AgentRunProps>>(
+    http,
+    `/spaces/${params.spaceId}/environments/${params.environmentId}/ai_agents/runs`,
+    {
+      params: params.query,
+      headers: {
+        ...AgentRunAlphaHeaders,
+        ...headers,
+      },
+    },
+  )
+}

lib/adapters/REST/endpoints/agent.ts

@@ -0,0 +1,64 @@
+import type { RawAxiosRequestHeaders } from 'axios'
+import type { AxiosInstance } from 'contentful-sdk-core'
+import type { CollectionProp, GetSpaceEnvironmentParams, QueryParams } from '../../../common-types'
+import type { AgentGeneratePayload, AgentProps } from '../../../entities/agent'
+import type { AgentRunProps } from '../../../entities/agent-run'
+import type { RestEndpoint } from '../types'
+import * as raw from './raw'
+
+const AgentAlphaHeaders = {
+  'x-contentful-enable-alpha-feature': 'agents',
+}
+
+export const get: RestEndpoint<'Agent', 'get'> = (
+  http: AxiosInstance,
+  params: GetSpaceEnvironmentParams & { agentId: string },
+  headers?: RawAxiosRequestHeaders,
+) => {
+  return raw.get<AgentProps>(
+    http,
+    `/spaces/${params.spaceId}/environments/${params.environmentId}/ai_agents/agents/${params.agentId}`,
+    {
+      headers: {
+        ...AgentAlphaHeaders,
+        ...headers,
+      },
+    },
+  )
+}
+
+export const getMany: RestEndpoint<'Agent', 'getMany'> = (
+  http: AxiosInstance,
+  params: GetSpaceEnvironmentParams,
+  headers?: RawAxiosRequestHeaders,
+) => {
+  return raw.get<CollectionProp<AgentProps>>(
+    http,
+    `/spaces/${params.spaceId}/environments/${params.environmentId}/ai_agents/agents`,
+    {
+      headers: {
+        ...AgentAlphaHeaders,
+        ...headers,
+      },
+    },
+  )
+}
+
+export const generate: RestEndpoint<'Agent', 'generate'> = (
+  http: AxiosInstance,
+  params: GetSpaceEnvironmentParams & { agentId: string },
+  data: AgentGeneratePayload,
+  headers?: RawAxiosRequestHeaders,
+) => {
+  return raw.post<AgentRunProps>(
+    http,
+    `/spaces/${params.spaceId}/environments/${params.environmentId}/ai_agents/agents/${params.agentId}/generate`,
+    data,
+    {
+      headers: {
+        ...AgentAlphaHeaders,
+        ...headers,
+      },
+    },
+  )
+}

lib/adapters/REST/endpoints/index.ts

@@ -1,5 +1,7 @@
 import * as AiAction from './ai-action'
 import * as AiActionInvocation from './ai-action-invocation'
+import * as Agent from './agent'
+import * as AgentRun from './agent-run'
 import * as AccessToken from './access-token'
 import * as ApiKey from './api-key'
 import * as AppAccessToken from './app-access-token'
@@ -75,6 +77,8 @@ import * as WorkflowsChangelog from './workflows-changelog'
 export default {
   AiAction,
   AiActionInvocation,
+  Agent,
+  AgentRun,
   ApiKey,
   AppAction,
   AppActionCall,

lib/common-types.ts

@@ -191,6 +191,8 @@
   AiActionInvocationProps,
   AiActionInvocationType,
 } from './entities/ai-action-invocation'
+import type { AgentGeneratePayload, AgentProps } from './entities/agent'
+import type { AgentRunProps, AgentRunQueryOptions } from './entities/agent-run'
 import type {
   UpdateVectorizationStatusProps,
   VectorizationStatusProps,
@@ -264,7 +266,7 @@
   select?: string
   links_to_entry?: string
 
   [key: string]: any
 }
 
 export interface SpaceQueryOptions extends PaginationQueryOptions {
@@ -458,6 +460,13 @@
 
   (opts: MROpts<'AiActionInvocation', 'get', UA>): MRReturn<'AiActionInvocation', 'get'>
 
+  (opts: MROpts<'Agent', 'get', UA>): MRReturn<'Agent', 'get'>
+  (opts: MROpts<'Agent', 'getMany', UA>): MRReturn<'Agent', 'getMany'>
+  (opts: MROpts<'Agent', 'generate', UA>): MRReturn<'Agent', 'generate'>
+
+  (opts: MROpts<'AgentRun', 'get', UA>): MRReturn<'AgentRun', 'get'>
+  (opts: MROpts<'AgentRun', 'getMany', UA>): MRReturn<'AgentRun', 'getMany'>
+
   (opts: MROpts<'AppAction', 'get', UA>): MRReturn<'AppAction', 'get'>
   (opts: MROpts<'AppAction', 'getMany', UA>): MRReturn<'AppAction', 'getMany'>
   (opts: MROpts<'AppAction', 'delete', UA>): MRReturn<'AppAction', 'delete'>
@@ -1033,6 +1042,36 @@
       return: AiActionInvocationProps
     }
   }
+  Agent: {
+    get: {
+      params: GetSpaceEnvironmentParams & { agentId: string }
+      headers?: RawAxiosRequestHeaders
+      return: AgentProps
+    }
+    getMany: {
+      params: GetSpaceEnvironmentParams
+      headers?: RawAxiosRequestHeaders
+      return: CollectionProp<AgentProps>
+    }
+    generate: {
+      params: GetSpaceEnvironmentParams & { agentId: string }
+      payload: AgentGeneratePayload
+      headers?: RawAxiosRequestHeaders
+      return: AgentRunProps
+    }
+  }
+  AgentRun: {
+    get: {
+      params: GetSpaceEnvironmentParams & { runId: string }
+      headers?: RawAxiosRequestHeaders
+      return: AgentRunProps
+    }
+    getMany: {
+      params: GetSpaceEnvironmentParams & { query?: AgentRunQueryOptions }
+      headers?: RawAxiosRequestHeaders
+      return: CollectionProp<AgentRunProps>
+    }
+  }
   AppAction: {
     get: { params: GetAppActionParams; return: AppActionProps }
     getMany: {