# 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).