From b53deb32c6aa40417a7f1470cd5b4301d524ba69 Mon Sep 17 00:00:00 2001 From: merwanehamadi Date: Mon, 28 Aug 2023 20:38:01 -0700 Subject: [PATCH] Version 0.4 (#55) Co-authored-by: GitHub Actions --- docs/src/app/endpoints/page.mdx | 2 +- ...on-RFC.md => 2023-08-28-Pagination-RFC.md} | 0 rfcs/2023-08-28-list-entities-RFC.md | 35 + schemas/openapi.json | 779 ++++++++++++++++-- schemas/openapi.yml | 60 +- test.sh | 90 ++ 6 files changed, 866 insertions(+), 100 deletions(-) rename rfcs/{2-Pagination-RFC.md => 2023-08-28-Pagination-RFC.md} (100%) create mode 100644 rfcs/2023-08-28-list-entities-RFC.md create mode 100644 test.sh diff --git a/docs/src/app/endpoints/page.mdx b/docs/src/app/endpoints/page.mdx index 87e6134..c4cc021 100644 --- a/docs/src/app/endpoints/page.mdx +++ b/docs/src/app/endpoints/page.mdx @@ -64,7 +64,7 @@ curl --request POST http://localhost:8000/agent/tasks ### Response - Returned list of agent's task IDs. + Returned list of agent's tasks. diff --git a/rfcs/2-Pagination-RFC.md b/rfcs/2023-08-28-Pagination-RFC.md similarity index 100% rename from rfcs/2-Pagination-RFC.md rename to rfcs/2023-08-28-Pagination-RFC.md diff --git a/rfcs/2023-08-28-list-entities-RFC.md b/rfcs/2023-08-28-list-entities-RFC.md new file mode 100644 index 0000000..fbe1d34 --- /dev/null +++ b/rfcs/2023-08-28-list-entities-RFC.md @@ -0,0 +1,35 @@ +# List tasks, artifacts and steps in a paginated way. + +| Feature name | Support Pagination | +| :------------ |:-----------------------------------------| +| **Author(s)** | Merwane Hamadi (merwanehamadi@gmail.com) | +| **RFC PR:** | | +| **Updated** | 2023-08-28 | +| **Obsoletes** | | + +## Summary + +Allows to list resources. + +## Motivation + +We can't build any app without an index. An index is a GET /tasks endpoint that list information about tasks. +It's like a table. + +Currently to build that you need to get the list of task ids. And if you want to display 20 tasks. You will make 20 GET calls to show them. + + +## Agent Builders Benefit + +- They can allow their users to list things: Currently they get a list of ids, that's not useful. + +## Design Proposal + +Just do what everyone does: return an array of objects that represent the resource + +### Alternatives Considered +- Just make 26 calls when you need to display a table of 25 tasks (1 call to get an id and then 25 calls to get the information of each task) + +### Compatibility + +- This is not backwards compatible. diff --git a/schemas/openapi.json b/schemas/openapi.json index e30648b..1ac236f 100644 --- a/schemas/openapi.json +++ b/schemas/openapi.json @@ -3,7 +3,7 @@ "info": { "title": "Agent Protocol", "description": "Specification of the API protocol for communication with an agent.", - "version": "v0.3" + "version": "v0.4" }, "servers": [ { @@ -183,16 +183,128 @@ ], "responses": { "200": { - "description": "Returned list of agent's task IDs.", + "description": "Returned list of agent's tasks.", "content": { "application/json": { "schema": { - "description": "A list of task IDs", - "type": "array", - "items": { - "type": "string" + "type": "object", + "properties": { + "tasks": { + "type": "array", + "items": { + "allOf": [ + { + "description": "Body of the task request.", + "type": "object", + "properties": { + "input": { + "description": "Input prompt for the task.", + "type": "string", + "example": "Write 'Washington' to the file 'output.txt'.", + "nullable": true + }, + "additional_input": { + "description": "Input parameters for the task. Any value is allowed.", + "type": "object", + "example": "{\n\"debug\": false,\n\"mode\": \"benchmarks\"\n}" + } + } + }, + { + "type": "object", + "description": "Definition of an agent task.", + "required": [ + "task_id", + "artifacts" + ], + "properties": { + "task_id": { + "description": "The ID of the task.", + "type": "string", + "example": "50da533e-3904-4401-8a07-c49adf88b5eb" + }, + "artifacts": { + "description": "A list of artifacts that the task has produced.", + "type": "array", + "items": { + "description": "An Artifact either created by or submitted to the agent.", + "type": "object", + "properties": { + "artifact_id": { + "description": "ID of the artifact.", + "type": "string", + "example": "b225e278-8b4c-4f99-a696-8facf19f0e56" + }, + "agent_created": { + "description": "Whether the artifact has been created by the agent.", + "type": "boolean", + "example": false + }, + "file_name": { + "description": "Filename of the artifact.", + "type": "string", + "example": "main.py" + }, + "relative_path": { + "description": "Relative path of the artifact in the agent's workspace.", + "type": "string", + "example": "python/code/", + "nullable": true + } + }, + "required": [ + "artifact_id", + "agent_created", + "file_name" + ] + }, + "example": [ + "7a49f31c-f9c6-4346-a22c-e32bc5af4d8e", + "ab7b4091-2560-4692-a4fe-d831ea3ca7d6" + ], + "default": [] + } + } + } + ] + } + }, + "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 + } + }, + "required": [ + "total_items", + "total_pages", + "current_page", + "page_size" + ] + } }, - "default": [] + "required": [ + "tasks", + "pagination" + ] } } } @@ -396,12 +508,161 @@ "content": { "application/json": { "schema": { - "description": "A list of step IDs for the task", - "type": "array", - "items": { - "type": "string" + "type": "object", + "properties": { + "steps": { + "type": "array", + "items": { + "allOf": [ + { + "description": "Body of the task request.", + "type": "object", + "properties": { + "input": { + "description": "Input prompt for the step.", + "type": "string", + "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.", + "type": "object", + "example": "{\n\"file_to_refactor\": \"models.py\"\n}" + } + } + }, + { + "type": "object", + "required": [ + "step_id", + "task_id", + "status", + "is_last", + "artifacts" + ], + "properties": { + "task_id": { + "description": "The ID of the task this step belongs to.", + "type": "string", + "example": "50da533e-3904-4401-8a07-c49adf88b5eb" + }, + "step_id": { + "description": "The ID of the task step.", + "type": "string", + "example": "6bb1801a-fd80-45e8-899a-4dd723cc602e" + }, + "name": { + "description": "The name of the task step.", + "type": "string", + "example": "Write to file", + "nullable": true + }, + "status": { + "description": "The status of the task step.", + "type": "string", + "example": "created", + "enum": [ + "created", + "running", + "completed" + ] + }, + "output": { + "description": "Output of the task step.", + "type": "string", + "example": "I am going to use the write_to_file command and write Washington to a file called output.txt bash