Governing AI agents, in plain language.

This guide explains how to use the Puyenpa Agent Control Plane, or ACP for short. Each chapter covers one part of the app. Read them in order, or jump to the one you need. A Glossary at the end explains the important words.

What is the ACP?

Many companies now use AI agents — software helpers that do tasks on their own, like drafting emails, raising purchase orders, or sorting support tickets. The problem is control. When many agents do real work, you need to know who runs them, what they can touch, how much they spend, and what they did.

The ACP is the single place where you watch and control every agent. Think of it as the control tower at an airport: the planes still fly themselves, but nothing takes off, lands, or changes course without the tower knowing and agreeing. It does five jobs — it registers every agent, approves them before they act, limits what they can do and spend, records everything, and can stop any or all of them instantly.

Chapter 01

Getting Started

Signing in

The ACP is private. You must sign in before you can see or do anything. Pick your name from the list, type your password, and click Sign in.

The screen layout

• The left rail is the menu. It lists every module. Number badges show when something needs attention.
• The top bar shows the module you are in, the clock, a notification bell, your name and role, and the Kill Switch.
• The main area is where the module you picked appears.

Your role

Everyone has a role. Your role decides what you can change. You can see everything, but only change what your role allows. If you try something you cannot do, the app refuses and tells you which permission you are missing — this keeps the system safe. Appendix A lists every role.

The Kill Switch

The Kill Switch is the red control in the top-right corner. When switched on, every agent is blocked at once — it is the emergency brake. Only senior officers (CEO, CIO, CISO) can use it. Use it only in a real emergency.

Chapter 02

Overview — the dashboard

The Overview is your home screen. It shows the health of the whole system at a glance. Four number tiles sit at the top:

• Agents — how many exist, are online, are waiting for approval, and are paused.
• Human queues — how many items are waiting for a person to approve.
• Active alarms — warnings not yet handled, and how many court cases are open.
• Gateway (24h) — agent actions in the last day that were allowed, sent for approval, or blocked.

Below the tiles, the live operations stream updates by itself, showing agent messages, approvals, blocks, alarms, and court decisions the moment they happen.

Chapter 03

Command Bridge

The Command Bridge is a more visual home screen — the same information as a picture. Agents appear as dots orbiting a glowing center, like planets around a sun.

• The center is the Kill Switch. Click it to stop or start the whole fleet.
• Rings show trust — inner-ring agents act more freely; the outer dashed ring holds agents not yet approved.
• A green glow means healthy and online; yellow means quiet; a red mark means the agent was punished for breaking a rule.

Down the left are the five life stages every agent passes through, with live counts. Along the bottom, the runtime loop shows which step each working agent is on: perceive, plan, act, or reflect. It is built to be shown on a big screen in an operations room.

Chapter 04

Fleet

The Fleet is the list of every governed agent — where you approve agents, set their freedom, pause them, and open their history.

Operating modes

• Observe the agent only watches and logs what it would do. It never acts. The safest place to start.
• Assist the agent proposes actions, but a person approves each one.
• Auto the agent acts on its own, as long as it stays inside the rules.

Commissioning an agent

A new agent starts as pending and cannot do anything. An authorized officer must commission it — officially approving it into service. This is the app's first rule: no agent works until a human has approved it.

Details: Dependencies and Transactions

Click Details on any agent to open its own page with two tabs. Dependencies lists everything it relies on — where it runs, which resources it may touch, which agents it may talk to, and who approves its work. Transactions is a complete history of everything that one agent has done, newest first — the best place to answer, "What has this agent been doing?"

Chapter 05

Orchestrate

Orchestrate is where agents are built and run, connected to IBM watsonx Orchestrate. It is split into tabs:

