RFC Allow Pagination (#53)

Co-authored-by: GitHub Actions <[email protected]>
Div99 · Aug 29, 2023 · 3fd7b4e · 3fd7b4e
1 parent 4d73475
commit 3fd7b4e
Show file tree

Hide file tree

Showing 4 changed files with 250 additions and 5 deletions.
diff --git a/docs/src/app/endpoints/page.mdx b/docs/src/app/endpoints/page.mdx
@@ -49,7 +49,17 @@ curl --request POST http://localhost:8000/agent/tasks
   <Col>
     List all tasks that have been created for the agent.
 
+    ### Path attributes
+
+  <Properties>
 
+    <Property name="current_page" type="integer">
+        Page number
+    </Property>
+    <Property name="page_size" type="integer">
+        Number of items per page
+    </Property>
+  </Properties>
 
 
     ### Response
@@ -113,6 +123,12 @@ curl  http://localhost:8000/agent/tasks/[task_id]
     <Property name="task_id" type="string">
         ID of the task.
     </Property>
+    <Property name="current_page" type="integer">
+        Page number
+    </Property>
+    <Property name="page_size" type="integer">
+        Number of items per page
+    </Property>
   </Properties>
 
 
@@ -223,6 +239,12 @@ curl  http://localhost:8000/agent/tasks/[task_id]/steps/[step_id]
     <Property name="task_id" type="string">
         ID of the task
     </Property>
+    <Property name="current_page" type="integer">
+        Page number
+    </Property>
+    <Property name="page_size" type="integer">
+        Number of items per page
+    </Property>
   </Properties>
 
 

diff --git a/rfcs/2-Pagination-RFC.md b/rfcs/2-Pagination-RFC.md
@@ -0,0 +1,32 @@
+# List tasks, artifacts and steps in a paginated way.
+
+| Feature name  | Support Pagination                       |
+| :------------ |:-----------------------------------------|
+| **Author(s)** | Merwane Hamadi ([email protected]) |
+| **RFC PR:**   | [PR 53](https://github.com/e2b-dev/agent-protocol/pull/53)                              |
+| **Updated**   | 2023-08-28                               |
+| **Obsoletes** |                                          |
+
+## Summary
+
+We just want to be able to list tasks, artifacts and steps in a paginated way.
+
+## Motivation
+
+Every app needs this. It's not really farfetched
+
+## Agent Builders Benefit
+
+- They can paginate their tasks, steps and artifacts.
+
+## Design Proposal
+
+Query parameters for now.
+
+### Alternatives Considered
+- query parameter is the simplest, leanest design. We can add more later (body, headers, etc) => let's start lean.
+- for now, we won't add the pages in the response of the requests, this is another RFC.
+
+### Compatibility
+
+- This is backwards compatible. We're just adding things.
diff --git a/schemas/openapi.json b/schemas/openapi.json
@@ -153,6 +153,34 @@
       "get": {
         "operationId": "listAgentTasksIDs",
         "summary": "List all tasks that have been created for the agent.",
+        "parameters": [
+          {
+            "name": "current_page",
+            "in": "query",
+            "description": "Page number",
+            "required": false,
+            "schema": {
+              "type": "integer",
+              "format": "int32",
+              "default": 1,
+              "minimum": 1
+            },
+            "example": 2
+          },
+          {
+            "name": "page_size",
+            "in": "query",
+            "description": "Number of items per page",
+            "required": false,
+            "schema": {
+              "type": "integer",
+              "format": "int32",
+              "default": 10,
+              "minimum": 1
+            },
+            "example": 25
+          }
+        ],
         "responses": {
           "200": {
             "description": "Returned list of agent's task IDs.",
@@ -334,6 +362,32 @@
                 "name": "task_id"
               }
             ]
+          },
+          {
+            "name": "current_page",
+            "in": "query",
+            "description": "Page number",
+            "required": false,
+            "schema": {
+              "type": "integer",
+              "format": "int32",
+              "default": 1,
+              "minimum": 1
+            },
+            "example": 2
+          },
+          {
+            "name": "page_size",
+            "in": "query",
+            "description": "Number of items per page",
+            "required": false,
+            "schema": {
+              "type": "integer",
+              "format": "int32",
+              "default": 10,
+              "minimum": 1
+            },
+            "example": 25
           }
         ],
         "responses": {
@@ -411,7 +465,8 @@
                   "input": {
                     "description": "Input prompt for the step.",
                     "type": "string",
-                    "example": "Write the words you receive to the file 'output.txt'."
+                    "example": "Write the words you receive to the file 'output.txt'.",
+                    "nullable": true
                   },
                   "additional_input": {
                     "description": "Input parameters for the task step. Any value is allowed.",
@@ -437,7 +492,8 @@
                         "input": {
                           "description": "Input prompt for the step.",
                           "type": "string",
-                          "example": "Write the words you receive to the file 'output.txt'."
+                          "example": "Write the words you receive to the file 'output.txt'.",
+                          "nullable": true
                         },
                         "additional_input": {
                           "description": "Input parameters for the task step. Any value is allowed.",
@@ -646,7 +702,8 @@
                         "input": {
                           "description": "Input prompt for the step.",
                           "type": "string",
-                          "example": "Write the words you receive to the file 'output.txt'."
+                          "example": "Write the words you receive to the file 'output.txt'.",
+                          "nullable": true
                         },
                         "additional_input": {
                           "description": "Input parameters for the task step. Any value is allowed.",
@@ -801,6 +858,32 @@
                 "name": "task_id"
               }
             ]
+          },
+          {
+            "name": "current_page",
+            "in": "query",
+            "description": "Page number",
+            "required": false,
+            "schema": {
+              "type": "integer",
+              "format": "int32",
+              "default": 1,
+              "minimum": 1
+            },
+            "example": 2
+          },
+          {
+            "name": "page_size",
+            "in": "query",
+            "description": "Number of items per page",
+            "required": false,
+            "schema": {
+              "type": "integer",
+              "format": "int32",
+              "default": 10,
+              "minimum": 1
+            },
+            "example": 25
           }
         ],
         "responses": {
@@ -1067,6 +1150,31 @@
   },
   "components": {
     "schemas": {
+      "Pagination": {
+        "type": "object",
+        "properties": {
+          "total_items": {
+            "description": "Total number of items.",
+            "type": "integer",
+            "example": 42
+          },
+          "total_pages": {
+            "description": "Total number of pages.",
+            "type": "integer",
+            "example": 97
+          },
+          "current_page": {
+            "description": "Current_page page number.",
+            "type": "integer",
+            "example": 1
+          },
+          "page_size": {
+            "description": "Number of items per page.",
+            "type": "integer",
+            "example": 25
+          }
+        }
+      },
       "TaskStepsListResponse": {
         "description": "A list of step IDs for the task",
         "type": "array",
@@ -1280,7 +1388,8 @@
           "input": {
             "description": "Input prompt for the step.",
             "type": "string",
-            "example": "Write the words you receive to the file 'output.txt'."
+            "example": "Write the words you receive to the file 'output.txt'.",
+            "nullable": true
           },
           "additional_input": {
             "description": "Input parameters for the task step. Any value is allowed.",
@@ -1298,7 +1407,8 @@
               "input": {
                 "description": "Input prompt for the step.",
                 "type": "string",
-                "example": "Write the words you receive to the file 'output.txt'."
+                "example": "Write the words you receive to the file 'output.txt'.",
+                "nullable": true
               },
               "additional_input": {
                 "description": "Input parameters for the task step. Any value is allowed.",

diff --git a/schemas/openapi.yml b/schemas/openapi.yml
@@ -36,6 +36,27 @@ paths:
     get:
       operationId: listAgentTasksIDs
       summary: List all tasks that have been created for the agent.
+      parameters:
+        - name: current_page
+          in: query
+          description: Page number
+          required: false
+          schema:
+            type: integer
+            format: int32
+            default: 1
+            minimum: 1
+          example: 2
+        - name: page_size
+          in: query
+          description: Number of items per page
+          required: false
+          schema:
+            type: integer
+            format: int32
+            default: 10
+            minimum: 1
+          example: 25
       responses:
         '200':
           description: Returned list of agent's task IDs.
@@ -94,6 +115,26 @@ paths:
           x-postman-variables:
             - type: load
               name: task_id
+        - name: current_page
+          in: query
+          description: Page number
+          required: false
+          schema:
+            type: integer
+            format: int32
+            default: 1
+            minimum: 1
+          example: 2
+        - name: page_size
+          in: query
+          description: Number of items per page
+          required: false
+          schema:
+            type: integer
+            format: int32
+            default: 10
+            minimum: 1
+          example: 25
       responses:
         '200':
           description: Returned list of agent's steps for the specified task.
@@ -200,6 +241,26 @@ paths:
           x-postman-variables:
             - type: load
               name: task_id
+        - name: current_page
+          in: query
+          description: Page number
+          required: false
+          schema:
+            type: integer
+            format: int32
+            default: 1
+            minimum: 1
+          example: 2
+        - name: page_size
+          in: query
+          description: Number of items per page
+          required: false
+          schema:
+            type: integer
+            format: int32
+            default: 10
+            minimum: 1
+          example: 25
       responses:
         '200':
           description: Returned the list of artifacts for the task.
@@ -283,6 +344,25 @@ paths:
         - agent
 components:
   schemas:
+    Pagination:
+      type: object
+      properties:
+        total_items:
+          description: Total number of items.
+          type: integer
+          example: 42
+        total_pages:
+          description: Total number of pages.
+          type: integer
+          example: 97
+        current_page:
+          description: Current_page page number.
+          type: integer
+          example: 1
+        page_size:
+          description: Number of items per page.
+          type: integer
+          example: 25
     TaskStepsListResponse:
       description: A list of step IDs for the task
       type: array
@@ -399,6 +479,7 @@ components:
           description: Input prompt for the step.
           type: string
           example: Write the words you receive to the file 'output.txt'.
+          nullable: true
         additional_input:
           $ref: '#/components/schemas/StepInput'
     Step: