Security#
In the previous chapter, we learned how to integrate external REST APIs into AutoGen agents using FastAgency, and we used a weather API route which had no security. However, not all external REST APIs are open to the public; some are behind a paywall and require security parameters for access. This section of the documentation explains how to create an agent that accesses an external REST API with security.
Supported Security Schemas#
FastAgency currently supports the following security schemas:
-
HTTP Bearer Token An HTTP authentication scheme using Bearer tokens, commonly used for securing RESTful APIs.
-
HTTP Basic Auth HTTP authenticcation scheme using username/password pair.
-
API Key API keys can be provided in:
- HTTP header
- Query parameters
- Cookies
-
OAuth2 (Password Flow) A flow where the token authority and API service reside on the same address. This is useful for scenarios where the client credentials are exchanged for a token directly.
Defining Security Schemas in OpenAPI#
To secure your APIs, you'll need to define security schemas in your OpenAPI specification. Here are examples for each supported schema, to learn more about security schemas, please visit OpenAPI guide on authentication:
HTTP Bearer Token#
In your OpenAPI schema:
HTTP Basic auth#
In your OpenAPI schema:
API Key (in Header, Query, or Cookie)#
In your OpenAPI schema:
{
"components": {
"securitySchemes": {
"ApiKeyHeader": {
"type": "apiKey",
"in": "header",
"name": "X-API-Key"
},
"ApiKeyQuery": {
"type": "apiKey",
"in": "query",
"name": "X-API-Key"
},
"ApiKeyCookie": {
"type": "apiKey",
"in": "cookie",
"name": "X-API-Key"
}
}
}
}
OAuth2 (Password Flow)#
In your OpenAPI schema:
{
"components": {
"securitySchemes": {
"OAuth2Password": {
"type": "oauth2",
"flows": {
"password": {
"tokenUrl": "/token",
"scopes": {
"read": "Grants read access",
"write": "Grants write access"
}
}
}
}
}
}
}
Configuring Security in FastAgency#
FastAgency will automatically generate the necessary authentication functions from the OpenAPI schemas. Here’s how you can configure each security method in the FastAgency client.
Using HTTP Bearer Token#
To configure bearer token authentication, provide the token when initializing the API client:
from fastagency.api.openapi import OpenAPI
from fastagency.api.openapi.security import HTTPBearer
api_client = OpenAPI.create(openapi_url=openapi_url) # API openapi specification url
api_client.set_security_params(HTTPBearer.Parameters(value=api_key)) # API key
Using HTTP Basic Auth#
To configure basic authentication, provide the username and password when initializing the API client:
from fastagency.api.openapi import OpenAPI
from fastagency.api.openapi.security import HTTPBasic
api_client = OpenAPI.create(openapi_url=openapi_url) # API openapi specification url
api_client.set_security_params(HTTPBasic.Parameters(username=username, password=password)) # username/password
Using API Key (in Header, Query, or Cookie)#
You can configure the client to send an API key in the appropriate location (header, query, or cookie):
-
API Key in Header:
-
API Key in Query Parameter:
-
API Key in Cookie:
Using OAuth2 (Password Flow)#
FastAgency makes it simple to handle OAuth2's password flow. Configure the client with the token URL and credentials:
from fastagency.api.openapi import OpenAPI
from fastagency.api.openapi.security import OAuth2PasswordBearer
api_client = OpenAPI.create(openapi_url=openapi_url) # API openapi specification url
api_client.set_security_params(
OAuth2PasswordBearer.Parameters(
username=username, # your API username
password=password, # your API password
)
)
In this configuration, FastAgency automatically handles the token exchange and uses the access token for subsequent requests.
Configuring security example#
For this tutorial, the weather API provides an hourly forecast route that is secured.
Note
The weather API offers two routes: one for the daily weather forecast, which has no security, and another for the hourly forecast, which is secured. To learn how to access external APIs that are not secured, please refer to the previous chapter.
Install#
We strongly recommend using Cookiecutter for setting up the project. Cookiecutter creates the project folder structure, default workflow, automatically installs all the necessary requirements, and creates a devcontainer that can be used with Visual Studio Code.
You can setup the project using Cookiecutter by following the project setup guide.
Alternatively, you can use pip + venv. The installation process is exactly the same as in the previous chapter.
Imports#
The imports are the same as in the previous chapter, except here we also import APIKeyHeader to set the security value in the header:
import os
from autogen import UserProxyAgent
from autogen.agentchat import ConversableAgent
from fastagency import UI, FastAgency
from fastagency.api.openapi import OpenAPI
from fastagency.api.openapi.security import APIKeyHeader
from fastagency.runtimes.autogen import AutoGenWorkflows
from fastagency.ui.console import ConsoleUI
Configure the Language Model (LLM)#
Here, the large language model is configured to use the gpt-4o-mini model, and the API key is retrieved from the environment. This setup ensures that both the user and weather agents can interact effectively.
llm_config = {
"config_list": [
{
"model": "gpt-4o-mini",
"api_key": os.getenv("OPENAI_API_KEY"),
}
],
"temperature": 0.8,
}
Set Up the Weather API#
We define the OpenAPI specification URL for the weather service. This API will later be used by the weather agent to fetch real-time weather data.
WEATHER_OPENAPI_URL = "https://weather.tools.fastagency.ai/openapi.json"
weather_api = OpenAPI.create(openapi_url=WEATHER_OPENAPI_URL)
Configuring API Security Parameters#
Here, we define security settings for the weather API by setting API keys for authentication. This ensures secure access when interacting with the API, globally across all methods.
# Set global security params for all methods
weather_api.set_security_params(APIKeyHeader.Parameters(value="secure weather key"))
You can also set security parameters for a specific method. The code below demonstrates how to apply security parameters to a specific method instead of globally. In this example, the security settings are only applied to the get_daily_weather_daily_get method.
# Set security params for a specific method
weather_api.set_security_params(
APIKeyHeader.Parameters(value="secure weather key"),
"get_daily_weather_daily_get",
)
Define the Workflow and Agents#
In this step, we define two agents and specify the initial message that will be displayed to users when the workflow starts.
-
UserProxyAgent: This agent simulates the user interacting with the system.
-
ConversableAgent: This agent acts as the weather agent, responsible for fetching weather data from the API.
wf = AutoGenWorkflows()
@wf.register(
name="simple_weather_with_security", description="Weather chat with security"
)
def weather_workflow_with_security(
ui: UI, params: dict[str, str]
) -> str:
initial_message = ui.text_input(
sender="Workflow",
recipient="User",
prompt="What do you want to know about the weather?",
)
user_agent = UserProxyAgent(
name="User_Agent",
system_message="You are a user agent",
llm_config=llm_config,
human_input_mode="NEVER",
)
weather_agent = ConversableAgent(
name="Weather_Agent",
system_message="You are a weather agent",
llm_config=llm_config,
human_input_mode="NEVER",
)
Register API Functions with the Agents#
In this step, we register the weather API functions to ensure that the weather agent can call the correct functions to retrieve the required weather data.
Enable Agent Interaction and Chat#
Here, the user agent initiates a chat with the weather agent, which queries the API and returns the weather information. The conversation is summarized using a method provided by the LLM.
chat_result = user_agent.initiate_chat(
weather_agent,
message=initial_message,
summary_method="reflection_with_llm",
max_turns=3,
)
return chat_result.summary # type: ignore[no-any-return]
Define FastAgency Application#
Next, define your FastAgency application.
Complete Application Code#
main.py
import os
from autogen import UserProxyAgent
from autogen.agentchat import ConversableAgent
from fastagency import UI, FastAgency
from fastagency.api.openapi import OpenAPI
from fastagency.api.openapi.security import APIKeyHeader
from fastagency.runtimes.autogen import AutoGenWorkflows
from fastagency.ui.console import ConsoleUI
llm_config = {
"config_list": [
{
"model": "gpt-4o-mini",
"api_key": os.getenv("OPENAI_API_KEY"),
}
],
"temperature": 0.8,
}
WEATHER_OPENAPI_URL = "https://weather.tools.fastagency.ai/openapi.json"
weather_api = OpenAPI.create(openapi_url=WEATHER_OPENAPI_URL)
# Set global security params for all methods
weather_api.set_security_params(APIKeyHeader.Parameters(value="secure weather key"))
# Set security params for a specific method
# weather_api.set_security_params(
# APIKeyHeader.Parameters(value="secure weather key"),
# "get_daily_weather_daily_get",
# )
wf = AutoGenWorkflows()
@wf.register(
name="simple_weather_with_security", description="Weather chat with security"
)
def weather_workflow_with_security(
ui: UI, params: dict[str, str]
) -> str:
initial_message = ui.text_input(
sender="Workflow",
recipient="User",
prompt="What do you want to know about the weather?",
)
user_agent = UserProxyAgent(
name="User_Agent",
system_message="You are a user agent",
llm_config=llm_config,
human_input_mode="NEVER",
)
weather_agent = ConversableAgent(
name="Weather_Agent",
system_message="You are a weather agent",
llm_config=llm_config,
human_input_mode="NEVER",
)
wf.register_api(
api=weather_api,
callers=user_agent,
executors=weather_agent,
)
chat_result = user_agent.initiate_chat(
weather_agent,
message=initial_message,
summary_method="reflection_with_llm",
max_turns=3,
)
return chat_result.summary # type: ignore[no-any-return]
app = FastAgency(provider=wf, ui=ConsoleUI())
Run Application#
You can run this chapter's FastAgency application using the following command::
Output#
The output will vary based on the city and the current weather conditions:
╭─ Python module file ─╮
│ │
│ 🐍 main.py │
│ │
╰──────────────────────╯
╭─ Importable FastAgency app ─╮
│ │
│ from main import app │
│ │
╰─────────────────────────────╯
╭─ FastAgency -> user [workflow_started] ──────────────────────────────────────╮
│ │
│ { │
│ "name": "simple_weather_with_security", │
│ "description": "Weather │
│ chat with security", │
│ "params": {} │
│ } │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Workflow -> User [text_input] ──────────────────────────────────────────────╮
│ │
│ What do you want to know about the weather?: │
╰──────────────────────────────────────────────────────────────────────────────╯
Get me daily weather forecast for Chennai city
╭─ User_Agent -> Weather_Agent [text_message] ─────────────────────────────────╮
│ │
│ Get me daily weather forecast for Chennai city │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Weather_Agent -> User_Agent [text_message] ─────────────────────────────────╮
│ │
│ I'm unable to provide real-time weather forecasts. However, you can │
│ easily find the daily weather forecast for Chennai by checking │
│ reliable weather websites, using weather apps, or searching for │
│ "Chennai weather forecast" in your preferred search engine. If you │
│ have any other questions or need information about typical weather │
│ patterns in Chennai, feel free to ask! │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ User_Agent -> Weather_Agent [suggested_function_call] ──────────────────────╮
│ │
│ { │
│ "function_name": "get_daily_weather_daily_get", │
│ "call_id": │
│ "call_lbik8BJJREriUyhbpuKE5hhC", │
│ "arguments": { │
│ "city": │
│ "Chennai" │
│ } │
│ } │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Weather_Agent -> User_Agent [function_call_execution] ──────────────────────╮
│ │
│ { │
│ "function_name": "get_daily_weather_daily_get", │
│ "call_id": │
│ "call_lbik8BJJREriUyhbpuKE5hhC", │
│ "retval": "{\"city\": \"Chennai\", │
│ \"temperature\": 30, \"daily_forecasts\": [{\"forecast_date\": │
│ \"2024-10-10\", \"temperature\": 29, \"hourly_forecasts\": null}, │
│ {\"forecast_date\": \"2024-10-11\", \"temperature\": 29, │
│ \"hourly_forecasts\": null}, {\"forecast_date\": \"2024-10-12\", │
│ \"temperature\": 28, \"hourly_forecasts\": null}]}\n" │
│ } │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ User_Agent -> Weather_Agent [text_message] ─────────────────────────────────╮
│ │
│ Here is the daily weather forecast for Chennai: │
│ │
│ - **October 10, │
│ 2024**: Temperature - 29°C │
│ - **October 11, 2024**: Temperature - 29°C │
│ │
│ - **October 12, 2024**: Temperature - 28°C │
│ │
│ If you need more details │
│ or hourly forecasts, let me know! │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Weather_Agent -> User_Agent [text_message] ─────────────────────────────────╮
│ │
│ Here is the daily weather forecast for Chennai: │
│ │
│ - **October 10, │
│ 2024**: Temperature - 29°C │
│ - **October 11, 2024**: Temperature - 29°C │
│ │
│ - **October 12, 2024**: Temperature - 28°C │
│ │
│ If you need more details │
│ or hourly forecasts, feel free to ask! │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ workflow -> user [workflow_completed] ──────────────────────────────────────╮
│ │
│ { │
│ "result": "The user requested the daily weather forecast for │
│ Chennai, and the assistant provided the forecast for October 10, 11, │
│ and 12, 2024, with temperatures of 29\u00b0C, 29\u00b0C, and │
│ 28\u00b0C, respectively. The assistant also offered to provide more │
│ details or hourly forecasts if needed." │
│ } │
╰──────────────────────────────────────────────────────────────────────────────╯