---
title: prefactor_http.endpoints.agent module
editUrl: true
head: []
template: doc
sidebar:
  hidden: false
  attrs: {}
pagefind: true
draft: false
---

# prefactor_http.endpoints.agent module

Agent endpoint client.

### *class* prefactor_http.endpoints.agent.AgentClient(http_client: [PrefactorHttpClient](prefactor_http.md#prefactor_http.PrefactorHttpClient))

Bases: `object`

Client for Agent endpoints.

Provides methods to manage agents including:
- create: Create a new agent
- get: Fetch an agent by ID
- update: Update an agent
- list: List agents
- show: Look up an agent by ID or external_identifier
- retire: Retire an agent
- reinstate: Reinstate a retired agent
- delete: Delete an agent

#### *async* create(details: [AgentForCreate](prefactor_http.models.agent.md#prefactor_http.models.agent.AgentForCreate), idempotency_key: str | None = None) → [Agent](prefactor_http.models.agent.md#prefactor_http.models.agent.Agent)

Create a new agent.

POST /api/v1/agent

* **Parameters:**
  * **details** – Agent creation parameters.
  * **idempotency_key** – Optional idempotency key.
* **Returns:**
  The created agent.
* **Raises:**
  * [**PrefactorApiError**](prefactor_http.md#prefactor_http.PrefactorApiError) – On API errors.
  * [**PrefactorValidationError**](prefactor_http.md#prefactor_http.PrefactorValidationError) – On validation errors.

#### *async* delete(agent_id: str, idempotency_key: str | None = None) → [Agent](prefactor_http.models.agent.md#prefactor_http.models.agent.Agent)

Delete an agent.

DELETE /api/v1/agent/{agent_id}

* **Parameters:**
  * **agent_id** – The agent ID to delete.
  * **idempotency_key** – Optional idempotency key.
* **Returns:**
  The deleted agent.
* **Raises:**
  * [**PrefactorNotFoundError**](prefactor_http.md#prefactor_http.PrefactorNotFoundError) – If agent not found.
  * [**PrefactorApiError**](prefactor_http.md#prefactor_http.PrefactorApiError) – On other errors.

#### *async* get(agent_id: str) → [Agent](prefactor_http.models.agent.md#prefactor_http.models.agent.Agent)

Fetch an agent by ID.

GET /api/v1/agent/{agent_id}

* **Parameters:**
  **agent_id** – The agent ID to fetch.
* **Returns:**
  The agent.
* **Raises:**
  * [**PrefactorNotFoundError**](prefactor_http.md#prefactor_http.PrefactorNotFoundError) – If agent not found.
  * [**PrefactorApiError**](prefactor_http.md#prefactor_http.PrefactorApiError) – On other errors.

#### *async* list_agents(risk_profile_id: str | None = None, team_id: str | None = None, owner_person_id: str | None = None, sorting: str | None = None, offset: int | None = None, page_size: int | None = None) → list[[AgentSummary](prefactor_http.models.agent.md#prefactor_http.models.agent.AgentSummary)]

List agents.

GET /api/v1/agent

* **Parameters:**
  * **risk_profile_id** – Filter by risk profile (null for agents with none).
  * **team_id** – Filter by team (null for agents with no team).
  * **owner_person_id** – Filter by owner (null for agents with no owner).
  * **sorting** – Sort order (e.g. `"name"` or `"-id"`).
  * **offset** – Zero-based offset for pagination.
  * **page_size** – Number of items per page (1-100).
* **Returns:**
  List of agent summaries.
* **Raises:**
  [**PrefactorApiError**](prefactor_http.md#prefactor_http.PrefactorApiError) – On API errors.

#### *async* reinstate(agent_id: str, idempotency_key: str | None = None) → [Agent](prefactor_http.models.agent.md#prefactor_http.models.agent.Agent)

Reinstate a retired agent.

POST /api/v1/agent/{agent_id}/reinstate

* **Parameters:**
  * **agent_id** – The agent ID to reinstate.
  * **idempotency_key** – Optional idempotency key.
* **Returns:**
  The updated agent.
* **Raises:**
  * [**PrefactorNotFoundError**](prefactor_http.md#prefactor_http.PrefactorNotFoundError) – If agent not found.
  * [**PrefactorApiError**](prefactor_http.md#prefactor_http.PrefactorApiError) – On other errors.

#### *async* retire(agent_id: str, idempotency_key: str | None = None) → [Agent](prefactor_http.models.agent.md#prefactor_http.models.agent.Agent)

Retire an agent.

POST /api/v1/agent/{agent_id}/retire

* **Parameters:**
  * **agent_id** – The agent ID to retire.
  * **idempotency_key** – Optional idempotency key.
* **Returns:**
  The updated agent.
* **Raises:**
  * [**PrefactorNotFoundError**](prefactor_http.md#prefactor_http.PrefactorNotFoundError) – If agent not found.
  * [**PrefactorApiError**](prefactor_http.md#prefactor_http.PrefactorApiError) – On other errors.

#### *async* show(, agent_id: str | None = None, external_identifier: str | None = None, environment_id: str | None = None, include_counts: bool = False, include_risk_rollup: bool = False) → [Agent](prefactor_http.models.agent.md#prefactor_http.models.agent.Agent)

Look up an agent by ID or external_identifier.

GET /api/v1/agent/show

Provide exactly one of `agent_id` or `external_identifier`.

* **Parameters:**
  * **agent_id** – Agent ID to look up.
  * **external_identifier** – External identifier to look up (exact match).
  * **environment_id** – Optional environment to scope risk rollup and counts.
  * **include_counts** – Include instance counts in the response.
  * **include_risk_rollup** – Include risk rollup in the response.
* **Returns:**
  The agent.
* **Raises:**
  * [**PrefactorNotFoundError**](prefactor_http.md#prefactor_http.PrefactorNotFoundError) – If agent not found.
  * [**PrefactorApiError**](prefactor_http.md#prefactor_http.PrefactorApiError) – On other errors.

#### *async* update(agent_id: str, details: [AgentForUpdate](prefactor_http.models.agent.md#prefactor_http.models.agent.AgentForUpdate), idempotency_key: str | None = None) → [Agent](prefactor_http.models.agent.md#prefactor_http.models.agent.Agent)

Update an agent.

PUT /api/v1/agent/{agent_id}

* **Parameters:**
  * **agent_id** – The agent ID to update.
  * **details** – Fields to update (only provided fields are changed).
  * **idempotency_key** – Optional idempotency key.
* **Returns:**
  The updated agent.
* **Raises:**
  * [**PrefactorNotFoundError**](prefactor_http.md#prefactor_http.PrefactorNotFoundError) – If agent not found.
  * [**PrefactorApiError**](prefactor_http.md#prefactor_http.PrefactorApiError) – On other errors.