docs(agent, forge): Update component configuration docs (#7232)

This commit is contained in:
Krzysztof Czerwinski
2024-07-03 09:50:38 +01:00
committed by GitHub
parent 7cb4d4a903
commit 39f70b0c83
8 changed files with 168 additions and 43 deletions

View File

@@ -1,6 +1,7 @@
# Configuration
Configuration is controlled through the `Config` object. You can set configuration variables via the `.env` file. If you don't have a `.env` file, create a copy of `.env.template` in your `AutoGPT` folder and name it `.env`.
Configuration of sensitive settings such as API credentials is done through environment variables.
You can set configuration variables via the `.env` file. If you don't have a `.env` file, create a copy of `.env.template` in your `AutoGPT` folder and name it `.env`.
## Environment Variables
@@ -21,7 +22,7 @@ Configuration is controlled through the `Config` object. You can set configurati
- `GROQ_API_KEY`: Set this if you want to use Groq models with AutoGPT
- `HUGGINGFACE_API_TOKEN`: HuggingFace API, to be used for both image generation and audio to text. Optional.
- `HUGGINGFACE_IMAGE_MODEL`: HuggingFace model to use for image generation. Default: CompVis/stable-diffusion-v1-4
- `OPENAI_API_KEY`: *REQUIRED*- Your [OpenAI API Key](https://platform.openai.com/account/api-keys).
- `OPENAI_API_KEY`: Set this if you want to use OpenAI models; [OpenAI API Key](https://platform.openai.com/account/api-keys).
- `OPENAI_ORGANIZATION`: Organization ID in OpenAI. Optional.
- `PLAIN_OUTPUT`: Plain output, which disables the spinner. Default: False
- `RESTRICT_TO_WORKSPACE`: The restrict file reading and writing to the workspace directory. Default: True
@@ -31,4 +32,3 @@ Configuration is controlled through the `Config` object. You can set configurati
- `TEMPERATURE`: Value of temperature given to OpenAI. Value from 0 to 2. Lower is more deterministic, higher is more random. See https://platform.openai.com/docs/api-reference/completions/create#completions/create-temperature
- `TEXT_TO_SPEECH_PROVIDER`: Text to Speech Provider. Options are `gtts`, `macos`, `elevenlabs`, and `streamelements`. Default: gtts
- `USE_AZURE`: Use Azure's LLM Default: False
- `WIPE_REDIS_ON_START`: Wipes data / index on start. Default: True

View File

@@ -71,18 +71,25 @@
- ./logs:/app/logs
## uncomment following lines if you want to make use of these files
## you must have them existing in the same folder as this docker-compose.yml
## component configuration file
#- type: bind
# source: ./config.json
# target: /app/config.json
```
</details>
4. Download [`.env.template`][.env.template] and save it as `.env` in the AutoGPT folder.
5. Follow the standard [configuration instructions](../index.md#completing-the-setup),
1. Download [`.env.template`][.env.template] and save it as `.env` in the AutoGPT folder.
2. Follow the standard [configuration instructions](../index.md#completing-the-setup),
from step 3 onwards and excluding `poetry install` steps.
6. Pull the latest image from [Docker Hub]
3. Pull the latest image from [Docker Hub]
```shell
docker pull significantgravitas/auto-gpt
```
4. _Optional: mount configuration file._
If you have component configuration file, for example `config.json`, place it in `autogpt/data/` directory. Or place it in `autogpt/` and uncomment the line in `docker-compose.yml` that mounts it.
To learn more about configuring, see [Component configuration](../../forge/components/components.md#json-configuration)
!!! note "Docker only supports headless browsing"
AutoGPT uses a browser in headless mode by default: `HEADLESS_BROWSER=True`.

View File

@@ -50,7 +50,13 @@ Since we don't ship AutoGPT as a desktop application, you'll need to download th
### Completing the Setup
Once you have cloned or downloaded the project, you can find the AutoGPT Agent in the
`autogpt/` folder. In this folder:
`autogpt/` folder.
Inside this folder you can configure the AutoGPT application with an `.env` file and (optionally) a JSON configuration file:
- `.env` for environment variables, which are mostly used for sensitive data like API keys
- a JSON configuration file to customize certain features of AutoGPT's [Components](../../forge/components/introduction.md)
See the [Configuration](../configuration/options.md) reference for a list of available environment variables.
1. Find the file named `.env.template`. This file may
be hidden by default in some operating systems due to the dot prefix. To reveal
@@ -71,6 +77,9 @@ Once you have cloned or downloaded the project, you can find the AutoGPT Agent i
6. Save and close the `.env` file.
7. _Optional: run `poetry install` to install all required dependencies._ The
application also checks for and installs any required dependencies when it starts.
8. _Optional: configure the JSON file (e.g. `config.json`) with your desired settings._
The application will use default settings if you don't provide a JSON configuration file.
Learn how to [set up the JSON configuration file](../../forge/components/components.md#json-configuration)
You should now be able to explore the CLI (`./autogpt.sh --help`) and run the application.
@@ -79,7 +88,6 @@ See the [user guide](../usage.md) for further instructions.
[show hidden files/Windows]: https://support.microsoft.com/en-us/windows/view-hidden-files-and-folders-in-windows-97fbc472-c603-9d90-91d0-1166d1d9f4b5
[show hidden files/macOS]: https://www.pcmag.com/how-to/how-to-access-your-macs-hidden-files
## Setting up LLM providers
You can use AutoGPT with any of the following LLM providers.

View File

@@ -1,25 +1,25 @@
# Built-in Components
This page lists all [🧩 Components](./components.md) and [⚙️ Protocols](./protocols.md) they implement that are natively provided. They are used by the AutoGPT agent.
Some components have additional configuration options listed in the table, see [Component configuration](./components.md/#ordering-components) to learn more.
Some components have additional configuration options listed in the table, see [Component configuration](./components.md/#component-configuration) to learn more.
!!! note
If a configuration field uses environment variable, it still can be passed using configuration model. **Value from the configuration takes precedence over env var!** Env var will be only applied if value in the configuration is not set.
If a configuration field uses environment variable, it still can be passed using configuration model. ### Value from the configuration takes precedence over env var! Env var will be only applied if value in the configuration is not set.
## `SystemComponent`
Essential component to allow an agent to finish.
**DirectiveProvider**
### DirectiveProvider
- Constraints about API budget
**MessageProvider**
### MessageProvider
- Current time and date
- Remaining API budget and warnings if budget is low
**CommandProvider**
### CommandProvider
- `finish` used when task is completed
@@ -27,7 +27,7 @@ Essential component to allow an agent to finish.
Adds ability to interact with user in CLI.
**CommandProvider**
### CommandProvider
- `ask_user` used to ask user for input
@@ -36,18 +36,20 @@ Adds ability to interact with user in CLI.
Adds ability to read and write persistent files to local storage, Google Cloud Storage or Amazon's S3.
Necessary for saving and loading agent's state (preserving session).
### `FileManagerConfiguration`
| Config variable | Details | Type | Default |
| ---------------- | -------------------------------------- | ----- | ---------------------------------- |
| `files_path` | Path to agent files, e.g. state | `str` | `agents/{agent_id}/`[^1] |
| `storage_path` | Path to agent files, e.g. state | `str` | `agents/{agent_id}/`[^1] |
| `workspace_path` | Path to files that agent has access to | `str` | `agents/{agent_id}/workspace/`[^1] |
[^1] This option is set dynamically during component construction as opposed to by default inside the configuration model, `{agent_id}` is replaced with the agent's unique identifier.
**DirectiveProvider**
### DirectiveProvider
- Resource information that it's possible to read and write files
**CommandProvider**
### CommandProvider
- `read_file` used to read file
- `write_file` used to write file
@@ -57,6 +59,8 @@ Necessary for saving and loading agent's state (preserving session).
Lets the agent execute non-interactive Shell commands and Python code. Python execution works only if Docker is available.
### `CodeExecutorConfiguration`
| Config variable | Details | Type | Default |
| ------------------------ | ---------------------------------------------------- | --------------------------- | ----------------- |
| `execute_local_commands` | Enable shell command execution | `bool` | `False` |
@@ -65,7 +69,7 @@ Lets the agent execute non-interactive Shell commands and Python code. Python ex
| `shell_denylist` | List of prohibited shell commands | `List[str]` | `[]` |
| `docker_container_name` | Name of the Docker container used for code execution | `str` | `"agent_sandbox"` |
**CommandProvider**
### CommandProvider
- `execute_shell` execute shell command
- `execute_shell_popen` execute shell command with popen
@@ -76,6 +80,8 @@ Lets the agent execute non-interactive Shell commands and Python code. Python ex
Keeps track of agent's actions and their outcomes. Provides their summary to the prompt.
### `ActionHistoryConfiguration`
| Config variable | Details | Type | Default |
| ---------------------- | ------------------------------------------------------- | ----------- | ------------------ |
| `model_name` | Name of the llm model used to compress the history | `ModelName` | `"gpt-3.5-turbo"` |
@@ -83,19 +89,19 @@ Keeps track of agent's actions and their outcomes. Provides their summary to the
| `spacy_language_model` | Language model used for summary chunking using spacy | `str` | `"en_core_web_sm"` |
| `full_message_count` | Number of cycles to include unsummarized in the prompt | `int` | `4` |
**MessageProvider**
### MessageProvider
- Agent's progress summary
**AfterParse**
### AfterParse
- Register agent's action
**ExecutionFailure**
### ExecutionFailure
- Rewinds the agent's action, so it isn't saved
**AfterExecute**
### AfterExecute
- Saves the agent's action result in the history
@@ -103,12 +109,14 @@ Keeps track of agent's actions and their outcomes. Provides their summary to the
Adds ability to iteract with git repositories and GitHub.
### `GitOperationsConfiguration`
| Config variable | Details | Type | Default |
| ----------------- | ----------------------------------------- | ----- | ------- |
| `github_username` | GitHub username, *ENV:* `GITHUB_USERNAME` | `str` | `None` |
| `github_api_key` | GitHub API key, *ENV:* `GITHUB_API_KEY` | `str` | `None` |
**CommandProvider**
### CommandProvider
- `clone_repository` used to clone a git repository
@@ -123,7 +131,9 @@ Link to the appropriate settings page: [Hugging Face > Settings > Tokens](https:
### Stable Diffusion WebUI
It is possible to use your own self-hosted Stable Diffusion WebUI with AutoGPT. **Make sure you are running WebUI with `--api` enabled.**
It is possible to use your own self-hosted Stable Diffusion WebUI with AutoGPT. ### Make sure you are running WebUI with `--api` enabled.
### `ImageGeneratorConfiguration`
| Config variable | Details | Type | Default |
| ------------------------- | ------------------------------------------------------------- | --------------------------------------- | --------------------------------- |
@@ -135,7 +145,7 @@ It is possible to use your own self-hosted Stable Diffusion WebUI with AutoGPT.
[available models]: https://huggingface.co/models?pipeline_tag=text-to-image
**CommandProvider**
### CommandProvider
- `generate_image` used to generate an image given a prompt
@@ -143,17 +153,19 @@ It is possible to use your own self-hosted Stable Diffusion WebUI with AutoGPT.
Allows agent to search the web. Google credentials aren't required for DuckDuckGo. [Instructions how to set up Google API key](../../AutoGPT/configuration/search.md)
### `WebSearchConfiguration`
| Config variable | Details | Type | Default |
| -------------------------------- | ----------------------------------------------------------------------- | ----- | ------- |
| `google_api_key` | Google API key, *ENV:* `GOOGLE_API_KEY` | `str` | `None` |
| `google_custom_search_engine_id` | Google Custom Search Engine ID, *ENV:* `GOOGLE_CUSTOM_SEARCH_ENGINE_ID` | `str` | `None` |
| `duckduckgo_max_attempts` | Maximum number of attempts to search using DuckDuckGo | `int` | `3` |
**DirectiveProvider**
### DirectiveProvider
- Resource information that it's possible to search the web
**CommandProvider**
### CommandProvider
- `search_web` used to search the web using DuckDuckGo
- `google` used to search the web using Google, requires API key
@@ -162,6 +174,8 @@ Allows agent to search the web. Google credentials aren't required for DuckDuckG
Allows agent to read websites using Selenium.
### `WebSeleniumConfiguration`
| Config variable | Details | Type | Default |
| ----------------------------- | ------------------------------------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `model_name` | Name of the llm model used to read websites | `ModelName` | `"gpt-3.5-turbo"` |
@@ -170,11 +184,11 @@ Allows agent to read websites using Selenium.
| `user_agent` | User agent used by the browser | `str` | `"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/83.0.4103.97 Safari/537.36"` |
| `browse_spacy_language_model` | Spacy language model used for chunking text | `str` | `"en_core_web_sm"` |
**DirectiveProvider**
### DirectiveProvider
- Resource information that it's possible to read websites
**CommandProvider**
### CommandProvider
- `read_website` used to read a specific url and look for specific topics or answer a question
@@ -182,11 +196,11 @@ Allows agent to read websites using Selenium.
Adds ability to keep up-to-date file and folder content in the prompt.
**MessageProvider**
### MessageProvider
- Content of elements in the context
**CommandProvider**
### CommandProvider
- `open_file` used to open a file into context
- `open_folder` used to open a folder into context
@@ -196,6 +210,6 @@ Adds ability to keep up-to-date file and folder content in the prompt.
Watches if agent is looping and switches to smart mode if necessary.
**AfterParse**
### AfterParse
- Investigates what happened and switches to smart mode if necessary

View File

@@ -37,7 +37,7 @@ Since components are regular classes you can pass data (including other componen
For example we can pass a config object and then retrieve an API key from it when needed:
```py
class ConfigurableComponent(MessageProvider):
class DataComponent(MessageProvider):
def __init__(self, config: Config):
self.config = config
@@ -51,6 +51,35 @@ class ConfigurableComponent(MessageProvider):
!!! note
Component-specific configuration handling isn't implemented yet.
## Configuring components
Components can be configured using a pydantic model.
To make component configurable, it must inherit from `ConfigurableComponent[BM]` where `BM` is the configuration class inheriting from pydantic's `BaseModel`.
You should pass the configuration instance to the `ConfigurableComponent`'s `__init__` or set its `config` property directly.
Using configuration allows you to load confugration from a file, and also serialize and deserialize it easily for any agent.
To learn more about configuration, including storing sensitive information and serialization see [Component Configuration](./components.md#component-configuration).
```py
# Example component configuration
class UserGreeterConfiguration(BaseModel):
user_name: str
class UserGreeterComponent(MessageProvider, ConfigurableComponent[UserGreeterConfiguration]):
def __init__(self):
# Creating configuration instance
# You could also pass it to the component constructor
# e.g. `def __init__(self, config: UserGreeterConfiguration):`
config = UserGreeterConfiguration(user_name="World")
# Passing the configuration instance to the parent class
UserGreeterComponent.__init__(self, config)
# This has the same effect as the line above:
# self.config = UserGreeterConfiguration(user_name="World")
def get_messages(self) -> Iterator[ChatMessage]:
# You can use the configuration like a regular model
yield ChatMessage.system(f"Hello, {self.config.user_name}!")
```
## Providing commands
To extend what an agent can do, you need to provide commands using `CommandProvider` protocol. For example to allow agent to multiply two numbers, you can create a component like this:

View File

@@ -10,7 +10,7 @@ This guide explains the component-based architecture of AutoGPT agents. It's a n
Agent is composed of *components*, and each *component* implements a range of *protocols* (interfaces), each one providing a specific functionality, e.g. additional commands or messages. Each *protocol* is handled in a specific order, defined by the agent. This allows for a clear separation of concerns and a more modular design.
This system is simple, flexible, requires basically no configuration, and doesn't hide any data - anything can still be passed or accessed directly from or between components.
This system is simple, flexible, and doesn't hide any data - anything can still be passed or accessed directly from or between components.
### Definitions & Guides

View File

@@ -19,16 +19,16 @@ Forge is a ready-to-go template for *your* agent application. All the boilerplat
### 🚀 **Get Started!**
The best way to get started is to fork or download the AutoGPT repository and look at the example agent in `forge/forge/agent/forge_agent.py`.
This can work as a starting point for your own agent.
Agents are built using *components* which provide different functionality, see the [Component Introduction](./components/introduction.md). You can find built-in components in `forge/forge/components/`.
!!! warning
The tutorial series below is out of date.
The getting started [tutorial series](https://aiedge.medium.com/autogpt-forge-e3de53cc58ec) will guide you through the process of setting up your project all the way through to building a generalist agent.
1. [AutoGPT Forge: A Comprehensive Guide to Your First Steps](https://aiedge.medium.com/autogpt-forge-a-comprehensive-guide-to-your-first-steps-a1dfdf46e3b4)
2. [AutoGPT Forge: The Blueprint of an AI Agent](https://aiedge.medium.com/autogpt-forge-the-blueprint-of-an-ai-agent-75cd72ffde6)
3. [AutoGPT Forge: Interacting with your Agent](https://aiedge.medium.com/autogpt-forge-interacting-with-your-agent-1214561b06b)
4. [AutoGPT Forge: Crafting Intelligent Agent Logic](https://medium.com/@aiedge/autogpt-forge-crafting-intelligent-agent-logic-bc5197b14cb4)
Coming soon:
5. Interacting with and Benchmarking your Agent
6. Abilities
7. The Planning Loop
8. Memories

View File

@@ -33,7 +33,7 @@ class MyAgent(BaseAgent):
## Component configuration
Each component can have its own configuration defined using a regular pydantic `BaseModel`.
To ensure the configuration is loaded from the file correctly, the component must inherit from `ConfigurableComponent[T]` where `T` is the configuration model it uses.
To ensure the configuration is loaded from the file correctly, the component must inherit from `ConfigurableComponent[BM]` where `BM` is the configuration model it uses.
`ConfigurableComponent` provides a `config` attribute that holds the configuration instance.
It's possible to either set the `config` attribute directly or pass the configuration instance to the component's constructor.
Extra configuration (i.e. for components that are not part of the agent) can be passed and will be silently ignored. Extra config won't be applied even if the component is added later.
@@ -72,6 +72,73 @@ class SensitiveConfig(BaseModel):
api_key: SecretStr = UserConfigurable(from_env="API_KEY", exclude=True)
```
### Configuration serialization
`BaseAgent` provides two methods:
1. `dump_component_configs`: Serializes all components' configurations as json string.
1. `load_component_configs`: Deserializes json string to configuration and applies it.
### JSON configuration
You can specify a JSON file (e.g. `config.json`) to use for the configuration when launching an agent.
This file contains settings for individual [Components](../components/introduction.md) that AutoGPT uses.
To specify the file use `--component-config-file` CLI option, for example to use `config.json`:
```shell
./autogpt.sh run --component-config-file config.json
```
!!! note
If you're using Docker to run AutoGPT, you need to mount or copy the configuration file to the container.
See [Docker Guide](../../AutoGPT/setup/docker.md) for more information.
### Example JSON configuration
You can copy configuration you want to change, for example to `autogpt/config.json` and modify it to your needs.
*Most configuration has default values, it's better to set only values you want to modify.*
You can see the available configuration fields and default values in [Build-in Components](./built-in-components.md).
You can set sensitive variables in the `.json` file as well but it's recommended to use environment variables instead.
```json
{
"CodeExecutorConfiguration": {
"execute_local_commands": false,
"shell_command_control": "allowlist",
"shell_allowlist": ["cat", "echo"],
"shell_denylist": [],
"docker_container_name": "agent_sandbox"
},
"FileManagerConfiguration": {
"storage_path": "agents/AutoGPT/",
"workspace_path": "agents/AutoGPT/workspace"
},
"GitOperationsConfiguration": {
"github_username": null
},
"ActionHistoryConfiguration": {
"model_name": "gpt-3.5-turbo",
"max_tokens": 1024,
"spacy_language_model": "en_core_web_sm"
},
"ImageGeneratorConfiguration": {
"image_provider": "dalle",
"huggingface_image_model": "CompVis/stable-diffusion-v1-4",
"sd_webui_url": "http://localhost:7860"
},
"WebSearchConfiguration": {
"duckduckgo_max_attempts": 3
},
"WebSeleniumConfiguration": {
"model_name": "gpt-3.5-turbo",
"web_browser": "chrome",
"headless": true,
"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/83.0.4103.97 Safari/537.36",
"browse_spacy_language_model": "en_core_web_sm"
}
}
```
## Ordering components
The execution order of components is important because some may depend on the results of the previous ones.