An Agent is an AI teammate that belongs to one Organization. Hiring an Agent creates it headless: you choose its identity, Runtime, Template Version, model behavior, Skills, and tool Integrations, and then start it.
This guide walks through the hire flow end to end using the built-in General Purpose Template on Hermes, then starts the Agent. Communication Connections are configured separately, after the Agent exists.
The current model is:
- An Agent belongs to one Organization.
- An Agent executes through one Runtime: Hermes or OpenClaw.
- An Agent pins one exact Template Version or Agent Template Override Version.
- An Agent may follow its Organization's default model or pin an explicit model.
- An Agent may pin exact Skill Versions.
- Agent Secrets and Shared Credentials configure tool Integrations.
- Every Agent is created headless.
- Communication Connections are added after the Agent exists.
- An Agent may later own zero or many Communication Connections, including several Connections to the same Platform.
What you will accomplish
By the end of this guide, you will have:
- Created a headless Agent in the correct Organization
- Chosen Hermes or OpenClaw as its Runtime
- Pinned an exact Template Version and Skill Versions
- Chosen model inheritance or an explicit allowed model
- Configured the tool Integration credentials the Agent needs
- Started the Agent and understood what comes next
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:
- An active Organization; see Create your first Organization
- Permission to create an Agent
- Access to at least one visible published Template Version
- An Organization model allowlist that supports the intended model behavior
- Any provider credentials required by the selected Skills or Template requirements
- Permission to manage Agent Secrets when adding or changing Integration credentials
- A working Hermes or OpenClaw Runtime image in the deployment
- Capacity in the configured Kubernetes namespace when the Agent is started
Organization Owners and Organization Administrators hold implicit authority over the Organization's Agents. Other Members need the appropriate Agent creation permission.
You do not need Slack, Microsoft Teams, Telegram, or Discord credentials to hire an Agent, and you do not need channel, chat, guild, team, user, or role identifiers. Those belong to the later Communication Connection workflow.
Never paste a provider secret into an Agent name, a Template, a Skill, 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
- Model
- Follow the Organization default
- Skills
- Required Skills only
Hermes is lightweight and is the Runtime offered first by the current hire flow, and the flow defaults built-in Templates to their newest published version. Keeping the first Agent to its required Skills means fewer provider credentials to prepare before it can start.
Open the hire flow
Switch to the Organization that should own the Agent, then select the action to create a new Agent: Hire a headless Agent in the current interface.
Enter the Agent name. For this first Agent, use a recognizable name such as Aria.
If you do not see the hire action, 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 Runtime
Select the Runtime that will execute the Agent. Select Hermes for this guide.
Hermes
Hermes is the lightweight Runtime option. It has its own execution model and its own command-approval behavior, and it is a good default for a first Agent.
OpenClaw
OpenClaw is the alternative Runtime. It has its own execution model and broader workspace behavior, which suits Agents that work across a larger set of files and tools.
Runtime selection is independent of communication:
- Both Runtimes use the same runtime-neutral Communications protocol.
- Platform choice does not determine Runtime choice.
- Communication Connections are independent of Runtime selection.
- The same Agent does not need to be recreated to add another Platform.
For a fuller comparison, see Choose an Agent runtime.
Select 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 the exact Template Version that will be pinned.
| 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 |
How pinning works
- The Agent pins an exact immutable Template Version.
- Publishing a newer Template Version does not automatically move the Agent.
- Required Skills are validated from the selected Template Version, not from the Template lineage as a whole.
An Agent can later use an Agent Template Override Version instead of a shared Template Version. See Work with Templates.
Choose the model behavior
Choose whether the Agent follows the Organization default model or uses an explicit allowed model. These are separate choices.
| Choice | Behavior |
|---|---|
| Follow the Organization default | The Agent uses the Organization's effective default model. An Organization may follow the deployment's platform default, or choose its own default instead. |
| Pin an explicit model | The Agent uses one allowed model until that choice is deliberately changed |
When the Agent is configured to inherit, the hire flow shows the effective default it will resolve to. A running Agent may continue serving its previously started model until it is restarted.
Managing the Organization's own default is outside this guide; see Configure an Agent for ongoing model configuration.
Review and select Skills
Skills add focused instructions, references, and Integration requirements to an Agent. Review the required Skills first, then select optional Skills and their published versions where the interface allows it.
| Skill type | Behavior |
|---|---|
| Required by the Template Version | 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.
Skill Version pinning and visibility
- Agent Skill assignments pin exact immutable Skill Versions.
- Publishing a newer Skill Version does not automatically move the Agent.
- Skills may be visible from Platform, Organization, or Agent-private scope.
- A Skill can declare required tool providers.
- Required provider credentials must be configured before the Agent can start successfully.
See Work with Skills for authoring and version management.
Configure Integration credentials
When a selected Skill or Template requirement needs an external provider, Agent Barn shows the credentials that provider requires. Depending on the provider, you can:
- Enter an Agent Secret for this Agent only
- Attach an eligible Shared Credential owned by the Organization
| Credential | Scope and purpose |
|---|---|
| Agent Secret | Provider credentials for tool Integrations used by the Runtime, scoped to one Agent |
| Shared Credential | Organization-owned Integration credentials that may be attached to eligible Agents |
Communication Connection credentials are separate from both. Slack, Microsoft Teams, Telegram, and Discord credentials do not belong in the Agent hire request, and communication credentials are never materialized into Hermes or OpenClaw.
Secret plaintext is not returned by Agent read operations. See Manage Agent credentials.
Select command approval
Select the supported command-approval behavior when the chosen Runtime exposes it.
| 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.
Review and complete the hire
Review the configuration, then complete the hire action.
Agent Barn validates the configuration, creates the Agent, pins the Template Version and Skill Versions, and encrypts any Integration credentials you entered.
What happens next
- The Agent creation operation persists a headless Agent in
STOPPED. - The web hire workflow may immediately issue a separate start operation after creation.
- Starting the Agent renders its pinned configuration and creates Runtime resources.
- A successful start transitions the Agent to
RUNNING. - A startup failure can transition it to
ERROR.
If the Agent remains stopped, open the Agent page and select Start. See Manage the Agent lifecycle.
Expected: The Agent reaches RUNNING. If Runtime provisioning fails, it reaches ERROR.
What hiring creates
Hiring creates:
- The Agent record
- Agent Creator provenance
- Explicit Agent Owner access for the creator
- Restricted Agent General Access by default
- A pinned Template Version
- Exact Skill Version assignments
- Agent Secrets or Shared Credential references for tool Integrations
- A LiteLLM key when configured
- A headless
STOPPEDAgent, before the separate start operation
Starting then creates or recreates:
- Runtime ConfigMap
- Runtime Secret
- PersistentVolumeClaim
- Runtime Service
- Runtime Deployment
- Fresh Ingest credentials
- Fresh Communications protocol credentials
Hiring does not create:
- A Communication Connection
- A Slack application
- A Telegram bot
- A Discord application
- A Microsoft Teams application
- Platform routing or access policy
Agent Access after hiring
- The Agent Creator receives explicit Agent Owner access.
- Agent General Access defaults to Restricted.
- Other Organization Members do not automatically receive Agent access.
- Organization Owners and Administrators retain their documented implicit authority.
- Additional explicit Agent Access can be assigned after hiring.
Agent Access inside Agent Barn is separate from who may interact with the Agent through a Communication Platform. Adding people to a Platform channel does not grant them access to the Agent's configuration in Agent Barn, and granting Agent Access does not let someone talk to the Agent on a Platform. See Roles, permissions, and Agent access.
Add a Communication Connection
The Agent is headless after hiring. To let people reach it on a Platform:
- Open the Agent's Configuration.
- Open Communication Connections.
- Add one or more Connections.
- Select a Platform Plugin.
- Enter the Connection settings and provider credentials.
- Save and enable the Connection.
- Complete the provider-side installation or membership steps.
- Test one allowed interaction.
Continue with Communication Connections for the Connection lifecycle, and Platforms for the provider setup guide that matches your Platform.
Completion checklist
Before moving on, confirm that you have:
- Created an Agent in the correct Organization
- Chosen Hermes or OpenClaw
- Pinned the intended Template Version
- Selected model inheritance or an explicit allowed model
- Satisfied required Skill Version and Integration requirements
- Confirmed the creator has Agent Owner access
- Started the Agent, or identified a startup error
- Understood that Communication Connections are configured separately
Troubleshooting
No Templates are available
Check Template visibility and read permission
- Confirm the Organization can see a published Platform or Organization Template.
- Confirm the user has the required Template read permission.
No models are available
Check the allowlist, the Organization default, and the provider
- Review the Organization model allowlist.
- Review the Organization Agent Settings default.
- Confirm the deployment model provider is configured.
A required Skill cannot be satisfied
Check the Template Version requirements and Skill visibility
- Review the exact Template Version requirements.
- Confirm the required Skill and Skill Version are visible.
- Configure any required tool provider credentials.
Hiring succeeds but start fails
Review lifecycle state and Runtime logs
- Open the Agent.
- Review its lifecycle state and Runtime logs.
- Check model availability, Runtime image access, Kubernetes capacity, Template rendering, Skills, and Integration credentials.
Do not diagnose this as a Communication Connection failure unless the Runtime is already running and only communication is affected.
The Agent is running but cannot receive messages
Check that a Connection exists and is enabled
- Confirm at least one Communication Connection exists.
- Confirm the Connection is enabled.
- Review Connection health separately from Agent health.
Then follow the relevant Platform setup guide under Platforms.
Other Members cannot see the Agent
Agent General Access defaults to Restricted
Agent General Access defaults to Restricted, so Members do not gain access automatically.
Assign explicit Agent Access, or deliberately change General Access.
Next steps
After the Agent is running:
- Add a Communication Connection so people can reach it
- 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
- Add the Skills and Integration credentials the Agent needs for its real work
- Review the pinned Template Versions before production use
Chat in the dashboard
For an initial conversation without external provider setup, use the experimental Chat tab once the Agent is Running and Working. See Chat with an Agent in the dashboard for permissions and thread behavior. External Connections can be configured separately.