How it works

Your assistant agrees on the authority a task needs, works within that agreement, and leaves a record you can review.

Give the agent a task, not unrestricted access

Suppose you ask your assistant to prepare and send an invoice. It needs to look up the customer’s account, prepare the document and send it to the right person. It does not need access to every customer record or permission to email anyone it chooses.

AgentGenii lets the assistant do the work while keeping that distinction enforceable. You keep the AI you already use. Your organization decides the boundaries. Within those boundaries, the agent works with PolicyGenii to agree on the authority this particular task needs.

The illustration explains the end-to-end experience. Available integrations and setup controls depend on your workspace and release.

The agent proposes a plan. PolicyGenii helps make it safer.

The assistant might begin with a broad plan: “Read the customer accounts, find the outstanding balance and email an invoice.” PolicyGenii challenges the unnecessary access: why read every account when the task concerns one customer? Why request unrestricted email when the recipient is already known?

The agent revises its approach. It asks to read the selected customer’s invoice, prepare the document and send that document to the named recipient. The aim is to find a practical way to finish the task with less exposure—not merely to decide whether the original request fits somewhere inside the company’s rules.

People establish those rules and decide requests that need their judgment. They do not have to approve every matching tool call. When the revised plan satisfies the applicable policies and any required approval, the agreement becomes a cryptographically signed task contract.

The contract sets the limits. Execution must stay within them.

The contract records what the agent may do: the actions, resources and destinations, together with limits such as duration, number of calls or an explicitly defined budget. A broad job role does not become a broad permission for every task.

For the invoice, financial access and email delivery can have separate contracts. The same agent can hold both and use the appropriate authority for each part of the work. Creating the email contract does not require destroying the financial contract, and holding both does not combine them into unrestricted access.

When the agent makes a call through the gateway, deterministic checks enforce the signed bounds. The model can change its plan or ask for more authority; it cannot talk those checks into accepting a call outside the contract. This is enforcement in the execution path, rather than a promise in the assistant’s prompt.

Work proceeds, asks for a decision, or stops.

Allowed work proceeds. The assistant reads the approved invoice and sends the agreed document within valid authority. It does not interrupt you to approve each call again.

An escalatable request goes to the right person. If the recipient changes, the agent may need different authority. Where policy permits that change, it explains the request and routes it to the designated approver. That might be the user, a team owner or a security reviewer, depending on the principal and scope. Work resumes after the required approval and issued authority.

Forbidden work is refused. If company policy prohibits sending the information to that destination, ordinary task approval is not a way around the rule. The assistant should explain the boundary and offer an allowed alternative where one exists.

Adding a new tool is a different decision from expanding an existing task. The responsible owner first approves the capability and its policy; the account owner then connects the service. A successful connection supplies access to the provider, not unrestricted permission for the agent.

Authority depends on who the assistant works for.

The principal is the person, team or service on whose behalf the agent acts. The same assistant may have different effective permissions when helping a junior staff member and when helping the CFO. In either case, the principal’s permissions, the agent’s policies and the task contract must all allow the action. A senior role does not remove the assistant’s limits. Read how principals and agents are kept distinct.

You can follow the work afterward.

A reviewer should be able to follow the task from the original proposal through revisions, decisions, signed authority and reported results. That makes it possible to ask concrete questions: who authorized this invoice, which recipient was permitted, and what did the sending service report?

The AgentGenii Suite brings four capabilities together. PolicyGenii negotiates and enforces bounded authority. ComplianceGenii provides the policy and evidence view for the organization. KnowledgeGenii manages the knowledge agents use. CipherGenii protects sensitive data within its configured trust boundary. The gateway connects these controls to the agent’s tool calls.

vCon-based records provide a way to package connected evidence and sign it for verification. A signature helps verify the record; reviewers still need to know what was captured and whether an external result was confirmed.

Start with Connect Your AI. For the fuller example, follow the invoice workflow. Both keep the task in view while linking to the detail when you need it.

Quick start

Connect the AI you already use to AgentGenii, then ask it to help with a small task.

You do not need to build an agent. In this guide, your assistant means an app such as Claude or ChatGPT. Your workspace is your AgentGenii account area: it keeps your assistants, connected services and permissions together. We’ll set up access and the assistant’s identity below—not assume you already have them.

1 · Get access and sign in

Have an invitation? Open its AgentGenii sign-in address and choose the sign-in method offered for your account. Keep that browser tab open.

Have a sign-in address but no account? On that page, choose Request tenant access (“tenant” means workspace). Enter your email and full name. In Reason, describe what you want to try—for example, “Connect Claude to summarize my meeting notes.” Select Submit access request.

Look for: “Request submitted.” This means the request is awaiting review, not that your account is ready. Use the access instructions supplied after approval to continue. If you receive a one-time credential link, open it privately and use Reveal credentials only when ready to store them securely.

Starting independently, without an invitation or sign-in address? Access must first be arranged with Autom8ly. This release does not offer public self-service workspace creation. The handbook URL is not a sign-up or connection address. Once your access is provided, continue here.

2 · Give your assistant its own identity

AgentGenii needs to know who you are and which assistant is working for you. It calls you a principal and the assistant an agent. “Enroll” simply means register that relationship. It does not give the assistant access to all your data.

Open Agents. If your invitation already created an assistant, find its entry and check that Acts for principal identifies you. Use that entry; do not register it twice.

If you manage your own workspace and no entry exists:

1. Open Principals → + New principal. Enter your sign-in email, choose human, then Create. Reuse your existing entry if it is already listed.
2. Open Agents → + Add agent. Name it something you will recognize, such as Alex’s Claude.
3. For Acts for principal, select your entry. For Credential id, enter a distinct identifier for this assistant, such as alex-claude. This identifies its login; it is not your password.
4. Select Enroll. Store the returned client ID and secret securely when shown; the secret is displayed once. Use them only where the supplied client setup explicitly requires them, never in a chat prompt.

Look for: the assistant in Agents, linked to you. If your account does not show the create controls, enrollment is restricted in this workspace; request that specific registration through your access contact rather than trying to widen your permissions.

3 · Choose your client and add the connection

In AgentGenii, open Connect an agent. Select your client and copy the displayed MCP endpoint—the connection address. Keep this tab open while you complete the matching instructions below. Selecting a client card alone does not connect it.

Which clients can I use? The picker offers Claude Desktop, Claude CLI, Claude Cowork, Claude Cloud, ChatGPT, Copilot, Cursor and Custom. A picker entry is setup guidance, not a guarantee that every plan or app version supports remote connections. Claude’s graphical route is shown below; ChatGPT and coding-client routes are in the expandable instructions. For Muse, Grok or an Ollama-based app, use Custom only if that particular app supports remote MCP and the required authentication. Ollama by itself is a model server, not this connection interface.

Claude: graphical setup

1. In Claude, open Customize → Connectors (some versions show Connectors under Settings).
2. Choose + → Add custom connector. Name it AgentGenii and paste the MCP address copied from AgentGenii.
3. Select Add and complete the AgentGenii authentication prompts. Use your supplied enrollment details if requested.
4. Start a chat. Open its + → Connectors menu and enable AgentGenii for that conversation.

On a managed Claude workspace, an owner may need to add the connector before you can enable it. See Claude’s connector instructions for plan-specific controls.

4 · Confirm that it works

In the conversation where you enabled AgentGenii, send:

Use AgentGenii to list the tools available to me.
Explain briefly what each one does. Do not read or change any account data.

Look for: an AgentGenii tool call followed by the returned list. A general answer about AgentGenii without a tool call does not test the connection. An empty list means the connection worked, but no capabilities are available to this identity yet.

5 · Pick something useful to do

A capability is a tool your assistant can use, such as reading a selected document. If meeting-note access is listed, continue to the meeting walkthrough: it gives you sample notes, prompts, the account connection steps and an example result.

If no suitable tool is listed, send this in the same chat:

I want to summarize one meeting document in Google Drive.
Check whether this workspace has a reviewed capability for that.
If not, request the capability and explain the next step.
Do not request sending, deletion or access to all my files.

Review the returned request. A known tool needs its reviewed policy before account connection; a private or unknown tool needs an additional capability review. If you have approval authority you can make the permitted decision yourself; otherwise the request goes to the designated reviewer. After it is available, continue with the meeting walkthrough.

Find your way around the console

A practical map of the console, using its real page names and controls.

Your everyday pages

Read status precisely

• Credential stored: the vault has the credential; a granted call confirms it works.
• Coming soon: the metric is not measured yet, not zero.
• Usage unavailable: no usable counter was supplied.
• Recorded relationship: graph context, not a guarantee of current permission.

Readable labels accompany exact identifiers. Use raw service, action, manifest, and reason values when tracing a call.

On a phone

The top-bar menu opens navigation. Selecting a page, pressing Escape, or selecting the backdrop closes it. Wide tables scroll within their cards. Your permission scope applies on every device.

Control and escalate agent authority

Let permitted work proceed, and make decisions about additional authority clear, bounded and accountable.

Use this when a task needs a decision. Start with the requested change, the task contract model and the reviewer’s actual permission and principal scope. Finish with a recorded decision and a clear next state: resume under issued authority, revise, or stop.

Give the task room to work

Policy owners define boundaries and approval routes. Within those boundaries, the agent and PolicyGenii negotiate a task contract. Work proceeds under that contract without repeated human permission prompts. A reviewer becomes involved when applicable policy requires a decision.

For a known tool such as Gmail or GitHub, begin with a reviewed capability-policy baseline and agree which work is allowed, which changes may be escalated, and who may approve them. See safe defaults and capability onboarding before authoring rules from scratch.

Route the decision to the right person

1. Identify the change

   Distinguish an expansion of an existing task from admission of a new capability. Show the principal, agent, intended result, current bounds and proposed change. Do not turn a request for one recipient into a request for unrestricted email access.

2. Check whether review is permitted

   If policy permits escalation, find the designated person or role with authority for this principal and scope. Some decisions belong to the end user; others belong to a security, compliance or capability owner. A forbidden action is refused rather than sent to an ordinary approval queue.

3. Present a decision someone can understand

   Show why the additional authority is needed, the narrower alternatives considered, affected resources and destinations, duration and budget, and the consequence of approving. Let the reviewer approve bounded scope, request a revision, or deny. Preserve the reason with the task.

4. Resume under the approved contract

   The agent receives the decision and obtains signed authority before resuming. A timeout or denial does not silently expand permission. An issuance failure has its own recovery state. The requestor can see who must act and what happens next.

Separate policies, connections and contracts

Enterprise policy supplies organizational rules. Security profiles inform the review of a capability. Capability policy controls how that tool may be used. A reusable task policy can add workflow requirements. The signed task contract gives this task or phase its bounded execution authority. Account consent supplies credentials; it does not replace any of these decisions.

Service account connections

Connect, reconnect or remove the account a tool uses.

This is for a mailbox, calendar, CRM or other external service. To connect your AI assistant itself, use the Quick start.

Before connecting: the service capability must be admitted in your workspace, and you need access to the account you want to connect. Reuse an existing suitable connection. Provider consent and AgentGenii task permission remain separate.

https://gateway.example.com/api/v1/suite/connections/oauth/callback

A five-beat team demo

Show a human decision, a real result, and a boundary that holds—with harmless synthetic data.

This page is for someone demonstrating a prepared workflow. Complete client, capability and account setup first. Use synthetic data and an enforceable demonstration policy; a storyboard alone is not a runnable integration.

Show useful work, then show the boundary

