RFC Allow Pagination (#53)

Co-authored-by: GitHub Actions <[email protected]>
AI-Engineer-Foundation · 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: