feat: update agent generate endpoint response type [PIC-918] (#2882)

* feat: migrate agent generation endpoint to new response types

* fix: prettier issues

* feat: update language and jsdoc

Author: mshaaban0

lib/adapters/REST/endpoints/agent.ts

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

lib/common-types.ts

@@ -193,7 +193,11 @@ import type {
   AiActionInvocationType,
 } from './entities/ai-action-invocation'
 import type { AgentGeneratePayload, AgentProps } from './entities/agent'
-import type { AgentRunProps, AgentRunQueryOptions } from './entities/agent-run'
+import type {
+  AgentGenerateResponse,
+  AgentRunProps,
+  AgentRunQueryOptions,
+} from './entities/agent-run'
 import type {
   AutomationDefinitionProps,
   AutomationDefinitionQueryOptions,
@@ -1074,7 +1078,7 @@ export type MRActions = {
       params: GetSpaceEnvironmentParams & { agentId: string }
       payload: AgentGeneratePayload
       headers?: RawAxiosRequestHeaders
-      return: AgentRunProps
+      return: AgentGenerateResponse
     }
   }
   AgentRun: {

lib/create-environment-api.ts

@@ -101,7 +101,7 @@ export default function createEnvironmentApi(makeRequest: MakeRequest) {
   const { wrapBulkAction } = entities.bulkAction
   const { wrapAppAccessToken } = entities.appAccessToken
   const { wrapAgent, wrapAgentCollection } = entities.agent
-  const { wrapAgentRun, wrapAgentRunCollection } = entities.agentRun
+  const { wrapAgentRun, wrapAgentRunCollection, wrapAgentGenerateResponse } = entities.agentRun
   const { wrapResourceTypesForEnvironmentCollection } = entities.resourceType
   const { wrapResourceCollection } = entities.resource
   const { wrapSemanticDuplicates } = entities.semanticDuplicates
@@ -2987,31 +2987,38 @@ export default function createEnvironmentApi(makeRequest: MakeRequest) {
      * Generates content using an AI Agent
      * @param agentId - AI Agent ID
      * @param payload - Generation payload
-     * @return Promise for the generation response
+     * @return Promise for a simplified response containing `sys.id`, `sys.type`, and `sys.status`.
+     *         Use `getAgentRun()` with the returned `sys.id` to poll for full results.
      * @example ```javascript
      * const contentful = require('contentful-management')
      *
-     * const client = contentful.createClient({
-     *   accessToken: '<content_management_api_key>'
-     * })
+     * async function generateContent() {
+     *   const client = contentful.createClient({
+     *     accessToken: '<content_management_api_key>'
+     *   })
      *
-     * client.getSpace('<space_id>')
-     *   .then((space) => space.getEnvironment('<environment_id>'))
-     *   .then((environment) => environment.generateWithAgent('<agent_id>', {
+     *   const space = await client.getSpace('<space_id>')
+     *   const environment = await space.getEnvironment('<environment_id>')
+     *
+     *   // Start generation (returns 202 Accepted)
+     *   const response = await environment.generateWithAgent('<agent_id>', {
      *     messages: [
      *       {
-     *         parts: [
-     *           {
-     *             type: 'text',
-     *             text: 'Write a short poem about Contentful'
-     *           }
-     *         ],
+     *         parts: [{ type: 'text', text: 'Write a short poem about Contentful' }],
      *         role: 'user'
      *       }
      *     ]
-     *   }))
-     *   .then((result) => console.log(result))
-     *   .catch(console.error)
+     *   })
+     *
+     *   // Poll for full results
+     *   let run = await environment.getAgentRun(response.sys.id)
+     *   while (run.sys.status === 'IN_PROGRESS') {
+     *     await new Promise((resolve) => setTimeout(resolve, 1000))
+     *     run = await environment.getAgentRun(response.sys.id)
+     *   }
+     *
+     *   console.log(run)
+     * }
      * ```
      */
     generateWithAgent(agentId: string, payload: AgentGeneratePayload) {
@@ -3025,7 +3032,7 @@ export default function createEnvironmentApi(makeRequest: MakeRequest) {
           agentId,
         },
         payload,
-      }).then((data) => wrapAgentRun(makeRequest, data))
+      }).then((data) => wrapAgentGenerateResponse(makeRequest, data))
     },
 
     /**

lib/entities/agent-run.ts

@@ -5,6 +5,14 @@ import { wrapCollection } from '../common-utils'
 
 export type AgentRunStatus = 'IN_PROGRESS' | 'FAILED' | 'COMPLETED' | 'PENDING_REVIEW' | 'DRAFT'
 
+export type AgentGenerateResponse = {
+  sys: {
+    id: string
+    type: 'AgentRun'
+    status: AgentRunStatus
+  }
+}
+
 export type AgentRunMessageRole = 'system' | 'user' | 'assistant' | 'tool'
 
 export type AgentRunMessageTextPart = {
@@ -60,4 +68,12 @@ export function wrapAgentRun(_makeRequest: MakeRequest, data: AgentRunProps): Ag
   return freezeSys(agentRun)
 }
 
+export function wrapAgentGenerateResponse(
+  _makeRequest: MakeRequest,
+  data: AgentGenerateResponse,
+): AgentGenerateResponse {
+  const response = toPlainObject(copy(data))
+  return freezeSys(response)
+}
+
 export const wrapAgentRunCollection = wrapCollection(wrapAgentRun)

lib/entities/agent.ts

@@ -3,7 +3,7 @@ import copy from 'fast-copy'
 import type { DefaultElements, MakeRequest, MetaSysProps } from '../common-types'
 import { wrapCollection } from '../common-utils'
 import enhanceWithMethods from '../enhance-with-methods'
-import { wrapAgentRun, type AgentRun } from './agent-run'
+import { wrapAgentGenerateResponse, type AgentGenerateResponse } from './agent-run'
 
 export type AgentToolLink = {
   sys: {
@@ -44,7 +44,7 @@ export type AgentGeneratePayload<TMetadata = Record<string, unknown>> = {
 }
 
 export interface Agent extends AgentProps, DefaultElements<AgentProps> {
-  generate(payload: AgentGeneratePayload): Promise<AgentRun>
+  generate(payload: AgentGeneratePayload): Promise<AgentGenerateResponse>
 }
 
 function createAgentApi(makeRequest: MakeRequest) {
@@ -62,7 +62,7 @@ function createAgentApi(makeRequest: MakeRequest) {
         action: 'generate',
         params: getParams(self),
         payload,
-      }).then((data) => wrapAgentRun(makeRequest, data))
+      }).then((data) => wrapAgentGenerateResponse(makeRequest, data))
     },
   }
 }

lib/export-types.ts

@@ -14,6 +14,7 @@ export type { AiAction, AiActionProps, CreateAiActionProps } from './entities/ai
 export type { AiActionInvocation, AiActionInvocationProps } from './entities/ai-action-invocation'
 export type { Agent, AgentGeneratePayload, AgentProps, AgentToolLink } from './entities/agent'
 export type {
+  AgentGenerateResponse,
   AgentRun,
   AgentRunMessage,
   AgentRunMessagePart,

lib/plain/entities/agent.ts

@@ -1,7 +1,7 @@
 import type { RawAxiosRequestHeaders } from 'axios'
 import type { CollectionProp, GetSpaceEnvironmentParams, QueryParams } from '../../common-types'
 import type { AgentGeneratePayload, AgentProps } from '../../entities/agent'
-import type { AgentRunProps } from '../../entities/agent-run'
+import type { AgentGenerateResponse } from '../../entities/agent-run'
 import type { OptionalDefaults } from '../wrappers/wrap'
 
 export type AgentPlainClientAPI = {
@@ -28,12 +28,13 @@ export type AgentPlainClientAPI = {
    * @param params Entity IDs to identify the AI Agent.
    * @param payload The generation payload.
    * @param headers Optional headers for the request.
-   * @returns A promise resolving with the AI Agent generation response.
+   * @returns A promise resolving with a simplified response containing `sys.id`, `sys.type`, and `sys.status`.
+   *          Use `agentRun.get()` with the returned `sys.id` to poll for full results.
    * @throws if the request fails or the payload is malformed.
    */
   generate(
     params: OptionalDefaults<GetSpaceEnvironmentParams & { agentId: string }>,
     payload: AgentGeneratePayload,
     headers?: Partial<RawAxiosRequestHeaders>,
-  ): Promise<AgentRunProps>
+  ): Promise<AgentGenerateResponse>
 }