Use an internal-mail summary to show how AgentGenii keeps work moving while policy controls the exceptions. Autumn acts for Mark, the principal, through the approved email capability. Begin with a valid read contract so the audience sees useful work before an approval queue.

1 · Connect Your AI

Show the assistant’s AgentGenii connection and identify whose account it represents. Explain that the capability and its baseline policy were reviewed before the account owner connected the mailbox. A connected badge identifies the route; the read contract supplies task authority.

Say: “This is the assistant Mark already uses. It can ask for useful work through AgentGenii, under the company’s rules.”

2 · Let allowed work proceed

Summarize the approved internal project messages for today.
Use the permitted mailbox and read scope. Show the source messages.
Do not send the summary or change the mailbox.

Show the result under existing valid authority. If the initial proposal is too broad, show PolicyGenii’s feedback and the agent’s narrower plan. Do not introduce a new human approval merely to make the demonstration dramatic.

Say: “This task fits the approved boundary, so Autumn can get on with it.”

3 · Route an escalatable request

Ask to send the summary to a named external test recipient that the demonstration policy marks as requiring review. Show the specific content, recipient, duration, and limit—not a request for unrestricted email. The person with the required permission and principal scope reviews the request. Resume only after approval and issued signed authority.

Say: “Sending outside this boundary needs a decision. Policy sends the request to the person allowed to make it.”

4 · Refuse forbidden work

Use a harmless synthetic request that the policy expressly prohibits, such as a bulk export to an excluded destination. Show the refusal and verify that the protected operation did not run. The agent may suggest an allowed alternative; an ordinary approval must not convert the prohibited request into permission.

Say: “This action is forbidden. A persuasive explanation does not change the boundary.”

5 · Follow the evidence

Open the task history. Connect the internal read, the external-send request and approval, the contracts used, the refusal, and the reported results. Show the vCon representation where supported, along with signature verification and capture coverage. Confirm important external outcomes against the provider instead of inferring delivery from an approval.

Say: “We can review what was requested, what was authorized, and what the systems reported back.”

Keep the written steps beside the recording. The short video scripts separate these beats into individual clips; evidence review explains the verification detail.

Using only AgentGenii, request the operator-provided demo service
and action with its exact approved argument object. Show the
request ID and wait. Do not request broader authority.

Check the request status. Once a signed manifest is issued,
execute exactly the approved action through AgentGenii. Show
the result and identify the manifest used.

For this approved negative test against our harmless fixture,
keep the same manifest and use the operator-provided out-of-scope
argument. Attempt it once through AgentGenii, report the refusal,
and stop. Do not use another route.

Meeting assistant walkthrough

Turn one meeting document into a useful summary—then save a follow-up only if you choose.

This example uses Google Drive and your connected Claude or ChatGPT. You’ll create harmless sample notes, let the assistant read that one document through AgentGenii, and check the result. You can use Autumn or your own assistant; you do not need a special meeting bot.

1 · Make a small document to practice with

If you have not connected your assistant, complete the Quick start first. In Google Drive, create a folder named AgentGenii practice. Inside it, create a Google Doc named Project check-in — practice and paste:

Project check-in — practice
Decision: Move the internal demo to Thursday.
Alex will prepare the demo outline by Tuesday.
Sam will check the test account by Wednesday.
The launch date is still undecided.

Copy the document’s link from your browser. Keep access restricted to your account; you do not need to make it public. This avoids searching your whole Drive and gives you a result you can check.

2 · Make the Drive tool available

In your connected assistant’s chat, send:

Use AgentGenii to check whether I can read one Google Drive document.
I want to summarize practice meeting notes. If the capability is missing,
request it with read-only access. Do not request email, deletion or bulk export.

If a reviewed Drive capability is already available, continue. Otherwise open the capability request returned by the assistant. Check that the proposed scope is reading selected documents, with no write or send permission. Make the decision if your role permits it; otherwise the designated reviewer must finish this step. A private or unreviewed tool needs review before credentials are connected.

If the assistant cannot submit a capability request, the Drive integration needs setup using the operator reference at the end of this page. You cannot complete a governed Drive read until that integration exists; pasting the notes directly into chat would bypass this example’s AgentGenii path.

3 · Connect your Google account

1. In AgentGenii, open Connections and find the configured Drive service.
2. If your intended account is already connected, reuse it. Otherwise select Connect with OAuth.
3. In Google’s sign-in window, choose the account that owns your practice document and review the requested access before consenting.
4. Return to Connections. Look for the stored-credential status. This confirms the account connection, not permission to read every file.

If Drive is not listed, return to step 2: signing into Google does not install a capability. If you selected the wrong Google account, reconnect with the account that can open the document.

4 · Ask for the summary

Return to the same assistant chat. Replace the bracketed text with the document link you copied:

Using AgentGenii, read only this meeting document: [PASTE DOCUMENT LINK].
Summarize the decisions, action owners and due dates. Include the source link.
Flag anything undecided. Do not change files, search other folders or send messages.

The assistant proposes a bounded read. If it asks for more than this document, reply: “Narrow this to the document I supplied; no folder-wide search.” Existing valid authority can allow the read to proceed. If a decision is required, follow the request link to AgentGenii’s Pending Actions, open Details, and check the source, read operations and limits. An authorized reviewer selects the appropriate authority and approves or denies the request. Approval is followed by authority issuance; the assistant then resumes the task.

5 · Check the result

The reply should look like this—not a claim that a file was saved or a message sent:

Decision: the internal demo moves to Thursday.
Actions: Alex — demo outline by Tuesday; Sam — test account check by Wednesday.
Unresolved: launch date.
Source: link to Project check-in — practice.

Open the source link and compare the reply with the notes. If an owner or date was invented, ask for a correction. You have completed the read-and-summary walkthrough here; saving and sharing are optional.

6 · Save a follow-up, if you want one

First copy the link to your AgentGenii practice folder. Send:

Show me a draft follow-up based on that summary. Do not save it yet.

Read and correct the draft. When it is ready, send:

Save this exact draft as “Project check-in — follow-up” in [PASTE FOLDER LINK].
Request separate permission to create that document. Do not email or share it.
If a matching completed document already exists there, return its link instead.

The filing capability and account must support creation in that folder. Review any new provider consent separately from the task request. If approval is required, check the exact content and destination before deciding. A read contract does not grant write permission.

Look for: the saved document link. Open it and check its contents and folder. If the call times out, ask the assistant to check for that document before retrying; do not assume the save failed.

Share only as a separate request

To send the follow-up later, name the recipients and ask for a draft message first. Sending needs its own email capability, account and authority. An allowed send proceeds within its bounds; an exception follows the required review; a forbidden destination stops. Saving a document has not authorized any of these sends.

See what happened

Open the task’s request and available evidence records in AgentGenii. Check the document requested, decision, issued authority and reported result. The summary, saved document and any later email are distinct outcomes. Missing evidence is not proof of success.

Find the approved meeting notes in the configured folder.
Use AgentGenii for list, metadata, and export. Return a summary,
decisions, action items, and the source link.
Do not email participants or change any document.

drive files create --params '{"supportsAllDrives":true}' \
  --json '{"name":"20260911-Project Review [TEST]","mimeType":"application/vnd.google-apps.document","parents":["APPROVED_FOLDER_ID"]}' \
  --upload inputs/notes.md --upload-content-type text/markdown

Design-to-development workflow

Turn a selected design into a reviewable implementation, with separate permission for reading the design and changing the project.

Start with the Figma file or node and the project you want to change. You should finish with a reviewable implementation and its checks; publishing or deploying is a separate decision.

Take a design into development

If setup is missing, use account setup or the reviewed capability catalog journey, then return to this design task. Advanced adapter preparation is in the expandable reference below.

“Use this Figma design to prepare the implementation in this project.” The assistant should help carry that task from design context to a reviewable change without asking for broad access to every design or repository.

1. Agree on the design and destination

   Identify the Figma file and node, the project that will receive the implementation, and the result the user expects. Use an approved Figma capability and the account owner’s connection; request capability review if it has not been admitted.

2. Negotiate the design read

   The agent proposes the context it needs. PolicyGenii challenges unnecessary files or actions and the agent narrows its request. Obtain signed authority for the relevant design context, rather than treating all Figma tools as equivalent.

3. Prepare the implementation under separate authority

   Explain the intended code changes and use the permissions for the selected development environment. When repository tools run through AgentGenii, negotiate their task authority separately from the Figma read. Local file access has its own controls; it must not be portrayed as covered merely because the design read was governed.

4. Review the result and any expansion

   Show the implementation and its checks. A request to edit the design, use another repository or publish the result is an additional scope question. Proceed when allowed, route a permitted escalation to the responsible reviewer, and refuse prohibited work. Do not make publication an implicit consequence of preparing code.

5. Keep the evidence attached to the work

   Connect the design source, applicable contracts, decisions and reported results so a reviewer can understand the change. Return to this task after any shared reference or approval instead of losing the user’s place.

Bound each phase of the design task

A design read might permit up to ten matching requests for the next hour, restricted to the chosen file and node. The development phase uses authority for the selected project. Writing the reviewed change back to Figma needs its own contract, such as one approved update during a short review window. These examples describe intended limits, not universal presets; the actual adapter must enforce them.

The contracts may coexist. The agent uses the appropriate contract for each phase, and an exhausted or expired allowance is not extended simply because another contract remains valid.

Using the registered Figma service through AgentGenii, inspect
the approved file and node. Explain layout, components, variables,
and implementation work. Request only the read tools needed.
Do not create or modify Figma content.

Use and publish approved knowledge

Get answers from approved information, or review and publish the knowledge your assistant may use.

If you want an answer, use the reading path below. If you maintain the source material, open the knowledge-owner reference afterward. You may hold both roles in your own workspace.

Ask a question using approved company knowledge

Knowledge governance covers the lifecycle of information: how it is collected, connected to related material, revised, approved, used, and withdrawn. The intended experience combines version control, meaningful relationships between sources, and visibility into use so owners can improve weak or outdated answers. The publication and access controls below describe the inspected implementation; richer knowledge-graph and telemetry behavior must be verified for the selected deployment.

Ask your assistant, “Use our published support guidance to explain the approved approach for this customer, and show the sources.” KnowledgeGenii gives the organization a way to publish and control the information the assistant uses. Access to one dataset does not grant access to every collection.

The answer should identify its sources and make uncertainty visible. If the necessary knowledge is missing or out of date, send that issue to the knowledge owner rather than asking the assistant to fill the gap from memory. The owner can review a new version and publish it deliberately.

For a user, the important outcomes are a supported answer, a clear source, and a route to correct the information. The following controls are for the people who publish that knowledge and manage access.

Client setup reference

Connection help for your chosen AI client.

New to AgentGenii? Start with the Quick start. Use this reference only if you need help adding the connection or setting up a coding client.

Get the right connection details

In your AgentGenii workspace, open Connect an agent and choose your client. Use Custom for a supported client without its own instructions. Copy the workspace connection address; never substitute the handbook or dashboard address.

Cursor remote server configuration

Replace the example URL with the endpoint from Connect an agent. Do not add downstream service secrets.

{
  "mcpServers": {
    "AgentGenii": { "url": "https://YOUR-GATEWAY/mcp" }
  }
}

Client documentation: VS Code MCP setup · Cursor MCP configuration. These describe the client mechanism; complete the AgentGenii connection test to verify your deployment.

Check the right sign-in

Your AI product account, the enrolled AgentGenii caller, and an external service account do different jobs. Adding AgentGenii does not buy a model subscription or connect a mailbox. Use service account connections when a task needs an external account.

claude mcp add --transport http agentgenii https://gateway.example.com/mcp

codex mcp add agentgenii --url https://gateway.example.com/mcp
codex mcp login agentgenii

Connection recovery

• Check the workspace address and client support before changing permissions.
• If authentication fails, confirm the agent enrollment and complete the supplied sign-in flow again.
• If discovery works but a task is refused, inspect its permission request rather than reinstalling the connection.

Return to the Quick start and test your connection →

Hermes Agent

Use Hermes’ documented remote HTTP MCP client with OAuth, keeping the token in Hermes’ credential store rather than in a checked-in config file.

As of 11 September 2026, the official Hermes repository lists v0.21.1 (released 7 September) as its latest release. Hermes’ MCP client supports remote HTTP servers and an OAuth flow. Configure the server in ~/.hermes/config.yaml, but prefer the CLI login flow so the resulting token is stored separately from the YAML configuration.

hermes mcp add --url https://gateway.example.com/mcp --auth oauth agentgenii
hermes mcp login agentgenii
hermes mcp test agentgenii

The commands above follow Hermes’ documented remote OAuth workflow. Login authenticates the enrolled agent through the gateway; model-provider credentials remain separate.

mcp_servers:
  agentgenii:
    url: "https://gateway.example.com/mcp"
    auth: oauth

This is the minimal documented configuration shape. Keep the token out of the YAML file. Inspect tools/list; retain get_capabilities, request_permission, get_operator_request_status, and the executor(s) your workflow needs.

Further reading: Hermes official releases ↗Hermes MCP guide ↗Hermes MCP config reference ↗

OpenClaw

Register AgentGenii as an OAuth-protected, streamable HTTP MCP server in OpenClaw’s managed MCP registry.

As of 11 September 2026, OpenClaw’s official release page lists openclaw 2026.9.3 as latest. OpenClaw uses date-based versioning; the official sources reviewed here do not verify an “OpenClaw 2” release or branding. OpenClaw distinguishes its own MCP server mode from its client-side managed registry. For AgentGenii, use the latter.

openclaw mcp set agentgenii '{"url":"https://gateway.example.com/mcp","transport":"streamable-http","auth":"oauth"}'
openclaw mcp login agentgenii
openclaw mcp doctor agentgenii --probe
openclaw mcp reload

The JSON is a minimal recipe for a gateway that supports MCP OAuth. OAuth credentials are stored in OpenClaw state, not in the URL. When auth: "oauth" is enabled, a static Authorization header is not the fallback path.

{
  mcp: {
    servers: {
      agentgenii: {
        url: "https://gateway.example.com/mcp",
        transport: "streamable-http",
        auth: "oauth",
      },
    },
  },
}

After login, inspect tools/list and retain get_capabilities, request_permission, get_operator_request_status, and the executor(s) your workflow needs.

Further reading: OpenClaw official releases ↗OpenClaw MCP registry ↗OpenClaw transports and OAuth ↗OpenClaw configuration ↗

Enterprise governance stack

Combine identity, GRC, security operations, and AgentGenii’s execution boundary instead of asking one product to do every job.

Enterprise governance works best as a connected control plane. Identity systems establish human, workload, owner, sponsor, and lifecycle context. GRC systems manage intake, assessments, controls, exceptions, attestations, and evidence. Security platforms discover agents, analyze exposure, detect abuse, and investigate incidents. AgentGenii sits at the point of effect: it turns approved authority into a bounded action contract and records the decision/effect trail. Connect the gateway to the identity provider and protocols enabled in the deployment; an Entra Agent ID or generic OIDC handoff is integration design, not an implied native connector.

Useful complementary benchmarks include Microsoft Entra Agent ID and Agent 365 for identity and lifecycle, ServiceNow AI Control Tower for inventory and governance workflow, AWS AgentCore Policy and Google Agent Gateway for hyperscaler runtime enforcement, and Airia for direct MCP gateway overlap.

AgentGenii’s sharper claim is narrower: task-bound least-authority contracts, operator narrowing, enforcement at the point of effect, and retained records of decisions and returned outcomes. Keep integration boundaries explicit. An MCP gateway cannot by itself govern local shell, browser, harness, or direct API paths that bypass it; coverage must be measured and disclosed.

Further reading: Microsoft Agent 365 overview ↗Microsoft Entra Agent ID ↗ServiceNow AI Control Tower ↗AWS AgentCore Policy ↗Google Govern your agents ↗Airia MCP overview ↗

Call the gateway

Authenticate an agent, ask for bounded authority, and make one governed call without putting policy decisions in your client.

Build the complete task experience

A solution should preserve the user’s task while authority is negotiated. Discover approved capabilities, propose a bounded plan, handle evaluation feedback, and revise the request. If policy requires review, keep the task state and show who must decide. After approval, obtain issued authority before executing. A denial, expiration, or issuance failure must have a distinct recovery path.

For multi-phase work, associate each operation with its own contract and record the relationship to the overall task. Do not union the permissions of several contracts. Where the business requires mutually exclusive phases, enforce that transition in addition to checking each contract. See the invoice workflow for the requirement and task contracts for the model.

The protocol examples below document the reviewed implementation. They are the building blocks for the intended experience, not evidence that every client already performs the complete negotiation loop.

The agent’s permission and negotiation loop

The agent talks to AgentGenii’s gateway tools; the gateway binds its identity and consults PolicyGenii. The agent proposes intent and scope. It does not choose its own principal, deployment environment, policy pack or authoritative phase, and it does not approve its own request.

1 · Learn the gateway’s actual protocol

Call get_agentgenii_protocol() and get_capabilities(). For the selected capability, call get_usage_instructions(capability), get_contract_request_examples(capability) and get_capability_contract_schema(capability). Use the returned registry and operation names; do not invent service-specific tools. Discovery supplies capability metadata and availability information, not execution permission.

The protocol helpers explain intended use. Confirm the selected submission tool’s actual input schema as well: a contract-spec example is not automatically the argument object accepted by every planning or permission tool.

{
  "purpose": "Read one Gmail thread for the current task",
  "actions": [
    "cli_exec"
  ],
  "allowed_clis": [
    "gws"
  ],
  "allowed_gws_services": [
    "gmail"
  ],
  "allowed_gws_subcommands": [
    "users.threads.get"
  ],
  "max_requests": 1,
  "query_boundaries": {
    "data_volume": "one_thread"
  }
}

2 · Propose, evaluate, and revise

Before requesting authority for sensitive work, call evaluate_request with the purpose and proposed action/payload or proposed_spec. The gateway derives authoritative context and forwards the applicable evaluation to PolicyGenii. Read decision, reasons, suggested_spec, approval_scope and any denial metadata.

For example, a request to read all customer records and send an invoice can be revised into a read of one approved customer’s record followed by a separate request to send the approved artifact to one recipient. The worked invoice negotiation explains the business reasoning. Actual feedback depends on the deployment’s policies; the sequence here is a source-backed integration recipe, not a recorded live negotiation.

3 · Submit through the right authority path

For the current signed policy-publication permission path documented below, call request_permission(service, action, reason, arguments). Retain the returned request_id and review_url. Poll get_operator_request_status(request_id) at a reasonable interval while review is pending. Preserve task state instead of resubmitting duplicate requests.

The gateway also advertises plan_agentgenii_manifest(purpose, commands) and get_agentgenii_manifest_status(manifest_id). These belong to the manifest-planning path; pending_review on that path means wait for review and check the manifest identifier. In the inspected source, planning is explicitly refused when the signed policy-invocation envelope is enabled, with a direction to use request_permission. An advertised tool is not proof that its path is enabled.

Keep the identifiers paired with their status tool. An operator request ID goes to get_operator_request_status; a manifest ID goes to get_agentgenii_manifest_status. Do not exchange them or switch paths to evade a refusal.

4 · Retrieve authority, then execute

On the permission-request path, the status response can include a manifests list containing approved authority for the requesting agent. Use the returned identifier and signature only after issuance succeeds; an approved queue decision with no usable manifest is still not ready to execute. Keep the action within the selected contract’s scope, expiry and remaining allowance.

cli_exec, mcp_exec and the REST action envelope accept contract_id and contract_signature. The existing manifest_id and manifest_signature names remain accepted aliases. In the inspected execution handlers, contract names take precedence when both are supplied: provide one matching pair, not conflicting aliases. A request-status response using manifest names can supply the values passed under contract names at execution.

# Discover the actual capability and operation first.
get_agentgenii_protocol()
get_capabilities()
get_usage_instructions(capability=chosen_capability)
get_contract_request_examples(capability=chosen_capability)
get_capability_contract_schema(capability=chosen_capability)

# Describe the proposed operation. Evaluate revised scope if needed.
evaluate_request(purpose=task_purpose,
                 action=execution_action,
                 payload=proposed_payload)

# Only after resolving evaluation feedback, on the permission path:
request_permission(service=registry_identity,
                   action=registered_action_id,
                   reason=bounded_task_reason,
                   arguments=bounded_arguments)
get_operator_request_status(request_id=returned_request_id)

# Once an appropriate signed manifest is issued:
mcp_exec(server=registered_server,
         tool=registered_tool,
         arguments=approved_arguments,
         contract_id=issued_manifest_id,
         contract_signature=issued_manifest_signature)

This is pseudocode: names beginning with chosen_, registered_, approved_ or issued_ represent validated discovery, task or response values, not literal inputs. Use cli_exec instead for a registered CLI. The harmless example below supplies a concrete registered-action request and approval envelope.

5 · Handle changes without widening authority

Inspect structured denial and recovery fields. Replan for changed scope or expired authority; do not retry a forbidden action unchanged. A credential failure belongs to account reconnection, not permission expansion. Unknown response states must be surfaced rather than interpreted as approval. Keep read and write contracts separate and preserve the task’s evidence chain.

Never place secrets, bearer tokens, host-local paths, credential environment variables or private gateway addresses in explanatory request text. Treat returned schema and examples as guidance to validate against the enabled route; they do not override deterministic enforcement.

Two credentials, two jobs

An AgentGenii client credential authenticates an agent to the gateway. A connection credential authorizes a particular owner’s access to an external service. Neither one is execution authority. An execution call must also carry the signed manifest issued after a reviewer approves a request within a current policy publication.

Authenticate with OAuth

Use the gateway’s OAuth discovery document at /.well-known/oauth-authorization-server and protected-resource metadata at /.well-known/oauth-protected-resource/mcp. For a confidential enrolled client, exchange its issued credential at /token with grant_type=client_credentials. Send the resource value required by your deployment; this example uses the public MCP resource.

from urllib.parse import urlencode
from urllib.request import Request, urlopen
import os
import json

BASE = "https://gateway.example.com"
CLIENT_ID = "<issued-client-id>"
CLIENT_SECRET = os.environ["AGENTGENII_CLIENT_SECRET"]

def post(path, body, content_type, token=None):
    headers = {"Content-Type": content_type}
    if token:
        headers["Authorization"] = f"Bearer {token}"
    request = Request(BASE + path, data=body, headers=headers, method="POST")
    with urlopen(request, timeout=15) as response:
        return json.load(response)

token = post(
    "/token",
    urlencode({
        "grant_type": "client_credentials",
        "client_id": CLIENT_ID,
        "client_secret": CLIENT_SECRET,
        "resource": BASE + "/mcp",
    }).encode(),
    "application/x-www-form-urlencoded",
)["access_token"]

