Skip to content

Commit 92ba55d

Browse files
elliotmassenelliotmassen
authored
feat: add agents and agent runs [PIC-828] (#2852)
* feat: add agents and agent runs * fix: skip agent API tests in CI for approved space IDs * fix: rename parameter in wrapAgentRun function for clarity * fix: remove unused query parameter from getMany method * fix: update AgentGenerateResponse type to include threadId * fix: make messages property required in AgentRunProps type * fix: remove limit parameter from getMany request in agent tests * fix: update types to replace AgentGenerateResponse with AgentRunProps * fix: remove AgentRunMessageType from agent-run types * docs: update README to include information on experimental agents and agent runs endpoints * fix: update alpha feature header to use 'agents-api'
1 parent d141cd1 commit 92ba55d

21 files changed

Lines changed: 1127 additions & 10 deletions

‎README.md‎

Lines changed: 13 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -162,7 +162,7 @@ const client = contentful.createClient(
162162
// This is the access token for this space. Normally you get the token in the Contentful web app
163163
accessToken: 'YOUR_ACCESS_TOKEN',
164164
},
165-
{ type: 'plain' }
165+
{ type: 'plain' },
166166
)
167167
//....
168168
```
@@ -177,7 +177,7 @@ const plainClient = contentful.createClient(
177177
{
178178
accessToken: 'YOUR_ACCESS_TOKEN',
179179
},
180-
{ type: 'plain' }
180+
{ type: 'plain' },
181181
)
182182

183183
const environment = await plainClient.environment.get({
@@ -205,7 +205,7 @@ const scopedPlainClient = contentful.createClient(
205205
spaceId: '<space_id>',
206206
environmentId: '<environment_id>',
207207
},
208-
}
208+
},
209209
)
210210

211211
// entries from '<space_id>' & '<environment_id>'
@@ -232,18 +232,19 @@ The benefits of using the "plain" version of the client, over the legacy version
232232
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`
233233

234234
```js
235-
const response = await environment.getEntriesWithCursor({ limit: 10 });
236-
console.log(response.items); // Array of items
237-
console.log(response.pages?.next); // Cursor for next page
235+
const response = await environment.getEntriesWithCursor({ limit: 10 })
236+
console.log(response.items) // Array of items
237+
console.log(response.pages?.next) // Cursor for next page
238238
```
239+
239240
Use the value from `response.pages.next` to fetch the next page.
240241
241242
```js
242243
const secondPage = await environment.getEntriesWithCursor({
243244
limit: 2,
244245
pageNext: response.pages?.next,
245-
});
246-
console.log(secondPage.items); // Array of items
246+
})
247+
console.log(secondPage.items) // Array of items
247248
```
248249
249250
## Legacy Client Interface
@@ -298,7 +299,7 @@ contentfulApp.init((sdk) => {
298299
environmentId: sdk.ids.environmentAlias ?? sdk.ids.environment,
299300
spaceId: sdk.ids.space,
300301
},
301-
}
302+
},
302303
)
303304

