Skip to content

Commit

Permalink
Update getting started guide (#384)
Browse files Browse the repository at this point in the history 
* Getting started rewrite

* packages updated

* test fix

* polishing
  • Loading branch information
@davorrunje
davorrunje authored Oct 14, 2024
1 parent 4b03563 commit a714f65
Show file tree
Hide file tree
Showing 41 changed files with 539 additions and 137 deletions.
256 changes: 214 additions & 42 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -53,44 +53,96 @@

---

Welcome to FastAgency! This guide will walk you through the initial setup and usage of FastAgency, a powerful tool that leverages the AutoGen framework to quickly build applications. FastAgency is designed to be flexible and adaptable, and we plan to extend support to additional agentic frameworks such as [CrewAI](https://www.crewai.com/) in the near future. This will provide even more options for defining workflows and integrating with various AI tools.
## What is FastAgency?

With FastAgency, you can create interactive applications using various interfaces such as a console or Mesop.
For start, FastAgency is not yet another agentic AI frameworks. There are many such
frameworks available today, the most popular open-source ones being [**AutoGen**](https://github.com/microsoft/autogen), [**CrewAI**](https://www.crewai.com/), [**Swarm**](https://github.com/openai/swarm) and [**LangGraph**](https://github.com/langchain-ai/langgraph). FastAgency provides you with a unified programming interface for deploying agentic workflows written in above agentic frameworks in both development and productional settings (current version supports [**AutoGen**](https://github.com/microsoft/autogen) only, but other frameworks will be supported very soon). With only a few lines of code, you can create a web chat application or REST API service interacting with agents of your choice. If you need to scale-up your workloads, FastAgency can help you deploy a fully distributed system using internal message brokers coordinating multiple machines in multiple datacenters with just a few lines of code changed from your local development setup.

## Supported Interfaces
In the rest of this guide, we will walk you through the initial setup and usage of FastAgency, using both development and production environments.

### Supported Runtimes

Currently, the only supported runtime is [**AutoGen**](https://github.com/microsoft/autogen), with support for [**CrewAI**](https://www.crewai.com/), [**Swarm**](https://github.com/openai/swarm) and [**LangGraph**](https://github.com/langchain-ai/langgraph) coming soon.

### Supported User Interfaces

FastAgency currently supports workflows defined using AutoGen and provides options for different types of applications:

- **Console**: Use the [ConsoleUI](https://fastagency.ai/0.2/api/fastagency/ui/console/ConsoleUI.md) interface for command-line based interaction. This is ideal for developing and testing workflows in a text-based environment.
- **Mesop**: Utilize [Mesop](https://google.github.io/mesop/) with [MesopUI](https://fastagency.ai/0.2/api/fastagency/ui/mesop/MesopUI.md) for web-based applications. This interface is suitable for creating web applications with a user-friendly interface.
- **Console**: Use the [**`ConsoleUI`**](../api/fastagency/ui/console/ConsoleUI.md) interface for command-line based interaction. This is ideal for developing and testing workflows in a text-based environment.

- [**Mesop**](https://google.github.io/mesop/): Utilize [**`MesopUI`**](../api/fastagency/ui/mesop/MesopUI.md) for web-based applications. This interface is suitable for creating web applications with a user-friendly interface.

We are also working on adding support for other frameworks, such as [**CrewAI**](https://www.crewai.com/), to broaden the scope and capabilities of FastAgency. Stay tuned for updates on these integrations.

### Supported Network Adapters

FastAgency can use chainable network adapters that can be used to easily create
scalable, production ready architectures for serving your workflows. Currently, we
support the following network adapters:

We are also working on adding support for other frameworks, such as [CrewAI](https://www.crewai.com/), to broaden the scope and capabilities of FastAgency. Stay tuned for updates on these integrations.
- [**REST API**](https://en.wikipedia.org/wiki/REST) via [**FastAPI**](https://fastapi.tiangolo.com/): Use the [**`FastAPIAdapter`**](../api/fastagency/adapters/fastapi/FastAPIAdapter.md) to serve your workflow using [**FastAPI**](https://fastapi.tiangolo.com/) server. This setup allows you to work your workflows in multiple workers and serve them using the highly extensible and stable ASGI server.

- [**NATS.io**](https://nats.io/) via [**FastStream**](https://github.com/airtai/faststream): Utilize the [**`NatsAdapter`**](../api/fastagency/adapters/nats/NatsAdapter.md) to use [**NATS.io MQ**](https://nats.io/) message broker for highly-scalable, production-ready setup. This interface is suitable for setups in VPN-s or, in combination with the [**`FastAPIAdapter`**](../api/fastagency/adapters/fastapi/FastAPIAdapter.md) to serve public workflows in an authenticated, secure manner.

## Quick start

There are four different setups, two for development and two for production workloads:

- Development setups

- **Console**: This setup uses console for interactively executing your workflow.
It is also very useful for automating testing and integration with CI/CD.


- **Mesop**: This setup uses [**Mesop**](https://google.github.io/mesop/)
to build a web application for interacting with our workflow. It supports
a single-worker deployments only, limiting its scalability. However, it
is the fastest way to debug your application.

- Production setups

- **FastAPI + Mesop**: This is fairly scalable setup using [**FastAPI**](https://fastapi.tiangolo.com/)
to execute your workflows and [**Mesop**](https://google.github.io/mesop/) for interactive web application. [**FastAPI**](https://fastapi.tiangolo.com/) supports execution with multiple workers with each workflowe being executed in the context of a websocket connection. [**Mesop**](https://google.github.io/mesop/) is still limited to a single worker, although there is much less load of it due to workflows being executed in the [**FastAPI**](https://fastapi.tiangolo.com/) workers.

- **NATS + FastAPI + Mesop**: This is the most scalable setup using a distributed message broker
[**NATS.io MQ**](https://nats.io/). Workflows are being executed with
multiple workers that attach to the MQ waiting for initiate workflow messages. Such workers
can be running on different machines or even different data centers/cloud providers.
Message queues are highly scalable, but more difficult to integrate with end-clients.
In order to make such integrations easier, we will connect our [**NATS**](https://nats.io/)-based message queue with the [**FastAPI**](https://fastapi.tiangolo.com/)
application.

We will show you how to deploy your workflow using the **FastAPI + Mesop** combination below.

### Install

To get started, you need to install FastAgency. You can do this using `pip`, Python's package installer. This command installs FastAgency with support for the [Mesop](https://google.github.io/mesop/) interface and AutoGen framework.
To get started, you need to install FastAgency. You can do this using `pip`, Python's package installer. Choose the installation command based on the interface you want to use:

```console
pip install "fastagency[autogen,mesop]"
pip install "fastagency[autogen,mesop,fastapi]"
```

## Write Code
This command installs FastAgency with support for both the Console and Mesop
interfaces for AutoGen workflows, but with FastAPI both serving input requests
and running workflows.


### Imports
Depending on the interface you choose, you'll need to import different modules. These imports set up the necessary components for your application:

```python
import os
from typing import Any

from autogen.agentchat import ConversableAgent
from fastapi import FastAPI

from fastagency import UI, FastAgency, Workflows
from fastagency import UI
from fastagency.adapters.fastapi import FastAPIAdapter
from fastagency.runtimes.autogen import AutoGenWorkflows
from fastagency.ui.mesop import MesopUI
```

For FastAPI applications, import `FastAPIAdapter` to expose your workflows as REST API.

### Define Workflow

Expand All @@ -104,16 +156,22 @@ llm_config = {
"api_key": os.getenv("OPENAI_API_KEY"),
}
],
"temperature": 0.0,
"temperature": 0.8,
}

wf = AutoGenWorkflows()


@wf.register(name="simple_learning", description="Student and teacher learning chat")
def simple_workflow(
wf: Workflows, ui: UI, initial_message: str, session_id: str
ui: UI, params: dict[str, Any]
) -> str:
initial_message = ui.text_input(
sender="Workflow",
recipient="User",
prompt="I can help you learn about mathematics. What subject you would like to explore?",
)

student_agent = ConversableAgent(
name="Student_Agent",
system_message="You are a student willing to learn.",
Expand All @@ -139,52 +197,166 @@ This code snippet sets up a simple learning chat between a student and a teacher

### Define FastAgency Application

Next, define your FastAgency application. This ties together your workflow and the interface you chose:

In the case of FastAPI application, we will create an `FastAPIAdapter` and then include a router to the `FastAPI` application.
The adapter will have all REST and Websocket routes for communicating with a client.

```python
app = FastAgency(wf=wf, ui=MesopUI(), title="Learning Chat")
adapter = FastAPIAdapter(provider=wf)

app = FastAPI()
app.include_router(adapter.router)
```

## Run Application
### Adapter Chaining

Once everything is set up, you can run your FastAgency application using the following command:
There is an additional specification file for an application using `MesopUI`
to connect to the `FastAPIAdapter`

#### `main_2_mesop.py`
```python
from fastagency.adapters.fastapi import FastAPIAdapter
from fastagency.app import FastAgency
from fastagency.ui.mesop import MesopUI

```
fastagency run
```
fastapi_url = "http://localhost:8008"

However, the preferred way of running Mesop application is a Python WSGI HTTP Server such as [Gunicorn](https://gunicorn.org/). First,
you need to install it using package manager such as `pip`:
```
pip install gunicorn
```
and then you can run it with:
```
gunicorn main:app
```
provider = FastAPIAdapter.create_provider(
fastapi_url=fastapi_url,
)

### Output
app = FastAgency(provider=provider, ui=MesopUI())
```

```console
[2024-10-01 16:18:59 +0000] [20390] [INFO] Starting gunicorn 23.0.0
[2024-10-01 16:18:59 +0000] [20390] [INFO] Listening at: http://127.0.0.1:8000 (20390)
[2024-10-01 16:18:59 +0000] [20390] [INFO] Using worker: sync
[2024-10-01 16:18:59 +0000] [20391] [INFO] Booting worker with pid: 20391
```

![Initial message](https://fastagency.ai/0.2/getting-started/images/chat.png?v1)
## Complete Application Code

#### `main_1_fastapi.py`

```python
import os
from typing import Any

## Future Plans
from autogen.agentchat import ConversableAgent
from fastapi import FastAPI

We are actively working on expanding FastAgency’s capabilities. In addition to supporting AutoGen, we plan to integrate support for other frameworks, such as [CrewAI](https://www.crewai.com/), to provide more flexibility and options for building applications. This will allow you to define workflows using a variety of frameworks and leverage their unique features and functionalities.
from fastagency import UI
from fastagency.adapters.fastapi import FastAPIAdapter
from fastagency.runtimes.autogen import AutoGenWorkflows

---
llm_config = {
"config_list": [
{
"model": "gpt-4o-mini",
"api_key": os.getenv("OPENAI_API_KEY"),
}
],
"temperature": 0.8,
}

wf = AutoGenWorkflows()


@wf.register(name="simple_learning", description="Student and teacher learning chat")
def simple_workflow(ui: UI, params: dict[str, Any]) -> str:
initial_message = ui.text_input(
sender="Workflow",
recipient="User",
prompt="I can help you learn about mathematics. What subject you would like to explore?",
)

student_agent = ConversableAgent(
name="Student_Agent",
system_message="You are a student willing to learn.",
llm_config=llm_config,
# human_input_mode="ALWAYS",
)
teacher_agent = ConversableAgent(
name="Teacher_Agent",
system_message="You are a math teacher.",
llm_config=llm_config,
# human_input_mode="ALWAYS",
)

chat_result = student_agent.initiate_chat(
teacher_agent,
message=initial_message,
summary_method="reflection_with_llm",
max_turns=5,
)

return chat_result.summary # type: ignore[no-any-return]


adapter = FastAPIAdapter(provider=wf)

app = FastAPI()
app.include_router(adapter.router)


# this is optional, but we would like to see the list of available workflows
@app.get("/")
def read_root() -> dict[str, dict[str, str]]:
return {"Workflows": {name: wf.get_description(name) for name in wf.names}}


# start the provider with the following command
# uvicorn main_1_fastapi:app --host 0.0.0.0 --port 8008 --reload
```

#### `main_2_mesop.py`

```python
from fastagency.adapters.fastapi import FastAPIAdapter
from fastagency.app import FastAgency
from fastagency.ui.mesop import MesopUI

fastapi_url = "http://localhost:8008"

provider = FastAPIAdapter.create_provider(
fastapi_url=fastapi_url,
)

app = FastAgency(provider=provider, ui=MesopUI())

# start the provider with the following command
# gunicorn main_2_mesop:app -b 0.0.0.0:8888 --reload
```

### Run Application

Once everything is set up, you can run your FastAgency application using the following command:


In this setup, we need to run two command in separate terminal windows:

#### Terminal 1
```
uvicorn main_1_fastapi:app --host 0.0.0.0 --port 8008 --reload
```

#### Terminal 2
```
gunicorn main_2_mesop:app -b 0.0.0.0:8888 --reload
```

### Output

The outputs will vary based on the interface, here is the output of the last terminal starting UI:

## Documentation
```console
[2024-10-10 13:19:18 +0530] [23635] [INFO] Starting gunicorn 23.0.0
[2024-10-10 13:19:18 +0530] [23635] [INFO] Listening at: http://127.0.0.1:8888 (23635)
[2024-10-10 13:19:18 +0530] [23635] [INFO] Using worker: sync
[2024-10-10 13:19:18 +0530] [23645] [INFO] Booting worker with pid: 23645
```

![Initial message](https://fastagency.ai/0.3/getting-started/images/chat.png)


## Future Plans

You can find detailed documentation on the following link: [fastagency.ai/latest](fastagency.ai/latest).
We are actively working on expanding FastAgency’s capabilities. In addition to supporting AutoGen, we plan to integrate support for other frameworks, other network provider and other UI frameworks.

---

Expand Down
3 changes: 3 additions & 0 deletions docs/docs/SUMMARY.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,9 @@ search:
- [Console](user-guide/ui/console/basics.md)
- [Mesop](user-guide/ui/mesop/basics.md)
- [FastAPI](user-guide/ui/fastapi/basics.md)
- [Adapters](user-guide/adapters/index.md)
- [FastAPI](user-guide/adapters/fastapi/index.md)
- [Nats.io](user-guide/adapters/nats/index.md)
- [API-s](user-guide/api/index.md)
- [OpenAPI](user-guide/api/openapi/index.md)
- [Security](user-guide/api/security.md)
Expand Down
Loading

0 comments on commit a714f65

Please sign in to comment.