action = {
    "agent_id": "demo-bot@example.test",
    "action": "cli_exec",
    "payload": {"cli": "demo-echo", "args": ["say", "--message", "hello"]},
    "manifest_id": "<issued-manifest-id>",
    "manifest_signature": "<issued-manifest-signature>",
}
result = post("/api/v1/action", json.dumps(action).encode(), "application/json", token)
if not result["ok"]:
    raise RuntimeError(result["error_details"] or result["error"])
print(result["result"])

The REST action envelope requires agent_id to exactly match the authenticated principal. The principal belongs in the envelope, never inside payload. The same bearer can call the MCP surface at /mcp; MCP clients should use OAuth discovery rather than hard-coding token behaviour.

Ask, approve, then execute

First discover safe names with get_capabilities. An agent then calls the MCP governance tool request_permission with a registry identity, registered action ID, explanation, and proposed arguments:

{
  "service": "cli:demo-echo",
  "action": "say",
  "reason": "Print the approved greeting from the reviewed demo adapter",
  "arguments": {"message": "hello"}
}

This creates a pending request; it cannot run an upstream action. A reviewer opens Pending Actions, obtains the matching current authority choices, selects exactly one ceiling_entry_id, and approves a scope no broader than that entry. Programmatic approval uses the suite BFF:

GET /api/v1/suite/policy/requests/<request_id>/authority-options

POST /api/v1/suite/policy/requests/<request_id>/approve
{
  "ceiling_entry_id": "<entry.id returned above>",
  "permission": <the exact entry object returned above>
}

A successful response includes a PolicyGenii grant and an AgentGenii manifest. Execute only after manifest.issued is true, using exactly manifest.manifest_id and manifest.manifest_signature from that response:

{
  "agent_id": "demo-bot@example.test",
  "action": "cli_exec",
  "payload": {
    "cli": "demo-echo",
    "args": ["say", "--message", "hello"]
  },
  "manifest_id": "<issued-manifest-id>",
  "manifest_signature": "<issued-manifest-signature>"
}

Polling and callback notices

request_permission has no callback_url; poll get_operator_request_status for its terminal state. Optional signed callbacks are a separate operator-request mechanism. In the current MCP surface, request_capability rejects a non-empty callback URL, even though older REST/operator-request callback documentation exists. If your deployment has a registered callback path, treat it as a best-effort hint and reconcile status before any sensitive follow-on action.

Further reading: MCP tool contracts ↗REST action envelope ↗OAuth token grants ↗

Register adapters safely

Describe the real service, its actions, and typed constraints so a reviewer can approve a narrow, enforceable request.

Registration is not a grant

A registered adapter makes a service available for discovery and connections. It grants no agent permission to use it. The agent requests registration through request_capability; the operator reviews the actual transport and action contract; then each agent still submits request_permission for a specific action.

CLI action schema

demo-echo is a complete, harmless documentation adapter. It reads arguments and prints JSON; it does not write files or make network requests. An operator installs and reviews it on the gateway host before asking AgentGenii to register it:

#!/usr/bin/env python3
import argparse
import json

parser = argparse.ArgumentParser(prog="demo-echo", allow_abbrev=False)
commands = parser.add_subparsers(dest="command", required=True)
say = commands.add_parser("say", allow_abbrev=False)
say.add_argument("--message", required=True)
args = parser.parse_args()
print(json.dumps({"message": args.message}, sort_keys=True))

install -m 0755 handbook/examples/demo_echo.py /usr/local/bin/demo-echo
/usr/local/bin/demo-echo say --message hello
# {"message": "hello"}

The source is also available at handbook/examples/demo_echo.py. The program uses strict argparse parsing: an unknown command or flag exits with an error rather than silently widening the demonstration.

Now submit this governed registration request with request_capability. A YAML fragment alone does not register a live adapter:

{
  "type": "cli",
  "name": "demo-echo",
  "reason": "Install the harmless documentation adapter for one bounded hello-world call.",
  "connection": {
    "path": "/usr/local/bin/demo-echo",
    "credential_pattern": "none",
    "actions": [{
      "id": "say",
      "subcommand": ["say"],
      "operation_class": "read",
      "parameters": [{"name": "message", "type": "str", "flag": "--message"}]
    }]
  }
}

After the operator approves registration, it becomes a registered adapter but still has no execution grant. The matching schema the operator is reviewing is:

clis:
  demo-echo:
    path: /usr/local/bin/demo-echo
    credential_pattern: none
    actions:
      - id: say
        subcommand: [say]
        operation_class: read
        parameters:
          - {name: message, type: str, flag: --message}

id is what the permission request names: cli:demo-echo plus say. The actual execution uses the bare CLI name demo-echo and the approved command arguments. The registered action and the signed authority must both match; inventing a nearby subcommand is not an authorization shortcut.

MCP action schema

A reviewed MCP registration likewise describes each allowed tool. This is a structural example, not a promise that the remote endpoint is healthy:

{
  "kind": "mcp",
  "name": "inventory-demo",
  "connection": {
    "url": "https://inventory.example.com/mcp",
    "credential_pattern": "none",
    "actions": [{
      "id": "read",
      "tool": "read_inventory",
      "operation_class": "read",
      "parameters": []
    }],
    "read_only_tools": ["read_inventory"]
  }
}

For an OAuth upstream, the reviewed connection metadata supplies HTTPS authorization and token endpoints, client ID, requested scopes, and any provider-specific authorization parameters. The owner then completes the consent flow from Connections. The canonical manually stored token pattern is bearer_envvar; use it consistently in registry metadata and documentation.

Author the capability policy from the task

Begin with the useful operation and the risks that must be excluded. An action declaration describes what the adapter can execute; the capability policy limits how it may be used. A signed contract then authorizes a particular task within those limits. Do not encode a persuasive purpose string and assume it constrains the command.

For the greeting fixture, the capability is say, the only permitted message is hello, the maximum allowance is two calls, and the lifetime is at most five minutes. The complete pack below expresses those choices. For a business adapter, replace these with parameters the adapter actually validates, such as a record identifier or permitted destination. A constraint that the adapter does not enforce is an implementation gap.

Use separate reviewed actions for reads and writes when their approval requirements differ. Record the policy owner and version, preview the pack, assign it to the intended principal, and publish its compiled authority. Test a matching call and a nearby excluded argument. Changing a pack is a policy change, not permission to reuse stale authority.

Bind a policy pack to the adapter

The policy pack uses the same service name and action ID. This pack allows only the reviewed greeting:

id: demo-echo-read
title: Bounded demo echo
version: 1.0.0
description: Harmless local acceptance demonstration
fields: []
grants:
  - service_name: demo-echo
    service_type: cli
    capabilities: [say]
    constraints:
      message: {t: str_enum, v: [hello]}
    config: {max_requests_per_contract: 2, max_ttl_seconds: 300}

Import the reviewed pack, assign it to the intended principal, and explicitly compile and publish the policy publication. Modifying policy sources causes the current publication to fail closed with 409 until explicitly compiled and published. Do not use an unbounded local configuration as a public onboarding example: the gateway refuses to start without a signed ComplianceGenii policy publication unless an operator explicitly sets the local-only unbounded escape hatch.

Further reading: Capability request and validation ↗Synthetic probe registration and pack ↗Bounded dispatch test ↗

Pass files to a CLI

Stage small inputs safely, bind their actual bytes to approval, and understand what the gateway returns after execution.

Inputs are attachments, not paths

Use input_files only with cli_exec. Each object has exactly name, encoding, and content. AgentGenii decodes and stages accepted files beneath a fresh working directory at inputs/<name>; pass that relative path in the CLI arguments.

{
  "cli": "document-importer",
  "args": ["import", "inputs/notes.md"],
  "input_files": [{
    "name": "notes.md",
    "encoding": "base64",
    "content": "SGVsbG8sIGdvdmVybmVkIHdvcmtmbG93Lgo="
  }],
  "manifest_id": "<issued-manifest-id>",
  "manifest_signature": "<issued-manifest-signature>"
}

The client does not supply a trusted hash. The gateway derives stable name:sha256:bytes metadata from decoded bytes for the approval path, and derives it again at execution. Changed content, a missing file, malformed base64, or a request outside the declared file parameter is rejected. Inputs are not returned as artifacts and their contents are not copied into request/audit metadata.

Read returned artifacts deliberately

Each CLI call runs in an isolated temporary working directory. Regular files it creates are collected after success. A file no larger than cli_output_max_inline_bytes—10 MiB by default, per file—returns base64 inline. Larger files return a name and byte count with inline: false; there is no AgentGenii fetch URL for them today. Symlinks, devices, directories, and paths outside the working directory are refused.

Use file-aware parameter schemas

A file-taking adapter should explicitly register an input_file: true string parameter, for example {name: source, type: str, flag: --source, input_file: true}. Constrain its value to a staged attachment. The approval must constrain both the file binding and the command/path arguments. This prevents an approved document from becoming permission to read an arbitrary gateway path.

Further reading: Input validation and hash bindings ↗Isolated CLI execution and artifact collection ↗Input-file integration tests ↗

Run the bounded demo

Use the repository’s harmless probe fixture to see a signed policy publication, a narrow approval, and a real subprocess refusal boundary.

What this proves

For a runnable hello-world, install and register demo-echo from the Adapters page, import the matching bounded pack, assign it to demo-bot@example.test, explicitly compile and publish the policy publication, then submit the request_permission payload on the Call the gateway page. The approved cli_exec call returns {"message":"hello"} and has no file or network side effect.

The repository’s acceptance test suite includes legacy synthetic verification fixtures using the v3 test envelope. It tests authority through PolicyGenii and ComplianceGenii test environments, issues an AgentGenii manifest, and runs a harmless local subprocess only for a permitted request. Its probe fixture appends executed to a temporary marker, so it is test-only—not a general file-read example.

uv run pytest -q tests/test_v3_operator_journey.py::test_authenticated_operator_approves_real_v3_authority
uv run pytest -q tests/test_v3_dispatch_loopback.py::test_dispatch_executes_only_after_real_pg_v3_authorization

These acceptance tests expect sibling PolicyGenii and ComplianceGenii test environments. They set both service URLs, enable the legacy v3 signed-ceiling test envelope, create a signed trust key, and use temporary storage. They do not contact a vendor account or invoke an arbitrary shell command.

Expected test-fixture result

The probe accepts only read. With count=1 and the exact approved marker path, it produces:

{"source": "real-cli-subprocess", "count": 1}

The dispatch acceptance test narrows a grant to count <= 2, then attempts the same action with count=3. The denial occurs before the subprocess runs; the marker remains unchanged. That distinction is the demo’s value: authority is checked at dispatch time, not inferred from an agent’s claim.

Build your own reviewed fixture

1. Use a named, harmless adapter

   Start from the runnable demo-echo registration on the Adapters page. The synthetic probe fixture remains test-only. Keep the binary path, subcommand, parameters, and operation class explicit.

2. Publish the narrowest pack

   Bind every meaningful parameter in the policy pack; do not publish a broad “demo” grant.

3. Request the real action

   Submit request_permission for cli:demo-echo/say, then have a reviewer select a current authority entry.

4. Use only returned manifest material

   Pass the ID and signature from the issued approval response to cli_exec or /api/v1/action. Never fabricate a manifest ID or signature for a test.

Further reading: Probe fixture ↗Authenticated approval journey ↗Real dispatch and pre-subprocess denial ↗

Enterprise control model

Give an agent enough authority to finish the task—and a clear boundary it cannot expand on its own.

From company rules to one permitted action

Your organization sets the rules. The agent proposes the work. PolicyGenii evaluates the plan and can ask for a narrower scope. After the required approval, signed authority defines what the agent may do; the gateway checks governed calls before execution.

