The AgentZ Mental Model¶

One hierarchy explains the whole platform. Learn it once and every other page in these docs falls into place.

One term needs settling

The launch plan calls the top-level container an organization. The platform's own object model calls it a tenant. This page uses tenant, because that is what the object model says, but the two must be reconciled before launch. Documentation should use one word for one thing.

The hierarchy in one diagram¶

A tenant contains workspaces. A workspace contains users, models and agents. An agent owns the workflows that run inside it, and the sandboxes those workflows execute in.

graph TD
    T["Tenant"] --> W1["Workspace<br/>Sales Ops"]
    T --> W2["Workspace<br/>AI-SOC"]

    W1 --> U["Users and roles"]
    W1 --> M["Models"]
    W1 --> A["Agent<br/>one compute allocation"]

    A --> WF["Workflows"]
    A --> SA["Sub-agents<br/>parallel fan-out"]
    A --> SB["Sandboxes<br/>Agent, Configure tab"]

    WF -.->|"shares compute, CPU throttled"| A

The one relationship worth stating twice: an agent is a compute allocation, not a separate thing that has compute. Everything an agent owns is scoped by that allocation.

Every relationship, with its cardinality¶

Relationship	Type	What it means
Tenant to Workspace	1:N	Many workspaces per tenant, commonly one per department
Workspace to Agent	1:N	A workspace owns its users, models and agents
Agent to Compute	1:1	The agent is the compute allocation, not a wrapper around one
Agent to Workflow	1:N	Workflows are owned by, and run inside, an agent
Agent to Sub-agent	1:N	A main agent fans out to sub-agents that run in parallel
Agent to Sandbox	1:N	Sandboxes are configured under Agent, on the Configure tab
Session to Workflow	N:N	Chat is global, not scoped to a single workflow
Compute to Workflow	1:N, shared	Concurrent workflows share the agent's compute. CPU throttling handles contention.

Two consequences fall out of that table.

Because compute is shared across concurrent workflows rather than reserved per workflow, a busy agent slows its own workflows down instead of failing them. Size the agent for peak concurrency, not for one run. And because a session is not tied to a workflow, chat history is not the place to look for a specific run's record. That lives in the trace.

Users and roles cutting across the tree¶

TODO: whether a role granted at tenant level applies in every workspace automatically, or is re-granted per workspace. Open question 2.

Who sees what¶

The super admin configures shared resources once. Everyone else inherits capability through a role, and never touches the underlying connector or inference-provider configuration.

graph TD
    SA["Super admin"] -->|"configures once"| SHARED["Shared resources<br/>credentials, environments, workflows"]
    SHARED -->|"inherited"| R1["Security role<br/>run, read, quarantine"]
    SHARED -->|"inherited"| R2["DevOps role<br/>deploy, rollback"]
    SHARED -->|"inherited"| R3["Data role<br/>query, export"]
    R1 --> P["People use the tools<br/>without seeing the config"]
    R2 --> P
    R3 --> P

This is the whole reason a non-technical team can use the platform. A team such as HR uses preconfigured connectors without understanding or editing the MCP configuration behind them.

The super admin configures shared resources¶

TODO: the full list of what counts as a shared resource, and where each is set.

Users inherit capability through roles¶

TODO: whether roles are fixed or custom, and who can create one.

How a single workflow uses the platform¶

A workflow draws on five things at once. Naming them in order is the fastest way to explain what AgentZ actually does.

graph TD
    TR["Trigger<br/>cron, webhook, or manual"] --> WF["Workflow"]
    WF --> SK["Skills<br/>the reusable steps"]
    SK --> AG["Agent<br/>the compute"]
    AG --> SBX["Sandbox<br/>default-deny boundary"]
    CR[("Credentials")] -.->|"injected at runtime"| SBX
    SBX --> OUT["Tool and model calls"]
    OUT --> TRACE[("Trace")]

Read it bottom to top and it is a security story: nothing reaches a tool without passing the sandbox, no credential exists inside the agent, and nothing happens without landing in the trace.