Skip to main content

Sidecars

Sidecars are auxiliary services or processes that operate alongside Paraflow agents to enhance functionality, manage external integrations, or support development tasks. In Paraflow-based projects, sidecars serve as a fundamental architectural pattern, promoting separation of concerns, modularity, and interoperability with external systems or resources.

This guide outlines how to design, implement, and utilize sidecars within your Paraflow workflows.

What Are Sidecars?​

A sidecar is an independent component that runs in parallel with Paraflow agents. Unlike agents specified in your Paraflow configuration (e.g., within the agents section), sidecars are not directly controlled by the Paranet runtime. They typically function as standalone processes—such as APIs, scripts, or services—and interact with Paraflow agents through standard protocols like HTTP or WebSockets.

Common Use Cases​

  • External Integrations: Retrieve data from external sources, such as hardware devices or APIs.
  • Monitoring and Debugging: Offer real-time visibility or diagnostic tools for developers.
  • Specialized Tasks: Offload complex operations, like data processing or computation, to dedicated services.

Designing Sidecars for Paraflow​

When incorporating sidecars into Paraflow workflows, adhere to these design principles:

  1. Independence: Sidecars should function as standalone entities, deployable independently of the Paranet.
  2. Interoperability: Leverage widely supported protocols (e.g., HTTP, gRPC) for communication with Paraflow agents.
  3. Configurability: Enable customization through environment variables or configuration files.
  4. Loose Coupling: Design sidecars to be optional or interchangeable, minimizing dependencies with the Paranet core.

Typical Architecture​

  • Paraflow Agent: Manages workflows and communicates with the sidecar.
  • Sidecar Service: Operates independently, providing APIs, data streams, or other resources.
  • Interaction: Agents connect to sidecars via requests, subscriptions, or event-driven mechanisms.

Implementing a Sidecar​

Follow these steps to create and integrate a sidecar with Paraflow:

Step 1: Define the Sidecar’s Role​

Identify the specific functionality the sidecar will provide, such as data retrieval, processing, or visualization.

Step 2: Develop the Sidecar​

Build the sidecar as a standalone service using a suitable framework (e.g., Flask for Python, Express for Node.js).

Step 3: Configure the Paraflow Agent​

In your Paraflow configuration, define an agent that interacts with the sidecar, typically by specifying connection details in the env section.

Example Configuration​

agents:
  - name: Example Agent
    path: ./paranet/
    python_sdk: ./agent_script.py
    env:
      SERVICE_URL: "http://localhost:5000/resource"

Step 4: Connect the Agent to the Sidecar​

In the agent’s code, add logic to interact with the sidecar using standard methods like asynchronous HTTP requests, WebSocket subscriptions, or event-driven mechanisms, depending on the sidecar’s interface.

Running Sidecars​

  1. Launch the Sidecar:

    • Start the sidecar service as an independent process.
    • Confirm it’s reachable at its designated endpoint (e.g., http://localhost:5000).

  2. Deploy the Paranet:

    • Start your Paranet services, including any agents that depend on the sidecar.
    • Example: Call actor.deploy("workflow", restart=False) in the agent script.

  3. Optional Debugging Sidecar:

    • Run an additional sidecar for monitoring or diagnostics on a separate port, if required.

Best Practices​

  • Environment Variables: Pass connection details (e.g., URLs) via the env section in the Paraflow configuration for flexibility.
  • Error Handling: Implement resilient error handling in agents to address potential sidecar failures or disruptions.
  • Scalability: Enable sidecars to run on separate machines by adjusting connection settings as needed.
  • Documentation: Provide clear documentation of sidecar interfaces, including endpoints and data formats, for agent developers.

Conclusion​

Sidecars enrich Paraflow development by facilitating integration with external systems and offering tools for monitoring and debugging. Designing them as independent, interoperable services enhances the adaptability and extensibility of your Paranet workflows across varied scenarios.