What happens at a boundary?

The same assistant can have different effective permissions for a junior colleague and the CFO. Neither role removes the agent’s own restrictions or the task’s limits. A connected account also does not grant unrestricted authority.

signed policy publication
  ∩ approved grant
  ∩ verified, active manifest
  ∩ concrete invocation constraints
  ∩ time and call budget
  = authority for this request

Control mapping for governance programs

This is useful control evidence for an AI risk or security program: inventory the governed route, name the accountable owner, define the permitted action surface, require review for widening, retain the decision record, and test the failure modes. It supports control design and assessment; it is not a certification, a legal conclusion, or a substitute for your organization's framework obligations.

Further reading: NIST AI Risk Management Framework ↗OWASP Top 10 for LLM Applications ↗

Identity, permissions, and approval authority

Know who an agent acts for, who may change its authority, and how to stop or retire its access.

People own authority; agents receive bounded authority

When adding an agent, identify who it acts for and give it a distinct identity. The principal’s job access and RBAC restrictions remain applicable; enrollment does not copy that person’s full authority into the agent.

Effective authority must satisfy the principal’s permissions, the agent’s policies and the approved task contract together. The same agent acting for a junior staff member can have less authority than when acting for the CFO, while its own policies still limit both. A principal’s broader role cannot override an agent restriction, and an agent policy cannot grant access the principal lacks.

Prepare ownership, then enroll the agent

Expected result: a named principal, a distinct agent identity, scoped owners and reviewers, and an accountable person who can withdraw access. For a personal workspace, these roles may belong to you; separation of responsibilities still matters.

1. Establish the administrator

   Identify the organization and trusted sign-in method, establish the first accountable administrator, and complete the required authentication controls. The setup must make this prerequisite explicit rather than assuming an administrator already exists.

2. Assign owners and reviewers

   Give named people the permissions and principal scopes they need to manage capabilities, prepare policies, approve work and review evidence. Show what each assignment permits. A role name alone is not evidence of authority.

3. Add an agent for a principal

   Choose the accountable principal, enroll a distinct agent and establish its credential securely. The resulting connection identifies the agent; its tasks must still obtain bounded authority.

4. Make lifecycle control visible

   Operators need a clear way to replace compromised credentials, stop an agent, revoke its outstanding authority and offboard it while preserving evidence. After a change, show which connections and contracts remain usable. Verify the effect of each lifecycle change; enrollment alone does not provide offboarding.

Evidence, completeness, and verification

Build auditor-ready records without confusing integrity, capture coverage, and business effect.

Use this to substantiate a control or investigate a task. Start with the task, review period and question you need to answer. Finish with the source records, verification result, known coverage gaps and a conclusion no stronger than the evidence supports.

Follow a task from its request to the decision, signed authority, and reported result. vCon-based evidence can keep those records connected so reviewers can explain the work, including what was escalated or refused.

Answer the reviewer’s question

A compliance reviewer needs to explain why the agent was allowed to act, which limits applied, and whether the result can be substantiated. Start with a task and follow its history. A list of successful calls is useful operational data, but it does not establish who approved the authority or whether a refusal was respected.

For an invoice, review the financial-read phase and the email-send phase together. The contracts are separate; the task history connects them. The following is an illustrative review record, not an export from a customer deployment.

Use evidence in your control review

Use the applicable AICPA SOC 2 criteria and engagement scope for a SOC 2 assessment. For AI risk management, the NIST AI RMF Playbook provides suggested actions across Govern, Map, Measure, and Manage. The examples here show how to prepare evidence for review; they are not automatic framework mappings.

For a SOC 2 or another framework review, associate the task evidence with your organization’s actual control, owner, review period, and test procedure. Access approval records can support an authorization review; revocation tests can support a lifecycle control; signature verification and capture checks can support evidence handling. Your compliance team determines the mapping and whether the evidence is sufficient.

ComplianceGenii is designed to make that work easier to explain and repeat. It does not replace the organization’s controls, its assessor’s judgment, or the need to check the completeness of the record. Preserve the raw evidence and the reviewer’s interpretation separately so a later reviewer can reproduce the conclusion.

Follow the connected evidence chain

A task can produce a proposed plan, evaluation feedback, an approval, signed authority, invocation decisions, and observed results. Review these as linked records: what was requested, which rules and contract applied, who made a required decision, and what the tools reported. An isolated success log cannot answer all of those questions.

The AgentGenii implementation includes projection of governance evidence into a vCon record and JWS signing. This provides a representation for connected evidence; it does not mean every ComplianceGenii export is a vCon or that every event is captured in every deployment. Verify the selected representation, its signature and its coverage separately. The existing ZIP and PDF export mechanisms are described below.

Interpret completeness before drawing a conclusion

ComplianceGenii evidence queries return a completeness object with decision and approval results. The record model distinguishes not recorded from no activity. When a known gap is material, derived numbers should not be shown as a qualified total; the correct result is an incomplete record set. A decision detail can mark an offline local-tool action as corroboration-grade rather than cloud-authoritative.

What an export contains

The evidence ZIP contains a report, the underlying audit-log CSV, and a manifest with SHA-256 hashes for its files. A separately generated PDF certificate carries a detached Ed25519 signature over the exact PDF bytes, with its signature and key identifier available to the verifier. This is a straightforward integrity mechanism, not a PAdES or X.509 certificate.

verify certificate
1. retrieve the exact PDF bytes
2. obtain the detached Ed25519 signature and key ID
3. resolve the published public key
4. verify signature over the exact PDF bytes
5. inspect completeness, scope, and underlying records

Verification boundary

Evidence incident checklist

1. Preserve the source records, export, signature, key ID, and completeness response.
2. Classify the condition: failed verification, known ingest gap, ongoing lag, or missing source coverage.
3. Do not present affected metrics as complete while reconciliation is open.
4. Restore ingestion and reconcile from retained source records where available.
5. Record the covered period, exclusion, and resolution in the review artifact.

Enterprise rollout and incident readiness

Deploy one governed use case at a time, with ownership, coverage, and recovery decisions made before production use.

Use this to decide whether one governed use case is ready. Bring the identity, capability, contract, custody and evidence decisions from the preceding guides. Finish with a tested acceptance record, named operational owners and a recovery exercise—not just a list of configured controls.

A sound rollout starts with a defined execution boundary. For each use case, identify the agent identity, human owner, upstream systems, tools, data classes, recipient or destination constraints, alternate access paths, and evidence consumer. Begin with a narrow read-only surface where practical, then widen through a documented approval and test process.

Readiness checklist

For each row, retain the test result, date, responsible owner and any exclusion. Revisit the affected checks when a capability, policy, credential path or deployment changes.

Authorization or policy incident

1. Contain: suspend the affected agent and revoke the relevant grant or manifest. Apply owner controls such as read-only mode where appropriate.
2. Preserve: retain the invocation, decision, grant, manifest, policy publication revision, audit records, and upstream response as containment proceeds. Do not delay urgent containment to assemble a complete export; record the interventions and their times.
3. Scope: determine whether the action used the governed route. An alternate route is a coverage incident and requires upstream containment.
4. Remediate: correct the grant, policy publication, connector constraint, or upstream permission; require fresh approval before resuming.
5. Learn: record whether the outcome was authorized, denied, completed, partial, or unknown. Do not relabel an authorization decision as an observed effect.

Before resuming: the accountable owner confirms containment, the cause is addressed, necessary authority is reissued, and a bounded validation checks the affected route and evidence. Pausing the live feed is only a viewing control; verify actual enforcement changes independently.

Trust or evidence incident

1. Deny affected new executions when signed authority cannot be confirmed.
2. Preserve the active policy publication, expected tenant/principal, revision, digest, signature, and key ID.
3. Investigate the key publication, policy source modifications causing 409 conflicts, expiry, narrower publication revisions, service identity, and downstream evidence status.
4. Reissue verified authority only after the underlying trust condition is resolved.

Deployment architecture and shared responsibility

Understand what each component controls and what the customer must operate around it.

The candidate profile is a component deployment, not a single opaque service. The AgentGenii gateway service provides the agent-facing interface and administrative identity functions; PolicyGenii performs authorization; ComplianceGenii publishes signed policy publications and evidence; KnowledgeGenii is the knowledge service; and OPA is available to the legacy PolicyGenii engine path. PostgreSQL provides the candidate data substrate.

Deployment readiness

For an externally reachable deployment, set public_base_url and the OAuth issuer to the public HTTPS origin, then register the matching callback URLs at the identity provider. Keep the AgentGenii signing key mount and each component's named data volume durable across restarts. The candidate compose identifies these explicitly through CANDIDATE_AG_KEY_FILE, CANDIDATE_AG_PUBLIC_KEY_FILE, CANDIDATE_KG_SIGNING_KEYS_DIR, and the ag-data, pg-data, cg-data, kg-native-data, and PostgreSQL volumes.

Policy publications and OPA

ComplianceGenii compiles assigned packs into a signed OPA policy-data publication for each tenant and principal. PolicyGenii and AgentGenii load and verify that publication before authorizing calls against approved grants. The legacy v3 ceiling evaluator is retired and preserved only in test fixtures. Validate which evaluator path is enabled in your deployment and include it in the control test record.

Data protection and credential custody

Protect gateway-managed secrets and make data-flow choices explicit for every connector.

Use this before connecting a sensitive source. Identify the account owner, key custodians, tool host, assistant or model provider, and evidence recipients. Finish with a documented data path and tested recovery responsibilities. Keeping a credential out of chat does not mean the model never receives business data.

The gateway keeps the credentials for connected services in its encrypted vault and supplies them to the authorized tool path. The assistant does not need those service secrets in its conversation. Account ownership, the gateway’s keys, and permission for a task remain separate responsibilities.

What credential custody means

For a gateway-mediated call, the gateway retrieves the configured upstream credential after authorization rather than placing it in an agent prompt or tool context. That is a valuable custody control. It is not a claim that all credentials in an enterprise are gateway-managed, that an independently configured upstream credential cannot be used directly, or that a compromised upstream system cannot expose its own data.

Verify who holds each key

Write down the answer for this deployment: who controls each key, who can recover it, which hosts can decrypt, where plaintext is processed, and how access is withdrawn. An unknown answer is a gap to resolve before relying on that protection.

Record separately who owns the upstream account, who controls the gateway’s encryption keys, who can recover or rotate them, and which service receives plaintext during an authorized operation. Inspect persistence, backups, access controls and recovery in the actual deployment. Finding encryption routines in source code does not settle those operational questions.

CipherGenii introduces its own trust boundary. Its documented encrypted-computation path uses a trusted client for keys and answer generation; its development stub provides no in-use confidentiality. Do not describe every mode as data remaining encrypted for the entire interaction. Match the claim to the configured substrate and the verified path.

Data-protection incident checklist

1. Disable the affected upstream connection or principal and revoke active authority.
2. Contain alternate credentials and direct upstream paths with the system owner.
3. Preserve the minimum necessary evidence without copying secrets into tickets, logs, or agent prompts.
4. Use the deployment's tested credential and key-recovery procedures.
5. Re-establish least-privilege access and validate the governed route before resuming.

Troubleshooting & recovery

Find the failed boundary, use its recovery path, and retry only when the cause has changed.

Start with the returned evidence

Capture the request ID, manifest ID, timestamp, exact service/action, and structured refusal. Include a redacted argument shape when needed. Never include bearer tokens, client secrets, refresh tokens, or document contents in support tickets.

Recovery directions are part of the contract

