hyperfluid 0.1.0__py3-none-any.whl

hyperfluid/api/ai_agents.py

@@ -0,0 +1,961 @@
+# this file is @generated
+"""Ai agents API."""
+
+from __future__ import annotations
+
+import builtins
+import functools
+import typing as t
+from uuid import UUID
+
+from .. import models as _models
+from ..models import (
+    AiAgentBudgetsDto,
+    AiAgentCapabilitiesResponse,
+    AiAgentDataSourceDto,
+    AiAgentDesiredStateDto,
+    AiAgentDesiredStateDtoLiteral,
+    AiAgentInferenceDto,
+    AiAgentMailDto,
+    AiAgentMailStatsResponse,
+    AiAgentMemoryResponse,
+    AiAgentResponse,
+    AskAiAgentRequest,
+    AskAiAgentResponse,
+    CreateAiAgentRequest,
+    UpdateAiAgentRequest,
+)
+from ..serialization import UNSET, Unset, to_json_value
+from ._response import async_to_raw_response_wrapper, to_raw_response_wrapper
+from .ai_agents_sessions import (
+    AiAgentsSessions,
+    AiAgentsSessionsWithRawResponse,
+    AsyncAiAgentsSessions,
+    AsyncAiAgentsSessionsWithRawResponse,
+)
+from .common import (
+    ApiBaseAsync,
+    ApiBaseSync,
+    ApiRequest,
+    Timeout,
+    decode_response,
+    encode_path_param,
+)
+
+
+class AsyncAiAgents(ApiBaseAsync):
+    """Ai agents API, for asyncio."""
+
+    @property
+    def with_raw_response(self) -> AsyncAiAgentsWithRawResponse:
+        """These methods, returning an :class:`APIResponse` with the status and headers."""
+        return AsyncAiAgentsWithRawResponse(self)
+
+    @functools.cached_property
+    def sessions(self) -> AsyncAiAgentsSessions:
+        """The sessions API."""
+        return AsyncAiAgentsSessions(self._cfg, self._httpx_client)
+
+    async def list(
+        self,
+        organization_id: UUID,
+        *,
+        extra_headers: t.Mapping[str, str] | None = None,
+        extra_query: t.Mapping[str, object] | None = None,
+        extra_body: t.Mapping[str, object] | None = None,
+        timeout: Timeout | Unset = UNSET,
+        max_retries: int | None = None,
+    ) -> builtins.list[AiAgentResponse]:
+        """`GET /api/v1/organizations/{organization_id}/ai-agents`."""
+        response = await self._request(
+            ApiRequest(
+                method="get",
+                path="/api/v1/organizations/{organization_id}/ai-agents",
+                path_params={
+                    "organization_id": encode_path_param(
+                        "organization_id", organization_id, "simple", False
+                    ),
+                },
+                error_types={
+                    "default": _models.ApiErrorBody,
+                },
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                max_retries=max_retries,
+            )
+        )
+        return decode_response(response, list[AiAgentResponse])
+
+    async def create(
+        self,
+        organization_id: UUID,
+        *,
+        harbor_id: UUID,
+        inference: AiAgentInferenceDto,
+        budgets: AiAgentBudgetsDto | None | Unset = UNSET,
+        context: str | None | Unset = UNSET,
+        data_sources: builtins.list[AiAgentDataSourceDto] | None = None,
+        description: str | None | Unset = UNSET,
+        desired_state: AiAgentDesiredStateDto
+        | AiAgentDesiredStateDtoLiteral
+        | None
+        | Unset = UNSET,
+        interfaces: builtins.list[str] | None | Unset = UNSET,
+        mail: AiAgentMailDto | None | Unset = UNSET,
+        mission: str | None | Unset = UNSET,
+        name: str | None | Unset = UNSET,
+        question_set: builtins.list[str] | None = None,
+        service_account_id: UUID | None | Unset = UNSET,
+        speciality: str | None | Unset = UNSET,
+        subagent_of: str | None | Unset = UNSET,
+        system_prompt: str | None | Unset = UNSET,
+        tools: builtins.list[str] | None | Unset = UNSET,
+        extra_headers: t.Mapping[str, str] | None = None,
+        extra_query: t.Mapping[str, object] | None = None,
+        extra_body: t.Mapping[str, object] | None = None,
+        timeout: Timeout | Unset = UNSET,
+        max_retries: int | None = None,
+    ) -> AiAgentResponse:
+        """Create an agent, or one of its capabilities.
+
+        A capability is an agent too: it names its router in `subagent_of` and what it
+        answers in `speciality`, and omits everything the platform decides about that
+        capability — its preamble, its tool subset, and the name it is known by, all
+        filled in here (see `compose_from_catalogue`) so that no client carries a copy of
+        a prompt and two clients cannot create the same capability differently.
+
+        :param context: Extra context appended to the system prompt.
+        :param data_sources: Data docks the agent may read.
+        :param harbor_id: Harbor (environment) the agent belongs to. Must be in the path org.
+        :param interfaces: Interfaces the agent is reachable from. Defaults to ["web"].
+        :param mission: The user's own instructions for a CAPABILITY, layered on top of the catalogue preamble in `system_prompt` — which, for a capability, is the console's rather than the user's. Kept separate so the runtime composes the two in a fixed order and user text cannot contradict the tool subset the capability was given (#3477).
+        :param name: Agent name (unique within the organization; slugified for the CR name).  Optional for a CAPABILITY: a request naming `subagent_of` and a `speciality` the platform offers is named `"<agent name> <capability name>"`, so what a capability is called does not depend on which client created it. Required for anything else.
+        :param question_set: Intent-extraction question set.
+        :param service_account_id: Hyperfluid Service-Account entity id the agent authenticates as. Must be viewer-scoped. Optional at creation.
+        :param speciality: What this agent is for, and what a routing agent matches a question against: `routing`, `platform-ops`, `data-sql`, `documents`, or a value of your own. Omit for an unspecialized agent.
+        :param subagent_of: The routing agent this one answers for, by CR name. Omit for a standalone agent. A subagent must declare a speciality and cannot have a mailbox.
+        :param system_prompt: System prompt injected at the start of every agent run.  Optional when `speciality` names a capability the platform offers: it is then filled from that capability's catalogue preamble. A preamble is deliberately not a client's to send — it is measured against the runtime, and a second copy in a client is a second copy to keep in step. `routing` still requires one: a router's prompt IS the user's own mission.
+        :param tools: Tools the agent may use: `ask_sender`, `hfctl` (all commands) or `hfctl:<command>`. An empty array means every tool and command.  Omitting the field — which is not the same as sending `[]` — takes the subset the `speciality` comes with: the capability's own from the catalogue, or `ask_sender` + `ask_subagent` for `routing`."""
+        response = await self._request(
+            ApiRequest(
+                method="post",
+                path="/api/v1/organizations/{organization_id}/ai-agents",
+                path_params={
+                    "organization_id": encode_path_param(
+                        "organization_id", organization_id, "simple", False
+                    ),
+                },
+                json_body=to_json_value(
+                    CreateAiAgentRequest(
+                        budgets=budgets,
+                        context=context,
+                        data_sources=data_sources,
+                        description=description,
+                        desired_state=t.cast(
+                            "AiAgentDesiredStateDto | None | Unset", desired_state
+                        ),
+                        harbor_id=harbor_id,
+                        inference=inference,
+                        interfaces=interfaces,
+                        mail=mail,
+                        mission=mission,
+                        name=name,
+                        question_set=question_set,
+                        service_account_id=service_account_id,
+                        speciality=speciality,
+                        subagent_of=subagent_of,
+                        system_prompt=system_prompt,
+                        tools=tools,
+                    ),
+                    CreateAiAgentRequest,
+                ),
+                error_types={
+                    "default": _models.ApiErrorBody,
+                },
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                max_retries=max_retries,
+            )
+        )
+        return decode_response(response, AiAgentResponse)
+
+    async def list_capabilities(
+        self,
+        organization_id: UUID,
+        *,
+        extra_headers: t.Mapping[str, str] | None = None,
+        extra_query: t.Mapping[str, object] | None = None,
+        extra_body: t.Mapping[str, object] | None = None,
+        timeout: Timeout | Unset = UNSET,
+        max_retries: int | None = None,
+    ) -> AiAgentCapabilitiesResponse:
+        """`GET /api/v1/organizations/{organization_id}/ai-agents/capabilities`."""
+        response = await self._request(
+            ApiRequest(
+                method="get",
+                path="/api/v1/organizations/{organization_id}/ai-agents/capabilities",
+                path_params={
+                    "organization_id": encode_path_param(
+                        "organization_id", organization_id, "simple", False
+                    ),
+                },
+                error_types={
+                    "default": _models.ApiErrorBody,
+                },
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                max_retries=max_retries,
+            )
+        )
+        return decode_response(response, AiAgentCapabilitiesResponse)
+
+    async def retrieve(
+        self,
+        organization_id: UUID,
+        id: UUID,
+        *,
+        extra_headers: t.Mapping[str, str] | None = None,
+        extra_query: t.Mapping[str, object] | None = None,
+        extra_body: t.Mapping[str, object] | None = None,
+        timeout: Timeout | Unset = UNSET,
+        max_retries: int | None = None,
+    ) -> AiAgentResponse:
+        """`GET /api/v1/organizations/{organization_id}/ai-agents/{id}`."""
+        response = await self._request(
+            ApiRequest(
+                method="get",
+                path="/api/v1/organizations/{organization_id}/ai-agents/{id}",
+                path_params={
+                    "organization_id": encode_path_param(
+                        "organization_id", organization_id, "simple", False
+                    ),
+                    "id": encode_path_param("id", id, "simple", False),
+                },
+                error_types={
+                    "default": _models.ApiErrorBody,
+                },
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                max_retries=max_retries,
+            )
+        )
+        return decode_response(response, AiAgentResponse)
+
+    async def delete(
+        self,
+        organization_id: UUID,
+        id: UUID,
+        *,
+        extra_headers: t.Mapping[str, str] | None = None,
+        extra_query: t.Mapping[str, object] | None = None,
+        extra_body: t.Mapping[str, object] | None = None,
+        timeout: Timeout | Unset = UNSET,
+        max_retries: int | None = None,
+    ) -> None:
+        """`DELETE /api/v1/organizations/{organization_id}/ai-agents/{id}`."""
+        await self._request(
+            ApiRequest(
+                method="delete",
+                path="/api/v1/organizations/{organization_id}/ai-agents/{id}",
+                path_params={
+                    "organization_id": encode_path_param(
+                        "organization_id", organization_id, "simple", False
+                    ),
+                    "id": encode_path_param("id", id, "simple", False),
+                },
+                error_types={
+                    "default": _models.ApiErrorBody,
+                },
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                max_retries=max_retries,
+            )
+        )
+
+    async def update(
+        self,
+        organization_id: UUID,
+        id: UUID,
+        *,
+        budgets: AiAgentBudgetsDto | None | Unset = UNSET,
+        context: str | None | Unset = UNSET,
+        data_sources: builtins.list[AiAgentDataSourceDto] | None | Unset = UNSET,
+        description: str | None | Unset = UNSET,
+        desired_state: AiAgentDesiredStateDto
+        | AiAgentDesiredStateDtoLiteral
+        | None
+        | Unset = UNSET,
+        detach_service_account: bool | None | Unset = UNSET,
+        inference: AiAgentInferenceDto | None | Unset = UNSET,
+        interfaces: builtins.list[str] | None | Unset = UNSET,
+        mail: AiAgentMailDto | None | Unset = UNSET,
+        mission: str | None | Unset = UNSET,
+        question_set: builtins.list[str] | None | Unset = UNSET,
+        service_account_id: UUID | None | Unset = UNSET,
+        speciality: str | None | Unset = UNSET,
+        subagent_of: str | None | Unset = UNSET,
+        system_prompt: str | None | Unset = UNSET,
+        tools: builtins.list[str] | None | Unset = UNSET,
+        extra_headers: t.Mapping[str, str] | None = None,
+        extra_query: t.Mapping[str, object] | None = None,
+        extra_body: t.Mapping[str, object] | None = None,
+        timeout: Timeout | Unset = UNSET,
+        max_retries: int | None = None,
+    ) -> AiAgentResponse:
+        """`PATCH /api/v1/organizations/{organization_id}/ai-agents/{id}`.
+
+        :param detach_service_account: True detaches the current service account.
+        :param mission: Replaces this capability's own instructions. An empty string clears them.
+        :param service_account_id: Attach this service account. Ignored when `detach_service_account`.
+        :param speciality: Replaces the speciality. An empty string clears it.
+        :param subagent_of: Replaces the owning router. An empty string detaches the subagent.
+        :param tools: Replaces the tool list. An empty array restores every tool and command."""
+        response = await self._request(
+            ApiRequest(
+                method="patch",
+                path="/api/v1/organizations/{organization_id}/ai-agents/{id}",
+                path_params={
+                    "organization_id": encode_path_param(
+                        "organization_id", organization_id, "simple", False
+                    ),
+                    "id": encode_path_param("id", id, "simple", False),
+                },
+                json_body=to_json_value(
+                    UpdateAiAgentRequest(
+                        budgets=budgets,
+                        context=context,
+                        data_sources=data_sources,
+                        description=description,
+                        desired_state=t.cast(
+                            "AiAgentDesiredStateDto | None | Unset", desired_state
+                        ),
+                        detach_service_account=detach_service_account,
+                        inference=inference,
+                        interfaces=interfaces,
+                        mail=mail,
+                        mission=mission,
+                        question_set=question_set,
+                        service_account_id=service_account_id,
+                        speciality=speciality,
+                        subagent_of=subagent_of,
+                        system_prompt=system_prompt,
+                        tools=tools,
+                    ),
+                    UpdateAiAgentRequest,
+                ),
+                error_types={
+                    "default": _models.ApiErrorBody,
+                },
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                max_retries=max_retries,
+            )
+        )
+        return decode_response(response, AiAgentResponse)
+
+    async def ask(
+        self,
+        organization_id: UUID,
+        id: UUID,
+        *,
+        question: str,
+        session_id: UUID | None | Unset = UNSET,
+        extra_headers: t.Mapping[str, str] | None = None,
+        extra_query: t.Mapping[str, object] | None = None,
+        extra_body: t.Mapping[str, object] | None = None,
+        timeout: Timeout | Unset = UNSET,
+        max_retries: int | None = None,
+    ) -> AskAiAgentResponse:
+        """`POST /api/v1/organizations/{organization_id}/ai-agents/{id}/ask`.
+
+        :param question: Natural-language question for the agent.
+        :param session_id: Conversation this question belongs to, so the agent can answer with the history of the exchange rather than treating every message as the first.  Omit it to start a new conversation — the response carries the id that was minted, and sending it back on the next question continues the thread. Mail needs no equivalent: it derives its conversation from the message headers.  This id IS the conversation's key: the same value comes back from `GET …/sessions` and addresses the transcript and delete routes. Typed as a `Uuid` so a value the read routes could not accept is rejected here rather than reaching the agent."""
+        response = await self._request(
+            ApiRequest(
+                method="post",
+                path="/api/v1/organizations/{organization_id}/ai-agents/{id}/ask",
+                path_params={
+                    "organization_id": encode_path_param(
+                        "organization_id", organization_id, "simple", False
+                    ),
+                    "id": encode_path_param("id", id, "simple", False),
+                },
+                json_body=to_json_value(
+                    AskAiAgentRequest(
+                        question=question,
+                        session_id=session_id,
+                    ),
+                    AskAiAgentRequest,
+                ),
+                error_types={
+                    "default": _models.ApiErrorBody,
+                },
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                max_retries=max_retries,
+            )
+        )
+        return decode_response(response, AskAiAgentResponse)
+
+    async def list_mail_stats(
+        self,
+        organization_id: UUID,
+        id: UUID,
+        *,
+        extra_headers: t.Mapping[str, str] | None = None,
+        extra_query: t.Mapping[str, object] | None = None,
+        extra_body: t.Mapping[str, object] | None = None,
+        timeout: Timeout | Unset = UNSET,
+        max_retries: int | None = None,
+    ) -> AiAgentMailStatsResponse:
+        """`GET /api/v1/organizations/{organization_id}/ai-agents/{id}/mail-stats`."""
+        response = await self._request(
+            ApiRequest(
+                method="get",
+                path="/api/v1/organizations/{organization_id}/ai-agents/{id}/mail-stats",
+                path_params={
+                    "organization_id": encode_path_param(
+                        "organization_id", organization_id, "simple", False
+                    ),
+                    "id": encode_path_param("id", id, "simple", False),
+                },
+                error_types={
+                    "default": _models.ApiErrorBody,
+                },
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                max_retries=max_retries,
+            )
+        )
+        return decode_response(response, AiAgentMailStatsResponse)
+
+    async def retrieve_memory(
+        self,
+        organization_id: UUID,
+        id: UUID,
+        *,
+        extra_headers: t.Mapping[str, str] | None = None,
+        extra_query: t.Mapping[str, object] | None = None,
+        extra_body: t.Mapping[str, object] | None = None,
+        timeout: Timeout | Unset = UNSET,
+        max_retries: int | None = None,
+    ) -> AiAgentMemoryResponse:
+        """`GET /api/v1/organizations/{organization_id}/ai-agents/{id}/memory`."""
+        response = await self._request(
+            ApiRequest(
+                method="get",
+                path="/api/v1/organizations/{organization_id}/ai-agents/{id}/memory",
+                path_params={
+                    "organization_id": encode_path_param(
+                        "organization_id", organization_id, "simple", False
+                    ),
+                    "id": encode_path_param("id", id, "simple", False),
+                },
+                error_types={
+                    "default": _models.ApiErrorBody,
+                },
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                max_retries=max_retries,
+            )
+        )
+        return decode_response(response, AiAgentMemoryResponse)
+
+
+class AsyncAiAgentsWithRawResponse:
+    """The methods of :class:`AsyncAiAgents`, returning an :class:`APIResponse`."""
+
+    def __init__(self, resource: AsyncAiAgents) -> None:
+        self._resource = resource
+        self.list = async_to_raw_response_wrapper(resource.list)
+        self.create = async_to_raw_response_wrapper(resource.create)
+        self.list_capabilities = async_to_raw_response_wrapper(
+            resource.list_capabilities
+        )
+        self.retrieve = async_to_raw_response_wrapper(resource.retrieve)
+        self.delete = async_to_raw_response_wrapper(resource.delete)
+        self.update = async_to_raw_response_wrapper(resource.update)
+        self.ask = async_to_raw_response_wrapper(resource.ask)
+        self.list_mail_stats = async_to_raw_response_wrapper(resource.list_mail_stats)
+        self.retrieve_memory = async_to_raw_response_wrapper(resource.retrieve_memory)
+
+    @property
+    def sessions(self) -> AsyncAiAgentsSessionsWithRawResponse:
+        """The sessions API."""
+        return AsyncAiAgentsSessionsWithRawResponse(self._resource.sessions)
+
+
+class AiAgents(ApiBaseSync):
+    """Ai agents API."""
+
+    @property
+    def with_raw_response(self) -> AiAgentsWithRawResponse:
+        """These methods, returning an :class:`APIResponse` with the status and headers."""
+        return AiAgentsWithRawResponse(self)
+
+    @functools.cached_property
+    def sessions(self) -> AiAgentsSessions:
+        """The sessions API."""
+        return AiAgentsSessions(self._cfg, self._httpx_client)
+
+    def list(
+        self,
+        organization_id: UUID,
+        *,
+        extra_headers: t.Mapping[str, str] | None = None,
+        extra_query: t.Mapping[str, object] | None = None,
+        extra_body: t.Mapping[str, object] | None = None,
+        timeout: Timeout | Unset = UNSET,
+        max_retries: int | None = None,
+    ) -> builtins.list[AiAgentResponse]:
+        """`GET /api/v1/organizations/{organization_id}/ai-agents`."""
+        response = self._request(
+            ApiRequest(
+                method="get",
+                path="/api/v1/organizations/{organization_id}/ai-agents",
+                path_params={
+                    "organization_id": encode_path_param(
+                        "organization_id", organization_id, "simple", False
+                    ),
+                },
+                error_types={
+                    "default": _models.ApiErrorBody,
+                },
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                max_retries=max_retries,
+            )
+        )
+        return decode_response(response, list[AiAgentResponse])
+
+    def create(
+        self,
+        organization_id: UUID,
+        *,
+        harbor_id: UUID,
+        inference: AiAgentInferenceDto,
+        budgets: AiAgentBudgetsDto | None | Unset = UNSET,
+        context: str | None | Unset = UNSET,
+        data_sources: builtins.list[AiAgentDataSourceDto] | None = None,
+        description: str | None | Unset = UNSET,
+        desired_state: AiAgentDesiredStateDto
+        | AiAgentDesiredStateDtoLiteral
+        | None
+        | Unset = UNSET,
+        interfaces: builtins.list[str] | None | Unset = UNSET,
+        mail: AiAgentMailDto | None | Unset = UNSET,
+        mission: str | None | Unset = UNSET,
+        name: str | None | Unset = UNSET,
+        question_set: builtins.list[str] | None = None,
+        service_account_id: UUID | None | Unset = UNSET,
+        speciality: str | None | Unset = UNSET,
+        subagent_of: str | None | Unset = UNSET,
+        system_prompt: str | None | Unset = UNSET,
+        tools: builtins.list[str] | None | Unset = UNSET,
+        extra_headers: t.Mapping[str, str] | None = None,
+        extra_query: t.Mapping[str, object] | None = None,
+        extra_body: t.Mapping[str, object] | None = None,
+        timeout: Timeout | Unset = UNSET,
+        max_retries: int | None = None,
+    ) -> AiAgentResponse:
+        """Create an agent, or one of its capabilities.
+
+        A capability is an agent too: it names its router in `subagent_of` and what it
+        answers in `speciality`, and omits everything the platform decides about that
+        capability — its preamble, its tool subset, and the name it is known by, all
+        filled in here (see `compose_from_catalogue`) so that no client carries a copy of
+        a prompt and two clients cannot create the same capability differently.
+
+        :param context: Extra context appended to the system prompt.
+        :param data_sources: Data docks the agent may read.
+        :param harbor_id: Harbor (environment) the agent belongs to. Must be in the path org.
+        :param interfaces: Interfaces the agent is reachable from. Defaults to ["web"].
+        :param mission: The user's own instructions for a CAPABILITY, layered on top of the catalogue preamble in `system_prompt` — which, for a capability, is the console's rather than the user's. Kept separate so the runtime composes the two in a fixed order and user text cannot contradict the tool subset the capability was given (#3477).
+        :param name: Agent name (unique within the organization; slugified for the CR name).  Optional for a CAPABILITY: a request naming `subagent_of` and a `speciality` the platform offers is named `"<agent name> <capability name>"`, so what a capability is called does not depend on which client created it. Required for anything else.
+        :param question_set: Intent-extraction question set.
+        :param service_account_id: Hyperfluid Service-Account entity id the agent authenticates as. Must be viewer-scoped. Optional at creation.
+        :param speciality: What this agent is for, and what a routing agent matches a question against: `routing`, `platform-ops`, `data-sql`, `documents`, or a value of your own. Omit for an unspecialized agent.
+        :param subagent_of: The routing agent this one answers for, by CR name. Omit for a standalone agent. A subagent must declare a speciality and cannot have a mailbox.
+        :param system_prompt: System prompt injected at the start of every agent run.  Optional when `speciality` names a capability the platform offers: it is then filled from that capability's catalogue preamble. A preamble is deliberately not a client's to send — it is measured against the runtime, and a second copy in a client is a second copy to keep in step. `routing` still requires one: a router's prompt IS the user's own mission.
+        :param tools: Tools the agent may use: `ask_sender`, `hfctl` (all commands) or `hfctl:<command>`. An empty array means every tool and command.  Omitting the field — which is not the same as sending `[]` — takes the subset the `speciality` comes with: the capability's own from the catalogue, or `ask_sender` + `ask_subagent` for `routing`."""
+        response = self._request(
+            ApiRequest(
+                method="post",
+                path="/api/v1/organizations/{organization_id}/ai-agents",
+                path_params={
+                    "organization_id": encode_path_param(
+                        "organization_id", organization_id, "simple", False
+                    ),
+                },
+                json_body=to_json_value(
+                    CreateAiAgentRequest(
+                        budgets=budgets,
+                        context=context,
+                        data_sources=data_sources,
+                        description=description,
+                        desired_state=t.cast(
+                            "AiAgentDesiredStateDto | None | Unset", desired_state
+                        ),
+                        harbor_id=harbor_id,
+                        inference=inference,
+                        interfaces=interfaces,
+                        mail=mail,
+                        mission=mission,
+                        name=name,
+                        question_set=question_set,
+                        service_account_id=service_account_id,
+                        speciality=speciality,
+                        subagent_of=subagent_of,
+                        system_prompt=system_prompt,
+                        tools=tools,
+                    ),
+                    CreateAiAgentRequest,
+                ),
+                error_types={
+                    "default": _models.ApiErrorBody,
+                },
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                max_retries=max_retries,
+            )
+        )
+        return decode_response(response, AiAgentResponse)
+
+    def list_capabilities(
+        self,
+        organization_id: UUID,
+        *,
+        extra_headers: t.Mapping[str, str] | None = None,
+        extra_query: t.Mapping[str, object] | None = None,
+        extra_body: t.Mapping[str, object] | None = None,
+        timeout: Timeout | Unset = UNSET,
+        max_retries: int | None = None,
+    ) -> AiAgentCapabilitiesResponse:
+        """`GET /api/v1/organizations/{organization_id}/ai-agents/capabilities`."""
+        response = self._request(
+            ApiRequest(
+                method="get",
+                path="/api/v1/organizations/{organization_id}/ai-agents/capabilities",
+                path_params={
+                    "organization_id": encode_path_param(
+                        "organization_id", organization_id, "simple", False
+                    ),
+                },
+                error_types={
+                    "default": _models.ApiErrorBody,
+                },
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                max_retries=max_retries,
+            )
+        )
+        return decode_response(response, AiAgentCapabilitiesResponse)
+
+    def retrieve(
+        self,
+        organization_id: UUID,
+        id: UUID,
+        *,
+        extra_headers: t.Mapping[str, str] | None = None,
+        extra_query: t.Mapping[str, object] | None = None,
+        extra_body: t.Mapping[str, object] | None = None,
+        timeout: Timeout | Unset = UNSET,
+        max_retries: int | None = None,
+    ) -> AiAgentResponse:
+        """`GET /api/v1/organizations/{organization_id}/ai-agents/{id}`."""
+        response = self._request(
+            ApiRequest(
+                method="get",
+                path="/api/v1/organizations/{organization_id}/ai-agents/{id}",
+                path_params={
+                    "organization_id": encode_path_param(
+                        "organization_id", organization_id, "simple", False
+                    ),
+                    "id": encode_path_param("id", id, "simple", False),
+                },
+                error_types={
+                    "default": _models.ApiErrorBody,
+                },
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                max_retries=max_retries,
+            )
+        )
+        return decode_response(response, AiAgentResponse)
+
+    def delete(
+        self,
+        organization_id: UUID,
+        id: UUID,
+        *,
+        extra_headers: t.Mapping[str, str] | None = None,
+        extra_query: t.Mapping[str, object] | None = None,
+        extra_body: t.Mapping[str, object] | None = None,
+        timeout: Timeout | Unset = UNSET,
+        max_retries: int | None = None,
+    ) -> None:
+        """`DELETE /api/v1/organizations/{organization_id}/ai-agents/{id}`."""
+        self._request(
+            ApiRequest(
+                method="delete",
+                path="/api/v1/organizations/{organization_id}/ai-agents/{id}",
+                path_params={
+                    "organization_id": encode_path_param(
+                        "organization_id", organization_id, "simple", False
+                    ),
+                    "id": encode_path_param("id", id, "simple", False),
+                },
+                error_types={
+                    "default": _models.ApiErrorBody,
+                },
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                max_retries=max_retries,
+            )
+        )
+
+    def update(
+        self,
+        organization_id: UUID,
+        id: UUID,
+        *,
+        budgets: AiAgentBudgetsDto | None | Unset = UNSET,
+        context: str | None | Unset = UNSET,
+        data_sources: builtins.list[AiAgentDataSourceDto] | None | Unset = UNSET,
+        description: str | None | Unset = UNSET,
+        desired_state: AiAgentDesiredStateDto
+        | AiAgentDesiredStateDtoLiteral
+        | None
+        | Unset = UNSET,
+        detach_service_account: bool | None | Unset = UNSET,
+        inference: AiAgentInferenceDto | None | Unset = UNSET,
+        interfaces: builtins.list[str] | None | Unset = UNSET,
+        mail: AiAgentMailDto | None | Unset = UNSET,
+        mission: str | None | Unset = UNSET,
+        question_set: builtins.list[str] | None | Unset = UNSET,
+        service_account_id: UUID | None | Unset = UNSET,
+        speciality: str | None | Unset = UNSET,
+        subagent_of: str | None | Unset = UNSET,
+        system_prompt: str | None | Unset = UNSET,
+        tools: builtins.list[str] | None | Unset = UNSET,
+        extra_headers: t.Mapping[str, str] | None = None,
+        extra_query: t.Mapping[str, object] | None = None,
+        extra_body: t.Mapping[str, object] | None = None,
+        timeout: Timeout | Unset = UNSET,
+        max_retries: int | None = None,
+    ) -> AiAgentResponse:
+        """`PATCH /api/v1/organizations/{organization_id}/ai-agents/{id}`.
+
+        :param detach_service_account: True detaches the current service account.
+        :param mission: Replaces this capability's own instructions. An empty string clears them.
+        :param service_account_id: Attach this service account. Ignored when `detach_service_account`.
+        :param speciality: Replaces the speciality. An empty string clears it.
+        :param subagent_of: Replaces the owning router. An empty string detaches the subagent.
+        :param tools: Replaces the tool list. An empty array restores every tool and command."""
+        response = self._request(
+            ApiRequest(
+                method="patch",
+                path="/api/v1/organizations/{organization_id}/ai-agents/{id}",
+                path_params={
+                    "organization_id": encode_path_param(
+                        "organization_id", organization_id, "simple", False
+                    ),
+                    "id": encode_path_param("id", id, "simple", False),
+                },
+                json_body=to_json_value(
+                    UpdateAiAgentRequest(
+                        budgets=budgets,
+                        context=context,
+                        data_sources=data_sources,
+                        description=description,
+                        desired_state=t.cast(
+                            "AiAgentDesiredStateDto | None | Unset", desired_state
+                        ),
+                        detach_service_account=detach_service_account,
+                        inference=inference,
+                        interfaces=interfaces,
+                        mail=mail,
+                        mission=mission,
+                        question_set=question_set,
+                        service_account_id=service_account_id,
+                        speciality=speciality,
+                        subagent_of=subagent_of,
+                        system_prompt=system_prompt,
+                        tools=tools,
+                    ),
+                    UpdateAiAgentRequest,
+                ),
+                error_types={
+                    "default": _models.ApiErrorBody,
+                },
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                max_retries=max_retries,
+            )
+        )
+        return decode_response(response, AiAgentResponse)
+
+    def ask(
+        self,
+        organization_id: UUID,
+        id: UUID,
+        *,
+        question: str,
+        session_id: UUID | None | Unset = UNSET,
+        extra_headers: t.Mapping[str, str] | None = None,
+        extra_query: t.Mapping[str, object] | None = None,
+        extra_body: t.Mapping[str, object] | None = None,
+        timeout: Timeout | Unset = UNSET,
+        max_retries: int | None = None,
+    ) -> AskAiAgentResponse:
+        """`POST /api/v1/organizations/{organization_id}/ai-agents/{id}/ask`.
+
+        :param question: Natural-language question for the agent.
+        :param session_id: Conversation this question belongs to, so the agent can answer with the history of the exchange rather than treating every message as the first.  Omit it to start a new conversation — the response carries the id that was minted, and sending it back on the next question continues the thread. Mail needs no equivalent: it derives its conversation from the message headers.  This id IS the conversation's key: the same value comes back from `GET …/sessions` and addresses the transcript and delete routes. Typed as a `Uuid` so a value the read routes could not accept is rejected here rather than reaching the agent."""
+        response = self._request(
+            ApiRequest(
+                method="post",
+                path="/api/v1/organizations/{organization_id}/ai-agents/{id}/ask",
+                path_params={
+                    "organization_id": encode_path_param(
+                        "organization_id", organization_id, "simple", False
+                    ),
+                    "id": encode_path_param("id", id, "simple", False),
+                },
+                json_body=to_json_value(
+                    AskAiAgentRequest(
+                        question=question,
+                        session_id=session_id,
+                    ),
+                    AskAiAgentRequest,
+                ),
+                error_types={
+                    "default": _models.ApiErrorBody,
+                },
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                max_retries=max_retries,
+            )
+        )
+        return decode_response(response, AskAiAgentResponse)
+
+    def list_mail_stats(
+        self,
+        organization_id: UUID,
+        id: UUID,
+        *,
+        extra_headers: t.Mapping[str, str] | None = None,
+        extra_query: t.Mapping[str, object] | None = None,
+        extra_body: t.Mapping[str, object] | None = None,
+        timeout: Timeout | Unset = UNSET,
+        max_retries: int | None = None,
+    ) -> AiAgentMailStatsResponse:
+        """`GET /api/v1/organizations/{organization_id}/ai-agents/{id}/mail-stats`."""
+        response = self._request(
+            ApiRequest(
+                method="get",
+                path="/api/v1/organizations/{organization_id}/ai-agents/{id}/mail-stats",
+                path_params={
+                    "organization_id": encode_path_param(
+                        "organization_id", organization_id, "simple", False
+                    ),
+                    "id": encode_path_param("id", id, "simple", False),
+                },
+                error_types={
+                    "default": _models.ApiErrorBody,
+                },
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                max_retries=max_retries,
+            )
+        )
+        return decode_response(response, AiAgentMailStatsResponse)
+
+    def retrieve_memory(
+        self,
+        organization_id: UUID,
+        id: UUID,
+        *,
+        extra_headers: t.Mapping[str, str] | None = None,
+        extra_query: t.Mapping[str, object] | None = None,
+        extra_body: t.Mapping[str, object] | None = None,
+        timeout: Timeout | Unset = UNSET,
+        max_retries: int | None = None,
+    ) -> AiAgentMemoryResponse:
+        """`GET /api/v1/organizations/{organization_id}/ai-agents/{id}/memory`."""
+        response = self._request(
+            ApiRequest(
+                method="get",
+                path="/api/v1/organizations/{organization_id}/ai-agents/{id}/memory",
+                path_params={
+                    "organization_id": encode_path_param(
+                        "organization_id", organization_id, "simple", False
+                    ),
+                    "id": encode_path_param("id", id, "simple", False),
+                },
+                error_types={
+                    "default": _models.ApiErrorBody,
+                },
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                max_retries=max_retries,
+            )
+        )
+        return decode_response(response, AiAgentMemoryResponse)
+
+
+class AiAgentsWithRawResponse:
+    """The methods of :class:`AiAgents`, returning an :class:`APIResponse`."""
+
+    def __init__(self, resource: AiAgents) -> None:
+        self._resource = resource
+        self.list = to_raw_response_wrapper(resource.list)
+        self.create = to_raw_response_wrapper(resource.create)
+        self.list_capabilities = to_raw_response_wrapper(resource.list_capabilities)
+        self.retrieve = to_raw_response_wrapper(resource.retrieve)
+        self.delete = to_raw_response_wrapper(resource.delete)
+        self.update = to_raw_response_wrapper(resource.update)
+        self.ask = to_raw_response_wrapper(resource.ask)
+        self.list_mail_stats = to_raw_response_wrapper(resource.list_mail_stats)
+        self.retrieve_memory = to_raw_response_wrapper(resource.retrieve_memory)
+
+    @property
+    def sessions(self) -> AiAgentsSessionsWithRawResponse:
+        """The sessions API."""
+        return AiAgentsSessionsWithRawResponse(self._resource.sessions)