> For the complete documentation index, see [llms.txt](https://docs.frends.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.frends.com/reference/administration/environments-and-agent-groups/agent-groups.md). # Agent Groups Grouping Agents that perform the same operations with same configuration. Agent Groups represent the core execution clusters within the Frends runtime architecture, grouping together individual worker Agents to provide load balancing, high availability, and targeted execution. ## What are Agent Groups? In the Frends architecture, an Agent Group is a logical cluster of Agents that share execution responsibilities, state persistence, and communication queues within a specific Environment. While Environments establish the boundaries for configuration and lifecycle management, Agent Groups provide the actual computational capacity required to execute integration Processes and host API endpoints. All Agents operating within the same Agent Group share a common database store and message bus. This shared infrastructure enables automatic load balancing across all active nodes and ensures seamless failover if an individual Agent host becomes unavailable. Agent Groups also define the execution boundaries for Process deployments, allowing organizations to direct specific integrations to designated hardware clusters, private corporate networks, or public cloud environments. Agent Groups can be tailored for distinct operational roles. A standard Agent Group executes scheduled, event-driven, and manual Processes, whereas a dedicated API Gateway group handles incoming HTTP traffic and reverse proxy routing. Furthermore, modern Agent Groups support cross-platform execution, enabling Agents to run as lightweight containers on Linux, Kubernetes, or Docker as well as traditional Windows server installations. ## Agent Group management The Agent Group management view in the Frends Control Panel provides administrators with full control over Agent Group's cluster settings, database connections, runtime capabilities, and child Agent instances. When an Agent Group is selected from the left panel, the main panel displays its operational configuration, including the group name, registration mode, database connection string, advanced runtime flags, and provisioning buttons for Agents and API Gateways.

Agent Group management view.

## Usage Managing Agent Groups is performed through the Environments interface located in the Administration menu of the Frends Control Panel. ### Accessing and navigating Agent Groups To access an Agent Group, open the `Administration` dropdown in the top navigation bar and select `Environments`. In the left panel, locate the parent Environment and click the desired Agent Group nested beneath the Environment header. Selecting the Agent Group loads its full configuration and runtime management settings into the main panel. ### Creating a new Agent Group To create a new Agent Group, select the target Environment from the left panel to load the Environment configuration into the main panel. Under the `Agent groups` section, click the `+ New Agent group` button. This opens the Agent Group creation form, where you provide a descriptive name for the group, select the initial `Agent registration mode`, and supply a database `Connection string` if shared state clustering is required. After configuring any necessary advanced options such as cross-platform compatibility, confirm the creation to establish the new Agent Group within the Environment. ### Renaming an Agent Group To rename an existing Agent Group, navigate to its configuration in the main panel and click the pencil edit icon located immediately next to the Agent Group title. Enter the updated name in the text field and confirm the changes to apply the new name across the Tenant and all associated deployment references. ### Configuring Agent registration mode The `Agent registration mode` selector determines the lifecycle, provisioning method, and registration behavior for all Agents connecting to the Agent Group. Selecting `Self-Hosted Agent` configures the group for manually managed infrastructure, such as on-premises virtual machines, dedicated physical servers, or standalone container instances. In this mode, administrators manually provision and decommission Agents using the `+ New Agent` button and interface controls. Once active Agents are connected to a Self-Hosted Agent group, the registration mode is locked and cannot be modified until all Agents are disconnected. Selecting `Kubernetes Deployment` enables dynamic lifecycle management for stateless container clusters. Agents deployed via Kubernetes Deployments automatically register with the Frends Control Panel upon sending their initial heartbeat, and are automatically deregistered and removed from the UI when a pod terminates. This mode is optimal for auto-scaling workloads where container instances scale up and down dynamically based on processing load. Selecting `Kubernetes StatefulSet` provides automated registration for stateful containerized workloads. Similar to Deployment mode, Agents automatically register when their initial heartbeat is received; however, Frends preserves the Agent registration records permanently, ensuring that worker identities remain intact across pod restarts, rolling updates, and node maintenance. Switching between Kubernetes Deployment and Kubernetes StatefulSet modes can be performed dynamically without disconnecting active Agents. ### Setting database connection string The `Connection string` field defines the database instance used by all Agents in the group to maintain shared state, coordinate distributed locks, and persist operational messages. Administrators can provide a valid SQL Server, Azure SQL, or PostgreSQL connection string depending on the database engine utilized. All Agents assigned to the group must possess network access to this database to ensure unified clustering and synchronized execution state. If you are using a separate database installation, you should include `;TrustServerCertificate=True` parameter within the connection string, unless the database has a certificate configured that the operating system and .NET libraries trust. This parameter enables the libraries to trust your database regardless of the certificate. ### Configuring advanced settings The collapsible `Advanced settings` section provides granular controls over runtime behavior and platform compatibility for the entire Agent Group. The `Allow running test processes` toggle controls whether developers can execute ad hoc Process tests and Task runs against this Agent Group directly from the Process Editor. Disabling this toggle in production prevents unauthorized test executions, while enabling it on development and testing Agent Groups facilitates debugging and integration development. The `Cross platform` setting specifies whether the Agent Group utilizes the modern cross-platform .NET runtime. Enabling cross-platform support allows Agents in the group to run across diverse operating systems including Linux, Docker, and Kubernetes environments. Modifying this setting on an existing cluster requires reinstalling or redeploying the connected Agents to ensure runtime compatibility. {% hint style="info" %} Legacy Agents will be discontinued in Frends version 6.4, and their usage is no longer recommended unless specifically required to support old Frends integrations. Cross-Platform Agent is the default and only Agent type and runtime moving forward. {% endhint %} ### Configuring containerized Agent Group settings When an Agent Group is configured with a containerized registration mode such as `Kubernetes Deployment` or `Kubernetes StatefulSet`, the management interface adapts the `Agents` section to support automated container orchestration.

Agent Group management view for containerized Agent Groups.

Selecting the `Download Kubernetes configuration` link generates and downloads a pre-configured Kubernetes YAML manifest containing the deployment specifications, environment variables, registration secrets, and container image parameters tailored for that specific Agent Group. The `Default external address for new agents` field allows administrators to define the base hostname or ingress URL prefix, such as `https://localhost` or a public domain, that newly registered container pods will use. When dynamic Agent pods register with the Frends Control Panel, they inherit this address template to construct accessible external API endpoints and Trigger URLs automatically. ### Adding Agents and API Gateways For Self-Hosted Agent groups, the `Agents` and `API Gateways` sections allow administrators to manually expand cluster capacity. Selecting the `+ New Agent` button opens the Agent provisioning dialog to generate registration tokens and configure credentials for new worker nodes. Selecting the `+ New API Gateway` button initiates the setup flow for provisioning a dedicated API routing gateway within the group. ### Managing Agents and download packages In Self-Hosted Agent Groups, the `Agents` section displays all configured worker nodes alongside direct installation, configuration, and management actions. Each Agent card presents the current connectivity state under `Status`, such as Active or Inactive, alongside the installed runtime `Version`. The card includes dedicated action icons in its header for downloading deployment packages, modifying configuration, and deleting the node.

Configuration options for existing Agents.

Selecting the download package dropdown on an Agent card reveals multiple installation options tailored for different operating environments. Choosing `Preconfigured Linux binary package` downloads a pre-configured archive containing the cross-platform runtime binaries and configuration files ready for deployment on Linux systems. Selecting `Windows installer` downloads a setup wizard pre-populated with the group's connection tokens for Windows server installations. The `Configuration only` option supplies the standalone configuration files for updating existing installations or configuring custom container workloads. The `Database Initializer` provides the database provisioning utility to prepare the shared database schema before launching newly installed Agents. Administrators can select the settings gear icon on an Agent card to adjust port bindings, external URLs, or security certificates, or select the trash bin icon to remove an inactive Agent node from the group. ### Managing API Gateways Beneath the Agents section, the `API Gateways` section allows administrators to provision dedicated API routing gateways for the group. Selecting the `+ New API Gateway` button initiates the setup form to configure gateway credentials, port bindings, and external routing addresses. Administrators can select the settings gear icon on an API Gateway card to adjust port bindings, external URLs, or security certificates, or select the trash bin icon to remove an inactive Gateway node from the group. In the download menu for API Gateways, only the `Database Initializer` option is available. ### Synchronizing Agents The `Synchronize agents` button located at the top right of the main panel sends an immediate synchronization signal from the Frends Control Panel to all active Agents in the group. Triggering a synchronization forces all connected Agents to refresh their deployment caches, reload active Process configurations, and update Environment Variables without requiring a service restart. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.frends.com/reference/administration/environments-and-agent-groups/agent-groups.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.