ArtifactStorage options for JS SDK (untested)

package.json

@@ -13,6 +13,9 @@
     }
   },
   "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/firebase": "^3.2.1",
+    "@types/redis": "^4.0.11",
     "@openapitools/openapi-generator-cli": "^2.9.0",
     "@typescript-eslint/eslint-plugin": "^5.62.0",
     "eslint": "^8.45.0",
@@ -23,6 +26,15 @@
     "prettier-plugin-tailwindcss": "^0.5.11",
     "typescript": "^5.1.6"
   },
+  "optionalDependencies": {
+    "@azure/storage-blob": "^12.17.0",
+    "@google-cloud/storage": "^7.7.0",
+    "@supabase/supabase-js": "^2.39.3",
+    "aws-sdk": "^2.1555.0",
+    "firebase": "^10.8.0",
+    "redis": "^4.6.13",
+    "simple-git": "^3.22.0"
+  },
   "dependencies": {
     "express": "^4.18.2",
     "express-openapi-validator": "^5.1.5",

packages/sdk/js/README.md

@@ -21,6 +21,7 @@ import Agent, {
   type StepResult,
   type TaskInput,
 } from 'agent-protocol'
+// import S3Storage from 'agent-protocol/storage/S3Storage'
 
 async function taskHandler(taskInput: TaskInput | null): Promise<StepHandler> {
   console.log(`task: ${taskInput}`)
@@ -35,7 +36,13 @@ async function taskHandler(taskInput: TaskInput | null): Promise<StepHandler> {
   return stepHandler
 }
 
-Agent.handleTask(taskHandler, {}).start()
+const config = {
+  // port: 8000,
+  // workspace: './workspace',
+  // Defaults to FileStorage, but other options are available, see also ArtifactStorageFactory
+  // artifactStorage: new S3Storage(s3, 'my-agent-artifacts'),
+}
+Agent.handleTask(taskHandler, config).start()
 ```
 
 See the [https://github.com/AI-Engineer-Foundation/agent-protocol/tree/main/packages/sdk/js/examples](examples folder) for running in serverless environments.

packages/sdk/js/src/agent.ts

@@ -1,6 +1,4 @@
 import { v4 as uuid } from 'uuid'
-import * as fs from 'fs'
-import * as path from 'path'
 
 import {
   type TaskInput,
@@ -18,9 +16,13 @@ import {
   createApi,
   type ApiConfig,
   type RouteRegisterFn,
-  type RouteContext,
 } from './api'
 import { type Router, type Express } from 'express'
+import { FileStorage, type ArtifactStorage } from './artifacts'
+
+export interface RouteContext {
+  agent: Agent
+}
 
 /**
  * A function that handles a step in a task.
@@ -337,39 +339,16 @@ const registerGetArtifacts: RouteRegisterFn = (router: Router) => {
   })
 }
 
-/**
- * Get path of an artifact associated to a task
- * @param taskId Task associated with artifact
- * @param artifact Artifact associated with the path returned
- * @returns Absolute path of the artifact
- */
-export const getArtifactPath = (
-  taskId: string,
-  workspace: string,
-  artifact: Artifact
-): string => {
-  const rootDir = path.isAbsolute(workspace)
-    ? workspace
-    : path.join(process.cwd(), workspace)
-
-  return path.join(
-    rootDir,
-    taskId,
-    artifact.relative_path ?? '',
-    artifact.file_name
-  )
-}
-
 /**
  * Creates an artifact for a task
  * @param task Task associated with new artifact
  * @param file File that will be added as artifact
  * @param relativePath Relative path where the artifact might be stored. Can be undefined
  */
 export const createArtifact = async (
-  workspace: string,
   task: Task,
-  file: any,
+  agent: Agent,
+  file: Express.Multer.File,
   relativePath?: string
 ): Promise<Artifact> => {
   const artifactId = uuid()
@@ -386,16 +365,16 @@ export const createArtifact = async (
       : []
   task.artifacts.push(artifact)
 
-  const artifactFolderPath = getArtifactPath(task.task_id, workspace, artifact)
-
-  // Save file to server's file system
-  fs.mkdirSync(path.join(artifactFolderPath, '..'), { recursive: true })
-  fs.writeFileSync(artifactFolderPath, file.buffer)
+  // Save the file
+  const [storage, workspace] = agent.getArtifactStorageAndWorkspace(
+    task.task_id
+  )
+  await storage.writeArtifact(task.task_id, workspace, artifact, file)
   return artifact
 }
 const registerCreateArtifact: RouteRegisterFn = (
   router: Router,
-  context: RouteContext
+  agent: Agent
 ) => {
   router.post('/agent/tasks/:task_id/artifacts', (req, res) => {
     void (async () => {
@@ -414,13 +393,18 @@ const registerCreateArtifact: RouteRegisterFn = (
 
         const files = req.files as Express.Multer.File[]
         const file = files.find(({ fieldname }) => fieldname === 'file')
-        const artifact = await createArtifact(
-          context.workspace,
-          task[0],
-          file,
-          relativePath
-        )
-        res.status(200).json(artifact)
+
+        if (file == null) {
+          res.status(400).json({ message: 'No file found in the request' })
+        } else {
+          const artifact = await createArtifact(
+            task[0],
+            agent,
+            file,
+            relativePath
+          )
+          res.status(200).json(artifact)
+        }
       } catch (err: Error | any) {
         console.error(err)
         res.status(500).json({ error: err.message })
@@ -450,17 +434,19 @@ export const getTaskArtifact = async (
 }
 const registerGetTaskArtifact: RouteRegisterFn = (
   router: Router,
-  context: RouteContext
+  agent: Agent
 ) => {
   router.get('/agent/tasks/:task_id/artifacts/:artifact_id', (req, res) => {
     void (async () => {
       const taskId = req.params.task_id
       const artifactId = req.params.artifact_id
       try {
         const artifact = await getTaskArtifact(taskId, artifactId)
-        const artifactPath = getArtifactPath(
+        const [storage, workspace] =
+          agent.getArtifactStorageAndWorkspace(taskId)
+        const artifactPath = storage.getArtifactPath(
           taskId,
-          context.workspace,
+          workspace,
           artifact
         )
         res.status(200).sendFile(artifactPath)
@@ -475,18 +461,26 @@ const registerGetTaskArtifact: RouteRegisterFn = (
 export interface AgentConfig {
   port: number
   workspace: string
+  artifactStorage: ArtifactStorage
 }
 
 export const defaultAgentConfig: AgentConfig = {
   port: 8000,
   workspace: './workspace',
+  artifactStorage: new FileStorage(),
 }
 
 export class Agent {
+  private workspace: string
+  private artifactStorage: ArtifactStorage
+
   constructor(
     public taskHandler: TaskHandler,
     public config: AgentConfig
-  ) {}
+  ) {
+    this.artifactStorage = config.artifactStorage
+    this.workspace = config.workspace
+  }
 
   static handleTask(
     _taskHandler: TaskHandler,
@@ -496,6 +490,8 @@ export class Agent {
     return new Agent(_taskHandler, {
       workspace: config.workspace ?? defaultAgentConfig.workspace,
       port: config.port ?? defaultAgentConfig.port,
+      artifactStorage:
+        config.artifactStorage ?? defaultAgentConfig.artifactStorage,
     })
   }
 
@@ -527,8 +523,24 @@ export class Agent {
         console.log(`Agent listening at http://localhost:${this.config.port}`)
       },
       context: {
-        workspace: this.config.workspace,
+        agent: this,
       },
     }
   }
