feat(agent): agent workflow service and tool-resolution API

api/oss/src/apis/fastapi/tools/models.py

@@ -1,6 +1,12 @@
-from typing import List, Optional, Union
+from typing import Any, List, Optional, Union
 
-from pydantic import BaseModel
+from agenta.sdk.agents.tools import (
+    BuiltinToolConfig,
+    GatewayToolConfig,
+    ToolConfigurationError,
+    coerce_tool_configs,
+)
+from pydantic import BaseModel, Field, field_validator
 
 from oss.src.core.tools.dtos import (
     # Tool Catalog
@@ -15,6 +21,9 @@
     ToolConnectionCreate,
     # Tool Calls
     ToolResult,
+    # Agent tools
+    AgentToolReference,
+    ResolvedAgentTool,
 )
 
 
@@ -87,3 +96,34 @@ class ToolConnectionsResponse(BaseModel):
 
 class ToolCallResponse(BaseModel):
     call: ToolResult
+
+
+# ---------------------------------------------------------------------------
+# Agent tool resolution
+# ---------------------------------------------------------------------------
+
+
+class ToolResolveRequest(BaseModel):
+    tools: List[AgentToolReference] = Field(default_factory=list)
+
+    @field_validator("tools", mode="before")
+    @classmethod
+    def _coerce_tools(cls, value: Any) -> List[AgentToolReference]:
+        try:
+            configs = coerce_tool_configs(value or []).tool_configs
+        except ToolConfigurationError as exc:
+            raise ValueError(str(exc)) from exc
+        unsupported = [
+            config
+            for config in configs
+            if not isinstance(config, (BuiltinToolConfig, GatewayToolConfig))
+        ]
+        if unsupported:
+            raise ValueError("/tools/resolve accepts only builtin and gateway tools")
+        return configs
+
+
+class ToolResolveResponse(BaseModel):
+    count: int = 0
+    builtins: List[str] = Field(default_factory=list)
+    custom: List[ResolvedAgentTool] = Field(default_factory=list)

api/oss/src/apis/fastapi/tools/router.py

@@ -29,6 +29,9 @@
     ToolConnectionsResponse,
     #
     ToolCallResponse,
+    #
+    ToolResolveRequest,
+    ToolResolveResponse,
 )
 
 from oss.src.core.shared.dtos import Status