• Agents — the full catalog, each agent's model, and whether it is governed yet. Two environments: draft (testing) and live (real work).
• Build — a step-by-step wizard to create an agent without writing code. Name it, describe what it should do, pick tools, choose the model, review.
• Runs & Chat — a test bench. Message an agent and see how it responds; every run is logged.
• Tools & Toolkits — the tools agents can use, plus a registry of which agents hold each tool.
• Knowledge & Flows — the facts agents work from, and the workflows that string agents and tools together.
• Connections — links to outside apps. Passwords stay safely inside watsonx, never in the ACP.
• Channels & Embed — the ways people chat with an agent (web chat, Slack, Teams, phone).
• ADK & Deploy — for developers who prefer to build agents in code.

Chapter 06

Automations

Automations make tasks happen by themselves. Each has a trigger (what starts it) and an action (what it does).

Triggers

• Schedule — run every set number of seconds, for example every hour.
• Event — run when something happens, such as a critical alarm or a court decision.
• Webhook — run when an outside system calls a private link with a secret token.

Actions

• Run an agent — start a watsonx agent to do a task.
• Request approval — put an item in the approvals list for a person.
• Data entry — save a row of information into a dataset (Chapter 18).
• Bus broadcast — post a message to all agents on the Service Bus.

If the Kill Switch is on, automations that run agents are blocked, like everything else.

Chapter 07

Service Bus

The Service Bus is the one approved channel for all agent activity. Agents may not talk to each other, or reach company resources, in secret. Everything goes through the bus, and everything is recorded. It carries three kinds of records you can filter:

• Agent messages — one agent talking to another, or posting to a topic.
• Asset access — every time an agent reaches a resource, written here as proof, with whether it was allowed.
• Gateway — a record of each decision the rules engine made about an action.

Because every message is copied into the history and shown live, the Service Bus is your real-time window into what agents are saying and touching.

Chapter 08

Approvals

Approvals is your inbox for decisions. When an agent wants to do something that needs sign-off, it appears here as a proposal — showing which agent asked, what it wants to do, the cost, the resources, and why it needs approval. You click Approve or Reject.

Chapter 09

Assets

An asset is any resource an agent might need: a database, business system, device, network device, cloud service, software platform, or outside API. The Assets module is your full inventory. Tiles group them by type; each asset shows its sensitivity, owner, location, and status.

The Agent Access Map shows, for each agent, which resources it may use and which requests are waiting. Owners can add assets, change their status, and retire them — retiring an asset cancels its permissions.

Chapter 10

Alarms

Alarms are warnings. The ACP raises one whenever an agent breaks a rule, or tries to, and for events like the Kill Switch being used or a budget running out. Each has a severity — info warning high critical. A blinking strip appears at the top of every screen while alarms are unhandled, so you cannot miss them.

To handle one, you acknowledge it — marking it as seen and being handled. You can filter alarms to focus on one agent or one resource.

Chapter 11

Costs

Agents can spend money and use computing power. The Costs module keeps that under control. You can give each agent a budget — a spending limit. The module shows each agent's spend, budget, how full it is, and its status. Agents near their limit are flagged early.

Chapter 12

Policies

Policies are the rulebook. They decide, for every agent, what it may do, who it may talk to, where it may work, and how much it may spend. One global rulebook applies to all agents, plus optional custom rules per agent. Policies cover five areas:

• What it may do — allowed actions, and a deny list that is always blocked.
• Who it may talk to — which agents it may message and which topics it may post on.
• Where it may act — business areas, outside web addresses, and a sensitivity ceiling that blocks the most sensitive resources even with a grant.
• Transactions — a hard cost cap, an approval level, a two-person level, a daily limit, and an actions-per-hour limit.
• When — the hours the agent may act; outside them, actions go to a person.

A matrix shows the final rules for every agent side by side, and a plain list shows the exact order the engine checks things — so you always know why an action was allowed or blocked.

Chapter 13

Enforcement

Enforcement is where rule-breaking is handled. The ACP models this like a small country with laws, police, and a court — so agents are cited, judged, and sentenced in the open, with a record.