+
+  /**
+   * @param taskId (potentially) POST /agent/tasks { additional_input } could configure the artifactStorage and/or workspace for a Task
+   */
+  getArtifactStorageAndWorkspace(taskId: string): [ArtifactStorage, string] {
+    return [this.artifactStorage, this.workspace]
+  }
+
+  /** It's easier for Serverless apps to configure artifactStorage after the app has been created */
+  setArtifactStorage(storage: ArtifactStorage): void {
+    this.artifactStorage = storage
+  }
+
+  setWorkspace(workspace: string): void {
+    this.workspace = workspace
+  }
 }

packages/sdk/js/src/api.ts

@@ -4,14 +4,11 @@ import express, { type Express, Router } from 'express' // <-- Import Router
 import type * as core from 'express-serve-static-core'
 
 import spec from '../../../../schemas/openapi.yml'
+import { type Agent, type RouteContext } from './agent'
 
 export type ApiApp = core.Express
 
-export interface RouteContext {
-  workspace: string
-}
-
-export type RouteRegisterFn = (app: Router, context: RouteContext) => void
+export type RouteRegisterFn = (app: Router, agent: Agent) => void
 
 export interface ApiConfig {
   context: RouteContext
@@ -44,7 +41,7 @@ export const createApi = (config: ApiConfig, start = true): Express => {
   const router = Router()
 
   config.routes.forEach((route) => {
-    route(router, config.context)
+    route(router, config.context.agent)
   })
 
   app.use('/ap/v1', router)

packages/sdk/js/src/artifacts/ArtifactStorage.ts

@@ -0,0 +1,49 @@
+import path from 'path'
+import { type Artifact } from '../models'
+
+/**
+ * @see ArtifactStorageFactory
+ */
+export default abstract class ArtifactStorage {
+  /**
+   * Save an artifact associated to a task
+   * @param taskId Task associated with artifact
+   * @param artifact Artifact associated with the path returned
+   * @returns Absolute path of the artifact
+   */
+  async writeArtifact(
+    taskId: string,
+    workspace: string,
+    artifact: Artifact,
+    file: Express.Multer.File
+  ): Promise<void> {
+    const artifactFolderPath = this.getArtifactPath(taskId, workspace, artifact)
+    await this.saveFile(artifactFolderPath, file.buffer)
+  }
+
+  /**
+   * Get path of an artifact associated to a task
+   * @param taskId Task associated with artifact
+   * @param workspace The path to the workspace, defaults to './workspace'
+   * @param artifact Artifact associated with the path returned
+   * @returns Absolute path of the artifact
+   */
+  getArtifactPath(
+    taskId: string,
+    workspace: string,
+    artifact: Artifact
+  ): string {
+    const rootDir = path.isAbsolute(workspace)
+      ? workspace
+      : path.join(process.cwd(), workspace)
+
+    return path.join(
+      rootDir,
+      taskId,
+      artifact.relative_path ?? '',
+      artifact.file_name
+    )
+  }
+
+  protected async saveFile(artifactPath: string, data: Buffer): Promise<void> {}
+}