Skip to main content
Agent Profiles are a Beta feature in OpenHands Enterprise and are off by default. To turn them on, go to Super Admin Dashboard > Instance Settings and enable Agent Profiles (Beta). See Super Admin Dashboard.
An Agent Profile is a named, reusable agent setup. It decides which agent runs a conversation or automation, which LLM profile it uses, and what it is allowed to touch: tools, secrets, skills, MCP servers, and built-in integrations. OpenHands Enterprise has two kinds of Agent Profiles:
  • Personal Agent Profiles belong to one member of an organization. Any member can create them.
  • Organization Agent Profiles belong to the organization. Admins and Owners create them, and every member can use them.
Both kinds appear on one page, Settings > Agent Profiles, in a Personal agent profiles section and an Organization agent profiles section. For the general Agent Profile concept and the Agent Canvas editor, see Agent Profiles.

Compare the Two Scopes

The main rule: an organization profile can use only organization-scoped resources. It cannot include anything from the personal settings of the Admin who creates it. A personal profile can use both your personal resources and the resources your organization shares. Neither scope supports the Model Router yet.

Why Organization Profiles Are Restricted

  • No ACP agents. An ACP agent connects to one person’s subscription, such as Codex or Claude Code. If many members share that connection, it can reach the provider’s rate limits quickly.
  • No MCP servers. MCP servers are configured per user today. An organization profile cannot depend on one member’s MCP servers.
  • No personal secrets. When a conversation starts from an organization profile that lists its secrets, those names resolve to organization-shared secrets only. A member’s personal secret with the same name is never used. See Agent Profile Secret Selection.
The server enforces these rules when an Admin saves an organization profile. It refuses an ACP agent, a non-empty MCP server list, and secret names that are not organization-shared secrets.

Permissions

Profile Names

Profile names must be unique across both scopes for each member. You cannot give a personal profile the name of an organization profile. An Admin cannot give an organization profile a name that any member already uses for a personal profile.

Use an Agent Profile

Set a Default Profile

  1. Open Settings > Agent Profiles.
  2. Open the actions menu on a personal or organization profile.
  3. Select Set as default.
The profile shows a Default badge, and new conversations use it. To clear the default, open the actions menu on the default profile and select Deactivate. New conversations then use your organization and personal settings without a profile. You can also choose a profile for one conversation from the agent profile picker in the chat input.

Use a Profile in an Automation

When you create or edit an automation, select a personal or organization Agent Profile. The automation’s conversations launch with that profile. The automation still runs as its creating user; the profile limits what the agent can do, but it does not change whose identity it runs under. Profile-backed automation templates, such as the PR reviewer, issue triage, and issue-to-PR templates, need an explicit tool list. In the profile’s Tools section, select Choose tools instead of Standard set.

Create a Personal Agent Profile

  1. Open Settings > Agent Profiles.
  2. In Personal agent profiles, select Add.
  3. Enter a name and choose the agent and LLM profile.
  4. Configure tools, system prompt, condenser, and verification as needed.
  5. Choose the MCP servers, secrets, skills, and built-in integrations the agent can use. Organization secrets and organization marketplace skills show an Organization badge.
  6. Save the profile.

Create an Organization Agent Profile

  1. Select the organization that should own the profile.
  2. As an Admin or Owner, open Settings > Agent Profiles.
  3. In Organization agent profiles, select Add.
  4. Enter a name and choose an organization LLM profile.
  5. Configure tools, parallel tool calls, system prompt, condenser, and verification as needed.
  6. Choose the organization secrets and skills the agent can use. All organization secrets are selected by default; clear the ones the agent does not need.
  7. Save the profile.
If you edit the seeded organization profile named default, saving converts it to an organization-only profile: no MCP servers and an explicit secret list. This applies to every member who launches conversations through it.
Organization ACP profiles created earlier through Agent Canvas or the API appear as read-only rows. You can delete them, but the editor does not open them.

Real-World Scenarios

Organization Profile: Standard Code Reviewer

A platform team wants every PR review in the organization to follow the same rules.
  • Scope: Organization, so every member and every review automation gets the same setup.
  • System prompt: OpenHands default plus the team’s review guidelines.
  • Tools: A chosen list, such as terminal, file_editor, and task_tracker, with no browser.
  • Secrets: Only ORG_SONARQUBE_TOKEN, an organization-shared secret.
  • Skills: The organization’s code-style skills from the organization marketplace.

Organization Profile: Partner or API-Driven Workload

An OEM partner or an internal platform starts conversations through the API for its own end users.
  • Scope: Organization, so the behavior does not depend on any one person’s settings.
  • System prompt: A custom persona that describes the product’s assistant.
  • LLM profile: An organization LLM profile that the Admin controls and pays for.
  • Secrets: An empty or short explicit list, so the agent has only the access the workload needs.

Organization Profile: Low-Risk Issue Triage

An automation labels and comments on new issues and should not change code.
  • Scope: Organization.
  • Tools: A small chosen list without code-editing tools.
  • Sub-agents: Off, so the agent handles each issue in one conversation.
  • Secrets: None selected.

Personal Profile: Bring Your Own Coding Agent Subscription

A developer has a Claude Code or Codex subscription and wants to use it in OpenHands Enterprise.
  • Scope: Personal. ACP agents are available only in personal profiles, so one person’s subscription is not shared by the whole organization.
  • Agent: The ACP agent, with the developer’s own credentials.

Personal Profile: Scoped Personal Automation

A member wants a weekly automation that summarizes their Notion pages and nothing else.
  • Scope: Personal, because it uses the member’s own Notion MCP server.
  • MCP servers: Only the Notion server, not all personal MCP servers.
  • Secrets: Only MY_NOTION_KEY.
  • Built-in integrations: All off, so the automation cannot use the member’s GitHub or Slack access.

Combine Personal and Organization Resources

Sometimes an agent needs both your own access and your organization’s shared resources. An organization profile cannot do this, because it cannot include personal settings. Use a personal Agent Profile instead. The personal profile editor lists organization resources next to your own, so you can select from both scopes in one profile:
  • Secrets: Personal secrets and organization-shared secrets, which show an Organization badge.
  • Skills: Your user skills and skills from organization and instance marketplaces.
  • MCP servers and built-in integrations: Your own, which an organization profile cannot use.
For example, an on-call engineer creates a personal profile named incident-debugging:
  • Organization resources: The shared SHARED_DATADOG_KEY secret and the organization’s runbook skills.
  • Personal resources: Their own Linear MCP server and their GitHub integration.
  • System prompt: The OpenHands default plus “Investigate before making changes. Do not push to main.”
You also choose between overlapping credentials. If the organization shares ORG_NOTION_KEY and you have a personal MY_NOTION_KEY, select only the one the profile should use. To start from an organization profile’s setup, create a personal profile and apply the same settings, then add your personal resources.
Give personal and shared secrets different names. When both scopes contain the same name, the personal secret keeps the name and the shared secret gets a suffix, such as TEAM_TOKEN_2. See Use Shared Secrets.

Choose a Scope