agent-protocol

1
openapi: 3.0.1
2
info:
3
  title: Agent Protocol
4
  description: Specification of the API protocol for communication with an agent.
5
  version: v1
6
servers:
7
  - url: 'http://0.0.0.0:8000'
8
    description: Agent Protocol API
9
paths:
10
  /ap/v1/agent/tasks:
11
    post:
12
      operationId: createAgentTask
13
      summary: Creates a task for the agent.
14
      requestBody:
15
        content:
16
          application/json:
17
            schema:
18
              $ref: '#/components/schemas/TaskRequestBody'
19
      responses:
20
        '200':
21
          description: A new agent task was successfully created.
22
          content:
23
            application/json:
24
              schema:
25
                $ref: '#/components/schemas/Task'
26
          x-postman-variables:
27
            - type: save
28
              name: task_id
29
              path: .task_id
30
        '422':
31
          $ref: '#/components/responses/UnprocessableEntity'
32
        default:
33
          description: Internal Server Error
34
      tags:
35
        - agent
36
    get:
37
      operationId: listAgentTasks
38
      summary: List all tasks that have been created for the agent.
39
      parameters:
40
        - name: current_page
41
          in: query
42
          description: Page number
43
          required: false
44
          schema:
45
            type: integer
46
            format: int32
47
            default: 1
48
            minimum: 1
49
          example: 2
50
        - name: page_size
51
          in: query
52
          description: Number of items per page
53
          required: false
54
          schema:
55
            type: integer
56
            format: int32
57
            default: 10
58
            minimum: 1
59
          example: 25
60
      responses:
61
        '200':
62
          description: Returned list of agent's tasks.
63
          content:
64
            application/json:
65
              schema:
66
                $ref: '#/components/schemas/TaskListResponse'
67
        default:
68
          description: Internal Server Error
69
      tags:
70
        - agent
71
  '/ap/v1/agent/tasks/{task_id}':
72
    get:
73
      operationId: getAgentTask
74
      summary: Get details about a specified agent task.
75
      parameters:
76
        - name: task_id
77
          in: path
78
          description: ID of the task
79
          required: true
80
          schema:
81
            type: string
82
          example: 1d5a533e-3904-4401-8a07-c49adf88b981
83
          x-postman-variables:
84
            - type: load
85
              name: task_id
86
      responses:
87
        '200':
88
          description: Returned details about an agent task.
89
          content:
90
            application/json:
91
              schema:
92
                $ref: '#/components/schemas/Task'
93
        '404':
94
          $ref: '#/components/responses/NotFound'
95
        default:
96
          description: Internal Server Error
97
      tags:
98
        - agent
99
  '/ap/v1/agent/tasks/{task_id}/steps':
100
    get:
101
      operationId: listAgentTaskSteps
102
      summary: List all steps for the specified task.
103
      parameters:
104
        - name: task_id
105
          in: path
106
          description: ID of the task.
107
          required: true
108
          schema:
109
            type: string
110
          example: 50da533e-3904-4401-8a07-c49adf88b5eb
111
          x-postman-variables:
112
            - type: load
113
              name: task_id
114
        - name: current_page
115
          in: query
116
          description: Page number
117
          required: false
118
          schema:
119
            type: integer
120
            format: int32
121
            default: 1
122
            minimum: 1
123
          example: 2
124
        - name: page_size
125
          in: query
126
          description: Number of items per page
127
          required: false
128
          schema:
129
            type: integer
130
            format: int32
131
            default: 10
132
            minimum: 1
133
          example: 25
134
      responses:
135
        '200':
136
          description: Returned list of agent's steps for the specified task.
137
          content:
138
            application/json:
139
              schema:
140
                $ref: '#/components/schemas/TaskStepsListResponse'
141
        '404':
142
          $ref: '#/components/responses/NotFound'
143
        default:
144
          description: Internal Server Error
145
      tags:
146
        - agent
147
    post:
148
      operationId: executeAgentTaskStep
149
      summary: Execute a step in the specified agent task.
