diff --git a/.secrets.baseline b/.secrets.baseline index 2871d864..ab6dc356 100644 --- a/.secrets.baseline +++ b/.secrets.baseline @@ -169,7 +169,7 @@ "filename": "docs/docs/en/user-guide/adapters/fastapi_nats/index.md", "hashed_secret": "3be2e9dd1980856faddf5bd205e3ff96b24776aa", "is_verified": false, - "line_number": 287, + "line_number": 273, "is_secret": false } ], @@ -179,7 +179,7 @@ "filename": "docs/docs/en/user-guide/adapters/nats/index.md", "hashed_secret": "3be2e9dd1980856faddf5bd205e3ff96b24776aa", "is_verified": false, - "line_number": 140, + "line_number": 131, "is_secret": false } ], diff --git a/docs/docs/en/user-guide/adapters/fastapi/index.md b/docs/docs/en/user-guide/adapters/fastapi/index.md index 65ee2cac..2e2fcc50 100644 --- a/docs/docs/en/user-guide/adapters/fastapi/index.md +++ b/docs/docs/en/user-guide/adapters/fastapi/index.md @@ -6,7 +6,7 @@ The [**`FastAPIAdapter`**](../../../api/fastagency/adapters/fastapi/FastAPIAdapt When to Use the [**`FastAPIAdapter`**](../../../api/fastagency/adapters/fastapi/FastAPIAdapter.md): -- **Custom Client Applications**: If you want to build your **own client applications** in a language other than Python, (e.g., [**HTML**](https://en.wikipedia.org/wiki/HTML){target="_blank"}/[**JavaScript**](https://en.wikipedia.org/wiki/JavaScript){target="_blank"}), that interacts with your FastAgency workflows using [**REST API**](https://en.wikipedia.org/wiki/REST){target="_blank"} and [**WebSockets**](https://en.wikipedia.org/wiki/WebSocket){target="_blank"}. +- **Custom Client Applications**: If you want to build your **own client applications** in a different language, (e.g., [**HTML**](https://en.wikipedia.org/wiki/HTML){target="_blank"}/[**JavaScript**](https://en.wikipedia.org/wiki/JavaScript){target="_blank"}, [**Go**](https://go.dev/){target="_blank"}, [**Java**](https://www.java.com/en/){target="_blank"}, etc.), that interacts with your FastAgency workflows using [**REST API**](https://en.wikipedia.org/wiki/REST){target="_blank"} and [**WebSockets**](https://en.wikipedia.org/wiki/WebSocket){target="_blank"}. - **Moderate User Demand**: This adapter is a good fit for scenarios where workflows need to be executed by [**multiple workers**](https://fastapi.tiangolo.com/deployment/server-workers/){target="_blank"} to efficiently handle higher machine load. @@ -30,7 +30,7 @@ This section provides [**high-level architecture**](https://en.wikipedia.org/wik The client App serves as the frontend interface for the system. It includes: - - [**`MesopUI`**](../../../api/fastagency/ui/mesop/MesopUI.md): A friendly web interface for users to interact with the workflows. It facilitates the communication with the user and the **`FastAPIProvider`**. + - [**`MesopUI`**](../../../api/fastagency/ui/mesop/MesopUI.md): A friendly web interface for users to interact with the workflows. It facilitates the communication with the user and the [**`FastAPIProvider`**](../../../api/fastagency/adapters/fastapi/FastAPIProvider.md). - [**`FastAPIProvider`**](../../../api/fastagency/adapters/fastapi/FastAPIProvider.md): A component that facilitates communication between the Mesop client and the [**`FastAPIAdapter`**](../../../api/fastagency/adapters/fastapi/FastAPIAdapter.md). This app handles all client interactions and presents the results back to the user. @@ -40,18 +40,9 @@ This section provides [**high-level architecture**](https://en.wikipedia.org/wik The FastAPI App forms the backend of our system and consists of: - **AutoGen Workflows**: These define the core logic and behavior of our application, utilizing agents to perform various tasks and achieve specific goals. - - The [**`FastAPIAdapter`**](../../../api/fastagency/adapters/fastapi/FastAPIAdapter.md): This component communicates with AutoGen, and implements routes and websocket for FastAPI. - - [**FastAPI**](https://fastapi.tiangolo.com/){target="_blank"}: Provides the infrastructure for building and exposing AutoGen workflows via REST API. + - The [**`FastAPIAdapter`**](../../../api/fastagency/adapters/fastapi/FastAPIAdapter.md): This component communicates with [**AutoGen**](https://microsoft.github.io/autogen){target="_blank"}, and implements routes and [**websocket**](https://en.wikipedia.org/wiki/WebSocket){target="_blank"} for [**FastAPI**](https://fastapi.tiangolo.com/){target="_blank"}. + - [**FastAPI**](https://fastapi.tiangolo.com/){target="_blank"}: Provides the infrastructure for building and exposing [**AutoGen**](https://microsoft.github.io/autogen){target="_blank"} workflows via [**REST API**](https://en.wikipedia.org/wiki/REST){target="_blank"}. - #### Interaction Flow - - 1. The user initiates communication with the Mesop client in the client App. - 2. The Mesop client interacts with the FastAPI Provider, sending requests based on user actions. - 3. The FastAPI Provider communicates these requests to the FastAPI Adapter in the FastAPI App. - 4. The FastAPI Adapter processes the requests and triggers the appropriate AutoGen workflows. - 5. The AutoGen workflows execute, performing the required tasks and generating results. - 6. Results are sent back through the FastAPI Adapter to the FastAPI Provider. - 7. The FastAPI Provider relays the results to the Mesop client, which then presents them to the user. === "Custom REST API and Websocket" @@ -59,29 +50,29 @@ This section provides [**high-level architecture**](https://en.wikipedia.org/wik The system consists of two main components: - #### Client App + #### Custom Client App - The Client App serves as the frontend interface for the system. It includes: + This application serves as the frontend interface for the system. It includes: - - **Custom Client**: A custom web interface for users to interact with the workflows. It facilitates the communication with the user and the **FastAPI App**. + - **Custom Client**: A client application built in a different language, (e.g., [**HTML**](https://en.wikipedia.org/wiki/HTML){target="_blank"}/[**JavaScript**](https://en.wikipedia.org/wiki/JavaScript){target="_blank"}, [**Go**](https://go.dev/){target="_blank"}, [**Java**](https://www.java.com/en/){target="_blank"}, etc.) facilitates communication between the user and the [**`FastAPIAdapter`**](../../../api/fastagency/adapters/fastapi/FastAPIAdapter.md). - This custom client app handles all interactions with the **FastAPI App** and presents the results back to the user. + This application handles all interactions with the [**`FastAPIAdapter`**](../../../api/fastagency/adapters/fastapi/FastAPIAdapter.md) and presents the results back to the user. #### FastAPI App The FastAPI App forms the backend of our system and consists of: - **AutoGen Workflows**: These define the core logic and behavior of our application, utilizing agents to perform various tasks and achieve specific goals. - - [**`FastAPIAdapter`**](../../../api/fastagency/adapters/fastapi/FastAPIAdapter.md): This component communicates with AutoGen, and implements routes and websocket for FastAPI. - - [**FastAPI**](https://fastapi.tiangolo.com/){target="_blank"}: Provides the infrastructure for building and exposing AutoGen workflows via REST API. + - The [**`FastAPIAdapter`**](../../../api/fastagency/adapters/fastapi/FastAPIAdapter.md): This component communicates with [**AutoGen**](https://microsoft.github.io/autogen){target="_blank"}, and implements routes and [**websocket**](https://en.wikipedia.org/wiki/WebSocket){target="_blank"} for [**FastAPI**](https://fastapi.tiangolo.com/){target="_blank"}. + - [**FastAPI**](https://fastapi.tiangolo.com/){target="_blank"}: Provides the infrastructure for building and exposing [**AutoGen**](https://microsoft.github.io/autogen){target="_blank"} workflows via [**REST API**](https://en.wikipedia.org/wiki/REST){target="_blank"}. #### Building Custom Client Applications - To write a custom application that interacts with FastAPI App, we first need to understand the **available server routes** and their purposes. This knowledge forms the foundation of our client-server interaction model. + To write a custom application that interacts with [**`FastAPIAdapter`**](../../../api/fastagency/adapters/fastapi/FastAPIAdapter.md), it's essential to first understand the available server routes it provides and their purposes. This knowledge forms the foundation of the [**client-server**](https://en.wikipedia.org/wiki/Client%E2%80%93server_model){target="_blank"} interaction model. ##### Available API Endpoints - FastAPI App provides three primary endpoints for building client applications: + [**`FastAPIAdapter`**](../../../api/fastagency/adapters/fastapi/FastAPIAdapter.md) provides three primary endpoints for building client applications: | Route | Method |Purpose | | -------- | ------- | ------- | @@ -94,12 +85,12 @@ This section provides [**high-level architecture**](https://en.wikipedia.org/wik ##### System Interaction Flow - The following sequence diagram illustrates the step-by-step process of how a **custom client application** interacts with the FastAgency FastAPI server: + The following sequence diagram illustrates the step-by-step process of how a **custom client application** interacts with the [**`FastAPIAdapter`**](../../../api/fastagency/adapters/fastapi/FastAPIAdapter.md): ```mermaid sequenceDiagram participant Client as Custom Client Application - participant FastAPI as FastAPI App + participant FastAPI as FastAPIAdapter Note over Client,FastAPI: 1. Setup & Discovery Phase Client->>FastAPI: GET /fastagency/discovery @@ -139,16 +130,16 @@ This section provides [**high-level architecture**](https://en.wikipedia.org/wik - **Selection**: User selects a workflow to execute. - **Initiation**: Client requests to start the chosen workflow. - **Connection**: WebSocket connection established for real-time communication. These includes: - - Server sending workflow message to the client - - Client sends optional response to server if previous server message requires user input - - Server processes and sends the next workflow message + - Server sending workflow message to the client. + - Client sends optional response to server if previous server message requires user input. + - Server processes and sends the next workflow message. ##### Message Types - Before diving into the implementation, we need to learn a bit about the **message types** that FastAgency FastAPI adapter provides. Understanding these will help us handle messages in our custom client and display them properly to the users. + Before diving into the implementation, we need to learn a bit about the **message types** that [**`FastAPIAdapter`**](../../../api/fastagency/adapters/fastapi/FastAPIAdapter.md) provides. Understanding these will help us handle messages in our custom client and display them properly to the users. - FastAgency tags each message sent from the server to the client over WebSocket with a `type` attribute. This helps the client differentiate between different types of messages and handle them accordingly. Let’s break them down into two categories: + FastAgency tags each message sent from the server to the client over [**WebSockets**](https://en.wikipedia.org/wiki/WebSocket){target="_blank"} with a `type` attribute. This helps the client differentiate between different types of messages and handle them accordingly. Let’s break them down into two categories: **Messages for Display**: @@ -168,14 +159,14 @@ This section provides [**high-level architecture**](https://en.wikipedia.org/wik ##### Implementation Guide - In the following sections, we'll walk through the process of creating a custom client application that implements the flow we've just described. We'll build a simple web-based client that demonstrates how to interact with **FastAPI App** effectively. + In the following sections, we'll walk through the process of creating a custom client application that implements the flow we've just described. We'll build a simple web-based client that demonstrates how to interact with [**`FastAPIAdapter`**](../../../api/fastagency/adapters/fastapi/FastAPIAdapter.md) effectively. Our implementation will cover these key aspects: - - Fetching and displaying available workflows - - Handling workflow initiation - - Managing WebSocket connections - - Processing real-time messages + - Fetching and displaying available workflows. + - Handling workflow initiation. + - Managing WebSockets connection. + - Processing real-time messages. !!! note @@ -189,33 +180,35 @@ This section provides [**high-level architecture**](https://en.wikipedia.org/wik ## Installation -Before getting started, make sure you have installed FastAgency by running the following command: - === "Mesop" + Before getting started, ensure that FastAgency is installed with support for the [**AutoGen**](../../../api/fastagency/runtimes/autogen/autogen/AutoGenWorkflows.md) runtime, along with the [**mesop**](../../../api/fastagency/ui/mesop/MesopUI.md), **fastapi**, and **server** submodules by running the following command: + ```bash pip install "fastagency[autogen,mesop,fastapi,server]" ``` - This command installs FastAgency with support for both the Console and Mesop interfaces for AutoGen workflows, but with FastAPI serving input requests and running workflows. + This command installs FastAgency with support for both the [**mesop**](../../../api/fastagency/ui/mesop/MesopUI.md) and [**console**](../../../api/fastagency/ui/console/ConsoleUI.md) interfaces for [**AutoGen**](https://microsoft.github.io/autogen){target="_blank"} workflows, but with [**FastAPI**](https://fastapi.tiangolo.com/){target="_blank"} serving input requests and running workflows. === "Custom REST API and Websocket" + Before getting started, ensure that FastAgency is installed with support for the [**AutoGen**](../../../api/fastagency/runtimes/autogen/autogen/AutoGenWorkflows.md) runtime, along with the **fastapi**, and **server** submodules by running the following command: + ```bash pip install "fastagency[autogen,fastapi,server]" ``` - This command installs FastAgency, but with FastAPI serving input requests and running workflows. + This command installs FastAgency, but with [**FastAPI**](https://fastapi.tiangolo.com/){target="_blank"} serving input requests and running workflows. ## Example: Student and Teacher Learning Chat === "Mesop" - In this example, we'll create a simple learning chat where a student agent asks questions and a teacher agent responds, simulating a learning environment. We'll use MesopUI for the web interface and the FastAPI Adapter to expose the workflow as a REST API. + In this example, we'll create a simple learning [**chatbot**](https://en.wikipedia.org/wiki/Chatbot){target="_blank"} where a student agent asks questions and a teacher agent responds, simulating a learning environment. We'll use [**`MesopUI`**](../../../api/fastagency/ui/mesop/MesopUI.md) for the web interface and the [**`FastAPIAdapter`**](../../../api/fastagency/adapters/fastapi/FastAPIAdapter.md) to expose the workflow as a [**REST API**](https://en.wikipedia.org/wiki/REST){target="_blank"}. === "Custom REST API and Websocket" - In this example, we'll create a simple learning chat where a student agent asks questions and a teacher agent responds, simulating a learning environment. We'll create a custom client for the web interface and the FastAPI Adapter to expose the workflow as a REST API. + In this example, we'll create a simple learning [**chatbot**](https://en.wikipedia.org/wiki/Chatbot){target="_blank"} where a student agent asks questions and a teacher agent responds, simulating a learning environment. We'll create a custom client using [**HTML**](https://en.wikipedia.org/wiki/HTML){target="_blank"} and [**JavaScript**](https://en.wikipedia.org/wiki/JavaScript){target="_blank"} for the web interface and the [**`FastAPIAdapter`**](../../../api/fastagency/adapters/fastapi/FastAPIAdapter.md) to expose the workflow as a [**REST API**](https://en.wikipedia.org/wiki/REST){target="_blank"}. ### Step-by-Step Breakdown @@ -223,7 +216,7 @@ Before getting started, make sure you have installed FastAgency by running the f === "Mesop" - To get started, import the required modules from the **FastAgency** and **AutoGen**. These imports provide the essential building blocks for creating agents, workflows, and integrating MesopUI. Additionally, import the [**`FastAPIAdapter`**](../../../api/fastagency/adapters/fastapi/FastAPIAdapter.md) class to expose the workflows as a REST API. + To get started, import the required modules from the **FastAgency** and **AutoGen**. These imports provide the essential building blocks for creating agents, workflows, and integrating [**`MesopUI`**](../../../api/fastagency/ui/mesop/MesopUI.md). Additionally, import the [**`FastAPIAdapter`**](../../../api/fastagency/adapters/fastapi/FastAPIAdapter.md) class to expose the workflows as a [**REST API**](https://en.wikipedia.org/wiki/REST){target="_blank"}. ```python hl_lines="8" {!> docs_src/getting_started/fastapi/main_1_fastapi.py [ln:1-9] !} @@ -231,7 +224,7 @@ Before getting started, make sure you have installed FastAgency by running the f === "Custom REST API and Websocket" - To get started, import the required modules from the **FastAgency** and **AutoGen**. These imports provide the essential building blocks for creating agents, workflows, and integrating with the Custom client. Additionally, import the [**`FastAPIAdapter`**](../../../api/fastagency/adapters/fastapi/FastAPIAdapter.md) and [**`HTMLResponse`**](https://fastapi.tiangolo.com/advanced/custom-response/#html-response){target="_blank"} class to expose the workflows as a REST API. + To get started, import the required modules from the **FastAgency** and **AutoGen**. These imports provide the essential building blocks for creating agents, workflows, and integrating with the custom client. Additionally, import the [**`FastAPIAdapter`**](../../../api/fastagency/adapters/fastapi/FastAPIAdapter.md) and [**`HTMLResponse`**](https://fastapi.tiangolo.com/advanced/custom-response/#html-response){target="_blank"} class to expose the workflows as a [**REST API**](https://en.wikipedia.org/wiki/REST){target="_blank"}. ```python hl_lines="6 9" {!> docs_src/getting_started/fastapi/main_fastapi_custom_client.py [ln:1-10] !} @@ -247,7 +240,7 @@ Next, define the workflow that your application will use. This is where you spec #### 3. **Define FastAgency Application** -Create an instance of the [**`FastAPIAdapter`**](../../../api/fastagency/adapters/fastapi/FastAPIAdapter.md) and pass your workflow to it. Then, include a router to the [**FastAPI**](https://fastapi.tiangolo.com/){target="_blank"} application. The adapter will have all REST API and WebSocket routes for communicating with the client. +Create an instance of the [**`FastAPIAdapter`**](../../../api/fastagency/adapters/fastapi/FastAPIAdapter.md) and pass your workflow to it. Then, include a router to the [**FastAPI**](https://fastapi.tiangolo.com/){target="_blank"} application. The adapter will have all [**REST API**](https://en.wikipedia.org/wiki/REST){target="_blank"} and [**WebSocket**](https://en.wikipedia.org/wiki/WebSocket){target="_blank"} routes for communicating with the client. ```python hl_lines="1 4" {!> docs_src/getting_started/fastapi/main_1_fastapi.py [ln:55-58] !} @@ -257,7 +250,7 @@ Create an instance of the [**`FastAPIAdapter`**](../../../api/fastagency/adapter #### 4. **Adapter Chaining** - Finally, create an additional specification file for an application using **MesopUI** to connect to the [**`FastAPIAdapter`**](../../../api/fastagency/adapters/fastapi/FastAPIAdapter.md). + Finally, create an additional specification file for an application using [**`MesopUI`**](../../../api/fastagency/ui/mesop/MesopUI.md) to connect to the [**`FastAPIAdapter`**](../../../api/fastagency/adapters/fastapi/FastAPIAdapter.md). !!! note "main_2_mesop.py" ```python @@ -268,7 +261,7 @@ Create an instance of the [**`FastAPIAdapter`**](../../../api/fastagency/adapter #### 4. **Serving the Custom HTML Client** - Finally, use the HTML Response from FastAPI to serve the custom client code. + Finally, use the [**HTML Response**](https://fastapi.tiangolo.com/advanced/custom-response/#html-response){target="_blank"} from FastAPI to serve the custom client code. ```python {!> docs_src/getting_started/fastapi/main_fastapi_custom_client.py [ln:12-98,146-148] !} @@ -309,13 +302,13 @@ Please copy and paste the following code into the same folder, using the file na Once everything is set up, you can run your FastAgency application using the following commands. You need to run **two** commands in **separate** terminal windows: - - Start **FastAPI** application using uvicorn: + - Start **FastAPI** application using [**uvicorn**](https://www.uvicorn.org){target="_blank"}: !!! note "Terminal 1" ``` uvicorn main_1_fastapi:app --host 0.0.0.0 --port 8008 --reload ``` - - Start **Mesop** web interface using gunicorn: + - Start **Mesop** web interface using [**gunicorn**](https://gunicorn.org){target="_blank"}: !!! note "Terminal 2" ``` gunicorn main_2_mesop:app -b 0.0.0.0:8888 --reload @@ -331,10 +324,10 @@ Please copy and paste the following code into the same folder, using the file na Once everything is set up, you can run your FastAgency application using the following command. - - Start **FastAPI** application using uvicorn: + - Start **FastAPI** application using [**uvicorn**](https://www.uvicorn.org){target="_blank"}: !!! note "Terminal 1" ``` - uvicorn main_fastapi_custom_client:app --host 0.0.0.0 --port 8008 --reload + uvicorn main_fastapi_custom_client:app --port 8008 --reload ``` ### Output @@ -365,4 +358,4 @@ The outputs will vary based on the interface. Here is the output of the last ter ![Output Screenshot](../images/custom_chat_output.png) -The **FastAPI Adapter** provides a powerful solution for developers seeking a **user-friendly** and efficient way to expose their FastAgency workflows as **REST APIs**, contributing to building production-ready applications. +The [**`FastAPIAdapter`**](../../../api/fastagency/adapters/fastapi/FastAPIAdapter.md) provides a powerful solution for developers seeking a **user-friendly** and efficient way to expose their FastAgency workflows as [**REST API**](https://en.wikipedia.org/wiki/REST){target="_blank"}, contributing to building production-ready applications. diff --git a/docs/docs/en/user-guide/adapters/fastapi_nats/index.md b/docs/docs/en/user-guide/adapters/fastapi_nats/index.md index 8565a3f0..c6289184 100644 --- a/docs/docs/en/user-guide/adapters/fastapi_nats/index.md +++ b/docs/docs/en/user-guide/adapters/fastapi_nats/index.md @@ -1,134 +1,123 @@ # FastAPI + Nats.io -The **FastAPI + Nats.io** Adapter in FastAgency offers the most scalable setup by combining the power of the [**FastAPI**](https://fastapi.tiangolo.com/){target="_blank"} framework for building and exposing workflows as [**REST APIs**](https://en.wikipedia.org/wiki/REST){target="_blank"} with the [**Nats.io MQ**](https://nats.io/){target="_blank"} message broker for **scalable and asynchronous** communication. This setup is the **preferred way** for running large workloads in production. +Combining the [**`FastAPIAdapter`**](../../../api/fastagency/adapters/fastapi/FastAPIAdapter.md) and [**`NatsAdapter`**](../../../api/fastagency/adapters/nats/NatsAdapter.md) in FastAgency provides the most scalable setup. It harnesses the power of the [**FastAPI**](https://fastapi.tiangolo.com/){target="_blank"} framework to build and expose workflows as [**REST APIs**](https://en.wikipedia.org/wiki/REST){target="_blank"} while utilizing the [**Nats.io**](https://nats.io/){target="_blank"} message broker for scalable and asynchronous communication. This setup is **preferred** for running large workloads in production. ## Use Cases -This section outlines the scenarios where it's particularly beneficial to use the **FastAPI + Nats** Adapter. +This section outlines the scenarios where it is particularly beneficial to combine the `FastAPIAdapter` and `NATSAdapter`. -### When to Use the FastAPI + Nats.io Adapter +When to Use the `FastAPIAdapter` and `NATSAdapter` Together: -- **High User Demand**: If you need to scale above what can be achieved with multiple-workers of the [**FastAPI** adapter](../fastapi/index.md), then you can use [**Nats.io MQ**](https://nats.io/){target="_blank"}-based message que and multiple workers consuming and producing messages. This kind of distributed, [message-queue architecture](https://en.wikipedia.org/wiki/Message_queue){target="_blank"} allows you to scale up not just across multiple workers, but also across multiple machines and even across multiple clusters. +- **High User Demand**: If you need to scale beyond what [**multiple workers**](https://fastapi.tiangolo.com/deployment/server-workers/){target="_blank"} of the [**FastAPIAdapter**](../fastapi/index.md) can achieve, you can use [**Nats.io**](https://nats.io/){target="_blank"} with a [**message queue**](https://en.wikipedia.org/wiki/Message_queue){target="_blank"} and [**multiple workers**](https://fastapi.tiangolo.com/deployment/server-workers/){target="_blank"} to consume and produce messages. This distributed message-queue architecture allows scaling not only across multiple workers but also across multiple machines and clusters. -- **Observability**: If you need the ability to **audit workflow executions** both in realtime and posteriori, the Nats Adapter provides the necessary infrastructure to enable this feature. +- [**Observability**](https://en.wikipedia.org/wiki/Observability_(software)){target="_blank"}: If you need the ability to **audit workflow executions** both in realtime and retrospectively, the [**`NatsAdapter`**](../../../api/fastagency/adapters/nats/NatsAdapter) provides the necessary infrastructure to enable this feature. -- Security features of FastAPI (links etc.) +- **Security features of FastAPI**: If you want to leverage the [**security features**](https://fastapi.tiangolo.com/tutorial/security){target="_blank"} of FastAPI, such as authentication, authorization, along with the [**distributed architecture**](https://en.wikipedia.org/wiki/Distributed_computing){target="_blank"} of NATS, this setup is the most suitable option. Please check the [**securing your FastAPIAdapter**](../fastapi/security.md) documentation for more information. ## Architecture Overview -The following section presents high-level architecture diagrams for the two available setups: +The following section presents high-level architecture diagrams for the two available setups using the [**`FastAPIAdapter`**](../../../api/fastagency/adapters/fastapi/FastAPIAdapter.md) and [**`NatsAdapter`**](../../../api/fastagency/adapters/nats/NatsAdapter.md) together with: -- **FastAPI + Nats Adapter with Mesop Client** -- **FastAPI + Nats Adapter with Custom Client** +- [**Mesop**](https://google.github.io/mesop/){target="_blank"} client using [**`MesopUI`**](../../../api/fastagency/ui/mesop/MesopUI.md), and -=== "FastAPI + Nats Adapter with Mesop Client" +- Custom [**REST API**](https://en.wikipedia.org/wiki/REST){target="_blank"} and [**WebSocket**](https://en.wikipedia.org/wiki/WebSocket){target="_blank"} client + +=== "Mesop" ![Mesop FastAPI](../images/mesop_fastapi_nats.png) The system is composed of three main components: - #### 1. FastAgency Client App + #### 1. Mesop Client App - The FastAgency Client App serves as the frontend interface for the system. It includes: + This application serves as the frontend interface for the system. It includes: - - **Mesop Client**: A friendly web interface for users to interact with the workflows. It facilitates the communication with the user and the FastAPI Provider. - - **FastAPI Provider**: A component that facilitates communication between the Mesop client and the FastAPI Adapter. + - [**`MesopUI`**](../../../api/fastagency/ui/mesop/MesopUI.md): A friendly web interface for users to interact with the workflows. It facilitates the communication with the user and the [**`FastAPIProvider`**](../../../api/fastagency/adapters/fastapi/FastAPIProvider.md). + - [**`FastAPIProvider`**](../../../api/fastagency/adapters/fastapi/FastAPIProvider.md): A component that facilitates communication between the Mesop client and the [**`FastAPIAdapter`**](../../../api/fastagency/adapters/fastapi/FastAPIAdapter.md). - This app handles all client interactions and presents the results back to the user. +=== "Custom REST API and WebSocket" - #### 2. FastAgency FastAPI App + ![Mesop FastAPI](../images/custom_fastapi_nats.png) - The FastAgency FastAPI App forms the backend of our system and consists of: + The system is composed of three main components: - - **Nats Provider**: Responsible for connecting to the Nats Provider, receiving workflow initiation messages, and distributing them to the workers for execution. - - **FastAPI Adapter**: This component communicates with AutoGen, and implements routes and websocket for FastAPI. - - **FastAPI**: Provides the infrastructure for building and exposing AutoGen workflows via REST API. + #### 1. Custom Client App - #### 3. FastAgency Nats App - - **Nats Adapter**: This adapter connects to the Nats Provider. Its primary responsibility is to receive workflow initiation messages and delegate them to available workers for execution. - - **AutoGen Workflows**: These workflows, defined using the AutoGen framework, embody the core logic and behavior of your application. They leverage agents to perform various tasks and accomplish specific goals. + This application serves as the frontend interface for the system. It includes: - #### Interaction Flow - 1. The user initiates communication with the Mesop client in the FastAgency Client App. - 2. The Mesop client relays requests, based on user actions, to the FastAPI Provider. - 3. The FastAPI Provider forwards these requests to the FastAPI Adapter in the FastAgency FastAPI App. - 4. The FastAPI Adapter processes the requests and sends a message to the Nats Provider to start the workflow. - 5. The Nats Adapter, connected to the Nats Provider, receives the workflow initiation message. - 6. The Nats Adapter distributes the task of executing the workflow to one of the available workers. - 7. The designated worker executes the AutoGen Workflow and sends the results back through the Nats Provider to the FastAPI Adapter. - 8. The FastAPI Adapter sends the results to the FastAPI Provider, which relays them to the Mesop client for presentation to the client. + - **Custom Client**: A client application built in a different language, (e.g., [**HTML**](https://en.wikipedia.org/wiki/HTML){target="_blank"}/[**JavaScript**](https://en.wikipedia.org/wiki/JavaScript){target="_blank"}, [**Go**](https://go.dev/){target="_blank"}, [**Java**](https://www.java.com/en/){target="_blank"}, etc.) that facilitates communication between the user and the [**`FastAPIAdapter`**](../../../api/fastagency/adapters/fastapi/FastAPIAdapter.md). - This architecture promotes a clear separation of concerns between the user interface, the API layer, and the workflow execution logic, enhancing modularity and maintainability. The FastAPI framework provides a user-friendly and efficient API, while the Nats Adapter, coupled with the Nats.io MQ message broker, ensures scalability and asynchronous communication. + This application handles all interactions with the [**`FastAPIAdapter`**](../../../api/fastagency/adapters/fastapi/FastAPIAdapter.md) and presents the results back to the user. -=== "FastAPI + Nats Adapter with Custom Client" +#### 2. FastAPI App - ![Mesop FastAPI](../images/custom_fastapi_nats.png) +This application is part of our system's backend and consists of: - The system is composed of three main components: +- [**`NatsProvider`**](../../../api/fastagency/adapters/nats/NatsProvider.md): Responsible for connecting to the [**`NatsAdapter`**](../../../api/fastagency/adapters/nats/NatsAdapter.md), receiving workflow initiation messages, and distributing them to the workers for execution. + +- [**`FastAPIAdapter`**](../../../api/fastagency/adapters/fastapi/FastAPIAdapter.md): This component communicates with `NatsProvider`, and implements routes and websocket for FastAPI. + +- [**FastAPI**](https://fastapi.tiangolo.com/){target="_blank"}: Provides the infrastructure for building and exposing [**AutoGen**](https://microsoft.github.io/autogen){target="_blank"} workflows via [**REST API**](https://en.wikipedia.org/wiki/REST){target="_blank"}. - #### 1. FastAgency Client App +#### 3. Nats App - The FastAgency Client App serves as the frontend interface for the system. It includes: +This application is also part of our system's backend and consists of: - - **Custom Client**: A custom web interface for users to interact with the workflows. It facilitates the communication with the user and the **FastAgency FastAPI App**. +- [**`NatsAdapter`**](../../../api/fastagency/adapters/nats/NatsAdapter.md): This adapter connects to the `NatsProvider` and is responsible for communicating with AutoGen workflows. - This custom client app handles all interactions with the **FastAgency FastAPI App** and presents the results back to the user. +- **AutoGen Workflows**: These workflows, defined using the AutoGen framework, embody the core logic and behavior of your application. They leverage agents to perform various tasks and accomplish specific goals. - #### 2. FastAgency FastAPI App +This architecture promotes a clear separation of concerns between the user interface, the API layer, and the workflow execution logic, enhancing modularity and maintainability. The [**FastAPI**](https://fastapi.tiangolo.com/){target="_blank"} framework provides a user-friendly and efficient [**REST API**](https://en.wikipedia.org/wiki/REST){target="_blank"}, while the `NATSAdapter`, combined with the [**Nats.io**](https://nats.io/){target="_blank"} message broker, ensures scalability and asynchronous communication. - The FastAgency FastAPI App forms the backend of our system and consists of: +=== "Mesop" - - **Nats Provider**: Responsible for connecting to the Nats Provider, receiving workflow initiation messages, and distributing them to the workers for execution. - - **FastAPI Adapter**: This component communicates with AutoGen, and implements routes and websocket for FastAPI. - - **FastAPI**: Provides the infrastructure for building and exposing AutoGen workflows via REST API. - #### 3. FastAgency Nats App - - **Nats Adapter**: This adapter connects to the Nats Provider. Its primary responsibility is to receive workflow initiation messages and delegate them to available workers for execution. - - **AutoGen Workflows**: These workflows, defined using the AutoGen framework, embody the core logic and behavior of your application. They leverage agents to perform various tasks and accomplish specific goals. +=== "Custom REST API and WebSocket" #### Building Custom Client Applications - For details on building a custom client that interacts with the FastAgency FastAPI backend, check out the guide [here](../fastapi/index.md#building-custom-client-applications). It covers the **routes, message types, and integration steps in detail**, helping you set up seamless communication with FastAgency’s FastAPI backend. + For details on building a custom client that interacts with the FastAPI backend, check out the guide [**here**](../fastapi/index.md#building-custom-client-applications). It covers the **routes, message types, and integration steps in detail**, helping you set up seamless communication with FastAPI backend. + +Now, it's time to see the [**`FastAPIAdapter`**](../../../api/fastagency/adapters/fastapi/FastAPIAdapter.md) and [**`NatsAdapter`**](../../../api/fastagency/adapters/nats/NatsAdapter) in action together. Let's dive into an example and learn how to use it! + -Now, it's time to see the **FastAPI + Nats Adapter** using FastAgency in action. Let's dive into an example and learn how to use it! ## Installation -Before getting started, make sure you have installed FastAgency by running the following command: +=== "Mesop" -=== "FastAPI + Nats Adapter with Mesop Client" + Before getting started, ensure that FastAgency is installed with support for the [**AutoGen**](../../../api/fastagency/runtimes/autogen/autogen/AutoGenWorkflows.md) runtime, along with the [**mesop**](../../../api/fastagency/ui/mesop/MesopUI.md), **fastapi**, **server**, and **nats** submodules by running the following command: ```bash pip install "fastagency[autogen,mesop,fastapi,server,nats]" ``` - This command installs FastAgency with support for both the Console and Mesop interfaces for AutoGen workflows, but with FastAPI serving input requests and independent workers communicating over Nats.io protocol running workflows. + This command installs FastAgency with support for both the [**mesop**](../../../api/fastagency/ui/mesop/MesopUI.md) and [**console**](../../../api/fastagency/ui/console/ConsoleUI.md) interfaces for [**AutoGen**](https://microsoft.github.io/autogen){target="_blank"} workflows, but with [**FastAPI**](https://fastapi.tiangolo.com/){target="_blank"} serving input requests and independent workers communicating over [**Nats.io**](https://nats.io/){target="_blank"} protocol running workflows. -=== "FastAPI + Nats Adapter with Custom Client" +=== "Custom REST API and WebSocket" + + Before getting started, ensure that FastAgency is installed with support for the [**AutoGen**](../../../api/fastagency/runtimes/autogen/autogen/AutoGenWorkflows.md) runtime, along with the **fastapi**, **server**, and **nats** submodules by running the following command: ```bash pip install "fastagency[autogen,fastapi,server,nats]" ``` - This command installs FastAgency, but with FastAPI serving input requests and independent workers communicating over Nats.io protocol running workflows. + This command installs FastAgency, but with [**FastAPI**](https://fastapi.tiangolo.com/){target="_blank"} serving input requests and independent workers communicating over [**Nats.io**](https://nats.io/){target="_blank"} protocol running workflows. ## Example: Student and Teacher Learning Chat -=== "FastAPI + Nats Adapter with Mesop Client" - - In this example, we'll create a simple learning chat where a student agent asks questions and a teacher agent responds, simulating a learning environment. We'll use **MesopUI** for the web interface and the **FastAPI + Nats** Adapter to expose the workflow as a REST API. +=== "Mesop" - ### Step-by-Step Breakdown + In this example, we'll create a simple learning [**chatbot**](https://en.wikipedia.org/wiki/Chatbot){target="_blank"} where a student agent asks questions and a teacher agent responds, simulating a learning environment. We'll use [**`MesopUI`**](../../../api/fastagency/ui/mesop/MesopUI.md) for the web interface and the [**`FastAPIAdapter`**](../../../api/fastagency/adapters/fastapi/FastAPIAdapter.md) and [**`NatsAdapter`**](../../../api/fastagency/adapters/nats/NatsAdapter) for serving and executing the workflows. - As shown in the [architecture overview](#architecture-overview), this setup requires **three** components (applications). Let's begin with the first component, the [FastAgency NATS App](#3-fastagency-nats-app). +=== "Custom REST API and WebSocket" -=== "FastAPI + Nats Adapter with Custom Client" + In this example, we'll create a simple learning [**chatbot**](https://en.wikipedia.org/wiki/Chatbot){target="_blank"} where a student agent asks questions and a teacher agent responds, simulating a learning environment. We'll create a custom client using [**HTML**](https://en.wikipedia.org/wiki/HTML){target="_blank"} and [**JavaScript**](https://en.wikipedia.org/wiki/JavaScript){target="_blank"} for the web interface and the [**`FastAPIAdapter`**](../../../api/fastagency/adapters/fastapi/FastAPIAdapter.md) and [**`NatsAdapter`**](../../../api/fastagency/adapters/nats/NatsAdapter) for serving and executing the workflows. - In this example, we'll create a simple learning chat where a student agent asks questions and a teacher agent responds, simulating a learning environment. We'll use **custom client** for the web interface and the **FastAPI + Nats** Adapter to expose the workflow as a REST API. - ### Step-by-Step Breakdown +### Step-by-Step Breakdown - As shown in the [architecture overview](#architecture-overview), this setup requires **three** components (applications). Let's begin with the first component, the [FastAgency NATS App](#3-fastagency-nats-app_1). +As shown in the [**architecture overview**](#architecture-overview), this setup requires **three** components (applications). Let's begin our code walkthrough, starting with the [**NATS App**](#3-nats-app). #### 1. **Import Required Modules** @@ -146,9 +135,9 @@ Next, define the workflow that your application will use. This is where you spec {! docs_src/getting_started/nats_n_fastapi/main_1_nats.py [ln:11-52] !} ``` -#### 3. **Configure the Nats Adapter** +#### 3. **Configure the `NatsAdapter`** -Create an instance of the NatsAdapter and pass your workflow to it. The adapter will handle the communication with the Nats Provider and distribute workflow execution to the workers. +Create an instance of the [**`NatsAdapter`**](../../../api/fastagency/adapters/nats/NatsAdapter.md) and pass your workflow to it. The adapter will handle the communication with the [**`NatsProvider`**](../../../api/fastagency/adapters/nats/NatsProvider.md) and distribute workflow execution to the workers. ```python hl_lines="5 7" {!> docs_src/getting_started/nats_n_fastapi/main_1_nats.py [ln:55-60] !} @@ -156,7 +145,7 @@ Create an instance of the NatsAdapter and pass your workflow to it. The adapter #### 4. **Define FastAgency Application** -Create an NatsAdapter and then add it to a FastAPI application using the lifespan parameter. The adapter will have all REST and Websocket routes for communicating with a client. For more information on the lifespan parameter, check out the official documentation [**here**](https://fastapi.tiangolo.com/advanced/events/){target="_blank"} +Create a [**`NatsAdapter`**](../../../api/fastagency/adapters/nats/NatsAdapter.md) and then add it to the [**FastAPI**](https://fastapi.tiangolo.com/){target="_blank"} application using the [**lifespan parameter**](https://fastapi.tiangolo.com/advanced/events/){target="_blank"}. ```python {!> docs_src/getting_started/nats_n_fastapi/main_1_nats.py [ln:61] !} @@ -166,33 +155,30 @@ Create an NatsAdapter and then add it to a FastAPI application using the lifespa Above, we created Nats.io provider that will start brokers waiting to consume initiate workflow messages from the message broker. -=== "FastAPI + Nats Adapter with Mesop Client" +Next, we set up a FastAPI service to interact with the NATS.io provider. This introduces the second component: the [**FastAPI App**](#2-fastapi-app). - Next, we set up a FastAPI service to interact with the NATS.io provider. This introduces the second component: the [**FastAgency FastAPI App**](#2-fastagency-fastapi-app). +=== "Mesop" !!! note "main_2_fastapi.py" ```python hl_lines="16-18 21-22" {!> docs_src/getting_started/nats_n_fastapi/main_2_fastapi.py [ln:1-22] !} ``` - Finally, the third component is the [**FastAgency Client App**](#1-fastagency-client-app), which uses the **Mesop client** to communicate with both the user and the FastAPI provider. + Finally, the last component is the [**Mesop Client App**](#1-mesop-client-app), which uses the [**`MesopUI`**](../../../api/fastagency/ui/mesop/MesopUI.md) to communicate with both the user and the [**`FastAPIProvider`**](../../../api/fastagency/adapters/fastapi/FastAPIProvider.md). !!! note "main_3_mesop.py" ```python hl_lines="7-9 11" {!> docs_src/getting_started/nats_n_fastapi/main_3_mesop.py [ln:1-11] !} ``` -=== "FastAPI + Nats Adapter with Custom Client" - - Next, we’ll set up a FastAPI service to interact with the NATS.io provider, introducing the second component: the [**FastAgency FastAPI App**](#2-fastagency-fastapi-app_1). - +=== "Custom REST API and WebSocket" !!! note "main_fastapi_custom_client.py" ```python hl_lines="17-19 22-23" {!> docs_src/getting_started/nats_n_fastapi/main_2_fastapi_custom_client.py [ln:1-8,96-110] !} ``` - Finally, for simplicity, we will serve our custom HTML client as part of the same [**FastAgency FastAPI App**](#2-fastagency-fastapi-app_1) using FastAPI's [**HTMLResponse**](https://fastapi.tiangolo.com/advanced/custom-response/#html-response){target="_blank"}. + Finally, for simplicity, we will serve our custom HTML client as part of the same [**FastAPI App**](#2-fastapi-app) using FastAPI's [**HTMLResponse**](https://fastapi.tiangolo.com/advanced/custom-response/#html-response){target="_blank"}. !!! note @@ -208,7 +194,7 @@ Above, we created Nats.io provider that will start brokers waiting to consume in #### 6. **Nats server setup** -The `NatsAdapter` requires a running Nats server. The easiest way to start the Nats server is by using [Docker](https://www.docker.com/){target="_blank"}. FastAgency uses the [JetStream](https://docs.nats.io/nats-concepts/jetstream){target="_blank"} feature of Nats and also utilizes authentication. +The [**`NatsAdapter`**](../../../api/fastagency/adapters/nats/NatsAdapter.md) requires a running NATS server. The easiest way to start the NATS server is by using [**Docker**](https://www.docker.com/){target="_blank"}. FastAgency leverages the [**JetStream**](https://docs.nats.io/nats-concepts/jetstream){target="_blank"} feature of NATS and also utilizes authentication. ```python hl_lines="1 3 6 11 17" {!> docs_src/getting_started/nats_n_fastapi/nats-server.conf [ln:1-23]!} @@ -220,7 +206,7 @@ In the above Nats configuration, we define a user called `fastagency`, and its p Please copy and paste the following code into the same folder, using the file names exactly as mentioned below. -=== "FastAPI + Nats Adapter with Mesop Client" +=== "Mesop"
nats-server.conf @@ -250,7 +236,7 @@ Please copy and paste the following code into the same folder, using the file na ```
-=== "FastAPI + Nats Adapter with Custom Client" +=== "Custom REST API and WebSocket"
nats-server.conf @@ -277,7 +263,7 @@ Please copy and paste the following code into the same folder, using the file na Once everything is set up, you can run your FastAgency application using the following commands. -=== "FastAPI + Nats Adapter with Mesop Client" +=== "Mesop" You need to run **Four** commands in **separate** terminal windows: @@ -311,7 +297,7 @@ Once everything is set up, you can run your FastAgency application using the fol waitress-serve --listen=0.0.0.0:8888 main_3_mesop:app ``` -=== "FastAPI + Nats Adapter with Custom Client" +=== "Custom REST API and WebSocket" You need to run **Three** commands in **separate** terminal windows: @@ -330,7 +316,7 @@ Once everything is set up, you can run your FastAgency application using the fol - Start **FastAPI** application integrated with a **Nats** messaging system: !!! note "Terminal 3" ``` - uvicorn main_2_fastapi_custom_client:app --host 0.0.0.0 --port 8008 --reload + uvicorn main_2_fastapi_custom_client:app --port 8008 --reload ``` @@ -338,7 +324,7 @@ Once everything is set up, you can run your FastAgency application using the fol The outputs will vary based on the interface. Here is the output of the last terminal starting the UI: -=== "FastAPI + Nats Adapter with Mesop Client" +=== "Mesop" ```console [2024-10-10 13:19:18 +0530] [23635] [INFO] Starting gunicorn 23.0.0 @@ -350,7 +336,7 @@ The outputs will vary based on the interface. Here is the output of the last ter ![Initial message](../../../getting-started/images/chat.png) -=== "FastAPI + Nats Adapter with Custom Client" +=== "Custom REST API and WebSocket" ```console INFO: Will watch for changes in these directories: ['/tmp/custom_fastapi_demo'] @@ -363,6 +349,4 @@ The outputs will vary based on the interface. Here is the output of the last ter ![Output Screenshot](../images/custom_chat_output.png) -The **FastAPI + Nats** Adapter in FastAgency provides a **highly scalable** and **flexible solution** for building distributed applications. By leveraging the power of [**FastAPI**](https://fastapi.tiangolo.com/){target="_blank"} for building REST APIs and the [**Nats.io MQ**](https://nats.io/){target="_blank"} for asynchronous communication, you can create robust and efficient workflows that can handle high user demand and complex production setups. - -Whether you're building custom client applications, **scalable chat systems**, or applications that require **conversation auditing**, the **FastAPI + Nats Adapter** has you covered. +The **FastAPI + Nats** Adapter in FastAgency provides a **highly scalable** and **flexible solution** for building distributed applications. By leveraging the power of [**FastAPI**](https://fastapi.tiangolo.com/){target="_blank"} for building [**REST APIs**](https://en.wikipedia.org/wiki/REST){target="_blank"} and the [**Nats.io MQ**](https://nats.io/){target="_blank"} for asynchronous communication, you can create robust and efficient workflows that can handle high user demand and complex production setups. diff --git a/docs/docs/en/user-guide/adapters/images/custom_chat_output.png b/docs/docs/en/user-guide/adapters/images/custom_chat_output.png index fb8c4d86..f27fdb6c 100644 --- a/docs/docs/en/user-guide/adapters/images/custom_chat_output.png +++ b/docs/docs/en/user-guide/adapters/images/custom_chat_output.png @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:05d41ff8711238ceb8e138d7d9bc258cb7b5ad79ec7e8d9bc3bec99d8ab947f1 -size 413481 +oid sha256:37aa3e81dd5e997c344925686ca777248f668d36877828286644b5293dce0b7b +size 185152 diff --git a/docs/docs/en/user-guide/adapters/images/custom_fastapi.png b/docs/docs/en/user-guide/adapters/images/custom_fastapi.png index 1bd709c8..276b6c77 100644 --- a/docs/docs/en/user-guide/adapters/images/custom_fastapi.png +++ b/docs/docs/en/user-guide/adapters/images/custom_fastapi.png @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:edb6084ad24286cb846df28d4009e5f7051de96759c1273db0d440657e4450a8 -size 50933 +oid sha256:96566560e27f0f84919b0524f0864fb0818ad82ba3af49bbd915d1525fcb129d +size 52494 diff --git a/docs/docs/en/user-guide/adapters/images/custom_fastapi_nats.png b/docs/docs/en/user-guide/adapters/images/custom_fastapi_nats.png index c4f941dc..e1549e2f 100644 --- a/docs/docs/en/user-guide/adapters/images/custom_fastapi_nats.png +++ b/docs/docs/en/user-guide/adapters/images/custom_fastapi_nats.png @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:960eb880b7d8bdf702e2a65af8b5e9cde43313b0acc54d94dacdafc154cfdfea -size 85139 +oid sha256:76287625c1857ad0bfa41cb4f535c9059fafd8b337e3bfbfcad45c23b35110bc +size 82513 diff --git a/docs/docs/en/user-guide/adapters/images/mesop_fastapi_nats.png b/docs/docs/en/user-guide/adapters/images/mesop_fastapi_nats.png index b3ae57b0..80199556 100644 --- a/docs/docs/en/user-guide/adapters/images/mesop_fastapi_nats.png +++ b/docs/docs/en/user-guide/adapters/images/mesop_fastapi_nats.png @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:b25ebca6aac45df3d6b3bfea86f0f11070e304d1b80b71a7fed31cbaf06583a1 -size 114991 +oid sha256:741ab41a6bc79f003b3ab36b73d23b6c494df97f3b95b57811fc0b33503c6c27 +size 104062 diff --git a/docs/docs/en/user-guide/adapters/images/mesop_nats.png b/docs/docs/en/user-guide/adapters/images/mesop_nats.png index 28bbd4eb..12e0d1bd 100644 --- a/docs/docs/en/user-guide/adapters/images/mesop_nats.png +++ b/docs/docs/en/user-guide/adapters/images/mesop_nats.png @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:8f489b9b2dc5ac50ca8302d4e230b83d363933ce8925eb33c9e4d68491e07be1 -size 71464 +oid sha256:01b5e3080e93a5f3403d5c4780b418d134e5ae873770426dc41881a0552dc699 +size 65189 diff --git a/docs/docs/en/user-guide/adapters/index.md b/docs/docs/en/user-guide/adapters/index.md index cf429ba5..43b51e03 100644 --- a/docs/docs/en/user-guide/adapters/index.md +++ b/docs/docs/en/user-guide/adapters/index.md @@ -1,54 +1,56 @@ # Network Adapters -Network Adapters in FastAgency provide a way to integrate your workflows with various communication protocols and interfaces. They allow you to **expose your workflows through different channels**, making it easier to interact with them from various client applications. +Network Adapters in FastAgency provide a way to integrate your workflows with various [**communication protocols**](https://en.wikipedia.org/wiki/Communication_protocol){target="_blank"} and interfaces. They allow you to **expose your workflows through different channels**, making it easier to interact with them from various client applications. FastAgency uses **chainable network adapters** that can be easily combined to create **scalable**, **production-ready architectures** for serving your workflows. These adapters enable you to deploy your workflows in **distributed environments** and handle high volumes of requests. ## Why Use Network Adapters? -- **Production Deployment**: You can use network adapters to deploy agentic workflows in production settings. They provide a way for you to **scale up workloads** and deploy **fully distributed systems**, ensuring high availability and performance. -- **API Integration**: You can utilize an adapter like [**`FastAPIAdapter`**](../../api/fastagency/adapters/fastapi/FastAPIAdapter.md) to expose your workflows as a **REST API**. This allows other applications to interact with your workflows through standard HTTP requests, making it easy for you to integrate with existing systems. +- **Production Deployment**: You can use network adapters to deploy agentic workflows in production settings. They provide a way for you to **scale up workloads** and deploy fully [**distributed systems**](https://en.wikipedia.org/wiki/Distributed_computing){target="_blank"}, ensuring high availability and performance. +- **API Integration**: You can utilize an adapter like [**`FastAPIAdapter`**](../../api/fastagency/adapters/fastapi/FastAPIAdapter.md) to expose your workflows as a [**REST API**](https://en.wikipedia.org/wiki/REST){target="_blank"}. This allows other applications to interact with your workflows through standard [**HTTP**](https://en.wikipedia.org/wiki/HTTP){target="_blank"} requests, making it easy for you to integrate with existing systems. -- **Messaging Systems**: You can use message queue adapters like [**`NatsAdapter`**](../../api/fastagency/adapters/nats/NatsAdapter.md) to scale your workflows and handle high volumes of requests. This enables you to implement **distributed processing** and asynchronous communication between different components of your system, allowing for efficient resource utilization and improved performance. +- **Messaging Systems**: You can use [**message queue**](https://en.wikipedia.org/wiki/Message_queue){target="_blank"} adapters like [**`NatsAdapter`**](../../api/fastagency/adapters/nats/NatsAdapter.md) to scale your workflows and handle high volumes of requests. This enables you to implement [**distributed**](https://en.wikipedia.org/wiki/Distributed_computing){target="_blank"} processing and asynchronous communication between different components of your system, allowing for efficient resource utilization and improved performance. ## Available Adapters ### FastAPI -Use the [**`FastAPIAdapter`**](../../api/fastagency/adapters/fastapi/FastAPIAdapter.md) to serve your workflow using [**FastAPI**](https://fastapi.tiangolo.com/){target="_blank"} server. This setup allows you to work your workflows in multiple workers and serve them using the highly extensible and stable ASGI server. +The [**`FastAPIAdapter`**](../../api/fastagency/adapters/fastapi/FastAPIAdapter.md) allows you to expose your FastAgency workflows as a [**REST API**](https://en.wikipedia.org/wiki/REST){target="_blank"} using the [**FastAPI**](https://fastapi.tiangolo.com/){target="_blank"} framework. -#### When to Use the [**`FastAPIAdapter`**](../../api/fastagency/adapters/fastapi/FastAPIAdapter.md) +When to Use the [**`FastAPIAdapter`**](../../api/fastagency/adapters/fastapi/FastAPIAdapter.md): -- **Custom Client Applications**: If you want to build your **own client applications** that interact with your FastAgency workflows using REST APIs, this adapter provides greater flexibility and control over the client-side implementation. -- **Moderate User Demand**: The FastAPI Adapter is a good fit for scenarios with **moderate user request volume**. For example, it's well-suited for a medium-sized company developing an internal custom chat application. -- **Simplified Production Setup**: Choose this adapter if you need a **simple and easy-to-manage** production setup for deploying your FastAgency workflows as a REST API. +- **Custom Client Applications**: If you want to build your **own client applications** in a different language, (e.g., [**HTML**](https://en.wikipedia.org/wiki/HTML){target="_blank"}/[**JavaScript**](https://en.wikipedia.org/wiki/JavaScript){target="_blank"}, [**Go**](https://go.dev/){target="_blank"}, [**Java**](https://www.java.com/en/){target="_blank"}, etc.), that interacts with your FastAgency workflows using [**REST API**](https://en.wikipedia.org/wiki/REST){target="_blank"} and [**WebSockets**](https://en.wikipedia.org/wiki/WebSocket){target="_blank"}. + +- **Moderate User Demand**: This adapter is a good fit for scenarios where workflows need to be executed by [**multiple workers**](https://fastapi.tiangolo.com/deployment/server-workers/){target="_blank"} to efficiently handle higher machine load. + +- **Simplified Production Setup**: This adapter is a good choice when you need a **simple and easy-to-manage** setup for [**deploying**](https://fastapi.tiangolo.com/deployment/){target="_blank"} FastAgency workflows as an [**ASGI**](https://asgi.readthedocs.io/en/latest/){target="_blank"} server in production. [Learn more about **FastAPI adapter** →](./fastapi/index.md) ### FastAPI + Nats.io -The [**`FastAPIAdapter`**](../../api/fastagency/adapters/fastapi/FastAPIAdapter.md) + [**`NatsAdapter`**](../../api/fastagency/adapters/nats/NatsAdapter.md) in FastAgency offers the most scalable setup by combining the power of the [**FastAPI**](https://fastapi.tiangolo.com/){target="_blank"} framework for building and exposing workflows as REST APIs with the [**NATS.io MQ**](https://nats.io/){target="_blank"} message broker for scalable and asynchronous communication. This setup is the preferred way for running large workloads in production. +Combining the [**`FastAPIAdapter`**](../../api/fastagency/adapters/fastapi/FastAPIAdapter.md) and [**`NatsAdapter`**](../../api/fastagency/adapters/nats/NatsAdapter.md) in FastAgency provides the most scalable setup. It harnesses the power of the [**FastAPI**](https://fastapi.tiangolo.com/){target="_blank"} framework to build and expose workflows as [**REST APIs**](https://en.wikipedia.org/wiki/REST){target="_blank"} while utilizing the [**Nats.io**](https://nats.io/){target="_blank"} message broker for scalable and asynchronous communication. This setup is **preferred** for running large workloads in production. + +When to Use the [**`FastAPIAdapter`**](../../api/fastagency/adapters/fastapi/FastAPIAdapter.md) and [**`NatsAdapter`**](../../api/fastagency/adapters/nats/NatsAdapter.md) Together -#### When to Use the FastAPI + NATS.io Adapter +- **High User Demand**: If you need to scale beyond what [**multiple workers**](https://fastapi.tiangolo.com/deployment/server-workers/){target="_blank"} of the [**FastAPIAdapter**](../fastapi/index.md) can achieve, you can use [**Nats.io**](https://nats.io/){target="_blank"} with a [**message queue**](https://en.wikipedia.org/wiki/Message_queue){target="_blank"} and [**multiple workers**](https://fastapi.tiangolo.com/deployment/server-workers/){target="_blank"} to consume and produce messages. This distributed message-queue architecture allows scaling not only across multiple workers but also across multiple machines and clusters. -- **Custom Client Applications**: If you want to build your **own client applications** that interact with your FastAgency workflows using REST APIs, this adapter provides greater flexibility and control over the client-side implementation. -- **High User Demand**: When your application needs to handle a large number of users or messages and requires high scalability, the FastAPI + NATS Adapter is an excellent choice. It is well-suited for building **scalable custom chat applications for larger companies or external customers**. -- **Conversation Auditing**: If you need the ability to **audit conversations**, the NATS Adapter provides the necessary infrastructure to enable this feature. +- [**Observability**](https://en.wikipedia.org/wiki/Observability_(software)){target="_blank"}: If you need the ability to **audit workflow executions** both in realtime and retrospectively, the [**`NatsAdapter`**](../../api/fastagency/adapters/nats/NatsAdapter) provides the necessary infrastructure to enable this feature. + +- **Security features of FastAPI**: If you want to leverage the [**security features**](https://fastapi.tiangolo.com/tutorial/security){target="_blank"} of FastAPI, such as authentication, authorization, along with the [**distributed architecture**](https://en.wikipedia.org/wiki/Distributed_computing){target="_blank"} of NATS, this setup is the most suitable option. Please check the [**securing your FastAPIAdapter**](../fastapi/security.md) documentation for more information. [Learn more about **FastAPI + NATS.io adapter** →](./fastapi_nats/index.md) ### Nats.io -Utilize the [**`NatsAdapter`**](../../api/fastagency/adapters/nats/NatsAdapter.md) to use [**NATS.io MQ**](https://nats.io/){target="_blank"} message broker for highly-scalable, production-ready setup. - -#### When to Use the [**`NatsAdapter`**](../../api/fastagency/adapters/nats/NatsAdapter.md) +The [**`NatsAdapter`**](../../api/fastagency/adapters/nats/NatsAdapter) in FastAgency enables seamless integration of your workflows with the [**Nats.io MQ**](https://nats.io/){target="_blank"} message broker, providing a scalable and flexible solution for building [**distributed**](https://en.wikipedia.org/wiki/Distributed_computing){target="_blank"} applications. -- **Default Client Application**: If you prefer using the **default Mesop client** provided by FastAgency without the need to build your own client application. +When to Use the [**`NatsAdapter`**](../../api/fastagency/adapters/nats/NatsAdapter): -- **High User Demand**: When your application requires **high scalability** to handle a large number of users or messages, and you are comfortable with a more complex production setup involving a message broker. For example, it's well-suited for building a **scalable chat application** for a larger company or external customers. +- **High User Demand**: If you need to scale beyond what [**multiple workers**](https://fastapi.tiangolo.com/deployment/server-workers/){target="_blank"} of the [**FastAPIAdapter**](../fastapi/index.md) can achieve, you can use [**Nats.io**](https://nats.io/){target="_blank"} with a [**message queue**](https://en.wikipedia.org/wiki/Message_queue){target="_blank"} and [**multiple workers**](https://fastapi.tiangolo.com/deployment/server-workers/){target="_blank"} to consume and produce messages. This distributed message-queue architecture allows scaling not only across multiple workers but also across multiple machines and clusters. -- **Conversation Auditing**: If you need the ability to **audit conversations**, the NATS Adapter provides the necessary infrastructure to enable this feature. +- [**Observability**](https://en.wikipedia.org/wiki/Observability_(software)){target="_blank"}: If you need the ability to **audit workflow executions** both in realtime and retrospectively, the [**`NatsAdapter`**](../../api/fastagency/adapters/nats/NatsAdapter) provides the necessary infrastructure to enable this feature. [Learn more about **NATS.io adapter** →](./nats/index.md) diff --git a/docs/docs/en/user-guide/adapters/nats/index.md b/docs/docs/en/user-guide/adapters/nats/index.md index 2eea6126..85a90485 100644 --- a/docs/docs/en/user-guide/adapters/nats/index.md +++ b/docs/docs/en/user-guide/adapters/nats/index.md @@ -1,71 +1,62 @@ # Nats.io -The **Nats Adapter** in FastAgency enables seamless integration of your workflows with the [**Nats.io MQ**](https://nats.io/){target="_blank"} message broker, providing a scalable and flexible solution for building distributed applications. +The [**`NatsAdapter`**](../../../api/fastagency/adapters/nats/NatsAdapter) in FastAgency enables seamless integration of your workflows with the [**Nats.io MQ**](https://nats.io/){target="_blank"} message broker, providing a scalable and flexible solution for building [**distributed**](https://en.wikipedia.org/wiki/Distributed_computing){target="_blank"} applications. ## Use Cases -When to Use the Nats Adapter: +When to Use the [**`NatsAdapter`**](../../../api/fastagency/adapters/nats/NatsAdapter): -- **High User Demand**: If you need to scale above what can be achieved with multiple-workers of the [**FastAPI** adapter](../fastapi/index.md), then you can use [**Nats.io MQ**](https://nats.io/){target="_blank"}-based message que and multiple workers consuming and producing messages. This kind of distributed, [message-queue architecture](https://en.wikipedia.org/wiki/Message_queue){target="_blank"} allows you to scale up not just across multiple workers, but also across multiple machines and even across multiple clusters. +- **High User Demand**: If you need to scale beyond what [**multiple workers**](https://fastapi.tiangolo.com/deployment/server-workers/){target="_blank"} of the [**FastAPIAdapter**](../fastapi/index.md) can achieve, you can use [**Nats.io**](https://nats.io/){target="_blank"} with a [**message queue**](https://en.wikipedia.org/wiki/Message_queue){target="_blank"} and [**multiple workers**](https://fastapi.tiangolo.com/deployment/server-workers/){target="_blank"} to consume and produce messages. This distributed message-queue architecture allows scaling not only across multiple workers but also across multiple machines and clusters. -- **Observability**: If you need the ability to **audit workflow executions** both in realtime and posteriori, the Nats Adapter provides the necessary infrastructure to enable this feature. +- [**Observability**](https://en.wikipedia.org/wiki/Observability_(software)){target="_blank"}: If you need the ability to **audit workflow executions** both in realtime and retrospectively, the [**`NatsAdapter`**](../../../api/fastagency/adapters/nats/NatsAdapter) provides the necessary infrastructure to enable this feature. ## Architecture Overview -The following diagram illustrates the high-level architecture of an application using the **Nats Adapter with Mesop UI** as its frontend: +The following diagram illustrates the high-level architecture of an application using the [**`NatsAdapter`**](../../../api/fastagency/adapters/nats/NatsAdapter) with [**`MesopUI`**](../../../api/fastagency/ui/mesop/MesopUI.md) as its frontend: ![Mesop Nats](../images/mesop_nats.png) The system consists of two main components: -### FastAgency Mesop App +### Mesop Client App -The FastAgency Mesop App serves as the frontend interface for the system. It includes: +This application serves as the frontend interface for the system. It includes: -- **Mesop UI**: A user-friendly web interface for users to interact with the workflows. It communicates with the client and the Nats Provider. +- [**`MesopUI`**](../../../api/fastagency/ui/mesop/MesopUI.md): A friendly web interface for users to interact with the workflows. It facilitates the communication with the user and the [**`NatsProvider`**](../../../api/fastagency/adapters/nats/NatsProvider.md). - **Nats Provider**: The [**Nats.io MQ**](https://nats.io/){target="_blank"} message broker responsible for handling message communication between different parts of the system. -This app handles all client interactions and presents the results back to the user. +This application handles all client interactions and presents the results back to the user. -### FastAgency Nats App +### Nats App -The FastAgency Nats App forms the backend of the system and consists of: +This application forms the backend of the system and consists of: -- **AutoGen Workflows**: The workflows defined using the AutoGen framework. They are executed by the workers in the Nats Adapter. -- **Nats Adapter**: Communicates with AutoGen, and makes the workflow messages available on corresponding Nats topics. - -### Interaction Flow - -1. The client interacts with the Mesop UI to initiate a workflow. -2. The Mesop UI sends a message to the Nats Provider to initiate the workflow. -3. The Nats Adapter, connected to the Nats Provider, receives the message. -4. The Nats Adapter distributes the workflow execution task to one of the available workers. -5. The worker executes the AutoGen Workflow. -6. The results are sent back through the Nats Provider to the Mesop UI and ultimately to the client. +- **AutoGen Workflows**: The workflows defined using the [**AutoGen**](https://microsoft.github.io/autogen){target="_blank"} framework. They are executed by the workers in the Nats Adapter. +- [**`NatsAdapter`**](../../../api/fastagency/adapters/nats/NatsAdapter): Communicates with AutoGen, and makes the workflow messages available on corresponding [**Nats topics**](https://docs.nats.io/nats-concepts/subjects){target="_blank"}. Now, it's time to see the Nats Adapter using FastAgency in action. Let's dive into an example and learn how to use it! ## Installation -Before getting started, make sure you have installed FastAgency by running the following command: +Before getting started, ensure that FastAgency is installed with support for the [**AutoGen**](../../../api/fastagency/runtimes/autogen/autogen/AutoGenWorkflows.md) runtime, along with the [**mesop**](../../../api/fastagency/ui/mesop/MesopUI.md), **fastapi**, **server** and **nats** submodules by running the following command: ```bash pip install "fastagency[autogen,mesop,fastapi,server,nats]" ``` -This command installs FastAgency with support for both the Console and Mesop interfaces for AutoGen workflows and the Nats Adapter for workflow execution. +This command installs FastAgency with support for both the [**mesop**](../../../api/fastagency/ui/mesop/MesopUI.md) and [**console**](../../../api/fastagency/ui/console/ConsoleUI.md) interfaces for AutoGen workflows and the [**`NatsAdapter`**](../../../api/fastagency/adapters/nats/NatsAdapter) for workflow execution. ## Example: Student and Teacher Learning Chat -In this example, we'll create a simple learning chat where a student agent asks questions and a teacher agent responds, simulating a learning environment. We'll use MesopUI for the web interface and the Nats Adapter for workflow execution. +In this example, we'll create a simple learning [**chatbot**](https://en.wikipedia.org/wiki/Chatbot){target="_blank"} where a student agent asks questions and a teacher agent responds, simulating a learning environment. We'll use [**`MesopUI`**](../../../api/fastagency/ui/mesop/MesopUI.md) for the web interface and the [**`NatsAdapter`**](../../../api/fastagency/adapters/nats/NatsAdapter) for workflow execution. ### Step-by-Step Breakdown #### 1. **Import Required Modules** -To get started, import the required modules from the **FastAgency** and **AutoGen**. These imports provide the essential building blocks for creating agents, workflows, and integrating MesopUI. Additionally, import the [**`NatsAdapter`**](../../../api/fastagency/adapters/nats/NatsAdapter.md) class for workflow execution. +To get started, import the required modules from the **FastAgency** and **AutoGen**. These imports provide the essential building blocks for creating agents, workflows, and integrating [**`MesopUI`**](../../../api/fastagency/ui/mesop/MesopUI.md). Additionally, import the [**`NatsAdapter`**](../../../api/fastagency/adapters/nats/NatsAdapter.md) class for workflow execution. ```python hl_lines="9" {!> docs_src/getting_started/nats/main_1_nats.py [ln:1-11] !} @@ -81,7 +72,7 @@ Define the workflow that your application will use. This is where you specify ho #### 3. **Configure the Nats Adapter** -Create an instance of the NatsAdapter and pass your workflow to it. The adapter will handle the communication with the Nats Provider and distribute workflow execution to the workers. +Create an instance of the [**`NatsAdapter`**](../../../api/fastagency/adapters/nats/NatsAdapter.md) and pass your workflow to it. The adapter will handle the communication with the [**`NatsProvider`**](../../../api/fastagency/adapters/nats/NatsProvider.md) and distribute workflow execution to the workers. ```python {!> docs_src/getting_started/nats/main_1_nats.py [ln:59-64] !} @@ -89,7 +80,7 @@ Create an instance of the NatsAdapter and pass your workflow to it. The adapter #### 4. **Define FastAgency Application** -Create an NatsAdapter and then add it to a FastAPI application using the lifespan parameter. The adapter will have all REST and Websocket routes for communicating with a client. For more information on the lifespan parameter, check out the official documentation [**here**](https://fastapi.tiangolo.com/advanced/events/){target="_blank"} +Create a [**`NatsAdapter`**](../../../api/fastagency/adapters/nats/NatsAdapter.md) and then add it to a [**FastAPI**](https://fastapi.tiangolo.com/){target="_blank"} application using the [**lifespan parameter**](https://fastapi.tiangolo.com/advanced/events/){target="_blank"}. The adapter will have all [**REST API**](https://en.wikipedia.org/wiki/REST){target="_blank"} and [**WebSocket**](https://en.wikipedia.org/wiki/WebSocket){target="_blank"} routes for communicating with a client. ```python {!> docs_src/getting_started/nats/main_1_nats.py [ln:66] !} @@ -97,7 +88,7 @@ Create an NatsAdapter and then add it to a FastAPI application using the lifespa #### 5. **Nats server setup** -The `NatsAdapter` requires a running Nats server. The easiest way to start the Nats server is by using [Docker](https://www.docker.com/){target="_blank"}. FastAgency uses the [JetStream](https://docs.nats.io/nats-concepts/jetstream){target="_blank"} feature of Nats and also utilizes authentication. +The `NatsAdapter` requires a running NATS server. The easiest way to start the NATS server is by using [**Docker**](https://www.docker.com/){target="_blank"}. FastAgency leverages the [**JetStream**](https://docs.nats.io/nats-concepts/jetstream){target="_blank"} feature of NATS and also utilizes authentication. ```python hl_lines="1 3 6 11 17" {!> docs_src/getting_started/nats_n_fastapi/nats-server.conf [ln:1-23]!} @@ -148,9 +139,9 @@ The above command starts a Nats container with the necessary ports exposed and c uvicorn main_1_nats:app --reload ``` -This command starts the FastAPI application using Uvicorn, a lightning-fast ASGI server. The --reload flag enables auto-reloading, so any changes made to the code will be automatically reflected without needing to restart the server. +This command starts the FastAPI application using [**uvicorn**](https://www.uvicorn.org){target="_blank"}, a lightning-fast [**ASGI**](https://asgi.readthedocs.io/en/latest/){target="_blank"} server. The --reload flag enables auto-reloading, so any changes made to the code will be automatically reflected without needing to restart the server. -- 3. Start **Mesop** web interface using gunicorn: +- 3. Start **Mesop** web interface using [**gunicorn**](https://gunicorn.org){target="_blank"}: !!! note "Terminal 3" ``` gunicorn main_2_mesop:app -b 0.0.0.0:8888 --reload @@ -162,7 +153,7 @@ This command starts the FastAPI application using Uvicorn, a lightning-fast ASGI waitress-serve --listen=0.0.0.0:8888 main_2_mesop:app ``` -This command starts the Mesop web interface using Gunicorn, a production-grade WSGI server. The -b flag specifies the binding address and port, and the --reload flag enables auto-reloading. +This command starts the Mesop web interface using [**gunicorn**](https://gunicorn.org){target="_blank"}, a production-grade [**WSGI server**](https://wsgi.readthedocs.io/en/latest/what.html){target="_blank"}. The -b flag specifies the binding address and port, and the --reload flag enables auto-reloading. ### Output @@ -177,4 +168,4 @@ The outputs will vary based on the interface. Here is the output of the last ter ![Initial message](../../../getting-started/images/chat.png) -The Nats Adapter in FastAgency provides a powerful and flexible way to integrate your workflows with the Nats.io message broker. By leveraging the scalability and distributed architecture of Nats, you can build highly scalable and production-ready applications. With its easy-to-use API and seamless integration with the Mesop UI, the Nats Adapter simplifies the development process while enabling advanced features like conversation auditing. +The [**`NatsAdapter`**](../../../api/fastagency/adapters/nats/NatsAdapter.md) in FastAgency provides a powerful and flexible way to integrate your workflows with the [**Nats.io**](https://nats.io/){target="_blank"} message broker. By leveraging the scalability and distributed architecture of Nats, you can build highly scalable and production-ready applications. With its easy-to-use API and seamless integration with the [**`MesopUI`**](../../../api/fastagency/ui/mesop/MesopUI.md), the `NatsAdapter` simplifies the development process while enabling advanced features like conversation auditing. diff --git a/docs/docs_src/getting_started/fastapi/main_fastapi_custom_client.py b/docs/docs_src/getting_started/fastapi/main_fastapi_custom_client.py index 368acd37..98147fb2 100644 --- a/docs/docs_src/getting_started/fastapi/main_fastapi_custom_client.py +++ b/docs/docs_src/getting_started/fastapi/main_fastapi_custom_client.py @@ -20,8 +20,8 @@