Service Agents
Overview
A service agent brings an unattended caller under the same HYPR AgentPass™ governance as the rest of your agent traffic.
Most agents act for a person. The supervisor onboards the agent, and the gateway attributes each call to that supervisor and governs it with the supervisor's role.
Some agents have no person to act for. A scheduled automation, a batch job or a model harness in your own cloud account calls the gateway's MCP servers continuously and unattended. Nobody is available to complete a sign-in or authorize a connection.
A service agent is a first-class agent with three things of its own:
- Its own credential. A static token you issue once and configure in the calling system. There is no interactive sign-in and no browser handshake.
- Its own role. Its access comes from the role you assign to it, not from the person accountable for it.
- Its own boundary. You name the connectors it may reach, and the gateway refuses calls to anything else.
Managing service agents is an administrator task. It needs a role that can manage service agents, which only AgentPassAdmin has out of the box. See Permissions.
When to Use One
Use a service agent when a caller needs your gateway's MCP tools and no person is available to authorize it:
- A model harness in your own cloud account, such as an agent hosted on AWS Bedrock, that calls a tool server through the gateway as part of a workflow
- A scheduled job or pipeline that uses gateway tools without a human in the loop
- A system integration that must keep running when the person who set it up is on leave or changes teams
When a person is available, use the ordinary paths instead. An agent a supervisor onboards, or an MCP server a person authorizes once through the gateway's OAuth handshake, keeps a human in the loop in a way a static credential cannot. See Connecting to a Gateway MCP Connector.
How a Service Agent Differs
A service agent appears on the Cloud Agents page beside your cloud and provider-hosted agents, and its activity is recorded the same way. It differs in where its authority comes from, and in which parts of the product apply to it.
| An agent with a supervisor | A service agent | |
|---|---|---|
| How it authenticates | Onboarding, or a person's authorization | A static credential you issue |
| Whose role governs it | Its supervisor's role | Its own role |
| Connectors it may reach | Every connector its supervisor may reach | Only the connectors you name on the credential |
| Approvals and conversations | Its supervisor approves and messages it from the HYPR mobile app | Not available, because there is no person to ask |
| Assigning it to people | Available | Not available |
A service agent carries its own role, so the tools it may call follow that role, not the owner's. Set them on the Agent tools permission tab of the role you assign. See Controlling MCP Tool Access by Role.
The Accountable Owner
Every service agent names a person as its accountable owner. The owner is who you ask about the credential. The gateway records the owner as accountable for what the credential does.
The owner is not the source of the agent's access. Naming an owner does not give the service agent the owner's role, the owner's connectors, or the accounts the owner has connected to the gateway. The separation is deliberate. A credential configured in a running system should not quietly carry a person's full access, or gain access when that person is promoted.
The one exception is opt-in, per connector. You can permit a service agent to use the owner's connected account on named connectors. See Acting as the owner, and leave it empty unless a connector requires it. The opt-in applies wherever the gateway would use a person's connected account: REST API connectors, and MCP server connectors whose OAuth tokens AgentPass manages.
Choose an owner who will stay accountable for the credential, such as a team lead or a platform owner, not whoever happens to set it up. A service agent keeps working after its owner leaves your organization. Review service agent owners as part of offboarding, and reassign any that need a new one.
What Governs a Service Agent
Everything that governs the rest of your agent traffic governs a service agent too:
- Policies. The gateway identifies the service agent on every request. A policy can match it by agent and allow, block or hold its calls, as for any other agent.
- Tool access by role. The role on the credential decides which MCP tools the service agent is offered and which calls it may make.
- Connector scope. The gateway refuses a call to a connector outside the credential's scope.
- Request Log and activity. Its calls appear in the Request Log and on the agent's own Activity tab, attributed to the service agent.
- Retention. Machine traffic can be high-volume, so a service agent retains request payloads only if you turn that on. Your organization's Data Management settings govern where recorded data goes and how long it is kept.
Actions that need a person are the exception. A service agent cannot be sent to a supervisor for approval, cannot hold a conversation, and cannot use the gateway's own onboarding, approval and messaging tools. All of those need someone to answer.
Permissions
One permission controls service agents.
| Permission | What it allows |
|---|---|
| Manage service agents | Create, edit and rotate service agents, and view their credentials |
Issuing a credential is an identity decision, so this permission is deliberately narrow. AgentPassAdmin holds it. AgentPassOperator and AgentPassSupervisor do not. Without it, a person whose role can view agents still sees service agents on the Cloud Agents page. Switching a service agent on or off follows the same rule as for any agent. See Who Can Turn an Agent Off and On. Changing its stage needs permission to edit agents, as for any agent.
You can grant the permission to a custom role if your organization divides responsibility differently. Its holder chooses the role a credential carries. A role that can manage service agents can therefore issue a credential that acts with any role except AgentPassAdmin.
Related
- Creating a Service Agent — issue the credential and set its boundary
- Connecting a Service Agent — configure the credential in the calling system
- Managing Service Agent Credentials — rotate, disable and expire