feat: Add PROJECT.md documentation for vibn-agent-runner

2026-02-26 23:04:01 +00:00
parent 45bca13479
commit 1eadbb6631
1 changed files with 103 additions and 0 deletions
--- a/PROJECT.md
+++ b/PROJECT.md
@@ -0,0 +1,103 @@
+# vibn-agent-runner Project Documentation
+
+## What it does
+
+The `vibn-agent-runner` is a service responsible for executing tasks or "agents" within the Vibn ecosystem. It likely receives requests to run specific agents, manages their execution, and reports back their status or results. This service acts as a crucial component for extending Vibn's capabilities through custom or predefined agents.
+
+## API Endpoints
+
+(Note: These are example endpoints. Please refer to the source code or API documentation for exact details.)
+
+### `POST /run-agent`
+
+Initiates the execution of an agent.
+
+- **Method:** `POST`
+- **URL:** `/run-agent`
+- **Request Body Example:**
+  ```json
+  {
+    "agentId": "your-agent-id",
+    "payload": {
+      "param1": "value1",
+      "param2": "value2"
+    }
+  }
+  ```
+- **Response Body Example (Success):**
+  ```json
+  {
+    "status": "success",
+    "runId": "unique-run-id",
+    "message": "Agent execution started."
+  }
+  ```
+- **Response Body Example (Error):**
+  ```json
+  {
+    "status": "error",
+    "message": "Failed to start agent execution.",
+    "details": "Error message details"
+  }
+  ```
+
+### `GET /agent-status/{runId}`
+
+Retrieves the status of a running or completed agent.
+
+- **Method:** `GET`
+- **URL:** `/agent-status/{runId}`
+- **Response Body Example:**
+  ```json
+  {
+    "runId": "unique-run-id",
+    "status": "running", // or "completed", "failed"
+    "progress": "50%",
+    "results": {} // or actual results if completed
+  }
+  ```
+
+## How to run locally
+
+To run the `vibn-agent-runner` locally, follow these steps:
+
+1.  **Clone the repository:**
+    ```bash
+    git clone <repository-url>
+    cd vibn-agent-runner
+    ```
+
+2.  **Install dependencies:**
+    ```bash
+    npm install
+    ```
+    or
+    ```bash
+    yarn install
+    ```
+
+3.  **Configure environment variables:**
+    Copy the `.env.example` file to `.env` and update the values as needed.
+    ```bash
+    cp .env.example .env
+    ```
+
+4.  **Build the project (if TypeScript):**
+    ```bash
+    npm run build
+    ```
+    or
+    ```bash
+    yarn build
+    ```
+
+5.  **Start the application:**
+    ```bash
+    npm start
+    ```
+    or
+    ```bash
+    yarn start
+    ```
+
+The application should now be running, typically accessible at `http://localhost:3000` (or another port specified in your environment configuration).