An Agent is an AI teammate that belongs to one Organization. Hiring an Agent is the step that turns a Template into a running teammate people can reach from Slack, Telegram, or Discord.
This guide walks through the hire wizard end to end using the built-in General Purpose Template on Hermes, then starts the Agent and confirms its first reply.
What you will accomplish
By the end of this guide, you will have:
- Selected a Template and pinned an exact Template version
- Chosen the Agent's Runtime and communication platform
- Connected the required platform credentials
- Configured the Agent's model, behavior, Skills, and access
- Started the Agent and verified its first response
Hiring an Agent is different from inviting a human Organization member: it creates an operational AI resource, and it does not create a user account, a Membership, or any change to Organization ownership.
Before you begin
You need:
- A running Agent Barn installation
- An existing Organization
- Permission to create Agents in that Organization
- At least one model allowed for the Organization
- Credentials for Slack, Telegram, or Discord
- Credentials required by any Skills you plan to assign
Organization Owners and Organization Administrators hold implicit authority over the Organization's Agents. Other members need the appropriate Agent creation and access permissions.
Platform credentials
Prepare the credentials for the platform you plan to use before opening the wizard.
| Platform | Required credentials | Additional preparation |
|---|---|---|
| Slack | An app-level token with the xapp- prefix and a bot token with the xoxb- prefix | Enable Socket Mode, apply the required app manifest, and install the app to the Slack workspace |
| Telegram | A bot token issued by BotFather | Create the bot and decide whether it will take part in group chats |
| Discord | A Discord bot token | Enable Message Content Intent and invite the bot to the required server |
If you plan to restrict Discord access by role, also enable Server Members Intent.
Never paste a platform or integration secret into an Agent name, a Template, a description, a chat message, a screenshot, or a documentation page.
Recommended first Agent
For the most predictable first run, hire this combination.
- Template
- General Purpose, on its newest available version
- Runtime
- Hermes
- Platform
- Slack
- Model
- The deployment's configured default model
The current built-in General Purpose Template contains Slack-oriented instructions and tools, so Slack is the safest path for it. Hermes is lightweight and is the Runtime recommended by the current hire flow, and the wizard defaults built-in Templates to their newest published version.
The current hire wizard exposes Slack, Telegram, and Discord. Microsoft Teams is not selectable in this wizard.
Open the hire wizard
Switch to the Organization that should own the Agent, then select Hire agent in the top navigation.
The dialog opens on the Template step, headed What kind of teammate do you need?
If you do not see Hire agent, confirm that:
- You are in Organization View rather than Platform View
- The correct Organization is selected
- Your account has permission to create Agents in that Organization
- The Organization is active
Choose a Template
Search for and select General Purpose.
A Template defines the Agent's identity, operating instructions, expected users, and available tools. Templates are either built into Agent Barn or created by your Organization.
After selecting a Template, review its version selector. The Agent pins the exact version you select here.
| Template | Version selected by default |
|---|---|
| Built-in or custom Template | The newest available version |
| Organization fork | The Organization's effective version |
| Explicit selection | The version you chose; the Agent stays on it until it is deliberately repinned |
Because an Agent pins one exact Template version, publishing a newer Template version does not change an existing Agent.
Select Continue.
Choose a Runtime
Select Hermes for this guide.
| Runtime | Supported platforms | Best fit |
|---|---|---|
| Hermes | Slack, Teams, Telegram, and Discord | Fast, lightweight Agents with plugin-based capabilities |
| OpenClaw | Slack, Teams, Telegram, and Discord | Multi-channel routing and broader platform support |
Runtime and communication platform are separate choices. Selecting a Runtime does not create or configure a platform account for you.
Select Continue.
Connect a platform
Choose the platform where people will talk to the Agent. The wizard lists Slack, Telegram, and Discord.
Slack
Recommended
Select Slack, then Continue, and choose one of the two setup paths.
Choose this path when you want Agent Barn to create the Slack app configuration for you.
If your account has no saved Slack configuration tokens, the wizard asks for a Slack configuration access token and its refresh token, which carries the xoxe- prefix. Generate both under App Configuration Tokens on Your Apps at api.slack.com. Agent Barn saves them to your account so later Slack bots can reuse them.
Then enter the bot's display name, description, and background color. After Agent Barn creates the Slack app:
- Open the generated Slack Basic Information link.
- Create an app-level token with the
connections:writescope and copy it. - Open Install App and install the app to your workspace.
- Copy the bot user OAuth token.
- Paste both tokens into Agent Barn.
Choose this path when the Slack app already exists.
- Open the app on Your Apps at api.slack.com.
- Open Features → App Manifest.
- Apply the manifest shown by Agent Barn, or merge its scopes and settings into your existing manifest.
- Under Basic Information, generate an app-level token with the
connections:writescope. - Under Install App, install or reinstall the app to the workspace.
- Copy the app-level token and the bot user OAuth token, then paste both into Agent Barn.
The app-level token carries the xapp- prefix and the bot token carries the xoxb- prefix. Socket Mode and the manifest's events and scopes must be enabled for the Agent to receive messages.
Telegram
Select Telegram to connect a Telegram bot.
- Open BotFather on Telegram.
- Send
/newbot. - Choose a display name.
- Choose a username that ends in
bot. - Copy the bot token that BotFather returns and paste it into Agent Barn.
A Telegram bot token is a numeric bot identifier and a secret joined by a colon. Treat it as a password, and never place a real token in documentation, a screenshot, or a chat message.
If the Agent will take part in group chats, review the bot's Group Privacy setting in BotFather.
Discord
Select Discord to connect a Discord bot.
- Create an application in the Discord Developer Portal.
- Add a bot to the application.
- Enable Message Content Intent.
- If you will allow users through Discord roles, also enable Server Members Intent.
- Copy the bot token into Agent Barn.
- Optionally enter the application ID so Agent Barn can generate an installation link.
- Enter the allowed server and channel identifiers.
- Invite the bot to the required Discord server.
Discord access can also be restricted by operator identifiers or role identifiers. When Allow all users is disabled, provide at least one allowed operator or role.
Configure the Agent
Complete the Agent details. For this first Agent, use a recognizable name such as Aria.
| Field | Behavior |
|---|---|
| Name | Required display name for the Agent |
| Model | Defaults to the deployment's configured default model when one is available to the Organization |
| Command approval | Available for Hermes; controls how command execution is approved |
| Channel or group access | Controls which channels or groups the Agent may respond in |
| Direct messages | Controls whether the Agent accepts direct messages, and from whom |
| Verbosity | Available for Hermes on Slack; chooses step announcements or final answers only |
Command approval
| Mode | Behavior |
|---|---|
| Auto | Automatically approves low-risk commands |
| Manual | Requests approval before running commands |
| Off | Skips command approval prompts |
Use Auto for a first controlled test. Use Manual when the Agent will act against sensitive systems or take consequential actions.
Platform access settings
For a safe initial Slack configuration:
- Set Channel access to Allowlist
- Leave Direct messages set to Off
- Leave Verbosity set to Verbose
You can select the specific Slack channels and users after the Agent is created.
Telegram defaults to open group access and open direct messages. Change either setting to Allowlist or Off when the bot should serve only a controlled audience.
Review the Template files
Expand Review configuration files to read the pinned version's identity, instructions, users, and tools. This preview is read-only. To change reusable Template content, edit the Template under Settings → Templates and publish a new version.
Select Continue.
Assign Skills
Skills add focused instructions, references, and integration requirements to an Agent. The Skills step distinguishes three cases.
| Skill type | Behavior |
|---|---|
| Required by the Template | Selected automatically and cannot be removed |
| Required group | At least one option in the group must be selected |
| Optional | Select only when the first Agent needs that capability |
The General Purpose Template currently has no required Skills, so you can hire it without selecting an optional Skill. Use the smallest practical Skill set for a first test; more Skills can be assigned later from the Agent's configuration page.
When you select a Skill that needs an external provider, Agent Barn shows the credentials that provider requires. Depending on the provider, you can:
- Enter a credential for this Agent only
- Select an existing Shared Credential
- Reuse the Agent's platform credential, where that is supported automatically
Assigned Skills pin their exact published versions, so publishing a newer Skill version does not change an existing Agent.
Hire and start the Agent
Review the configuration and select Hire with the Agent's name.
Agent Barn validates the configuration, creates the Agent profile, pins the Template and Skill versions, encrypts the credentials, and saves the platform integration.
What happens next differs by platform.
| Platform | After creation | How the Agent starts |
|---|---|---|
| Slack | Shows Set up Slack access | Save the access settings, or select Skip for now |
| Telegram | Shows Set up Telegram access | Save the access settings, or select Skip for now |
| Discord | Closes the hire dialog with the Agent stopped | Open the Agent page and select Start |
Discord Agents are created stopped by design. Confirm that the Discord application has been invited to an allowed server, then start the Agent from its page.
Expected: The Agent's state changes to Running. If runtime provisioning fails, the state changes to Error.
Verify the first response
Open an allowed Slack channel, Telegram group, or Discord channel, and make sure the platform bot has been added or invited to that location.
Send a short message that explicitly mentions the Agent:
@Aria Reply with: Agent Barn connection verified.Then confirm each of the following:
- The Agent is shown as Running
- The message was sent from an allowed channel or group
- The Agent was explicitly mentioned
- The Agent returned the expected reply
- The conversation appears in the Agent's activity
- No unexpected tool or integration action ran
What Agent Barn creates
Hiring an Agent creates more than a chat-platform connection.
| Result | Behavior |
|---|---|
| Organization relationship | The Agent belongs to the selected Organization |
| Creator provenance | The user who hired the Agent is recorded as its creator |
| Agent Owner access | The creator receives explicit Agent Owner access |
| Agent General Access | Defaults to Restricted, so other Organization members do not automatically gain access |
| Template pin | The Agent references one exact active Template version until it is deliberately repinned |
| Skill pins | Each assigned Skill references one exact published version |
| Platform configuration | Stores the Slack, Telegram, or Discord routing configuration |
| Secrets | Platform and integration credentials are encrypted at rest and omitted from reads |
| Model configuration | Records the selected configured model |
| Runtime resources | Created or refreshed when the Agent starts |
| LiteLLM identity | A per-Agent key is created when LiteLLM is configured |
Agent access and platform routing
These are two separate controls:
- Agent General Access and explicit Agent Access determine which Organization members can view or operate the Agent in Agent Barn.
- Platform routing determines which Slack channels, Telegram chats, or Discord servers and channels can talk to it.
Granting one does not grant the other. See Roles, permissions, and Agent access for the full access model.
Troubleshooting
The Slack Agent is running but does not reply
Check the install, the invite, the allowlist, and the mention
Confirm all of the following:
- The Slack app is installed in the correct workspace
- The bot has been invited to the channel
- The channel is included in the Agent's allowed channels
- The message explicitly mentions the Agent
- Every message carries a fresh mention, including thread replies
- The app-level token carries the
xapp-prefix and the bot token carries thexoxb-prefix - Socket Mode and the manifest's required events and scopes are enabled
The Agent was hired but remains stopped
Save or skip the access panel, then start the Agent
On Slack and Telegram, saving the post-hire access settings or selecting Skip for now continues into startup. Closing that panel can leave the Agent stopped.
Open the Agent page and select Start.
Discord Agents are created stopped by design and always require this manual start step.
The Hire button is disabled
Review the Skills step
Confirm that:
- Every required Skill group has at least one selection
- Every required credential field is complete
- A valid Shared Credential is selected where shared credentials are used
- A Slack-only Skill is not being assigned to a Telegram or Discord Agent
A Slack or Discord token is already in use
Bot tokens must be unique among active Agents
Slack and Discord bot tokens must be unique among active Agents on the same platform.
Create a separate platform bot for the new Agent, or delete the Agent that holds the existing token before reusing it.
No models are available
Check the Organization's allowed models
The Organization must have at least one allowed model, and the corresponding provider must be configured for the installation.
Review the allowed models under Manage organization, then review the deployment's model provider configuration.
No Templates or Skills appear
Confirm the selected Organization
Templates and Skills are scoped to the current Organization, alongside the available built-in resources.
Confirm that you selected the correct Organization. Organization-managed Templates and Skills are listed under Settings → Templates and Settings → Skills.
The Agent enters the Error state
Inspect the Agent's status, health, and logs
Open the Agent page and review its status, health information, and logs. Common causes include:
- Invalid or expired platform credentials
- A missing required integration credential
- An unavailable configured model
- Runtime provisioning failure
- Platform permissions or intents that were never enabled
- Kubernetes capacity or image-pull failures in a self-hosted deployment
Correct the configuration, then start or restart the Agent.
Next steps
After the first Agent replies successfully:
- Verify your Agent against its operational signals
- Review the Agent's health and logs
- Configure Agent access and sharing for the rest of the Organization
- Replace any temporary open platform policy with channel and group allowlists
- Add the Skills and Shared Credentials the Agent needs for its real work
- Review the pinned Template versions before production use