@@ -42,10 +45,12 @@
     ToolResultData,
 )
 from oss.src.core.tools.exceptions import (
+    ActionNotFoundError,
     AdapterError,
     ConnectionInactiveError,
     ConnectionInvalidError,
     ConnectionNotFoundError,
+    ToolSlugInvalidError,
 )
 from oss.src.core.tools.service import (
     ToolsService,
@@ -208,6 +213,14 @@ def __init__(
         )
 
         # --- Tool operations ---
+        self.router.add_api_route(
+            "/resolve",
+            self.resolve_tools,
+            methods=["POST"],
+            operation_id="resolve_agent_tools",
+            response_model=ToolResolveResponse,
+            response_model_exclude_none=True,
+        )
         self.router.add_api_route(
             "/call",
             self.call_tool,
@@ -886,6 +899,51 @@ async def callback_connection(
     # Tool Calls
     # -----------------------------------------------------------------------
 
+    @intercept_exceptions()
+    @handle_adapter_exceptions()
+    async def resolve_tools(
+        self,
+        request: Request,
+        *,
+        body: ToolResolveRequest,
+    ) -> ToolResolveResponse:
+        """Resolve an agent's tool references into model-ready specs.
+
+        Validates Composio connections up front and enriches each action from the
+        catalog, so a running agent (e.g. Pi) gets ``customTools`` whose ``execute``
+        routes back through ``POST /tools/call`` — provider keys stay server-side.
+        """
+        if is_ee():
+            has_permission = await check_action_access(
+                user_uid=request.state.user_id,
+                project_id=request.state.project_id,
+                permission=Permission.VIEW_TOOLS,
+            )
+            if not has_permission:
+                raise FORBIDDEN_EXCEPTION
+
+        try:
+            resolution = await self.tools_service.resolve_agent_tools(
+                project_id=UUID(request.state.project_id),
+                tools=body.tools,
+            )
+        except ConnectionNotFoundError as e:
+            raise HTTPException(status_code=404, detail=e.message) from e
+        except ConnectionInactiveError as e:
+            raise HTTPException(status_code=400, detail=e.message) from e
+        except ConnectionInvalidError as e:
+            raise HTTPException(status_code=400, detail=e.message) from e
+        except ToolSlugInvalidError as e:
+            raise HTTPException(status_code=400, detail=e.message) from e
+        except ActionNotFoundError as e:
+            raise HTTPException(status_code=404, detail=e.message) from e
+
+        return ToolResolveResponse(
+            count=len(resolution.builtins) + len(resolution.custom),
+            builtins=resolution.builtins,
+            custom=resolution.custom,
+        )
+
     @intercept_exceptions()
     @handle_adapter_exceptions()
     async def call_tool(
@@ -931,39 +989,12 @@ async def call_tool(
         connection_slug = slug_parts[4]
 
         try:
-            connections = await self.tools_service.query_connections(
+            connection = await self.tools_service.resolve_connection_by_slug(
                 project_id=UUID(request.state.project_id),
                 provider_key=provider_key,
                 integration_key=integration_key,
+                connection_slug=connection_slug,
             )
-
-            connection = next(
-                (c for c in connections if c.slug == connection_slug), None
-            )
-
-            if not connection:
-                raise ConnectionNotFoundError(
-                    connection_slug=connection_slug,
-                    provider_key=provider_key,
-                    integration_key=integration_key,
-                )
-
-            if not connection.is_active:
-                raise ConnectionInactiveError(connection_id=connection_slug)
-
-            if not connection.is_valid:
-                raise ConnectionInvalidError(
-                    connection_slug=connection_slug,
-                    detail="Please refresh the connection.",
-                )
-
-            if not connection.provider_connection_id:
-                raise ConnectionNotFoundError(
-                    connection_slug=connection_slug,
-                    provider_key=provider_key,
-                    integration_key=integration_key,
-                )
-
         except ConnectionNotFoundError as e:
             raise HTTPException(status_code=404, detail=e.message) from e
         except ConnectionInactiveError as e:

api/oss/src/core/tools/dtos.py

@@ -1,8 +1,9 @@
 from enum import Enum
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, List, Optional, Union
 
+from agenta.sdk.agents.tools import BuiltinToolConfig, GatewayToolConfig
 from agenta.sdk.models.workflows import JsonSchemas
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 
 from oss.src.core.shared.dtos import (
     Header,
@@ -124,6 +125,13 @@ def provider_connection_id(self) -> Optional[str]:
             )
         return None
 
+    @property
+    def is_no_auth(self) -> bool:
+        """True for a no-auth toolkit connection (no Composio auth config/account)."""
+        return bool(
+            self.data and isinstance(self.data, dict) and self.data.get("no_auth")
+        )
+
     @property
     def is_active(self) -> bool:
         """Check if connection is active (not deleted)."""
@@ -227,7 +235,7 @@ class ToolExecutionRequest(BaseModel):
 
     integration_key: str
     action_key: str
-    provider_connection_id: str
+    provider_connection_id: Optional[str] = None  # absent for no-auth toolkits
     user_id: Optional[str] = None
     arguments: Dict[str, Any] = {}
 
@@ -238,3 +246,42 @@ class ToolExecutionResponse(BaseModel):
     data: Optional[Json] = None
     error: Optional[str] = None
     successful: bool = False
+
+
+# ---------------------------------------------------------------------------
+# Agent tools (config references + resolution)
+# ---------------------------------------------------------------------------
+
+# A provider-agnostic list of tool references lives under an agent revision's
+# ``parameters["tools"]``. Each entry is a discriminated union on ``type``: config
+# holds references and display metadata only, never secrets. The backend resolves
+# them into model-ready specs at invoke time (see ToolsService.resolve_agent_tools).
+
+
+AgentBuiltinTool = BuiltinToolConfig
+AgentComposioTool = GatewayToolConfig
+AgentToolReference = Union[BuiltinToolConfig, GatewayToolConfig]
+
+
+class ResolvedAgentTool(BaseModel):
+    """A runnable reference resolved into a model-ready tool spec.
+
+    ``call_ref`` is the ``tools.{provider}.{integration}.{action}.{connection}`` slug
+    the execution bridge sends back to ``POST /tools/call``.
+    """
+
+    name: str
+    description: Optional[str] = None
+    input_schema: Optional[Dict[str, Any]] = None
+    call_ref: str
+
+
+class AgentToolsResolution(BaseModel):
+    """Outcome of resolving an agent's ``tools`` list.
+
+    ``builtins`` pass straight into Pi's ``tools: string[]``; ``custom`` become Pi
+    ``customTools`` whose ``execute`` routes through ``/tools/call``.
+    """
+
+    builtins: List[str] = Field(default_factory=list)
+    custom: List[ResolvedAgentTool] = Field(default_factory=list)

api/oss/src/core/tools/exceptions.py

@@ -40,6 +40,24 @@ def __init__(
         super().__init__(msg)
 
 
+class ActionNotFoundError(ToolsError):
+    """Raised when a catalog action cannot be found for an integration."""
+
+    def __init__(
+        self,
+        *,
+        provider_key: str,
+        integration_key: str,
+        action_key: str,
+    ):
+        self.provider_key = provider_key
+        self.integration_key = integration_key
+        self.action_key = action_key
+        super().__init__(
+            f"Action not found: {provider_key}/{integration_key}/{action_key}"
+        )
+
+
 class ConnectionSlugConflictError(ToolsError):
     """Raised when a connection slug already exists for the integration."""
 

api/oss/src/core/tools/providers/composio/adapter.py

@@ -24,6 +24,18 @@
 COMPOSIO_DEFAULT_API_URL = "https://backend.composio.dev/api/v3"
 
 
+def _is_no_auth_toolkit(toolkit: Dict[str, Any]) -> bool:
+    """A toolkit needs no auth when every auth_config_details entry is NO_AUTH.
+
+    Composio's GET /toolkits/{slug} reports a single ``{"mode": "NO_AUTH"}`` entry
+    for toolkits like ``codeinterpreter`` and the ``composio`` meta-toolkit.
+    """
+    details = toolkit.get("auth_config_details") or []
+    if not details:
+        return False
+    return all((detail.get("mode") or "").upper() == "NO_AUTH" for detail in details)
+
+
 class ComposioToolsAdapter(ComposioCatalogClient, ToolsGatewayInterface):
     """Composio V3 API adapter — uses httpx directly (no SDK).
 
@@ -199,15 +211,25 @@ async def initiate_connection(
                 detail=str(e),
             ) from e
 
-        # Step 2: create an auth config for this integration.
-        # api_key → use_custom_auth; Composio's redirect UI collects the credentials.
-        # oauth / None → use_composio_managed_auth.
         log.info(
             "initiate_connection: integration_key=%s auth_scheme=%r",
             integration_key,
             auth_scheme,
         )
 
+        # No-auth toolkits (e.g. codeinterpreter) reject auth-config creation with a
+        # 400. They need neither an auth config nor a connected account — their tools
+        # execute directly. Return a marked connection the service persists as valid.
+        if _is_no_auth_toolkit(toolkit):
+            return ToolConnectionResponse(
+                provider_connection_id="",
+                redirect_url=None,
+                connection_data={"no_auth": True},
+            )
+
+        # Step 2: create an auth config for this integration.
+        # api_key → use_custom_auth; Composio's redirect UI collects the credentials.
+        # oauth / None → use_composio_managed_auth.
         if auth_scheme == "api_key":
             # Derive Composio authScheme from toolkit's auth_config_details.
             # Fall back to "API_KEY" as the common default.
@@ -388,10 +410,10 @@ async def execute(
             action_key=request.action_key,
         )
 
-        payload: Dict[str, Any] = {
-            "arguments": request.arguments,
-            "connected_account_id": request.provider_connection_id,
-        }
+        payload: Dict[str, Any] = {"arguments": request.arguments}
+        # No-auth toolkits run without a connected account; only send the id when set.
+        if request.provider_connection_id:
+            payload["connected_account_id"] = request.provider_connection_id
         if request.user_id:
             payload["user_id"] = request.user_id