# Agent Management

Capsule discovers the AI agents across your organization, shows what each one is allowed to do, and flags the risks they carry, both in how they are configured and in how they behave.

Agents come from the platforms you connect: agent builders such as Microsoft Copilot Studio, Salesforce Agentforce, and AWS Bedrock; AI assistants such as ChatGPT Enterprise and Microsoft 365 Copilot; coding agents such as Claude Code, Cursor, and GitHub Copilot; and endpoint, identity, and gateway integrations that reveal AI tools in use. See the **Integrations** section for the full list and setup steps.

## How Capsule Defines an Agent

Capsule describes every agent the same way, whether it is a coding assistant on a laptop, a Copilot Studio bot, a Bedrock agent, or a custom GPT. Each agent is defined by three things:

1. **System instructions**: what the agent is told to do.
2. **Identity**: whose identity the agent acts with.
3. **Access and permissions**: what the agent can reach.


Because the model is shared, you can compare agents across platforms side by side and apply one set of policies to all of them. How much of each part Capsule can collect depends on what the source platform exposes.

### System Instructions

Where the source platform exposes it, Capsule captures the system prompt that shapes the agent's behavior.

| Agent kind | What Capsule captures |
|  --- | --- |
| Built agents (Copilot Studio, AWS Bedrock, Azure AI Foundry, ChatGPT custom GPTs, Salesforce Agentforce, and more) | The instructions written by the agent's maker |
| Coding agents (Claude Code, Cursor, Codex, GitHub Copilot, Devin/Windsurf) | The instruction files the agent loads, such as `CLAUDE.md`, `AGENTS.md`, `.cursorrules`, and `copilot-instructions.md` |


Some sources expose no system prompt. For example, personal Microsoft 365 Copilot Chat usage carries no instructions, so instruction analysis does not apply to it.

For coding agents that keep a memory across sessions, Capsule also captures what the agent wrote for itself, shown separately from the instructions a person authored.

How instructions are used:

- **Posture**: Capsule analyzes instructions for unclear scope, goal-manipulation risk, embedded credentials, and instruction poisoning (hidden exfiltration, override, or concealment directives planted in instruction files).
- **Runtime**: instructions define the agent's intended scope. Behavior outside that scope is flagged as an intent violation, and attempts to extract the system prompt are flagged as prompt injection.


### Identity

**On behalf of a user vs. standalone.** Capsule classifies each agent by whose identity it acts with:

| Identity type | Meaning | Examples |
|  --- | --- | --- |
| **On behalf of a user** | The agent acts as the person operating it, with that person's access | Coding agents, personal ChatGPT usage, personal AWS Bedrock usage |
| **Standalone** | The agent runs autonomously under its own identity, regardless of who interacts with it | Copilot Studio agents, ChatGPT workspace GPTs, managed AWS Bedrock agents, Azure AI Foundry agents |


An on-behalf agent is bounded by its user's permissions. A standalone agent carries its own access to everyone who can reach it.

**Accessibility.** Who can use the agent:

- **Public**: Anyone, including users outside your organization
- **Tenant**: Anyone in your organization
- **Limited**: Specific people only, or a single person


**Ownership.** The owner is the person accountable for the agent. When the source platform reports one, Capsule resolves the owner to a single identity across your connected platforms. Agents with no owner are flagged so you can assign accountability.

**Agent identity.** When an agent is registered in your identity provider, such as Microsoft Entra Agent ID or Okta for AI Agents, Capsule links the agent to that identity. Each link shows how it was established:

- **Exact**: the agent's platform reported the identity's ID.
- **Display name**: the link was inferred from a unique name match.


### Access and Permissions

Capsule maps each agent to everything it is connected to:

| Resource | Examples |
|  --- | --- |
| **Knowledge sources** | SharePoint sites, file stores, web search, working directories |
| **Tools and actions** | Connectors, APIs, plugins, and skills the agent can invoke |
| **MCP servers** | Connected MCP servers and the tools each one exposes |
| **Channels** | Where people reach the agent: Microsoft Teams, Microsoft 365 Copilot, web, API |
| **Model** | The foundation model powering the agent |
| **Configured permissions** | For coding agents: allow and deny rules, sandbox settings, and which settings your organization enforces vs. the user sets |


Capsule flags risky access before anything happens, for example excessive tool permissions, over-permissioned MCP servers, privilege escalation paths, unrestricted public access, sensitive data exposed through shared agents, agents without an owner, and coding agents configured to bypass permission prompts.

At runtime, what Capsule can do depends on the integration. Integrations that hook in before a tool runs, such as Claude Code, let a policy in **Prevention** mode block the call. Other integrations report activity after it happens, so Capsule detects and alerts but cannot stop it. Each integration guide states its coverage.

### Example: A Microsoft 365 Copilot Agent

**Acme HR Policy Assistant** is built in Copilot Studio and published to Microsoft 365 Copilot and Microsoft Teams.

|  | What Capsule shows |
|  --- | --- |
| **Instructions** | "Answer employee questions using the Acme HR handbook. Never share salary data." |
| **Model** | GPT-4o |
| **Identity type** | Standalone: the agent runs as itself, not as the employee asking |
| **Agent identity** | Linked to its Microsoft Entra Agent ID (Exact) |
| **Accessibility** | Tenant |
| **Owner** | jane@acme.com |
| **Knowledge sources** | Acme HR SharePoint site, web search |
| **Tools** | Office 365 Users connector |
| **Channels** | Microsoft 365 Copilot, Microsoft Teams |


