--- title: Hire your first Agent canonical: "https://agentbarn.dev/guides/get-started/hire-first-agent" pubDate: "2026-08-29T00:00:00.000Z" updatedDate: "2026-09-13T13:41:42.000Z" author: Agent Barn description: "Create a headless, STOPPED Agent from a versioned Template, choose its Runtime and model behavior, and configure Skills, tool Integrations, and access before starting it." tags: [Get started, Guide, "Agent operators, Organization owners, and Organization administrators", hire agent, create agent, headless Agent, Agent Template, Template Version, Hermes, OpenClaw, Agent Skills, Skill Version, Agent Secret] categories: [Guides, Get started] --- 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. **Important** Hiring no longer selects Slack, Microsoft Teams, Telegram, or Discord. Platform selection, provider credentials, and routing policy belong to a Communication Connection that you add after the Agent is created. ## 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](/guides/get-started/create-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. **Important** Create the Agent inside the correct Organization. An Agent belongs to exactly one Organization, and its Templates, Skills, credentials, activity, and costs are scoped to that Organization. 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. **Recommended first Agent** 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. **Tip** Nothing about this combination limits which Platforms the Agent can reach later. You can add Connections for one or several Platforms to the same Agent once it is running. ## 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](/guides/agents/choose-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](/guides/templates-and-skills/templates). **Note** The version preview is read-only. Template placeholders are filled in when the Agent starts. ## 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](/guides/agents/configuration) 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](/guides/templates-and-skills/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](/guides/integrations/credentials). **Important** The hire action stays unavailable while a required Skill group has no selection or a required credential is incomplete. Complete every required credential field before continuing. ## 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 1. The Agent creation operation persists a headless Agent in `STOPPED`. 2. The web hire workflow may immediately issue a separate start operation after creation. 3. Starting the Agent renders its pinned configuration and creates Runtime resources. 4. A successful start transitions the Agent to `RUNNING`. 5. 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](/guides/agents/lifecycle). **Expected:** The Agent reaches `RUNNING`. If Runtime provisioning fails, it reaches `ERROR`. **Note** Communication Connection creation is not required for the Runtime to start. A running headless Agent simply cannot receive provider messages until a Communication Connection is added and enabled, and Connection provider failures do not move a running Agent to `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 `STOPPED` Agent, 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](/guides/roles-permissions-and-agent-access). ## Add a Communication Connection The Agent is headless after hiring. To let people reach it on a Platform: 1. Open the Agent's **Configuration**. 2. Open **Communication Connections**. 3. Add one or more Connections. 4. Select a Platform Plugin. 5. Enter the Connection settings and provider credentials. 6. Save and enable the Connection. 7. Complete the provider-side installation or membership steps. 8. Test one allowed interaction. Continue with [Communication Connections](/guides/agents/communication-connections) for the Connection lifecycle, and [Platforms](/guides/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 1. Open the Agent. 2. Review its lifecycle state and Runtime logs. 3. 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](/guides/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](/guides/agents/communication-connections) so people can reach it - [Verify your Agent](/guides/get-started/verify-agent) against its operational signals - Review the Agent's [health and logs](/guides/agents/health-and-logs) - Configure [Agent access and sharing](/guides/agents/sharing) for the rest of the Organization - Add the [Skills](/guides/templates-and-skills/skills) and [Integration credentials](/guides/integrations/credentials) the Agent needs for its real work - Review the pinned [Template Versions](/guides/templates-and-skills/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](/guides/agents/web-chat) for permissions and thread behavior. External Connections can be configured separately.