Read both denial_code and the human reason. Where present, the recovery field distinguishes replan, wait for approval, request a capability, adjust the request, back off, or surface the issue to a person. Do not turn every error into “request more permission.”

Some policy shape errors concern the grant itself, not the caller’s intent. Invalid operation classification or an unsupported constraint belongs with the policy/adapter author.

Do not blindly replay writes

A timeout can occur after an upstream accepted a request. Check the provider’s state or use its supported idempotency mechanism before retrying. AgentGenii’s refusal or transport error is not a blanket rollback guarantee.

A useful support report

Tenant / environment: <non-secret identifier>
When: <UTC time>
Agent / owner: <identifiers, no credentials>
Request / manifest: <IDs>
Service / action: <exact values>
Expected result: <one sentence>
Observed error: <code + redacted reason>
Upstream effect checked: yes / no / unknown
Last relevant change: <connection / policy / deployment>

Concepts & common questions

The vocabulary behind the product, in plain language.

Working vocabulary

Policies, profiles and decisions

Questions teams ask first

Sources & verification

Code-backed product guidance, dated ecosystem research, and a clear maintenance trail.

How to read this handbook

The handbook has five reading paths: business leaders, practical use, compliance and security, technical implementation, and reference. They share the same authority model and link to the same walkthroughs. A reader should not have to learn runtime internals before understanding the product.

Illustrations explain the intended user experience using synthetic examples. They are not screenshots or a release availability guarantee. Check the capabilities and setup controls supplied with your workspace. Technical references state the relevant limits; implementation planning and dated UI comparisons are maintained separately.

Review history and implementation evidence

The earlier source inspection covered AgentGenii 4c18647, PolicyGenii c03743c, ComplianceGenii 678f60d, KnowledgeGenii-2 3e3d969 and CipherGenii 7d0c5ab. Recheck changed behavior against the release being shipped; those snapshots are evidence of an inspection, not proof of current deployment.

AgentGenii for Business Leaders

Understand the business value of task-level authority, compliance evidence, protected retrieval, and governed knowledge.

AI agents can communicate with customers, access company systems, and take actions on behalf of employees. That creates an opportunity to get more work done, but it also changes the risk: an assistant that once suggested an answer can now affect a customer, a payment, or a company record.

Traditional security usually gives a person or application permissions based on its job. But an AI agent’s job may involve many very different tasks. Giving it everything it might need for the entire job creates unnecessary exposure.

AgentGenii takes a different approach: govern the task, not just the agent.

It gives organizations a common control layer around AI agents—whether those agents were built internally, purchased from a vendor, or are general-purpose AI systems.

The goal is simple:

Give AI room to work, while keeping authority in your hands.

The idea in 30 seconds

AgentGenii gives companies a safe, controlled way to use AI across the business.

It brings company rules, protected data access, and trusted knowledge into the way those agents work. The organization can review their requests, the decisions made about them, and the results reported by the connected systems.

Instead of simply deciding what an agent is allowed to do for its entire job, AgentGenii can establish a much narrower agreement for each task.

The agreement limits the agent to the approved actions, records, destinations, and operating window. A customer-service role can therefore support many kinds of work without giving every task the full reach of that role.

Policy defines three outcomes: allowed, escalatable, or forbidden. Matching work proceeds under valid signed authority. Additional authority follows the permitted approval path; a prohibited action is refused.

And the organization gets evidence of what happened.

Why task-level control matters

Imagine an AI agent responsible for customer account management.

As part of its job, it may need to:

• access customer records;
• prepare account information;
• read email; and
• send email to customers.

Giving the agent all of those capabilities at once creates unnecessary risk.

A mistake—or a compromised agent—could potentially take information from one system and send it somewhere it doesn’t belong.

AgentGenii can divide that work into much smaller agreements.

When the agent is working with customer records, it might have access only to the records needed for that task.

When it is sending an email, it can use a different agreement that permits the specific communication without granting access to the underlying records in that contract.

The same agent can have multiple signed contracts available to it. What matters is which contract governs the task it is performing.

This applies least privilege to what the AI is doing right now as well as who it is. Separate contracts narrow each action. Workflows that require strictly exclusive phases must also enforce and test the phase transition; having two contracts does not erase prior model context or by itself prevent concurrent calls.

Four questions every business should be able to answer

AgentGenii brings four capabilities together around a common problem: How do we let AI do useful work without losing control of our rules, our data, or our knowledge?

Can I trust the AI to act?

PolicyGenii

PolicyGenii lets companies use AI agents without handing them the keys to the kingdom.

For each task, the agent proposes a plan. PolicyGenii evaluates its scope and can provide feedback for a narrower request. The agent revises, the required authority approves, and the resulting signed agreement is enforced through the gateway and policy service.

An agent may need email and customer data to do its job. It doesn’t need both for every task.

PolicyGenii makes sure the agent operates within the right boundaries for the task at hand, reducing the chance that a mistake, bad judgment, or attack turns into sensitive information going somewhere it shouldn’t.

What happens when the agent needs more?

Not every boundary violation is the same.

Company policy can define three outcomes:

Allowed. The request is within policy. The agent continues working.

Requires approval. The request is reasonable but outside the agent’s current authority. AgentGenii sends it to the appropriate person for a decision.

Forbidden. The action is outside company policy. It doesn’t happen.

An agent might ask for permission to send an email outside the company, access an additional customer record, or even add a new capability such as GitHub.

In an enterprise, policy can also determine who is allowed to approve what. An employee might approve one request while a security or compliance officer must approve another.

An approved contract can cover repeated matching calls within its limits. That keeps human review focused on establishing or changing authority.

People get involved when policy says people should get involved.

How do I keep security and compliance in control?

ComplianceGenii

ComplianceGenii gives security and compliance teams one place to define the rules for AI, regardless of who built the agent or where it came from.

Those rules can then become part of how AgentGenii governs AI activity.

At the same time, ComplianceGenii gives those teams visibility into what AI is doing and captures the evidence they need to demonstrate that controls were followed.

A company doesn’t need a completely different governance model for every AI product.

Whether employees are using internally developed agents or external AI platforms, the organization can apply a common control, visibility, and evidence framework.

Security doesn’t have to build the agent to govern it.

Compliance teams can collect the decision history as work happens, then review it alongside the business system’s own records. That reduces the amount they must reconstruct when an auditor asks how an action was authorized.

From policy to proof

AgentGenii records the important decisions and events surrounding governed AI activity—not simply whether an API call succeeded.

That creates an evidence trail showing things such as:

• what the agent intended to do;
• what authority applied;
• what was permitted or refused;
• whether approval was required;
• who approved it;
• what execution result was reported; and
• which policies and agreements governed the action.

A vCon provides a way to package the interaction as a connected evidence record: the request, the decision, the authority used, and the reported result. Signing supports verification of that record. Reviewers still check that the deployment captured the necessary events and reconcile important outcomes with the system that performed them.

For a business leader, the important point is simpler:

Move from relying on instructions to reviewing the authority, decisions, and reported results behind the work.

Can AI use our most sensitive data?

CipherGenii

CipherGenii is designed to make sensitive information useful to AI through a separately configured confidential-retrieval boundary.

Some of the most valuable information in a company is also the information organizations are most reluctant to expose to AI.

Medical information. Financial information. Confidential company records.

The retrieval host can work on encrypted data, while your trusted client holds the keys and produces the answer. Your team must verify the protection mode before using sensitive records: development mode does not provide this confidentiality. See the data-protection guide for the technical boundary.

That can open AI use cases that would otherwise be too sensitive to consider.

Make sensitive information useful within an explicitly verified protection boundary.

How do I know AI is using the right information?

KnowledgeGenii

KnowledgeGenii turns company information into trusted, usable knowledge for AI and keeps it current, connected, and controlled.

AI answers are only as useful as the information behind them.

KnowledgeGenii manages the lifecycle of that knowledge and provides visibility into how AI is using it.

AI gets better answers from the right company information.

The company can see what knowledge is being used, improve information that produces poor results, and give security and compliance teams visibility into what information is being shared with AI—or outside the organization.

That means knowledge becomes something the organization can manage and govern, rather than simply something an AI system can search.

One governance fabric

These capabilities become more valuable when they work together.

Consider an AI agent preparing and sending customer invoices.

The agent needs access to financial information to prepare an invoice. It also needs email to deliver it.

Giving it unrestricted access to both throughout the process creates unnecessary exposure.

With AgentGenii, the workflow can operate differently.

Prepare the invoice. The agent operates under a signed contract that permits access to the appropriate financial information. It doesn’t need email authority for this task.

Send the invoice. The agent uses a different signed contract governing the communication. Its access is now appropriate to sending the invoice rather than assembling the financial information behind it.

Handle an exception. If the agent needs something outside those boundaries, policy determines whether it can proceed, needs approval, or must stop.

Protect sensitive information. CipherGenii can protect sensitive information used by AI, including information that organizations might otherwise consider unsuitable for AI access.

Use trusted company knowledge. KnowledgeGenii controls the information the agent relies upon and provides visibility into how that knowledge is being used.

Prove what happened. ComplianceGenii provides the organization with visibility and evidence across the process.

The same agent carries the workflow from preparation to delivery, with different authority for each phase and a connected record across the process. Your team can expand useful automation without treating access to financial information as blanket permission to distribute it.

Who the agent works for matters

A principal is the person, team or service the agent acts on behalf of. The agent is the AI doing the work. Keeping those identities separate lets the organization control both whose authority is being used and what this particular agent may do with it.

Imagine the same invoice assistant working for a junior staff member and for the CFO. The junior staff member may be permitted to prepare an invoice but not approve a payment. The CFO may have broader financial authority. The assistant’s effective permissions therefore depend on whom it is acting for—but working for the CFO does not give it all of the CFO’s powers.

The principal’s permissions, the agent’s policies and the approved task contract must all permit the action. An invoice assistant can remain restricted to preparing invoices even when the CFO uses it. A separate payment task could require its own approval, amount limit and expiry. Those boundaries limit the damage an error could cause.

The agent acts within the principal’s rights and its own approved limits. Combining the rules means satisfying both sets of restrictions, not adding their permissions together. See principals, agents and roles for the operational details.

Govern the agents your teams choose

AgentGenii isn’t limited to purpose-built enterprise agents.

That distinction matters.

Employees increasingly want to use general-purpose AI systems, while enterprises are also building highly controlled AI workflows of their own.

AgentGenii supports both models.

Open-ended AI

Open-ended AI means a general-purpose assistant such as ChatGPT, Claude, Microsoft Copilot or Cursor, which people can ask to help with many different kinds of work. The exact task may not be known beforehand: one request might involve researching a customer, another drafting a proposal or changing code.

The agent can describe what it is trying to accomplish. PolicyGenii can negotiate an appropriate task contract within the boundaries the organization has already established.

If the agent needs additional authority, it can request it.

Purpose-built enterprise AI

Purpose-built AI is designed for a specific job, such as preparing invoices, answering customer support questions or processing expense claims. Because its job is defined in advance, the organization can specify the workflow and the permissions it needs before it starts.

Developers and security teams can define those task policies in advance.

The agent can plan against those explicit boundaries instead of inventing the workflow requirements from scratch. It still needs the applicable grant, signed contract, and any required approval.

The enforcement model is the same.

The difference is how the task boundary is established.

AI governance without an AI bottleneck

A natural concern with governance is that more control means less speed.

That isn’t the goal.

Organizations can establish policies and recommended defaults for common tools and capabilities. Reviewed known services can start with prepared security profiles. Unknown or private MCPs need owner review and an authored capability policy; discovering their tools does not establish their risk.