What Capsule surfaces for this agent:

- **Posture**: a tenant-wide agent grounded in HR data is a candidate for sensitive data exposure, and web search adds a path for data to leave. If the instructions are vague about what must not be disclosed, Capsule flags them as unclear.
- **Runtime**: Capsule reads the agent's conversation transcripts from Copilot Studio, so content policies such as PII and credential exposure apply to what was said.


Coverage differs for agents built with Agent Builder in Microsoft 365 Copilot. Their activity comes from Microsoft Purview audit records, which show which knowledge sources and tools an interaction used but not the message content, so content policies cannot inspect them.

When Jane uses Microsoft 365 Copilot Chat directly, Capsule tracks that as her own personal assistant, limited to her and separate from the HR agent she built.

## Finding Your Agents

Agents are listed in **Inventory**, on the **Agents** tab. Switch between **List view** and **Graph view** to see agents on their own or as a map of their connections.

| Column | What it shows |
|  --- | --- |
| Name | The agent's name |
| Platform | The integration it was discovered through |
| Risk | Highest severity of its open issues |
| Owner | The accountable person, when known |
| Identity type | On behalf or Standalone |
| Environment | Where the agent lives on its platform |
| Status | Enabled or Disabled |
| Related | Tools, knowledge sources, and channels it uses |
| Updated | When Capsule last saw a change |
| Created | When the agent was created |


- **Filter** by severity, platform, AI platform, owner (including agents with no owner), environment, date range, agent status and access, finding type, detection type, and triage status.
- **Group by** owner, severity, platform, or AI platform.
- **Export** the current query or all agents to CSV.


## Agent Details

Select an agent to open its details.

| Tab | What it contains |
|  --- | --- |
| **Overview** | Status, severity, environment, accessibility, identity type, owner, model, usage, first and last seen, and a graph of the agent's connections |
| **Configuration** | Description, system prompt, memory, linked agent identity, settings by scope (with compare for coding agents), and raw platform metadata |
| **Risk** | Posture findings and a summary of runtime violations |
| **Activity** | Sessions from the last 30 days and a timeline of activity |


Actions available on an agent:

- **Investigate**: open Observability filtered to this agent's sessions.
- **Ask**: ask Capsule's AI assistant about the agent.
- **Sync**: refresh the agent from its source platform.
- **Flag**: mark the agent for attention, with an optional reason. Flagged agents raise a finding under the default warning policy.
- **Kill**: create a Prevention policy that blocks the agent in real time.


## Risks and Violations

Capsule reports two kinds of issues:

- **Findings** (Posture): risks in how an agent is configured, such as an agent without an owner, insecure agent configuration, or excessive tool permissions.
- **Detections** (Runtime): risky behavior during a session, such as PII exposure, prompt injection, credential exposure, or dangerous actions.


When a finding or detection matches a policy, Capsule creates a **violation**.

**Severity**: Critical, High, Medium, Low.

**Status**: Active, Suppressed, Resolved. Violations list Active by default.

**Triage**: use **Set status** on one or many violations to mark them **Confirmed**, **False positive**, or **Dismissed**, with an optional reason. Confirmed and false-positive verdicts measure each policy's precision, which tells you when a policy is ready to block.

Each violation shows its evidence, timeline, related activity, and compliance mapping, with options to remediate or share.

## Policies

Policies decide what Capsule does when a finding or detection matches.

| Mode | Behavior |
|  --- | --- |
| **Draft** | Not evaluated |
| **Monitoring** | Records violations, without alerts or blocking |
| **Warning** | Records violations and sends real-time alerts to a notification channel |
| **Prevention** | Blocks the action or session in real time, on integrations that support blocking |


Policies with high precision are labeled **Prevention Ready**.

## Activity and Sessions

**Observability** shows what agents did, session by session. Filter by activity type:

- Session Started
- User Message, Agent Message, Agent Reasoning
- Tool Call, Skill Invoked
- Data Source Access, Access Channel Trigger
- Policy Evaluated, Detection Created
- System, Error


Use **Show detections only** to focus a session on the steps that raised a detection. What is recorded per session depends on the integration; some sources report only metadata, not message content.

## Best Practices

- **Assign an owner to every agent.** Unowned agents are flagged; resolve them first.
- **Prefer Limited accessibility.** Shared and public agents carry their access to everyone who can reach them, especially standalone agents.
- **Remove what agents do not use.** Unused tools, connectors, and MCP servers widen the attack surface without adding value.
- **Start policies in Monitoring.** Triage the violations, then move to Warning or Prevention once the policy is Prevention Ready.
- **Review high and critical issues first.** Triage them so policy precision reflects real risk.


## Troubleshooting

**An agent is missing**

- Check that the integration is connected and enabled in the **Integration center**.
- Confirm the integration has the permissions listed in its setup guide.
- Use **Sync** or wait for the next scheduled sync.


**Information is missing on an agent**

- Not every platform exposes every field. A missing system prompt, owner, or model usually means the source platform does not report it.
- Confirm the integration's permissions match its setup guide.