Platform hierarchy
Before you invite users or build your first AI Agent, it helps to understand how Bevaya organizes your resources. Everything in Bevaya lives inside a three-level hierarchy — organization, workspace, and AI Agent — that determines how work is grouped and who can access it.
Code
Organization
The organization is the top-level boundary for your company in Bevaya. It is the tenant boundary: all of your workspaces, AI Agents, flows, users, and configuration belong to your organization and are isolated from other customers.
Organization-level settings apply across everything beneath them. Users are members of the organization, and their access to specific workspaces and AI Agents is governed by the roles and permissions assigned to them. Environments are defined at the organization level, and enterprise identity configuration, where available, is managed there too.
Workspace
A workspace is a grouping of related AI Agents within your organization. Workspaces let you separate work along boundaries that match how your teams operate — for example, by line of business (such as underwriting versus claims), by team, or by stage of work.
Workspaces have their own members. Granting someone access to a workspace controls which AI Agents and resources they can see and work with inside it.
AI Agent
An AI Agent is the working area that contains flows and their related configuration. AI Agents are where automations are built, tested, and run. An AI Agent groups together the flows you create along with their flow-specific configuration, including variables scoped to the agent. The environments that flows run against are defined at the organization level and selected when you run or publish a flow.
Most day-to-day building and monitoring happens at the AI Agent level: you build the agent's flows, test the draft, publish it, and then monitor its runs and review items there.
How resources are grouped
The hierarchy determines where each kind of resource lives:
- Users are members of the organization. Their access to individual workspaces and AI Agents is controlled by their assigned roles and permissions. See Users and access.
- Flows define an AI Agent's behavior and belong to that agent.
- Environments are defined at the organization level and provide the runtime context used when testing, publishing, and running flows; you select an environment in the builder when you run or publish a draft. Variables are set within an environment and can be scoped more narrowly — to a workspace, AI Agent, or flow. See Configure environments and variables.
- Configuration such as connections and settings is applied at the level where it is used — organization-wide settings at the organization, and flow-specific configuration within the AI Agent.
Choosing the right workspace and AI Agent
A little planning up front keeps your hierarchy easy to navigate as you add automations:
- Use workspaces to draw broad boundaries. Group AI Agents by line of business, team, or function so the people working in one area aren't navigating unrelated work. Keep the number of workspaces small enough to stay meaningful.
- Use AI Agents to group flows that belong together. Put the flows that support a single process or use case — and the configuration they share — in the same AI Agent.
- Match access to the boundary. Because access is granted at the workspace and AI Agent level, organize resources so that giving someone access to a workspace or AI Agent grants exactly the access they need and no more.
If you are standing up Bevaya for the first time, start with one workspace per major function and one AI Agent per use case you intend to automate, then expand as your coverage grows.
Access boundaries
Access in Bevaya follows the hierarchy. Users belong to the organization, and roles and permissions determine what each user can do and which workspaces and AI Agents they can reach. This means you can give a builder access to the AI Agents they create and maintain, give a reviewer access to the work they need to review, and keep administrative control with platform administrators — all without exposing one team's work to another.
For how to invite users, assign roles, and manage access in practice, see Users and access.
Where to go next
- Users and access — invite users and assign roles and permissions.
- Build AI Agents — create your first AI Agent.
- Platform concepts — review the core vocabulary used across the docs.