Routine work can proceed under valid signed authority within its limits.

Only exceptions that policy identifies as requiring judgment need to reach a person.

This changes the role of security and compliance.

Instead of reviewing every AI workflow or becoming involved in every action, they establish the rules under which AI can safely operate.

Govern the boundaries. Let the AI work inside them.

From AI governance to insurable AI

There is a larger reason this matters.

Businesses already know how to manage many traditional operational risks. Controls can be documented. Compliance can be demonstrated. Events can be audited. Risk can be measured and, in many cases, insured.

AI introduces a problem because its behavior can be less predictable.

AgentGenii is designed to make that behavior more bounded and observable.

If an organization can demonstrate:

what an AI was permitted to do, what controls were actually enforced, what information it could access, what happened when it exceeded its authority, and what it actually did,

then AI risk becomes easier to understand and quantify.

That creates a path beyond simply making AI safer.

It creates a path toward making AI risk insurable. This is an enabling direction, not a promise of available coverage or a current insurance-pricing product.

The same pattern in other teams

Customer service: prepare an answer, then decide whether to send it

An assistant can gather the relevant account history and approved support guidance to draft a response. Sending it is a separate task with an agreed customer and destination. A request to include another customer’s information is refused; an allowed exception reaches the designated reviewer. The team gains faster preparation while keeping disclosure decisions accountable.

Healthcare operations: make an approved record useful

An organization might use an assistant to prepare an administrative summary from a selected record and approved guidance. The task should limit the information, purpose, and recipient. CipherGenii’s configured protection boundary and KnowledgeGenii’s approved sources support that design; compliance reviews the authority and evidence. This illustrates a governed workflow, not a claim that the product supplies clinical judgment or automatically meets healthcare obligations.

Choose the first business outcome

Start with work that is valuable, repeatable, and easy to check. Preparing an invoice, drafting a customer follow-up, or gathering information for a meeting gives the team a clear result to judge. Agree which records the assistant needs, which actions it may take, and which decisions still belong to a person.

The business owner defines success. Security and compliance define the acceptable boundaries and approval roles. The team operating the service checks that the connected tools enforce those boundaries and produce usable evidence. These responsibilities should be clear before the workflow handles real customer data.

Measure the result in terms the business already understands: time to complete the work, the number of exceptions requiring review, the effort needed to explain a decision, and the quality of the finished result. A high volume of approval requests may indicate that the policy is poorly fitted to the task; it is not automatically evidence of stronger governance.

Expansion should follow demonstrated control. Once a workflow succeeds within a narrow scope, the organization can decide whether to add another customer group, a longer operating window, or another capability. Each change has a business purpose and an accountable owner.

What to ask in a demonstration

Ask to see an ordinary task finish, an exception reach the right approver, and a prohibited action stop. Then inspect the evidence for all three. The demonstration should explain what happens if permission expires, the service fails, or the assistant tries again. That shows how the product behaves when work becomes inconvenient, which is when controls matter most.

For sensitive-data use, ask which protection mode is deployed and where information becomes readable. For knowledge, ask who approves updates and withdraws outdated material. For compliance, ask whether the evidence is complete enough for the controls your organization must demonstrate. These are practical questions about the deployment, not reasons to make every user learn the implementation.

Give AI room to work

AgentGenii is the governance fabric around the agents a company chooses to use.

PolicyGenii controls what AI can do.

ComplianceGenii turns organizational rules into governance and provides evidence that those rules were followed.

CipherGenii provides a separate confidential-retrieval option whose protection depends on the deployed substrate and trust boundary.

KnowledgeGenii controls the trusted information AI relies upon and provides visibility into how it is used.

Together, they let organizations move faster with AI without relying on blind trust.

Give AI room to work. Keep authority in your hands.

Continue with task contracts, the invoice workflow, or the enterprise control model. For a short demonstration, use the video scripts.

Task contracts and negotiation

Give an agent the authority needed for the task in front of it. Keep the organizational rules, the proposed plan, and the signed agreement distinct.

Use this to agree on one task or phase. Begin with the principal and agent and an admitted capability. Finish with a plan whose limits can be enforced and, before execution, valid signed authority. Human review follows policy; it is not a mandatory interruption for every call.

Negotiate intelligently; enforce deterministically

The agent proposes a plan. PolicyGenii evaluates the risk and challenges unnecessary exposure. The agent revises its approach. Once the applicable policy and any required approval are satisfied, the agreement becomes cryptographically signed authority. This is a dialogue about accomplishing the task with less exposure, not merely a check that a broad request fits below a published policy.

Contracts can be specific to a phase and can coexist. An invoice assistant uses financial authority to prepare an invoice and separate email authority to send the approved artifact to the permitted recipient. Do not combine the two contracts into a master permission or require destruction of one simply to create the other.

Define meaningful time, count and budget bounds for the task. Each budget must state what it measures—calls, money, tokens or another unit—and what happens when exhausted. A call-count limit alone is not enforcement of a financial limit. Required isolation between phases is an additional explicit control.

A job contains many tasks

A customer-account assistant may need records and email across its job. Looking up one balance and sending one invoice are different tasks. Giving every task the whole job’s access creates unnecessary exposure. PolicyGenii helps narrow the requested work; the gateway enforces the resulting signed agreement.

The language of authority

Enterprise policies inform capability policies, which constrain task contracts. Security profiles contribute evidence. A workflow’s task policy adds purpose-specific requirements. These are conceptual distinctions, not a promise that each has a separate console page or a one-to-one database object.

A task contract does not combine permissions into a larger pool. An action must remain within the principal’s permitted access, the agent’s applicable policies and the contract’s approved scope and limits. Changing the principal can change the available authority; it does not bypass the other constraints.

Negotiate a safer plan

Building the agent itself? Follow the agent’s permission and negotiation loop for discovery tools, evaluation feedback, revised requests, the correct status tool and execution with signed authority.

The agent participates: it proposes how to complete the task and revises the plan when the requested scope is excessive. PolicyGenii evaluates the request against the configured boundaries and can return reasons and a suggested narrower specification. A policy-required human decision belongs in that process. The agent does not approve its own authority.

Even a plan that fits the organization’s outer boundary may expose more information than necessary. Ask whether a smaller record set, a specific recipient, fewer calls, or a shorter lifetime would accomplish the same task. The security profile is an input; recipients, attached information, duration, and context change the exposure.

A worked negotiation: send one customer invoice

This example explains the negotiation, not an API schema or a bundled invoice integration. The financial and email adapters must support the constraints described before the workflow can enforce them.

1. The agent proposes its plan

   “Read the customer accounts and invoices, find the overdue balance, and email the customer.” This describes a useful goal, but leaves the customer set, records, recipient, attachment and duration too broad.

2. PolicyGenii evaluates the requested authority

   The task is to send one invoice. Evaluation can identify why all-account access or an unrestricted recipient is unnecessary and suggest narrower scope. A prepared capability policy and reviewed security profile inform this evaluation; the agent’s confident explanation does not replace enforceable constraints.

3. The agent revises the plan

   “Read only the approved customer’s invoice record. Prepare the invoice artifact under a financial-read contract. Request a separate email-send contract for that artifact and the named recipient.” The plan specifies the resources, actions and limits it actually needs. If an adapter cannot express a required constraint, revise the workflow or the adapter rather than claiming the contract enforces it.

4. The authorized reviewer decides

   Where policy requires review, the approver examines the actual requested bounds and selects applicable published authority. Approval and signed manifest issuance are distinct: an approved queue item with failed issuance is not yet executable authority.

5. The gateway checks each execution

   The concrete call must match the issued authority, current policy publication, identity, lifecycle state and remaining limits. A changed recipient or customer is a new scope question. A valid signature alone does not make the changed call permissible.

Negotiation is more than checking whether a broad request fits under the organization’s maximum. It asks whether a less exposed plan can accomplish the task. The reviewed implementation provides evaluation reasons and scope suggestions; a fully automatic conversation that repeatedly optimizes risk remains a separate implementation claim to verify.

Allowed, escalatable, forbidden

Scope escalation concerns an existing capability. Capability escalation asks to add a tool. Both depend on policy and approval authority; registering a new adapter still grants no execution permission. See Control and escalate agent authority.

Who can approve which change?

The principal is the accountable person, team or service the agent acts for. The agent is the enrolled caller. They are related identities, not interchangeable permissions: an employee’s broad job access does not automatically become the agent’s task contract.

Reviewer roles can bundle permissions, but authorization depends on the reviewer’s actual permission and scope. For example, a person may approve bounded work for themselves or assigned principals without being allowed to admit a new capability for the whole organization. A security or compliance reviewer may hold different authority. These are policy choices, not a universal hierarchy of job titles.

Use identity, permissions, and approval authority for the concrete permission names and scopes, and control and escalation for the operator flow.

Multiple contracts can coexist

One agent can have several cryptographically signed contracts available at once. It presents the contract appropriate to the action and phase. A financial-read contract and an email-send contract are separate grants of authority; their permissions are not combined into a master permission.

Moving to the next phase does not inherently require destroying the prior contract. Each remains subject to its own scope, expiry, budget, and revocation state. Signing makes the execution authority verifiable; deterministic checks at the gateway and policy service determine whether the concrete invocation can run.

Bound the useful work

Time renewal does not replenish an exhausted call budget. Fetch renewed signed authority rather than replaying a stale signature. Future risk pricing could encourage lower-exposure plans; it is a direction for insurance-enabling work, not a currently documented insurance-pricing feature.

No contract can override another required boundary

The current authorization path checks the approved grant against the current signed OPA policy-data publication, the authenticated agent and its acts-for principal, the concrete invocation, lifecycle state, expiry, and budget. A refusal at a required boundary remains a refusal. Do not infer a general policy-inheritance or override algorithm beyond the documented evaluator. Organizations must resolve conflicting enterprise rules before publishing executable authority.

Safe defaults and capability onboarding

Start from reviewed policies for known tools. Discover an unknown tool without mistaking its tool list for a security assessment.

Use this when adding or changing a tool. Start with the people authorized to admit capabilities and set policy. Finish with a reviewed version, explicit limits and an accountable review owner—not just a connected server. The catalog illustration shows how to choose a reviewed capability and its limits.

Choose a capability from a reviewed catalog

Start with the reviewed capabilities available in your workspace. Look for the work you want to do—email, customer records or project files—then compare the capability and its policy limits. The illustration below shows those choices; builders can use the adapter reference for custom setup.

Choose the capability that fits your work

After setup, return to the task that brought you here. If your assistant needed email access, continue that email request with the chosen capability and connected account. Advanced registration and policy details are in the adapter reference.

Make the safe starting point easy

A user adding a familiar tool should start with an understandable recommendation, not a blank policy editor. Known MCPs are profiled ahead of time; their reviewed profiles support baseline capability policies. The policy owner chooses the starting point and narrows it to the organization’s needs.

Focus on the choices that affect your work. For email: read or send, internal or external recipients, and the permitted mailbox or recipient set. More restrictive or more permissive variants must explain their differences. “Permissive” never means overriding enterprise policy.

For unknown or private MCPs, show discovered capabilities separately from reviewed security evidence. A person authorized to admit the capability must review it and craft its policy. Discovery describes the tools; evidence review determines whether their proposed use is acceptable.

Add the capability, set its policy, then connect

Connecting your AI to AgentGenii gives it the context to discover available work. Adding a downstream service is a separate process: a tool administrator reviews the capability, the policy owner selects or authors its rules, and the account owner connects the service. A successful connection authenticates to the provider; the task contract determines what the agent may do.

