Skip to main content
Hyperagent
Guides

How to run client work in Hyperagent

Workspaces, access, billing, and handover: a practical setup guide for AI agencies and consultancies.

Before client work goes live, decide who can change the agents, who pays for runs, and who maintains the setup. This guide outlines the standard operating architecture for AI agencies and automation consultancies deploying custom agent fleets for SMB clients.

Keep client work and its costs together

With Pay for all workspace usage turned on, the client pays for work in its organization's workspaces, including agency testing and automations. Your builders can keep their own agency billing arrangements for work elsewhere.


Overview and operating model

Running client work as an AI automation agency requires clear boundaries around data, liability, compute costs, and permissions. You cannot mix Client A's context, customer records, and internal prompts with Client B's. At the same time, your agency team needs central oversight to monitor agent performance, tune prompts, and jump in when an agent needs human help.

Hyperagent supports this agency workflow out of the box through Workspaces, role-based governance, workspace-owned agents, and flexible billing models.


Workspace architecture and isolation

The golden rule: one workspace per client

Always create a dedicated Workspace for each client engagement (Workspaces).

A workspace isolates resources by default:

  • Agents: Agents created in or transferred to this workspace belong to its team. (Note: A personal agent explicitly shared into the workspace remains runnable by members, but stays under its author's ownership).
  • Skills and custom tools: Reusable procedures and scripts added to the workspace stay scoped to this client.
  • Memories and knowledge: Workspace memories and agent-owned memories stay inside the workspace perimeter. (Note: An agent explicitly shared from Personal retains access to the personal memories configured by its author; keeping client agents workspace-owned prevents personal context crossover).
  • Documents and artifacts: Research reports, plans, generated tables, and files remain within the client perimeter.
  • Conversations and threads: All client runs, chat logs, and execution histories are contained in that workspace.

Operational rule

Never run multiple clients inside a single workspace. Even if you are the sole operator building prototypes, starting in a dedicated workspace prevents prompt crossover, accidental credential reuse, or contaminated memory pools.

Agency operators navigate between client accounts using the workspace switcher at the top of the sidebar.

  • Personal: Reserved for your own internal agency operations, private research, and skill prototyping.
  • Client Workspaces: Each client has its own named workspace (for example: "[Client] Acme Logistics", "[Client] Apex Dental").
  • Switching workspaces immediately re-scopes the sidebar, thread history, agent directory, and knowledge base.

Roles and access governance

Hyperagent provides three distinct workspace roles: Owner, Editor, and Member (Workspace roles). Use them to separate who administers the environment, who maintains prompts and tools, and who merely runs the agents.

Role allocation matrix

Owner

Who gets it: Agency Account Lead & Client Primary Admin.
Capabilities: Full workspace administration, member management, role assignments, read-only oversight across all member threads within that workspace, and permanent resource deletion.
Why it matters: Gives the agency lead visibility across all client runs in that workspace to debug issues and audit usage (What's private and what's shared). Does not grant access to members' Personal threads or other workspaces.

Editor

Who gets it: Agency Builders & Client Technical Co-builders.
Capabilities: Create and edit workspace agents, skills, memories, and documents.
Why it matters: Allows agency engineers to adjust system prompts, attach skills, and tune behavior without granting access to member administration or cross-thread reading.

Member

Who gets it: Client End-Users & Day-to-Day Staff.
Capabilities: Run agents, start threads, and read workspace-library documents and memories. Cannot edit agent configurations, skills, or workspace memories.
Why it matters: Crucial guardrail: Prevents clients from accidentally altering system prompts, switching models, breaking tool integrations, or deleting core skills.

Invitation strategy

  • When inviting client team members, use Email Invites rather than the reusable workspace link (Create a workspace and add people).
  • Reusable workspace links default everyone to Editor.
  • Sending individual email invites lets you explicitly select Member as the starting role, ensuring client staff can use the agents without permission to modify the underlying agent configurations.

Billing and financial architecture

Choose funding separately from workspace access. For a client-funded engagement, have the client organization's billing Owner enable Pay for all workspace usage in Organization settings → General. Work in that organization's workspaces then draws on its plan and balance, including work by agency guests. Adding a credit card or inviting someone to a workspace does not enable this coverage. See Workspace billing setup.

Who pays for which run

With Pay for all workspace usage on for the client organization:

Where the work runsBilled toSetup requirement
Client staff chat in the client workspaceClient organizationPay for all workspace usage on
Agency guest tests in the client workspaceClient organizationPay for all workspace usage on and workspace access
Workspace-owned agent's schedule or Live Mode checkClient organizationPay for all workspace usage on; existing schedule and access requirements still apply
Agency builder works in PersonalExisting personal or Shared Billing payerSeparate from client workspace funding

Keep billing membership and workspace access separate

Shared Billing covers people; the Pay for all workspace usage switch covers work in the organization's workspaces. Both use the same organization plan and balance. Turning the switch on applies across that organization's shared workspaces, not just one client engagement.

Agency builders can stay on their agency billing profile while the client pays for work done in its funded workspaces. They need workspace access to do the work, not membership in the client's billing organization. Joining the client's Shared Billing organization would also make it their default payer outside separately funded workspaces, so choose that membership separately. Being an Owner of the client workspace does not by itself give an agency lead control of the client's billing.

The switch does not transfer schedules, credentials, or agent ownership. Have a client Owner create and save production schedules so the client controls their ongoing access and operation.

When Pay for all workspace usage is off, the runner's billing arrangements apply. Scheduled runs and Live Mode checks use the schedule owner's personal or Shared Billing arrangement. Keep agency-funded prototyping costs in your project budget, and confirm workspace funding before launching client-paid work.

Setting up client billing correctly

  1. Client Setup: The client creates their Hyperagent account, signs up for a paid web plan, and creates the client workspace under their organization. Have the client do this rather than creating the workspace under your agency's organization.
  2. Enable Shared Billing: In Settings → Billing, the client's billing Owner enters an Organization name on the Shared Billing card and selects Enable Shared Billing. This moves that account's plan, payment method, and credits to the organization, with no self-serve undo. If Shared Billing is already active, manage it in Organization settings.
  3. Enable Workspace billing: In Organization settings → General, turn on Pay for all workspace usage. Refresh the page and confirm the switch stays on. Invite people into the billing organization only when their usage outside funded workspaces should also be covered.
  4. Review funding: The billing Owner checks the organization's plan, available credits, and spending controls in Settings → Billing. Its workspaces share this balance; each workspace does not get a separate allocation.
  5. Agency Role: The client invites agency personnel into the workspace as Owners or Editors. Agency staff remain on their own agency billing profile. Before launch, test a request from an agency account in the client workspace and confirm it can run using the client's plan.

Agent deployment and multi-agent architecture

Hyperagent supports two agent ownership types: Workspace-Owned and Shared Personal (Workspace agents).

Always choose workspace-owned agents for client engagements

When deploying agents for clients, always build or transfer them as Workspace-Owned:

  • Collaborative Maintenance: All agency Editors and Owners can inspect and tune the agent's system prompt, tools, context files, and model settings together.
  • Multi-Agent Delegation: Workspace-owned agents can delegate tasks to other workspace-owned agents and to agents shared with the workspace (Agent delegation). A shared personal agent cannot itself delegate work.
  • Configuration Persistence: The agent definition, prompt, model settings, and linked memories belong to the workspace. If an individual agency builder leaves your firm, the agent configuration remains intact in the workspace.
  • Schedule ownership: Pay for all workspace usage funds runs of the organization's workspace-owned agents regardless of who owns the schedule, but it does not transfer schedules or credentials. Have a client Owner create production schedules and Live Mode setups so they remain under client control when agency access ends. See Schedules.

Moving an agent from personal R&D into a client workspace

If you prototype an agent in your Personal workspace first:

  1. Open the agent's configuration and click Share....
  2. Select Transfer to a workspace (do not select "Share with a workspace", which only grants run-only access).
  3. Select the target client workspace.
  4. Review the transfer screen to confirm that associated tools, skills, and memories move cleanly into the workspace.

Managing agency templates across multiple clients

Current limit: no automated fleet sync

Hyperagent does not currently feature an automated cross-workspace template sync tool. Plan around this constraint with a master template workflow.

  1. Maintain an Agency Golden Template Base: Keep master agent configurations, prompt specifications, and toolsets in your internal agency workspace.
  2. Export and Import Configurations: Export agent configuration JSON files from your master template. When spinning up a new client engagement, import the configuration into the client's workspace.
  3. Packaging Standard Fleets: Package functional clusters (for example: Inbound Lead Triage, Meeting Prep, and Content Operations) as proven templates, then customize the final 20% (integrations and company tone) for each client.

Tooling, credentials and integrations

Client agents frequently require access to third-party services: Google Workspace, Slack, CRMs, data warehouses, and custom APIs. Hyperagent supports personal connections and, where available, workspace-owned connections. Check which kind each client agent uses before handing over the work.

1. Native integrations (OAuth and MCP)

  • Connection ownership: In Integrations, confirm whether you are managing Personal workspace or the client's workspace. Where shared connections are available, connect a client-controlled service account for that workspace.
  • OAuth identity: Personal and workspace-owned connections both authorize an account at the external service, such as Google Drive. That account and its authorization must remain valid regardless of who owns the connection in Hyperagent.
  • Unattended Run Safety: Scheduled runs and Live Mode heartbeat checks run unattended. Confirm in the schedule settings whether "Integration writes during this schedule's runs" should be enabled (read/write) or kept read-only (Schedules).
  • Membership changes: An agent can lose access to a teammate's personal connection when that teammate leaves the workspace. Workspace-owned connections are not removed when their connector leaves the Hyperagent workspace. See connection handover checks before removing a member.

2. Workspace Skills (custom scripts and API credentials)

When deploying custom scripts through Workspace Skills (Workspace skills), choose the credential mode based on who owns the tool:

  • "Use my credentials": The skill executes using the API credentials provided by the person who shared or configured the skill. Useful when the agency supplies shared utility tooling (such as a web-scraping API key or proxy). If the sharer's stored credentials are missing, the next run prompts for credentials.
  • "Each member adds their own": Each user running the skill is prompted to enter their own credentials. Essential when an agent acts on behalf of individual client staff members (such as personal calendar access or individual CRM seats).

Best practice for client work

For client infrastructure, have a client Owner authorize client-controlled service accounts and enter production API keys, using workspace-owned connections where available. Keep agency-provided utility tools under "Use my credentials". Before removing agency access, review any credentials still supplied by the agency and test the client's agents and schedules.


Knowledge curation and quality governance

One of the primary ongoing responsibilities of an automation agency is ensuring that client agents continuously improve without hallucinating or drifting from business reality (Workspace memories).

The agent learning workflow

Hyperagent agents learn continuously from interaction, but agency governance is required to maintain accuracy:

  1. Set Initial Save Destination: In the agent's Knowledge settings, configure the save destination to This agent's memories rather than the shared workspace library.
  2. Enable Suggestions: Set learning behavior to Suggested rather than Auto-saved (Manage learning behavior).
  3. The Three-Step Curation Sequence:
    • Step 1 (Review Suggestion): Agency operators open the suggestions queue in Learning to review proposed learnings surfaced from client runs.
    • Step 2 (Accept to Agent): Accept and save accurate, verified lessons. This persists the lesson as an agent-owned memory (This agent's memories), ensuring it assists that specific agent without prematurely altering shared context.
    • Step 3 (Promote to Workspace): When a saved memory represents broad company policy, brand guidelines, or shared operational rules, open that agent-owned memory and select Promote to workspace memories from its actions menu.

This three-step sequence guarantees that unvetted agent suggestions never enter the client's shared organizational truth without deliberate human approval.


Client delivery, monitoring and handoff lifecycle

Deploying client agents follows four operational phases from initial provisioning to long-term operations or eventual client handover.

Phase 1: Workspace and billing provisioning

  • The client creates a dedicated Workspace (for example, "[Client] Acme Corp").
  • The client's billing Owner enables Shared Billing in Settings → Billing, then turns on Pay for all workspace usage in Organization settings → General. Confirm the switch stays on after refreshing, then review the organization's plan and credits.
  • The client Owner invites the Agency Account Lead as an Owner via email.

Phase 2: Agent configuration and context definition

  • Agency builders import agent configurations into the client workspace as Workspace-Owned agents (Workspace agents).
  • Agency operators define multi-agent delegation paths between workspace agents (Agent delegation).
  • Essential client standard operating procedures, schemas, and brand guidelines are added as Context files.
  • Knowledge settings are configured: save destination set to This agent's memories and learning behavior set to Suggested (Workspace memories).

Phase 3: Integration binding and operational launch

  • Client native integrations (Google Workspace, Slack, CRM) are connected under client credentials.
  • A client Owner creates production schedules and Live Mode setups to keep ongoing access and operation with the client. Pay for all workspace usage covers these runs from the client's organization balance; it does not change who owns them. See Schedules.
  • Client staff are invited via email as Members to run agents without permission to edit prompts or tool configs (Workspace roles).
  • The client team is onboarded to Approvals to handle approvals, answer agent clarification questions, and view finished outputs.
  • Agency operators use Agents → Command Center to scan current work and usage attributed to them. For aggregate client-workspace costs, use Workspace settings → Usage; inspect an agent's earlier threads in Work → History.

Phase 4: Long-term retainers vs. full client handover

Operating on a retainer

The agency remains in the workspace as an Owner or Editor to maintain agent prompts, add new skills, and review suggested memories weekly. With Pay for all workspace usage on, both agency maintenance runs and client day-to-day work there draw on the client's organization balance.

Full handover audit (if the client takes over entirely)

If an agency offboards and removes its accounts, avoid assuming automatic continuity. Follow this transition checklist before stepping down:

  1. Audit Production Dependencies: Identify agency-dependent connections, skill credentials, and schedules. Move production dependencies to client-controlled accounts and test them before removing agency access.
  2. Native Integrations: Confirm that all third-party integrations (Slack, Google Drive, CRM) are authorized by an active client account.
  3. Custom Skills & API Keys: For skills set to "Use my credentials", confirm that the stored credentials belong to a client administrator account so runs do not hit a "Credentials missing" state.
  4. Scheduled Invocations: Confirm that every production schedule and Live Mode setup has a client-controlled owner, and test a run before removing agency access. Pay for all workspace usage keeps funding with the client but does not transfer an agency-owned setup. Review schedule ownership for existing schedules.
  5. Ownership Transfer: Promote a client administrator to Owner before agency accounts step down. A workspace must always have at least one active Owner (Create a workspace and add people).

Client kickoff checklist

The verified setup sequence for launching a new client engagement.

Step 1: Workspace and billing provisioning

  • Client creates a dedicated Workspace under their own organization via Sidebar → Create workspace (for example: "[Client] Acme Logistics").
  • Client's billing Owner signs up for a paid web plan and enables Shared Billing in Settings → Billing.
  • In Organization settings → General, turn on Pay for all workspace usage and refresh to confirm it stays on.
  • The billing Owner checks the organization's plan, available credits, and spending controls before launch. All its funded workspaces share that balance.
  • Client invites the Agency Account Lead as an Owner via direct email invite.

Step 2: Agency team onboarding and governance

  • Agency Account Lead accepts email invite and joins client workspace.
  • Agency Lead invites agency technical builders via email with the Editor role.
  • Verify that agency builders remain on their agency billing profile. Workspace access lets them work in the client-funded workspace without joining the client's billing organization.

Step 3: Agent deployment and multi-agent architecture

  • Import master agency agent JSON configurations into the client workspace.
  • Verify all agents are set to Workspace-Owned (not shared personal).
  • Configure delegation scopes between workspace-owned agents where needed.
  • Add client SOPs, brand guidelines, and schema definitions as Context files.

Step 4: Tools, integrations, and credentials

  • Client Owner connects client native tools (Google Workspace, Slack, CRM) under Settings → Integrations.
  • Set agency-provided utility tools to "Use my credentials".
  • Set user-specific client actions to "Each member adds their own".
  • Set unattended schedule integration write permissions (read-only vs read/write).

Step 5: Knowledge curation and quality settings

  • Configure agent memory save destination to This agent's memories.
  • Set learning behavior to Suggested (not Auto-saved).
  • Schedule weekly agency operator check-ins to review suggestions, accept verified lessons to the agent, and Promote to workspace memories for shared business rules.

Step 6: Client user onboarding and channel invocations

  • Invite client day-to-day staff via email with the Member role.
  • Connect agents to client Slack channels with clear trigger rules (for example: mentions-only).
  • Client Owner creates production schedules and Live Mode setups under their account so they remain client-controlled.
  • Test a request from an agency account in the funded client workspace before launch.
  • Onboard client team to Approvals (Sidebar → Approvals) for approvals and questions.