Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
Namespace: microsoft.graph
Important
APIs under the /beta version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported. To determine whether an API is available in v1.0, use the Version selector.
Represents a collection of agent instances in the agentRegistry. Agent collections provide a way to organize and group related agent instances for management and organizational purposes.
Agent collections allow grouping of agent instances for organizational and access control purposes. Special collections are Global and Quarantined.
Reserved Collections
Two system-reserved collections are always available per tenant:
| Collection | ID | Purpose |
|---|---|---|
| Global | 00000000-0000-0000-0000-000000000001 |
Tenant-wide pool of generally available agents |
| Quarantined | 00000000-0000-0000-0000-000000000002 |
Holding area for blocked / review-pending agents |
Key behaviors:
- Always-present: A GET by reserved ID never returns 404 (synthetic returned if not persisted).
- Immutability: You can't UPDATE or DELETE a reserved collection, otherwise, a
403 Forbiddenerror code with the message "collectionImmutable" is returned. - Creation protections: Attempting to create a new collection whose displayName matches a reserved one returns
409 Conflicterror code.
Inherits from entity.
Methods
| Method | Return type | Description |
|---|---|---|
| List | agentCollection collection | Get a list of the agentCollection objects and their properties. |
| Create | agentCollection | Create a new agentCollection object. |
| Get | agentCollection | Read the properties and relationships of agentCollection object. |
| Update | None | Update the properties of an agentCollection object. |
| List members of agentCollection | agentInstance collection | List of agentInstance objects in the collection. |
| Add to collection | agentInstance | Add an agentInstance to the agentCollection. |
| Remove from collection | None | Remove an agentInstance object from the agentCollection. |
Properties
| Property | Type | Description |
|---|---|---|
| createdBy | String | Object ID of the user or app that created the agent instance. |
| createdDateTime | DateTimeOffset | Timestamp when agent collection was created. |
| description | String | Description / purpose of the collection. |
| displayName | String | Friendly name of the collection. |
| id | String | Unique identifier for the collection. Key. Inherited from entity. |
| lastModifiedDateTime | DateTimeOffset | Timestamp of last update. |
| managedBy | String | appId (referred to as Application (client) ID on the Microsoft Entra admin center) of the service principal managing this agent. |
| originatingStore | String | Source system/store where the collection originated. For example Copilot Studio. |
| ownerIds | String collection | List of object IDs for the owners of the agent instance. |
Relationships
| Relationship | Type | Description |
|---|---|---|
| members | agentInstance collection | List of agent instances that are members of this collection. Supports $expand. |
JSON representation
The following JSON representation shows the resource type.
{
"@odata.type": "#microsoft.graph.agentCollection",
"id": "String (identifier)",
"ownerIds": [
"String"
],
"managedBy": "String",
"originatingStore": "String",
"createdBy": "String",
"displayName": "String",
"description": "String",
"createdDateTime": "String (timestamp)",
"lastModifiedDateTime": "String (timestamp)"
}