test/integration/agent-integration.test.ts

@@ -58,7 +58,9 @@ describe.skipIf(!process.env.API_INTEGRATION_TESTS)('Agent api', { sequential: t
         },
       ],
     })
-    expect(result.result).to.be.ok
+    expect(result.sys.id, 'sys.id').to.be.ok
+    expect(result.sys.type, 'sys.type').equals('AgentRun')
+    expect(result.sys.status, 'sys.status').to.be.ok
   })
 
   test('Get specific ai agent run', async () => {

test/unit/mocks/entities.ts

@@ -91,7 +91,7 @@ import {
   AiActionInvocationType,
 } from '../../../lib/entities/ai-action-invocation'
 import { AgentProps } from '../../../lib/entities/agent'
-import { AgentRunProps } from '../../../lib/entities/agent-run'
+import { AgentGenerateResponse, AgentRunProps } from '../../../lib/entities/agent-run'
 import {
   EmbeddingSetStatus,
   VectorizationStatusProps,
@@ -1022,6 +1022,14 @@ const agentRunMock: AgentRunProps = {
   ],
 }
 
+const agentGenerateResponseMock: AgentGenerateResponse = {
+  sys: {
+    id: 'mocked-agent-run-id',
+    type: 'AgentRun' as const,
+    status: 'IN_PROGRESS' as const,
+  },
+}
+
 const apiKeyMock: ApiKeyProps = {
   sys: Object.assign(cloneDeep(sysMock), {
     type: 'ApiKey',
@@ -1563,6 +1571,7 @@ const mocks = {
   aiActionInvocationPayload: aiActionInvocationPayloadMock,
   agent: agentMock,
   agentRun: agentRunMock,
+  agentGenerateResponse: agentGenerateResponseMock,
   apiKey: apiKeyMock,
   appAction: appActionMock,
   appActionCall: appActionCallMock,
@@ -1693,6 +1702,7 @@ function setupEntitiesMock() {
     agentRun: {
       wrapAgentRun: vi.fn(),
       wrapAgentRunCollection: vi.fn(),
+      wrapAgentGenerateResponse: vi.fn(),
     },
     appAction: {
       wrapAppAction: vi.fn(),

test/unit/plain/agent.test.ts

@@ -70,7 +70,11 @@ describe('Agent', () => {
 
   test('generate', async () => {
     const mockResponse = {
-      result: 'Generated response',
+      sys: {
+        id: 'generated-run-id',
+        type: 'AgentRun' as const,
+        status: 'IN_PROGRESS' as const,
+      },
     }
     const { httpMock, adapterMock } = setupRestAdapter(Promise.resolve({ data: mockResponse }))
     const plainClient = createClient({ apiAdapter: adapterMock }, { type: 'plain' })
@@ -89,7 +93,9 @@ describe('Agent', () => {
     const response = await plainClient.agent.generate({ spaceId, environmentId, agentId }, payload)
 
     expect(response).toBeInstanceOf(Object)
-    expect(response.result).toBe('Generated response')
+    expect(response.sys.id).toBe('generated-run-id')
+    expect(response.sys.type).toBe('AgentRun')
+    expect(response.sys.status).toBe('IN_PROGRESS')
 
     expect(httpMock.post).toHaveBeenCalledWith(
       `/spaces/${spaceId}/environments/${environmentId}/ai_agents/agents/${agentId}/generate`,