304305
// ...rest of initialization code
@@ -444,9 +445,11 @@ To download a build that has features that are not yet released, you can use the
444445
npm install contentful-management@canary
445446
```
446447

448+
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:
449+
447450
### Current experimental features
448451

449-
Currently there are no features in experimental status.
452+
- **AI Agents**: The Agent and Agent Run APIs (`getAgent`, `getAgents`, `getAgentRun`, `getAgentRuns`, `generateWithAgent`) are experimental and subject to breaking changes without notice.
450453

451454
## Reach out to us
452455

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

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
import type { RawAxiosRequestHeaders } from 'axios'
2+
import type { AxiosInstance } from 'contentful-sdk-core'
3+
import type { CollectionProp, GetSpaceEnvironmentParams } from '../../../common-types'
4+
import type { AgentRunProps, AgentRunQueryOptions } from '../../../entities/agent-run'
5+
import type { RestEndpoint } from '../types'
6+
import * as raw from './raw'
7+
8+
const AgentRunAlphaHeaders = {
9+
'x-contentful-enable-alpha-feature': 'agents-api',
10+
}
11+
12+
export const get: RestEndpoint<'AgentRun', 'get'> = (
13+
http: AxiosInstance,
14+
params: GetSpaceEnvironmentParams & { runId: string },
15+
headers?: RawAxiosRequestHeaders,
16+
) => {
17+
return raw.get<AgentRunProps>(
18+
http,
19+
`/spaces/${params.spaceId}/environments/${params.environmentId}/ai_agents/runs/${params.runId}`,
20+
{
21+
headers: {
22+
...AgentRunAlphaHeaders,
23+
...headers,
24+
},
25+
},
26+
)
27+
}
28+
29+
export const getMany: RestEndpoint<'AgentRun', 'getMany'> = (
30+
http: AxiosInstance,
31+
params: GetSpaceEnvironmentParams & { query?: AgentRunQueryOptions },
32+
headers?: RawAxiosRequestHeaders,
33+
) => {
34+
return raw.get<CollectionProp<AgentRunProps>>(
35+
http,
36+
`/spaces/${params.spaceId}/environments/${params.environmentId}/ai_agents/runs`,
37+
{
38+
params: params.query,
39+
headers: {
40+
...AgentRunAlphaHeaders,
41+
...headers,
42+
},
43+
},
44+
)
45+
}

‎lib/adapters/REST/endpoints/agent.ts‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
import type { RawAxiosRequestHeaders } from 'axios'
2+
import type { AxiosInstance } from 'contentful-sdk-core'
3+
import type { CollectionProp, GetSpaceEnvironmentParams, QueryParams } from '../../../common-types'
4+
import type { AgentGeneratePayload, AgentProps } from '../../../entities/agent'
5+
import type { AgentRunProps } from '../../../entities/agent-run'
6+
import type { RestEndpoint } from '../types'
7+
import * as raw from './raw'
8+
9+
const AgentAlphaHeaders = {
10+
'x-contentful-enable-alpha-feature': 'agents-api',
11+
}
12+
13+
export const get: RestEndpoint<'Agent', 'get'> = (
14+
http: AxiosInstance,
15+
params: GetSpaceEnvironmentParams & { agentId: string },
16+
headers?: RawAxiosRequestHeaders,
17+
) => {
18+
return raw.get<AgentProps>(
19+
http,
20+
`/spaces/${params.spaceId}/environments/${params.environmentId}/ai_agents/agents/${params.agentId}`,
21+
{
22+
headers: {
23+
...AgentAlphaHeaders,
24+
...headers,
25+
},
26+
},
27+
)
28+
}
29+
30+
export const getMany: RestEndpoint<'Agent', 'getMany'> = (
31+
http: AxiosInstance,
32+
params: GetSpaceEnvironmentParams,
33+
headers?: RawAxiosRequestHeaders,
34+
) => {
35+
return raw.get<CollectionProp<AgentProps>>(
36+
http,
37+
`/spaces/${params.spaceId}/environments/${params.environmentId}/ai_agents/agents`,
38+
{
39+
headers: {
40+
...AgentAlphaHeaders,
41+
...headers,
42+
},
43+
},
44+
)
45+
}
46+
47+
export const generate: RestEndpoint<'Agent', 'generate'> = (
48+
http: AxiosInstance,
49+
params: GetSpaceEnvironmentParams & { agentId: string },
50+
data: AgentGeneratePayload,
51+
headers?: RawAxiosRequestHeaders,
52+
) => {
53+
return raw.post<AgentRunProps>(
54+
http,
55+
`/spaces/${params.spaceId}/environments/${params.environmentId}/ai_agents/agents/${params.agentId}/generate`,
56+
data,
57+
{
58+
headers: {
59+
...AgentAlphaHeaders,
60+
...headers,
61+
},
62+
},
63+
)
64+
}

‎lib/adapters/REST/endpoints/index.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
import * as AiAction from './ai-action'
22
import * as AiActionInvocation from './ai-action-invocation'
3+
import * as Agent from './agent'
4+
import * as AgentRun from './agent-run'
35
import * as AccessToken from './access-token'
46
import * as ApiKey from './api-key'
57
import * as AppAccessToken from './app-access-token'
@@ -75,6 +77,8 @@ import * as WorkflowsChangelog from './workflows-changelog'
7577
export default {
7678
AiAction,
7779
AiActionInvocation,
80+
Agent,
81+
AgentRun,
7882
ApiKey,
7983
AppAction,
8084
AppActionCall,

‎lib/common-types.ts‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -191,6 +191,8 @@ import type {
191191
AiActionInvocationProps,
192192
AiActionInvocationType,
193193
} from './entities/ai-action-invocation'
194+
import type { AgentGeneratePayload, AgentProps } from './entities/agent'
195+
import type { AgentRunProps, AgentRunQueryOptions } from './entities/agent-run'
194196
import type {
195197
UpdateVectorizationStatusProps,
196198
VectorizationStatusProps,
@@ -458,6 +460,13 @@ type MRInternal<UA extends boolean> = {
458460

459461
(opts: MROpts<'AiActionInvocation', 'get', UA>): MRReturn<'AiActionInvocation', 'get'>
460462

463+
(opts: MROpts<'Agent', 'get', UA>): MRReturn<'Agent', 'get'>
464+
(opts: MROpts<'Agent', 'getMany', UA>): MRReturn<'Agent', 'getMany'>
465+
(opts: MROpts<'Agent', 'generate', UA>): MRReturn<'Agent', 'generate'>
466+
467+
(opts: MROpts<'AgentRun', 'get', UA>): MRReturn<'AgentRun', 'get'>
468+
(opts: MROpts<'AgentRun', 'getMany', UA>): MRReturn<'AgentRun', 'getMany'>
469+
461470
(opts: MROpts<'AppAction', 'get', UA>): MRReturn<'AppAction', 'get'>
462471
(opts: MROpts<'AppAction', 'getMany', UA>): MRReturn<'AppAction', 'getMany'>
463472
(opts: MROpts<'AppAction', 'delete', UA>): MRReturn<'AppAction', 'delete'>
@@ -1033,6 +1042,36 @@ export type MRActions = {
10331042
return: AiActionInvocationProps
10341043
}
10351044
}
1045+
Agent: {
1046+
get: {
1047+
params: GetSpaceEnvironmentParams & { agentId: string }
1048+
headers?: RawAxiosRequestHeaders
1049+
return: AgentProps
1050+
}
1051+
getMany: {
1052+
params: GetSpaceEnvironmentParams
1053+
headers?: RawAxiosRequestHeaders
1054+
return: CollectionProp<AgentProps>
1055+
}
1056+
generate: {
1057+
params: GetSpaceEnvironmentParams & { agentId: string }
1058+
payload: AgentGeneratePayload
1059+
headers?: RawAxiosRequestHeaders
1060+
return: AgentRunProps
1061+
}
1062+
}
1063+
AgentRun: {
1064+
get: {
1065+
params: GetSpaceEnvironmentParams & { runId: string }
1066+
headers?: RawAxiosRequestHeaders
1067+
return: AgentRunProps
1068+
}
1069+
getMany: {
1070+
params: GetSpaceEnvironmentParams & { query?: AgentRunQueryOptions }
1071+
headers?: RawAxiosRequestHeaders
1072+
return: CollectionProp<AgentRunProps>
1073+
}
1074+
}
10361075
AppAction: {
10371076
get: { params: GetAppActionParams; return: AppActionProps }
10381077
getMany: {

0 commit comments

Comments
 (0)
⚡