prefactor_http.endpoints.agent module

prefactor_http.endpoints.agent module

Agent endpoint client.

class prefactor_http.endpoints.agent.AgentClient(http_client: 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, idempotency_key: str | None = None) → 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 – On API errors.
  • PrefactorValidationError – On validation errors.

async delete(agent_id: str, idempotency_key: str | None = None) → 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 – If agent not found.
  • PrefactorApiError – On other errors.

async get(agent_id: str) → 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 – If agent not found.
  • 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]

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 – On API errors.

async reinstate(agent_id: str, idempotency_key: str | None = None) → 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 – If agent not found.
  • PrefactorApiError – On other errors.

async retire(agent_id: str, idempotency_key: str | None = None) → 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 – If agent not found.
  • 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

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 – If agent not found.
  • PrefactorApiError – On other errors.

async update(agent_id: str, details: AgentForUpdate, idempotency_key: str | None = None) → 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 – If agent not found.
  • PrefactorApiError – On other errors.