• The Constitution — eight short articles stating the core rules, such as "no agent works without approval" and "every action is recorded."
• Police — a special agent patrols constantly and writes a citation when it finds a blocked, rule-breaking action.
• Court — another special agent reviews agents that collect citations, then issues a judgement and a fitting punishment.

Punishments, lightest to heaviest: Warning (a recorded caution) · Fine (spending limits cut in half) · Probation (forced into Assist mode) · Suspension (paused) · Banishment recommended (the court flags it, but a human makes the final call). The most serious punishments always stay in human hands.

Chapter 14

Governance — evaluations

This module connects to IBM watsonx.governance. While the rest of the ACP controls what agents are allowed to do, Governance measures how well they do it — the quality and safety of their answers. It has tabs for the Platform setup, live Monitors (scores like accuracy and drift against safe limits), Records of what agents produced, Explainability (why an AI gave an answer), Risk (model risk management), and the full Metrics menu — answer quality, content safety, retrieval quality, tool-use quality, and performance.

If no watsonx.governance system is connected, this module shows realistic sample data so you can still learn your way around it.

Chapter 15

Audit

The Audit module is the permanent history book. Every important event is written here and never changed: sign-ins, agent registrations, mode changes, rule edits, every gateway decision, every approval, every alarm, every court judgement. Because nothing can be edited or deleted, it is your source of truth for "who did what, and when."

Filtering

Audit, Alarms, and the Service Bus share a filter bar with two dropdowns: by agent and by resource. Your choice follows you across all three modules, so you can trace one agent or one resource everywhere.

Chapter 16

Settings

• Integrations — the connection status for IBM watsonx and settings to embed the watsonx chat window.
• Users & Roles — every user, their role, and what each role can do. Also the Change my password form.
• Notifications — choose which alerts reach you and how (Chapter 17).
• Appearance — a dark or light look and an accent color, saved in your browser.
• Register Agent — register an agent from any provider (watsonx, OpenAI, Anthropic Claude, Palantir, Microsoft, Salesforce, your own). Registration returns a secret key; the agent still must be commissioned before it can act.

Chapter 17

Notifications

Notifications make sure the right alerts reach the right people. Each user has their own settings. You choose:

• Channels — how you are told. In-app (the bell) is always on; you can add email and a webhook (for Slack or a pager), or mute everything.
• Subscriptions — which events you want: the Kill Switch, critical alarms, approvals, resource requests, citations, court judgements, budget problems, and agent sign-ups.

A Send test notification button lets you check your settings. The bell always shows your unread count, and critical alerts also pop up briefly.

Chapter 18

Storing Agent Data

Agents often produce information — matched invoices, sorted tickets, drafted reports. The ACP gives every agent a safe place to store this, and gives operators a way to read it. Behind the scenes it uses a PostgreSQL database when one is connected, or a built-in store when one is not; either way it works the same for you.

• Datasets are named collections of records, like folders.
• Records are the individual rows agents save.
• Artifacts are larger outputs, like a full report or a file.
• Config is a set of named settings agents read and operators set.

Developers connecting their own agents can read the full technical instructions on the built-in API documentation page — open /api-docs.html in a browser for every command and copy-ready examples.

Appendix A

Roles & Permissions

Everyone has one role. The role decides what they can change; everyone can view.

A key idea is separation of duties: no single person can register, approve, empower, and excuse an agent alone. Different roles hold different keys.

Appendix B

Glossary

Appendix C

Quick Reference

• Sign-in default password — puyenpa2026 (change it right away).
• Emergency stop — the Kill Switch, top-right (senior officers only).
• Where is the history? The Audit module.
• Who approved this? Check Approvals or the agent's Transactions tab.
• An agent is misbehaving — Pause it in Fleet, or check Enforcement for its citations.
• Costs look high — the Costs module; set or lower the agent's budget.
• Technical API help — open /api-docs.html in your browser.
• Sign out — the Logout button, top-right.