150
      parameters:
151
        - name: task_id
152
          in: path
153
          description: ID of the task
154
          required: true
155
          schema:
156
            type: string
157
          example: 50da533e-3904-4401-8a07-c49adf88b5eb
158
          x-postman-variables:
159
            - type: load
160
              name: task_id
161
      requestBody:
162
        content:
163
          application/json:
164
            schema:
165
              $ref: '#/components/schemas/StepRequestBody'
166
      responses:
167
        '200':
168
          description: Executed step for the agent task.
169
          content:
170
            application/json:
171
              schema:
172
                $ref: '#/components/schemas/Step'
173
          x-postman-variables:
174
            - type: save
175
              name: step_id
176
              path: .step_id
177
        '404':
178
          $ref: '#/components/responses/NotFound'
179
        '422':
180
          $ref: '#/components/responses/UnprocessableEntity'
181
        default:
182
          description: Internal Server Error
183
      tags:
184
        - agent
185
  '/ap/v1/agent/tasks/{task_id}/steps/{step_id}':
186
    get:
187
      operationId: getAgentTaskStep
188
      summary: Get details about a specified task step.
189
      parameters:
190
        - name: task_id
191
          in: path
192
          description: ID of the task
193
          required: true
194
          schema:
195
            type: string
196
          example: 50da533e-3904-4401-8a07-c49adf88b5eb
197
          x-postman-variables:
198
            - type: load
199
              name: task_id
200
            - type: load
201
              name: step_id
202
        - name: step_id
203
          in: path
204
          description: ID of the step
205
          required: true
206
          schema:
207
            type: string
208
          example: 28ca533e-3904-4401-8a07-c49adf8891c2
209
          x-postman-variables:
210
            - type: load
211
              name: step_id
212
      responses:
213
        '200':
214
          description: Returned details about an agent task step.
215
          content:
216
            application/json:
217
              schema:
218
                $ref: '#/components/schemas/Step'
219
        '404':
220
          $ref: '#/components/responses/NotFound'
221
        default:
222
          description: Internal Server Error
223
      tags:
224
        - agent
225
  '/ap/v1/agent/tasks/{task_id}/artifacts':
226
    get:
227
      operationId: listAgentTaskArtifacts
228
      summary: List all artifacts that have been created for the given task.
229
      parameters:
230
        - name: task_id
231
          in: path
232
          description: ID of the task
233
          required: true
234
          schema:
235
            type: string
236
          example: 50da533e-3904-4401-8a07-c49adf88b5eb
237
          x-postman-variables:
238
            - type: load
239
              name: task_id
240
        - name: current_page
241
          in: query
242
          description: Page number
243
          required: false
244
          schema:
245
            type: integer
246
            format: int32
247
            default: 1
248
            minimum: 1
249
          example: 2
250
        - name: page_size
251
          in: query
252
          description: Number of items per page
253
          required: false
254
          schema:
255
            type: integer
256
            format: int32
257
            default: 10
258
            minimum: 1
259
          example: 25
260
      responses:
261
        '200':
262
          description: Returned the list of artifacts for the task.
263
          content:
264
            application/json:
265
              schema:
266
                $ref: '#/components/schemas/TaskArtifactsListResponse'
267
        '404':
268
          $ref: '#/components/responses/NotFound'
269
        default:
270
          description: Internal Server Error
271
      tags:
272
        - agent
273
    post:
274
      operationId: uploadAgentTaskArtifacts
275
      summary: Upload an artifact for the specified task.
276
      parameters:
277
        - name: task_id
278
          in: path
279
          description: ID of the task
280
          required: true
281
          schema:
282
            type: string
283
          example: 50da533e-3904-4401-8a07-c49adf88b5eb
284
          x-postman-variables:
285
            - type: load
286
              name: task_id
287
      requestBody:
288
        content:
289
          multipart/form-data:
290
            schema:
291
              $ref: '#/components/schemas/ArtifactUpload'
292
      responses:
293
        '200':
