Skip to content

AutoGPT is the vision of accessible AI for everyone, to use and to build on. Our mission is to provide the tools, so that you can focus on what matters.

feat(platform): add external api routes for store search and tool usage (#11463)

Swifty00148f4e3d0c
diff --git a/autogpt_platform/backend/backend/server/external/api.py b/autogpt_platform/backend/backend/server/external/api.py
index ee2cec2fa1..f865d69aef 100644
--- a/autogpt_platform/backend/backend/server/external/api.py
+++ b/autogpt_platform/backend/backend/server/external/api.py
@@ -3,6 +3,7 @@ from fastapi import FastAPI
from backend.monitoring.instrumentation import instrument_fastapi
from backend.server.middleware.security import SecurityHeadersMiddleware
+from .routes.tools import tools_router
from .routes.v1 import v1_router
external_app = FastAPI(
@@ -14,6 +15,7 @@ external_app = FastAPI(
external_app.add_middleware(SecurityHeadersMiddleware)
external_app.include_router(v1_router, prefix="/v1")
+external_app.include_router(tools_router, prefix="/v1")
# Add Prometheus instrumentation
instrument_fastapi(
diff --git a/autogpt_platform/backend/backend/server/external/routes/tools.py b/autogpt_platform/backend/backend/server/external/routes/tools.py
new file mode 100644
index 0000000000..d07bc1bda4
--- /dev/null
+++ b/autogpt_platform/backend/backend/server/external/routes/tools.py
@@ -0,0 +1,239 @@
+"""External API routes for chat tools - stateless HTTP endpoints.
+
+Note: These endpoints use ephemeral sessions that are not persisted to Redis.
+As a result, session-based rate limiting (max_agent_runs, max_agent_schedules)
+is not enforced for external API calls. Each request creates a fresh session
+with zeroed counters. Rate limiting for external API consumers should be
+handled separately (e.g., via API key quotas).
+"""
+
+import logging
+from typing import Any
+
+from fastapi import APIRouter, Security
+from prisma.enums import APIKeyPermission
+from pydantic import BaseModel, Field
+
+from backend.data.api_key import APIKeyInfo
+from backend.server.external.middleware import require_permission
+from backend.server.v2.chat.model import ChatSession
+from backend.server.v2.chat.tools import (
+ find_agent_tool,
+ get_agent_details_tool,
+ get_required_setup_info_tool,
+ run_agent_tool,
+ setup_agent_tool,
+)
+from backend.server.v2.chat.tools.models import ToolResponseBase
+
+logger = logging.getLogger(__name__)
+
+tools_router = APIRouter(prefix="/tools", tags=["tools"])
+
+# Note: We use Security() as a function parameter dependency (api_key: APIKeyInfo = Security(...))
+# rather than in the decorator's dependencies= list. This avoids duplicate permission checks
+# while still enforcing auth AND giving us access to the api_key for extracting user_id.
+
+
+# Request models
+class FindAgentRequest(BaseModel):
+ query: str = Field(..., description="Search query for finding agents")
+
+
+class AgentSlugRequest(BaseModel):
+ username_agent_slug: str = Field(
+ ...,
+ description="The marketplace agent slug (e.g., 'username/agent-name')",
+ )
+
+
+class GetRequiredSetupInfoRequest(AgentSlugRequest):
+ inputs: dict[str, Any] = Field(
+ default_factory=dict,
+ description="The input dictionary you plan to provide",
+ )
+
+
+class RunAgentRequest(AgentSlugRequest):
+ inputs: dict[str, Any] = Field(
+ default_factory=dict,
+ description="Dictionary of input values for the agent",
+ )
+
+
+class SetupAgentRequest(AgentSlugRequest):
+ setup_type: str = Field(
+ default="schedule",
+ description="Type of setup: 'schedule' for cron, 'webhook' for triggers",
+ )
+ name: str = Field(..., description="Name for this setup/schedule")
+ description: str | None = Field(None, description="Description of this setup")
+ cron: str | None = Field(
+ None,
+ description="Cron expression (5 fields: minute hour day month weekday)",
+ )
+ timezone: str = Field(
+ default="UTC",
+ description="IANA timezone (e.g., 'America/New_York', 'UTC')",
+ )
+ inputs: dict[str, Any] = Field(
+ default_factory=dict,
+ description="Dictionary with required inputs for the agent",
+ )
+ webhook_config: dict[str, Any] | None = Field(
+ None,
+ description="Webhook configuration (required if setup_type is 'webhook')",
+ )
+
+
+def _create_ephemeral_session(user_id: str | None) -> ChatSession:
+ """Create an ephemeral session for stateless API requests.
+
+ Note: These sessions are NOT persisted to Redis, so session-based rate
+ limiting (max_agent_runs, max_agent_schedules) will not be enforced
+ across requests.
+ """
+ return ChatSession.new(user_id)
+
+
+@tools_router.post(path="/find-agent")
+async def find_agent(
+ request: FindAgentRequest,
+ api_key: APIKeyInfo = Security(require_permission(APIKeyPermission.USE_TOOLS)),
+) -> dict[str, Any]:
+ """
+ Search for agents in the marketplace based on capabilities and user needs.
+
+ Args:
+ request: Search query for finding agents
+
+ Returns:
+ List of matching agents or no results response
+ """
+ session = _create_ephemeral_session(api_key.user_id)
+ result = await find_agent_tool._execute(
+ user_id=api_key.user_id,
+ session=session,
+ query=request.query,
+ )
+ return _response_to_dict(result)
+
+
+@tools_router.post(path="/get-agent-details")
+async def get_agent_details(
+ request: AgentSlugRequest,
+ api_key: APIKeyInfo = Security(require_permission(APIKeyPermission.USE_TOOLS)),
+) -> dict[str, Any]:
+ """
+ Get detailed information about a specific agent including inputs,
+ credentials required, and execution options.
+
+ Args:
+ request: Agent slug in format 'username/agent-name'
+
+ Returns:
+ Detailed agent information
+ """
+ session = _create_ephemeral_session(api_key.user_id)
+ result = await get_agent_details_tool._execute(
+ user_id=api_key.user_id,
+ session=session,
+ username_agent_slug=request.username_agent_slug,
+ )
+ return _response_to_dict(result)
+
+
+@tools_router.post(path="/get-required-setup-info")
+async def get_required_setup_info(
+ request: GetRequiredSetupInfoRequest,
+ api_key: APIKeyInfo = Security(require_permission(APIKeyPermission.USE_TOOLS)),
+) -> dict[str, Any]:
+ """
+ Check if an agent can be set up with the provided input data and credentials.
+ Validates that you have all required inputs before running or scheduling.
+
+ Args:
+ request: Agent slug and optional inputs to validate
+
+ Returns:
+ Setup requirements and user readiness status
+ """
+ session = _create_ephemeral_session(api_key.user_id)
+ result = await get_required_setup_info_tool._execute(
+ user_id=api_key.user_id,
+ session=session,
+ username_agent_slug=request.username_agent_slug,
+ inputs=request.inputs,
+ )
+ return _response_to_dict(result)
+
+
+@tools_router.post(path="/run-agent")
+async def run_agent(
+ request: RunAgentRequest,
+ api_key: APIKeyInfo = Security(require_permission(APIKeyPermission.USE_TOOLS)),
+) -> dict[str, Any]:
+ """
+ Run an agent immediately (one-off manual execution).
+
+ IMPORTANT: Before calling this endpoint, first call get-agent-details
+ to determine what inputs are required.
+
+ Args:
+ request: Agent slug and input values
+
+ Returns:
+ Execution started response with execution_id
+ """
+ session = _create_ephemeral_session(api_key.user_id)
+ result = await run_agent_tool._execute(
+ user_id=api_key.user_id,
+ session=session,
+ username_agent_slug=request.username_agent_slug,
+ inputs=request.inputs,
+ )
+ return _response_to_dict(result)
+
+
+@tools_router.post(path="/setup-agent")
+async def setup_agent(
+ request: SetupAgentRequest,
+ api_key: APIKeyInfo = Security(require_permission(APIKeyPermission.USE_TOOLS)),
+) -> dict[str, Any]:
+ """
+ Set up an agent with credentials and configure it for scheduled execution
+ or webhook triggers.
+
+ For SCHEDULED execution:
+ - Cron format: "minute hour day month weekday"
+ - Examples: "0 9 * * 1-5" (9am weekdays), "0 0 * * *" (daily at midnight)
+ - Timezone: Use IANA timezone names like "America/New_York", "Europe/London"
+
+ For WEBHOOK triggers:
+ - The agent will be triggered by external events
+
+ Args:
+ request: Agent slug, setup type, schedule configuration, and inputs
+
+ Returns:
+ Schedule or webhook created response
+ """
+ session = _create_ephemeral_session(api_key.user_id)
+ result = await setup_agent_tool._execute(
+ user_id=api_key.user_id,
+ session=session,
+ username_agent_slug=request.username_agent_slug,
+ setup_type=request.setup_type,
+ name=request.name,
+ description=request.description,
+ cron=request.cron,
+ timezone=request.timezone,
+ inputs=request.inputs,
+ webhook_config=request.webhook_config,
+ )
+ return _response_to_dict(result)
+
+
+def _response_to_dict(result: ToolResponseBase) -> dict[str, Any]:
+ """Convert a tool response to a dictionary for JSON serialization."""
+ return result.model_dump()
diff --git a/autogpt_platform/backend/backend/server/external/routes/v1.py b/autogpt_platform/backend/backend/server/external/routes/v1.py
index d4175b5d9d..1b2840acf9 100644
--- a/autogpt_platform/backend/backend/server/external/routes/v1.py
+++ b/autogpt_platform/backend/backend/server/external/routes/v1.py
@@ -1,12 +1,15 @@
import logging
+import urllib.parse
from collections import defaultdict
-from typing import Annotated, Any, Optional, Sequence
+from typing import Annotated, Any, Literal, Optional, Sequence
from fastapi import APIRouter, Body, HTTPException, Security
from prisma.enums import AgentExecutionStatus, APIKeyPermission
from typing_extensions import TypedDict
import backend.data.block
+import backend.server.v2.store.cache as store_cache
+import backend.server.v2.store.model as store_model
from backend.data import execution as execution_db
from backend.data import graph as graph_db
from backend.data.api_key import APIKeyInfo
@@ -144,3 +147,149 @@ async def get_graph_execution_results(
else None
),
)
+
+
+##############################################
+############### Store Endpoints ##############
+##############################################
+
+
+@v1_router.get(
+ path="/store/agents",
+ tags=["store"],
+ dependencies=[Security(require_permission(APIKeyPermission.READ_STORE))],
+ response_model=store_model.StoreAgentsResponse,
+)
+async def get_store_agents(
+ featured: bool = False,
+ creator: str | None = None,
+ sorted_by: Literal["rating", "runs", "name", "updated_at"] | None = None,
+ search_query: str | None = None,
+ category: str | None = None,
+ page: int = 1,
+ page_size: int = 20,
+) -> store_model.StoreAgentsResponse:
+ """
+ Get a paginated list of agents from the store with optional filtering and sorting.
+
+ Args:
+ featured: Filter to only show featured agents
+ creator: Filter agents by creator username
+ sorted_by: Sort agents by "runs", "rating", "name", or "updated_at"
+ search_query: Search agents by name, subheading and description
+ category: Filter agents by category
+ page: Page number for pagination (default 1)
+ page_size: Number of agents per page (default 20)
+
+ Returns:
+ StoreAgentsResponse: Paginated list of agents matching the filters
+ """
+ if page < 1:
+ raise HTTPException(status_code=422, detail="Page must be greater than 0")
+
+ if page_size < 1:
+ raise HTTPException(status_code=422, detail="Page size must be greater than 0")
+
+ agents = await store_cache._get_cached_store_agents(
+ featured=featured,
+ creator=creator,
+ sorted_by=sorted_by,
+ search_query=search_query,
+ category=category,
+ page=page,
+ page_size=page_size,
+ )
+ return agents
+
+
+@v1_router.get(
+ path="/store/agents/{username}/{agent_name}",
+ tags=["store"],
+ dependencies=[Security(require_permission(APIKeyPermission.READ_STORE))],
+ response_model=store_model.StoreAgentDetails,
+)
+async def get_store_agent(
+ username: str,
+ agent_name: str,
+) -> store_model.StoreAgentDetails:
+ """
+ Get details of a specific store agent by username and agent name.
+
+ Args:
+ username: Creator's username
+ agent_name: Name/slug of the agent
+
+ Returns:
+ StoreAgentDetails: Detailed information about the agent
+ """
+ username = urllib.parse.unquote(username).lower()
+ agent_name = urllib.parse.unquote(agent_name).lower()
+ agent = await store_cache._get_cached_agent_details(
+ username=username, agent_name=agent_name
+ )
+ return agent
+
+
+@v1_router.get(
+ path="/store/creators",
+ tags=["store"],
+ dependencies=[Security(require_permission(APIKeyPermission.READ_STORE))],
+ response_model=store_model.CreatorsResponse,
+)
+async def get_store_creators(
+ featured: bool = False,
+ search_query: str | None = None,
+ sorted_by: Literal["agent_rating", "agent_runs", "num_agents"] | None = None,
+ page: int = 1,
+ page_size: int = 20,
+) -> store_model.CreatorsResponse:
+ """
+ Get a paginated list of store creators with optional filtering and sorting.
+
+ Args:
+ featured: Filter to only show featured creators
+ search_query: Search creators by profile description
+ sorted_by: Sort by "agent_rating", "agent_runs", or "num_agents"
+ page: Page number for pagination (default 1)
+ page_size: Number of creators per page (default 20)
+
+ Returns:
+ CreatorsResponse: Paginated list of creators matching the filters
+ """
+ if page < 1:
+ raise HTTPException(status_code=422, detail="Page must be greater than 0")
+
+ if page_size < 1:
+ raise HTTPException(status_code=422, detail="Page size must be greater than 0")
+
+ creators = await store_cache._get_cached_store_creators(
+ featured=featured,
+ search_query=search_query,
+ sorted_by=sorted_by,
+ page=page,
+ page_size=page_size,
+ )
+ return creators
+
+
+@v1_router.get(
+ path="/store/creators/{username}",
+ tags=["store"],
+ dependencies=[Security(require_permission(APIKeyPermission.READ_STORE))],
+ response_model=store_model.CreatorDetails,
+)
+async def get_store_creator(
+ username: str,
+) -> store_model.CreatorDetails:
+ """
+ Get details of a specific store creator by username.
+
+ Args:
+ username: Creator's username
+
+ Returns:
+ CreatorDetails: Detailed information about the creator
+ """
+ username = urllib.parse.unquote(username).lower()
+ creator = await store_cache._get_cached_creator_details(username=username)
+ return creator
diff --git a/autogpt_platform/backend/backend/server/v2/chat/routes.py b/autogpt_platform/backend/backend/server/v2/chat/routes.py
index ac82deb398..86bcf861c0 100644
--- a/autogpt_platform/backend/backend/server/v2/chat/routes.py
+++ b/autogpt_platform/backend/backend/server/v2/chat/routes.py
@@ -64,7 +64,10 @@ async def create_session(
CreateSessionResponse: Details of the created session.
"""
- logger.info(f"Creating session with user_id: {user_id}")
+ logger.info(
+ f"Creating session with user_id: "
+ f"...{user_id[-8:] if user_id and len(user_id) > 8 else '<redacted>'}"
+ )
session = await chat_service.create_chat_session(user_id)
diff --git a/autogpt_platform/backend/backend/server/v2/library/db.py b/autogpt_platform/backend/backend/server/v2/library/db.py
index 1609929ecd..c8e7d0341b 100644
--- a/autogpt_platform/backend/backend/server/v2/library/db.py
+++ b/autogpt_platform/backend/backend/server/v2/library/db.py
@@ -396,8 +396,7 @@ async def create_library_agent(
DatabaseError: If there's an error during creation or if image generation fails.
"""
logger.info(
- f"Creating library agent for graph #{graph.id} v{graph.version}; "
- f"user #{user_id}"
+ f"Creating library agent for graph #{graph.id} v{graph.version}; user:<redacted>"
)
graph_entries = (
[graph, *graph.sub_graphs] if create_library_agents_for_sub_graphs else [graph]
diff --git a/autogpt_platform/backend/migrations/20251126141555_add_api_key_store_permissions/migration.sql b/autogpt_platform/backend/migrations/20251126141555_add_api_key_store_permissions/migration.sql
new file mode 100644
index 0000000000..c921244c99
--- /dev/null
+++ b/autogpt_platform/backend/migrations/20251126141555_add_api_key_store_permissions/migration.sql
@@ -0,0 +1,2 @@
+-- AlterEnum
+ALTER TYPE "APIKeyPermission" ADD VALUE 'READ_STORE';
diff --git a/autogpt_platform/backend/migrations/20251127092500_add_api_key_tools_permission/migration.sql b/autogpt_platform/backend/migrations/20251127092500_add_api_key_tools_permission/migration.sql
new file mode 100644
index 0000000000..11549032e9
--- /dev/null
+++ b/autogpt_platform/backend/migrations/20251127092500_add_api_key_tools_permission/migration.sql
@@ -0,0 +1,2 @@
+-- AlterEnum
+ALTER TYPE "APIKeyPermission" ADD VALUE 'USE_TOOLS';
diff --git a/autogpt_platform/backend/schema.prisma b/autogpt_platform/backend/schema.prisma
index ca015a3cb9..7ebfa54905 100644
--- a/autogpt_platform/backend/schema.prisma
+++ b/autogpt_platform/backend/schema.prisma
@@ -910,6 +910,8 @@ enum APIKeyPermission {
READ_GRAPH // Can get graph versions and details
EXECUTE_BLOCK // Can execute individual blocks
READ_BLOCK // Can get block information
+ READ_STORE // Can read store agents and creators
+ USE_TOOLS // Can use chat tools via external API
}
model APIKey {
diff --git a/autogpt_platform/frontend/src/app/api/openapi.json b/autogpt_platform/frontend/src/app/api/openapi.json
index 99db625c2f..5b4ebaa547 100644
--- a/autogpt_platform/frontend/src/app/api/openapi.json
+++ b/autogpt_platform/frontend/src/app/api/openapi.json
@@ -5291,7 +5291,14 @@
},
"APIKeyPermission": {
"type": "string",
- "enum": ["EXECUTE_GRAPH", "READ_GRAPH", "EXECUTE_BLOCK", "READ_BLOCK"],
+ "enum": [
+ "EXECUTE_GRAPH",
+ "READ_GRAPH",
+ "EXECUTE_BLOCK",
+ "READ_BLOCK",
+ "READ_STORE",
+ "USE_TOOLS"
+ ],
"title": "APIKeyPermission"
},
"APIKeyStatus": {