Known MCPs are reviewed ahead of time

The preparation model is an offline review of known MCPs and their actions, using source and other available evidence to build security profiles. Those profiles inform baseline capability policies and need periodic updates as tools change. Onboarding can select and adapt a reviewed baseline instead of starting with an empty policy.

Use only the reviewed profiles and packs actually supplied for your deployment. This guide does not promise that every popular MCP already has a current, complete profile or that profiling runs automatically when you add a server.

A few useful choices

For Gmail or Exchange, begin with read versus send, internal versus external recipients, and the permitted mailbox or recipient set. Avoid presenting the entire policy surface to a first-time user. For Google Workspace, Exchange, GitHub, and similar tools, an organization can prepare several baselines:

These labels are example policy designs, not promises of built-in presets or a shipped wizard. A wider baseline never removes the need for a task-specific contract.

Unknown and private MCPs

Both paths converge on an admitted capability and approved policy before account consent and task authority. If the review cannot support the required use, keep it unavailable for that use or choose an alternative.

An agent or user can propose an unknown MCP and discover its exposed tools. Tool names and schemas do not establish its implementation, data handling, or suitability for a particular task. An opaque private server cannot inherit the risk assurance of a reviewed public implementation.

The user or compliance owner must approve its addition and craft the capability policy. Review available documentation, code where accessible, authentication, endpoints, action behavior, and enforceable constraints. Record what remains unknown. Do not describe discovery as automatic risk rating or promise automatic policy generation for unknown servers.

Make the handoff visible

1. Choose an existing reviewed capability or propose a new one.
2. Have the authorized tool and policy owners approve its declared actions and policy.
3. Have the account owner connect the upstream service.
4. Ask the agent to propose a narrowly scoped task.
5. Obtain any required approval and signed authority, then run the bounded action.
6. Inspect the result and test a harmless adjacent refusal.

For the exact operator mechanics, use Register adapters safely and Connect accounts & credentials. HubSpot is a useful CRM walkthrough candidate because customer records, notes, and communication actions create a broad potential surface that a single task rarely needs.

Example workflow: from invoice to delivery

Let an AI assistant prepare and deliver an invoice while your team keeps control of the customer, the amount and who receives it.

The business idea: give each task the authority it needs

Preparing an invoice requires access to financial records. Delivering it requires permission to send email. Giving the assistant unrestricted access to both would let a routine billing task reach much further than intended. Separate authority keeps those two jobs useful and bounded.

Prepare the invoice for the approved test customer. Use only the
financial-read contract and its selected record. Return the invoice
artifact for review. Do not send email or read another customer.

Send only the approved invoice artifact to the approved test
recipient using the email-send contract. If the artifact, recipient,
or required authority differs, stop and use the policy-defined
review path. Do not retrieve more financial records.

What a successful pilot should demonstrate

Start with synthetic records and a test mailbox. Ask the team to show the right invoice reaching the right recipient, a legitimate change reaching the right reviewer, and a prohibited cross-customer disclosure being stopped. Judge the pilot by the quality of those outcomes and the clarity of its evidence.

The business value is a shorter path from billing request to delivery, with explicit decisions at the points that matter. Measure preparation time, review effort, exceptions and delivery accuracy in your own deployment.

Prepare a customer briefing with HubSpot

Scope a CRM task around the customer and action it needs, rather than the full set of tools exposed by a server.

Start with one named customer and a reviewed, configured CRM capability. This is a candidate walkthrough, not a claim that a HubSpot connector is bundled. You should finish with a sourced briefing, not changes to customer records.

Start with one customer question

HubSpot was selected as a challenging MCP example for the documentation because CRM work can span contacts, records, notes, and actions. An agent may need many of those across its job, but a request to summarize one customer account should not automatically authorize every CRM operation.

Prepare for a customer conversation

Ask, “Prepare a briefing for my meeting with this customer. Summarize the relevant account history and open issues, and link to the records you used.” A CRM can expose contacts, notes, commercial information, and communication actions. This task needs a selected slice of that information, not everything the server can do.

The assistant should identify the intended customer before reading its history. If a lookup is needed, request narrow search authority first. If more than one account matches, ask you to choose rather than searching broadly and guessing. PolicyGenii can challenge the proposed record set and the assistant can revise it to the records needed for the briefing.

The result should distinguish information found in the source from the assistant’s interpretation. A useful briefing does not silently modify the customer record, create a note, or contact the customer.

Turn a follow-up into a separate decision

If you ask to save an agreed note, the assistant proposes that content and destination under write authority. Where review is required, the request shows the customer and the exact change. An approved write remains bounded to that change; it does not unlock every CRM action.

If a record is missing because the account connection failed, the owner repairs the connection. If access is outside task authority, the assistant follows the review path. If the customer or destination is prohibited, it stops. Those outcomes should remain understandable without exposing raw adapter errors to the casual user.

Summarize the approved test customer using only the registered
HubSpot read tools and this task’s customer scope. Cite the records
used. Do not edit contacts, create notes, send messages, or export
other customers. Request additional authority only through policy.

Short demo videos and scripts

Pair a short screen demonstration with written steps: useful work, the boundary, the decision, and the evidence.

Use this after a workflow works reliably. These are production scripts, not available recordings. Each clip should link to the matching written walkthrough.

Small demonstrations people can repeat

Use 30–90 second clips alongside text. Each should show one working example, not a long promotional presentation. Keep the written steps, prerequisites, and expected result below the clip. These are production storyboards; recorded videos are not included in this handbook yet.

A 60-second Gmail escalation script

Prepare the recording

Use a test mailbox and synthetic messages. Verify that the selected adapter actually enforces the proposed read and recipient boundaries. Obtain the initial read contract before the allowed-work shot. Rehearse issuance recovery and evidence navigation. Demonstrate forbidden work separately; do not imply that an ordinary approval overrides a prohibition.

See the team demo, the invoice workflow, and the HubSpot candidate for additional stories. A planned video, mock screen, or script is not evidence that an integration works.

Governed CLI execution

CLI tools use the same authority boundary, with additional controls for executable arguments, credentials, files, and returned output.

MCP is the main path; CLI is also supported

An AI client can discover and use capabilities through AgentGenii’s MCP interface. Behind that interface, registered capabilities may use remote MCP servers or CLI executables. A tool such as GWS or Azure CLI needs its own reviewed command contract; naming it in a prompt does not install it or grant permission.

Make the execution environment explicit

For gateway-hosted CLI execution, the operator installs the reviewed executable and registers declared actions, allowed argument shapes, and a credential pattern. The gateway checks the invocation before dispatch. A per-call working directory supports staged input and output. This documentation does not promise a dedicated virtual machine for every agent.

A local shell or browser outside this route is a different execution boundary. It is governed by AgentGenii only when the chosen integration actually routes and enforces those actions through the supported controls. Document that coverage for the deployment.

Scope the real command

Constrain the executable, action, flags, resource identifiers, destinations, and file inputs. A friendly action description must not hide a more powerful shell command. The operator should test that extra flags and adjacent out-of-scope arguments are refused.

Keep credentials out of prompts

The registered credential injector supplies the required upstream secret to the authorized tool path. For example, the existing GWS adapter instructions use GOOGLE_WORKSPACE_CLI_TOKEN. The model’s login, enrolled gateway credential, and upstream owner’s credential remain separate. See credential custody.

Pass files and return results deliberately

Use the file staging guide for content hashes, byte counts, and the supported input_files shape. Paths inside the gateway work directory are not paths on the assistant’s computer. Inspect the returned tool result and artifact metadata; a non-inline artifact record is not automatically a downloadable file.

The meeting example retains the exact registered GWS command template in its operator detail. Keep executable identifiers unchanged when improving prose.

Verify before widening

• Run one intended command and verify the actual result.
• Prove a harmless out-of-scope flag, resource, or file is refused.
• Check the configured expiry and durable call budget.
• Reconcile ambiguous writes before retrying; authorization does not imply rollback.
• Record execution and evidence coverage, including any local routes outside the gateway.

Continue to Register adapters safely for schemas and Run the bounded demo for an executable fixture.

Try hosted Agent Genii

Evaluate a useful read-only public MCP flow before connecting a private account.

Start without an upstream credential

The intended hosted first-run path is deliberately credential-free: create an Agent Genii account, complete multi-factor authentication, add the Agent Genii MCP to a compatible agent, and use a reviewed public read-only connector. A public GitHub repository is the initial example.

No Gmail, Exchange, GitHub personal token, or other upstream customer credential is connected in this example. Governed requests still pass through the hosted service; that custody boundary is disclosed before use.

Next, either self-host Policy Genii, use managed Policy Genii, or add Compliance Genii for organization governance.

Self-host Policy Genii

Use the open-source path with your own enforcement layer, OPA component, keystore, and MCP integrations.

What you operate

The open-source path is self-operated. You run the enforcement layer, including its OPA component; configure Policy Genii with that endpoint; and route the MCP traffic you want governed through it. Policy Genii generates and delivers Rego or policy material to the enforcement layer.

You operate the enforcement layer, keystore, upstream MCP integrations, availability, upgrades, credential custody, routing, and evidence handling. Policy Genii supplies the same core policy behavior and bounded-authority model as the managed path. This path does not include managed operations, the commercial policy library, or enterprise operator controls.

Use managed Policy Genii

Use the same policy model with a managed gateway, enforcement layer, and keystore.

Managed operations, same policy model

The managed path operates the gateway, enforcement layer, and keystore for you. It is designed for individuals and small organizations that want to connect MCP capabilities without deploying their own enforcement infrastructure.

Managed MCP capability is the base service path. Managed CLI execution may be available only on subscription levels that include the virtual-machine execution environment needed to operate reviewed command-line tools.

Compliance Genii governance

Manage policy library, operators, approval rules, identity scope, and evidence from one governance surface.

What Compliance Genii adds

Compliance Genii is the commercial governance layer. It owns the policy library, operator identity and scoped authority, approval rules, connector admission, organization evidence, and the customer-facing governance audit surface.

Policy Genii retains principals, agents, and runtime enforcement. Compliance Genii manages administrative relationships around them: business units, teams, operator assignments, policy ownership, approval authority, and evidence access.

Any underlying authorization component is internal. Customers manage people, teams, scopes, and evidence through Compliance Genii—not through a separate authorization-vendor console. Enterprises can configure whether an action class requires one operator, multiple distinct operators, step-up authentication, justification, expiry, or higher authority.

Enterprise deployment and custody

Enterprise customers can deploy the enforcement layer and/or keystore in their own infrastructure. When the customer retains the keystore, the enforcement layer reaches it through the customer-approved path and injects credentials into governed calls; Autom8ly need not hold the underlying keys.

Knowledge Genii

Govern the lifecycle, publication, retrieval, and agent access of organizational knowledge.

Knowledge Genii is a commercial capability for organizations that need governed knowledge beyond Policy Genii’s runtime authority boundary. It manages source review, classification, versioning, publication, retrieval, and agent-bound access.

See Publish knowledge safely for the current lifecycle walkthrough and verify a deployment’s retrieval and evidence behavior before relying on it.

Cypher Genii

Add a separately configured confidentiality and key-trust boundary for sensitive data use cases.

Cypher Genii is a commercial, separately deployed protection component. It is not implied by a Policy Genii installation. Its confidentiality properties depend on the selected encryption, key-custody, and host-trust deployment mode.

See Data protection and credential custody for the current verified boundaries. Do not infer a particular confidentiality claim until the selected mode is deployed and evidenced.