294
          description: Returned the content of the artifact.
295
          content:
296
            application/json:
297
              schema:
298
                $ref: '#/components/schemas/Artifact'
299
        '404':
300
          $ref: '#/components/responses/NotFound'
301
        default:
302
          description: Internal Server Error
303
      tags:
304
        - agent
305
  '/ap/v1/agent/tasks/{task_id}/artifacts/{artifact_id}':
306
    get:
307
      operationId: downloadAgentTaskArtifact
308
      summary: Download a specified artifact.
309
      parameters:
310
        - name: task_id
311
          in: path
312
          description: ID of the task
313
          required: true
314
          schema:
315
            type: string
316
          example: 50da533e-3904-4401-8a07-c49adf88b5eb
317
          x-postman-variables:
318
            - type: load
319
              name: task_id
320
        - name: artifact_id
321
          in: path
322
          description: ID of the artifact
323
          required: true
324
          schema:
325
            type: string
326
          example: 1e41533e-3904-4401-8a07-c49adf8893de
327
      responses:
328
        '200':
329
          description: Returned the content of the artifact.
330
          content:
331
            application/octet-stream:
332
              schema:
333
                type: string
334
                format: binary
335
        '404':
336
          $ref: '#/components/responses/NotFound'
337
        default:
338
          description: Internal Server Error
339
      tags:
340
        - agent
341
components:
342
  schemas:
343
    Pagination:
344
      type: object
345
      properties:
346
        total_items:
347
          description: Total number of items.
348
          type: integer
349
          example: 42
350
        total_pages:
351
          description: Total number of pages.
352
          type: integer
353
          example: 97
354
        current_page:
355
          description: Current_page page number.
356
          type: integer
357
          example: 1
358
        page_size:
359
          description: Number of items per page.
360
          type: integer
361
          example: 25
362
      required:
363
        - total_items
364
        - total_pages
365
        - current_page
366
        - page_size
367
    TaskListResponse:
368
      type: object
369
      properties:
370
        tasks:
371
          type: array
372
          items:
373
            $ref: '#/components/schemas/Task'
374
        pagination:
375
          $ref: '#/components/schemas/Pagination'
376
      required:
377
        - tasks
378
        - pagination
379
    TaskStepsListResponse:
380
      type: object
381
      properties:
382
        steps:
383
          type: array
384
          items:
385
            $ref: '#/components/schemas/Step'
386
        pagination:
387
          $ref: '#/components/schemas/Pagination'
388
      required:
389
        - steps
390
        - pagination
391
    TaskArtifactsListResponse:
392
      type: object
393
      properties:
394
        artifacts:
395
          type: array
396
          items:
397
            $ref: '#/components/schemas/Artifact'
398
        pagination:
399
          $ref: '#/components/schemas/Pagination'
400
      required:
401
        - artifacts
402
        - pagination
403
    TaskInput:
404
      description: Input parameters for the task. Any value is allowed.
405
      type: object
406
      example: |-
407
        {
408
        "debug": false,
409
        "mode": "benchmarks"
410
        }
411
    Artifact:
412
      description: An Artifact either created by or submitted to the agent.
413
      type: object
414
      properties:
415
        artifact_id:
416
          description: ID of the artifact.
417
          type: string
418
          example: b225e278-8b4c-4f99-a696-8facf19f0e56
419
        agent_created:
420
          description: Whether the artifact has been created by the agent.
421
          type: boolean
422
          example: false
423
        file_name:
424
          description: Filename of the artifact.
425
          type: string
426
          example: main.py
427
        relative_path:
428
          description: Relative path of the artifact in the agent's workspace.
429
          type: string
430
          example: python/code/
431
          nullable: true
432
      required:
433
        - artifact_id
434
        - agent_created
435
        - file_name
436
    ArtifactUpload:
437
      description: Artifact to upload to the agent.
438
      type: object
439
      properties:
440
        file:
441
          description: File to upload.
442
          type: string
443
          format: binary
444
          example: binary representation of file
445
        relative_path:
