feat(server): agent build actions, agent origin tracking (#1307)

Signed-off-by: Radek Ježek <[email protected]>

Author: jezekra1

apps/beeai-cli/src/beeai_cli/commands/build.py

@@ -16,6 +16,7 @@
 import typer
 from a2a.utils import AGENT_CARD_WELL_KNOWN_PATH
 from anyio import open_process
+from beeai_sdk.platform import AddProvider
 from beeai_sdk.platform.provider_build import BuildState, ProviderBuild
 from httpx import AsyncClient, HTTPError
 from tenacity import AsyncRetrying, retry_if_exception_type, stop_after_delay, wait_fixed
@@ -136,18 +137,21 @@ async def server_side_build_experimental(
     github_url: typing.Annotated[
         str, typer.Argument(..., help="Github repository URL (public or private if supported by the platform instance)")
     ],
+    add: typing.Annotated[bool, typer.Option(help="Add agent to the platform after build")] = False,
 ):
     """EXPERIMENTAL: Build agent from github repository in the platform."""
     from beeai_cli.configuration import Configuration
 
     async with Configuration().use_platform_client():
-        build = await ProviderBuild.create(location=github_url)
+        build = await ProviderBuild.create(location=github_url, on_complete=AddProvider() if add else None)
         async for message in build.stream_logs():
             print_log(message, ansi_mode=True)
         build = await build.get()
         if build.status == BuildState.COMPLETED:
-            console.success(
-                f"Agent built successfully, add it to the platform using: [bold]beeai add {build.destination}[/bold]"
-            )
+            if add:
+                message = "Agent added successfully. List agents using [green]beeai list[/green]"
+            else:
+                message = f"Agent built successfully, add it to the platform using: [green]beeai add {build.destination}[/green]"
+            console.success(message)
         else:
             console.error("Agent build failed, see logs above for details.")

apps/beeai-sdk/src/beeai_sdk/a2a/extensions/ui/agent_detail.py

@@ -22,6 +22,12 @@ class AgentDetailContributor(pydantic.BaseModel):
     url: str | None = None
 
 
+class EnvVar(pydantic.BaseModel):
+    name: str
+    description: str | None = None
+    required: bool = False
+
+
 class AgentDetail(pydantic.BaseModel, extra="allow"):
     interaction_mode: str | None = pydantic.Field("multi-turn", examples=["multi-turn", "single-turn"])
     user_greeting: str | None = None
@@ -35,6 +41,7 @@ class AgentDetail(pydantic.BaseModel, extra="allow"):
     container_image_url: str | None = None
     author: AgentDetailContributor | None = None
     contributors: list[AgentDetailContributor] | None = None
+    variables: list[EnvVar] | None = None
 
 
 class AgentDetailExtensionSpec(BaseExtensionSpec[AgentDetail]):

apps/beeai-sdk/src/beeai_sdk/platform/provider.py

@@ -12,7 +12,7 @@
 from a2a.types import AgentCard
 
 from beeai_sdk.platform.client import PlatformClient, get_platform_client
-from beeai_sdk.util.utils import parse_stream
+from beeai_sdk.util.utils import filter_dict, parse_stream
 
 
 class ProviderErrorMessage(pydantic.BaseModel):
@@ -27,11 +27,13 @@ class EnvVar(pydantic.BaseModel):
 
 class Provider(pydantic.BaseModel):
     id: str
-    auto_stop_timeout: timedelta | None = None
+    auto_stop_timeout: timedelta
     source: str
+    origin: str
     registry: str | None = None
     auto_remove: bool = False
     created_at: pydantic.AwareDatetime
+    updated_at: pydantic.AwareDatetime
     last_active_at: pydantic.AwareDatetime
     agent_card: AgentCard
     state: typing.Literal["missing", "starting", "ready", "running", "error"] = "missing"
@@ -45,17 +47,66 @@ async def create(
         location: str,
         agent_card: AgentCard | None = None,
         auto_remove: bool = False,
+        origin: str | None = None,
+        auto_stop_timeout: timedelta | None = None,
+        variables: dict[str, str] | None = None,
         client: PlatformClient | None = None,
     ) -> "Provider":
+        auto_stop_timeout_sec = auto_stop_timeout.total_seconds() if auto_stop_timeout is not None else None
+
         async with client or get_platform_client() as client:
             return pydantic.TypeAdapter(Provider).validate_python(
                 (
                     await client.post(
                         url="/api/v1/providers",
-                        json={
-                            "location": location,
-                            "agent_card": agent_card.model_dump(mode="json") if agent_card else None,
-                        },
+                        json=filter_dict(
+                            {
+                                "location": location,
+                                "agent_card": agent_card.model_dump(mode="json") if agent_card else None,
+                                "origin": origin,
+                                "variables": variables,
+                                "auto_stop_timeout_sec": auto_stop_timeout_sec,
+                            }
+                        ),
+                        params={"auto_remove": auto_remove},
+                    )
+                )
+                .raise_for_status()
+                .json()
+            )
+
+    async def patch(
+        self: "Provider | str",
+        *,
+        location: str | None = None,
+        agent_card: AgentCard | None = None,
+        auto_remove: bool = False,
+        origin: str | None = None,
+        auto_stop_timeout: timedelta | None = None,
+        variables: dict[str, str] | None = None,
+        client: PlatformClient | None = None,
+    ) -> "Provider":
+        # `self` has a weird type so that you can call both `instance.patch()` to update an instance, or `Provider.patch("123", ...)` to update a provider
+
+        provider_id = self if isinstance(self, str) else self.id
+        payload = filter_dict(
+            {
+                "location": location,
+                "agent_card": agent_card.model_dump(mode="json") if agent_card else None,
+                "variables": variables,
+                "auto_stop_timeout_sec": None if auto_stop_timeout is None else auto_stop_timeout.total_seconds(),
+                "origin": origin,
+            }
+        )
+        if not payload:
+            return await Provider.get(self)
+
+        async with client or get_platform_client() as client:
+            return pydantic.TypeAdapter(Provider).validate_python(
+                (
+                    await client.patch(
+                        url=f"/api/v1/providers/{provider_id}",
+                        json=payload,
                         params={"auto_remove": auto_remove},
                     )
                 )

apps/beeai-sdk/src/beeai_sdk/platform/provider_build.py

@@ -5,7 +5,8 @@
 from collections.abc import AsyncIterator
 from datetime import timedelta
 from enum import StrEnum
-from typing import Any, Literal
+from typing import Any, Literal, TypeAlias
+from uuid import UUID
 
 import pydantic
 
@@ -17,23 +18,83 @@
 class BuildState(StrEnum):
     MISSING = "missing"
     IN_PROGRESS = "in_progress"
+    BUILD_COMPLETED = "build_completed"
     COMPLETED = "completed"
     FAILED = "failed"
 
 
+class AddProvider(pydantic.BaseModel):
+    """
+    Will add a new provider or update an existing one with the same base docker image ID
+    (docker registry + repository, excluding tag)
+    """
+
+    type: Literal["add_provider"] = "add_provider"
+    auto_stop_timeout_sec: int | None = pydantic.Field(
+        default=None,
+        gt=0,
+        le=600,
+        description=(
+            "Timeout after which the agent provider will be automatically downscaled if unused."
+            "Contact administrator if you need to increase this value."
+        ),
+    )
+    variables: dict[str, str] | None = None
+
+
+class UpdateProvider(pydantic.BaseModel):
+    """Will update provider specified by ID"""
+
+    type: Literal["update_provider"] = "update_provider"
+    provider_id: UUID
+
+
+class NoAction(pydantic.BaseModel):
+    type: Literal["no_action"] = "no_action"
+
+
+OnCompleteAction: TypeAlias = AddProvider | UpdateProvider | NoAction
+
+
 class ProviderBuild(pydantic.BaseModel):
     id: str
     created_at: pydantic.AwareDatetime
     status: BuildState
     source: ResolvedGithubUrl
     destination: str
     created_by: str
+    error_message: str | None = None
+
+    @staticmethod
+    async def create(
+        *, location: str, client: PlatformClient | None = None, on_complete: OnCompleteAction | None = None
+    ) -> ProviderBuild:
+        on_complete = on_complete or NoAction()
+        async with client or get_platform_client() as client:
+            return pydantic.TypeAdapter(ProviderBuild).validate_python(
+                (
+                    await client.post(
+                        url="/api/v1/provider_builds",
+                        json={"location": location, "on_complete": on_complete.model_dump(exclude_none=True)},
+                    )
+                )
+                .raise_for_status()
+                .json()
+            )
 
     @staticmethod
-    async def create(*, location: str, client: PlatformClient | None = None) -> ProviderBuild:
+    async def preview(
+        *, location: str, client: PlatformClient | None = None, on_complete: OnCompleteAction | None = None
+    ) -> ProviderBuild:
+        on_complete = on_complete or NoAction()
         async with client or get_platform_client() as client:
             return pydantic.TypeAdapter(ProviderBuild).validate_python(
-                (await client.post(url="/api/v1/provider_builds", json={"location": location}))
+                (
+                    await client.post(
+                        url="/api/v1/provider_builds/preview",
+                        json={"location": location, "on_complete": on_complete.model_dump(exclude_none=True)},
+                    )
+                )
                 .raise_for_status()
                 .json()
             )

apps/beeai-sdk/src/beeai_sdk/util/utils.py

@@ -3,17 +3,18 @@
 import json
 import re
 from collections.abc import AsyncIterator
-from typing import Any, TypeVar
+from typing import Any, TypeVar, cast
 
 import httpx
 from httpx import HTTPStatusError
 
+T = TypeVar("T")
 V = TypeVar("V")
 
 
-def filter_dict(map: dict[str, V], value_to_exclude: V = None) -> dict[str, V]:
+def filter_dict(map: dict[str, T | V], value_to_exclude: V = None) -> dict[str, T]:
     """Remove entries with unwanted values (None by default) from dictionary."""
-    return {filter: value for filter, value in map.items() if value is not value_to_exclude}
+    return {key: cast(T, value) for key, value in map.items() if value is not value_to_exclude}
 
 
 async def parse_stream(response: httpx.Response) -> AsyncIterator[dict[str, Any]]:

apps/beeai-server/src/beeai_server/api/routes/provider_builds.py

@@ -29,7 +29,19 @@ async def create_provider_build(
         request: CreateProviderBuildRequest,
         provider_build_service: ProviderBuildServiceDependency,
     ) -> ProviderBuild:
-        return await provider_build_service.create_build(location=request.location, user=user.user)
+        return await provider_build_service.create_build(
+            location=request.location, user=user.user, on_complete=request.on_complete
+        )
+
+    @router.post("/preview")
+    async def preview_provider_build(
+        user: Annotated[AuthorizedUser, Depends(RequiresPermissions(provider_builds={"write"}))],
+        request: CreateProviderBuildRequest,
+        provider_build_service: ProviderBuildServiceDependency,
+    ) -> ProviderBuild:
+        return await provider_build_service.preview_build(
+            location=request.location, user=user.user, on_complete=request.on_complete
+        )
 
     @router.get("/{id}")
     async def get_provider_build(

apps/beeai-server/src/beeai_server/api/routes/providers.py

@@ -1,6 +1,5 @@
 # Copyright 2025 © BeeAI a Series of LF Projects, LLC
 # SPDX-License-Identifier: Apache-2.0
-from datetime import timedelta
 from typing import Annotated
 from uuid import UUID
 
@@ -16,8 +15,9 @@
     RequiresPermissions,
 )
 from beeai_server.api.routes.a2a import create_proxy_agent_card
+from beeai_server.api.schema.common import EntityModel
 from beeai_server.api.schema.env import ListVariablesSchema, UpdateVariablesRequest
-from beeai_server.api.schema.provider import CreateProviderRequest
+from beeai_server.api.schema.provider import CreateProviderRequest, PatchProviderRequest
 from beeai_server.domain.models.common import PaginatedResult
 from beeai_server.domain.models.permissions import AuthorizedUser
 from beeai_server.domain.models.provider import ProviderWithState
@@ -38,14 +38,33 @@ async def create_provider(
         raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Auto remove functionality is disabled")
     return await provider_service.create_provider(
         user=user.user,
-        auto_stop_timeout=timedelta(seconds=request.auto_stop_timeout_sec),
+        auto_stop_timeout=request.auto_stop_timeout,
         location=request.location,
+        origin=request.origin,
         agent_card=request.agent_card,
         auto_remove=auto_remove,
         variables=request.variables,
     )
 
 
+@router.patch("/{id}")
+async def patch_provider(
+    id: UUID,
+    user: Annotated[AuthorizedUser, Depends(RequiresPermissions(providers={"write"}))],
+    request: PatchProviderRequest,
+    provider_service: ProviderServiceDependency,
+) -> ProviderWithState:
+    return await provider_service.patch_provider(
+        provider_id=id,
+        user=user.user,
+        auto_stop_timeout=request.auto_stop_timeout,
+        location=request.location,
+        origin=request.origin,
+        agent_card=request.agent_card,
+        variables=request.variables,
+    )
+
+
 @router.post("/preview")
 async def preview_provider(
     request: CreateProviderRequest,
@@ -61,15 +80,16 @@ async def list_providers(
     request: Request,
     user: Annotated[AuthorizedUser, Depends(RequiresPermissions(providers={"read"}), use_cache=False)],
     user_owned: Annotated[bool, Query()] = False,
-) -> PaginatedResult[ProviderWithState]:
+    origin: Annotated[str | None, Query()] = None,
+) -> PaginatedResult[EntityModel[ProviderWithState]]:
     providers = []
-    for provider in await provider_service.list_providers(user=user.user if user_owned else None):
+    for provider in await provider_service.list_providers(user=user.user if user_owned else None, origin=origin):
         new_provider = provider.model_copy(
             update={
                 "agent_card": create_proxy_agent_card(provider.agent_card, provider_id=provider.id, request=request)
             }
         )
-        providers.append(new_provider)
+        providers.append(EntityModel(new_provider))
 
     return PaginatedResult(items=providers, total_count=len(providers))
 
@@ -80,10 +100,14 @@ async def get_provider(
     provider_service: ProviderServiceDependency,
     request: Request,
     _: Annotated[AuthorizedUser, Depends(RequiresPermissions(providers={"read"}))],
-) -> ProviderWithState:
+) -> EntityModel[ProviderWithState]:
     provider = await provider_service.get_provider(provider_id=id)
-    return provider.model_copy(
-        update={"agent_card": create_proxy_agent_card(provider.agent_card, provider_id=provider.id, request=request)}
+    return EntityModel(
+        provider.model_copy(
+            update={
+                "agent_card": create_proxy_agent_card(provider.agent_card, provider_id=provider.id, request=request)
+            }
+        )
     )
 
 

apps/beeai-server/src/beeai_server/api/schema/common.py

@@ -7,10 +7,10 @@
 
 
 class PaginationQuery(BaseModel):
-    limit: int = Field(default=40, ge=1, le=100)
+    limit: int = Field(default_factory=lambda: 40, ge=1, le=100)
     page_token: UUID | None = None
-    order: str = Field(default="desc", pattern="^(asc|desc)$")
-    order_by: str = Field(default="created_at", pattern="^created_at|updated_at$")
+    order: str = Field(default_factory=lambda: "desc", pattern="^(asc|desc)$")
+    order_by: str = Field(default_factory=lambda: "created_at", pattern="^created_at|updated_at$")
 
 
 class ErrorStreamResponseError(BaseModel, extra="allow"):