446
          description: Relative path of the artifact in the agent's workspace.
447
          type: string
448
          example: python/code
449
      required:
450
        - file
451
    StepInput:
452
      description: Input parameters for the task step. Any value is allowed.
453
      type: object
454
      example: |-
455
        {
456
        "file_to_refactor": "models.py"
457
        }
458
    StepOutput:
459
      description: Output that the task step has produced. Any value is allowed.
460
      type: object
461
      example: |-
462
        {
463
        "tokens": 7894,
464
        "estimated_cost": "0,24$"
465
        }
466
      nullable: true
467
    TaskRequestBody:
468
      description: Body of the task request.
469
      type: object
470
      properties:
471
        input:
472
          description: Input prompt for the task.
473
          type: string
474
          example: Write 'Washington' to the file 'output.txt'.
475
          nullable: true
476
        additional_input:
477
          $ref: '#/components/schemas/TaskInput'
478
    Task:
479
      allOf:
480
        - $ref: '#/components/schemas/TaskRequestBody'
481
        - type: object
482
          description: Definition of an agent task.
483
          required:
484
            - task_id
485
            - artifacts
486
          properties:
487
            task_id:
488
              description: The ID of the task.
489
              type: string
490
              example: 50da533e-3904-4401-8a07-c49adf88b5eb
491
            artifacts:
492
              description: A list of artifacts that the task has produced.
493
              type: array
494
              items:
495
                $ref: '#/components/schemas/Artifact'
496
              example:
497
                - 7a49f31c-f9c6-4346-a22c-e32bc5af4d8e
498
                - ab7b4091-2560-4692-a4fe-d831ea3ca7d6
499
              default: []
500
    StepRequestBody:
501
      description: Body of the task request.
502
      type: object
503
      properties:
504
        input:
505
          description: Input prompt for the step.
506
          type: string
507
          example: Write the words you receive to the file 'output.txt'.
508
          nullable: true
509
        additional_input:
510
          $ref: '#/components/schemas/StepInput'
511
    Step:
512
      allOf:
513
        - $ref: '#/components/schemas/StepRequestBody'
514
        - type: object
515
          required:
516
            - step_id
517
            - task_id
518
            - status
519
            - is_last
520
            - artifacts
521
          properties:
522
            task_id:
523
              description: The ID of the task this step belongs to.
524
              type: string
525
              example: 50da533e-3904-4401-8a07-c49adf88b5eb
526
            step_id:
527
              description: The ID of the task step.
528
              type: string
529
              example: 6bb1801a-fd80-45e8-899a-4dd723cc602e
530
            name:
531
              description: The name of the task step.
532
              type: string
533
              example: Write to file
534
              nullable: true
535
            status:
536
              description: The status of the task step.
537
              type: string
538
              example: created
539
              enum:
540
                - created
541
                - running
542
                - completed
543
            output:
544
              description: Output of the task step.
545
              type: string
546
              example: "I am going to use the write_to_file command and write Washington to a file called output.txt <write_to_file('output.txt', 'Washington')"
547
              nullable: true
548
            additional_output:
549
              $ref: '#/components/schemas/StepOutput'
550
            artifacts:
551
              description: A list of artifacts that the step has produced.
552
              type: array
553
              items:
554
                $ref: '#/components/schemas/Artifact'
555
              default: []
556
            is_last:
557
              description: Whether this is the last step in the task.
558
              type: boolean
559
              example: true
560
              default: false
561
  responses:
562
    UnprocessableEntity:
563
      description: Unable to process request. Likely due to improperly formatted request.
564
      content:
565
        application/json:
566
          schema:
567
            description: A generic JSON object without any specific requirements.
568
            type: object
569
    NotFound:
570
      description: Unable to find entity with a given identifier
571
      content:
572
        application/json:
573
          schema:
574
            type: object
575
            properties:
576
              message:
577
                description: Message stating the entity was not found
578
                type: string
579
                example: Unable to find entity with the provided id
580
            required:
581
              - message
582