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.

fix(backend/copilot): keep credential setup inline on run and schedule paths (#12739)

Zamil Majdy55fe900650d5
diff --git a/autogpt_platform/backend/backend/copilot/sdk/agent_generation_guide.md b/autogpt_platform/backend/backend/copilot/sdk/agent_generation_guide.md
index 28b6f1c7dc..35b4a348b9 100644
--- a/autogpt_platform/backend/backend/copilot/sdk/agent_generation_guide.md
+++ b/autogpt_platform/backend/backend/copilot/sdk/agent_generation_guide.md
@@ -135,6 +135,12 @@ inputs or see outputs. NEVER skip them.
output to the consuming block's input.
- **Credentials**: Do NOT require credentials upfront. Users configure
credentials later in the platform UI after the agent is saved.
+ Do NOT call `create_agent` / `edit_agent` to handle credentials, and
+ do NOT redirect to the Builder. Credentials are set up inline as part
+ of the run flow: `run_agent` surfaces the setup card automatically
+ when credentials are missing or invalid, then proceeds to execute once
+ connected. Use `connect_integration` only for a standalone provider
+ setup not tied to a specific run.
- **Node spacing**: Position nodes with at least 800 X-units between them.
- **Nested properties**: Use `parentField_#_childField` notation in link
sink_name/source_name to access nested object fields.
diff --git a/autogpt_platform/backend/backend/copilot/tools/create_agent.py b/autogpt_platform/backend/backend/copilot/tools/create_agent.py
index 5c00f555c8..7710cbafca 100644
--- a/autogpt_platform/backend/backend/copilot/tools/create_agent.py
+++ b/autogpt_platform/backend/backend/copilot/tools/create_agent.py
@@ -24,7 +24,7 @@ class CreateAgentTool(BaseTool):
def description(self) -> str:
return (
"Create a new agent from JSON (nodes + links). Validates, auto-fixes, and saves. "
- "Before calling, search for existing agents with find_library_agent."
+ "If you haven't already, call get_agent_building_guide first."
)
@property
diff --git a/autogpt_platform/backend/backend/copilot/tools/edit_agent.py b/autogpt_platform/backend/backend/copilot/tools/edit_agent.py
index 59081b1527..0282070453 100644
--- a/autogpt_platform/backend/backend/copilot/tools/edit_agent.py
+++ b/autogpt_platform/backend/backend/copilot/tools/edit_agent.py
@@ -24,7 +24,7 @@ class EditAgentTool(BaseTool):
def description(self) -> str:
return (
"Edit an existing agent. Validates, auto-fixes, and saves. "
- "Before calling, search for existing agents with find_library_agent."
+ "If you haven't already, call get_agent_building_guide first."
)
@property
diff --git a/autogpt_platform/backend/backend/copilot/tools/run_agent.py b/autogpt_platform/backend/backend/copilot/tools/run_agent.py
index 5e18120c38..d29869c3fe 100644
--- a/autogpt_platform/backend/backend/copilot/tools/run_agent.py
+++ b/autogpt_platform/backend/backend/copilot/tools/run_agent.py
@@ -13,8 +13,9 @@ from backend.data.execution import ExecutionStatus
from backend.data.graph import GraphModel
from backend.data.model import CredentialsMetaInput
from backend.executor import utils as execution_utils
+from backend.executor.utils import is_credential_validation_error_message
from backend.util.clients import get_scheduler_client
-from backend.util.exceptions import DatabaseError, NotFoundError
+from backend.util.exceptions import DatabaseError, GraphValidationError, NotFoundError
from backend.util.timezone_utils import (
convert_utc_time_to_user_timezone,
get_user_timezone_or_utc,
@@ -106,7 +107,9 @@ class RunAgentTool(BaseTool):
@property
def description(self) -> str:
return (
- "Run or schedule an agent. Automatically checks inputs and credentials. "
+ "Run or schedule an agent. Automatically checks inputs and credentials "
+ "and surfaces the inline credentials-setup card if anything is missing — "
+ "do NOT redirect to the Builder for credential setup. "
"Identify by username_agent_slug ('user/agent') or library_agent_id. "
"For scheduling, provide schedule_name + cron."
)
@@ -362,6 +365,117 @@ class RunAgentTool(BaseTool):
trigger_info=trigger_info,
)
+ def _build_setup_requirements_from_validation_error(
+ self,
+ graph: GraphModel,
+ error: GraphValidationError,
+ session_id: str,
+ ) -> SetupRequirementsResponse | None:
+ """Convert a credential-related ``GraphValidationError`` into
+ the inline ``SetupRequirementsResponse`` the frontend renders.
+
+ Returns ``None`` if *error* isn't credential-related — the
+ caller should then fall back to a plain text error.
+
+ This is the race-condition path (prereq check passed → creds
+ deleted/invalidated → executor/scheduler raised). All credential
+ fields are shown as missing so the user sees exactly which
+ accounts to reconnect.
+ """
+ # Only surface the credential-setup UI when ALL errors are credential-
+ # related. If there are also structural errors (missing inputs, invalid
+ # node config), fall through to the plain error path so those errors are
+ # not hidden from the user — they would surface on the next run attempt
+ # after the credential fix, creating a confusing two-step failure.
+ #
+ # Collect all error messages once so we can check both emptiness and
+ # uniformity without iterating twice. all() returns True vacuously on
+ # an empty sequence, so the ``not messages`` guard is essential — an
+ # empty node_errors dict must fall through to the plain error path.
+ messages = [
+ msg
+ for node_errors in error.node_errors.values()
+ for msg in node_errors.values()
+ ]
+ if not messages or not all(
+ is_credential_validation_error_message(msg) for msg in messages
+ ):
+ return None
+
+ # Show ALL credential fields as missing — in the race case the
+ # previously-matched credentials have since become invalid, so
+ # the user needs to reconnect all of them. Passing ``None``
+ # means no field is treated as "already connected".
+ #
+ # Trade-off: we could narrow to only the failing nodes in
+ # ``error.node_errors``, but we cannot trust the old credential
+ # mapping (those creds were valid at prereq time but are now
+ # gone/invalid), so showing all is safer than showing a partial
+ # list that might still contain broken entries. The user sees
+ # every account that may need attention in a single card.
+ credentials_dict = build_missing_credentials_from_graph(graph, None)
+ return SetupRequirementsResponse(
+ message=(
+ f"Agent '{graph.name}' has credentials that are missing or "
+ "no longer valid. Please connect the required account(s) "
+ "and try again."
+ ),
+ session_id=session_id,
+ setup_info=SetupInfo(
+ agent_id=graph.id,
+ agent_name=graph.name,
+ user_readiness=UserReadiness(
+ has_all_credentials=False,
+ missing_credentials=credentials_dict,
+ ready_to_run=False,
+ ),
+ requirements={
+ "credentials": list(credentials_dict.values()),
+ "inputs": get_inputs_from_schema(graph.input_schema),
+ "execution_modes": self._get_execution_modes(graph),
+ },
+ ),
+ graph_id=graph.id,
+ graph_version=graph.version,
+ )
+
+ def _handle_graph_validation_race(
+ self,
+ error: GraphValidationError,
+ graph: GraphModel,
+ user_id: str,
+ session_id: str,
+ action_verb: str,
+ ) -> ToolResponseBase:
+ """Handle a ``GraphValidationError`` that slipped past the prereq check.
+
+ Shared by both the run and schedule paths — logs the race, attempts to
+ rebuild the credential setup card, and falls back to a user-friendly
+ ``ErrorResponse`` when the error is structural (not credential-related).
+ """
+ logger.warning(
+ "Race: GraphValidationError after prereq check passed "
+ "(user_id=%s graph_id=%s failing_fields=%s)",
+ user_id,
+ graph.id,
+ {node_id: list(fields) for node_id, fields in error.node_errors.items()},
+ )
+ creds_setup = self._build_setup_requirements_from_validation_error(
+ graph=graph,
+ error=error,
+ session_id=session_id,
+ )
+ if creds_setup is not None:
+ return creds_setup
+ return ErrorResponse(
+ message=(
+ f"Agent has configuration issues that need to be resolved "
+ f"before {action_verb}: {error}"
+ ),
+ error="graph_validation_failed",
+ session_id=session_id,
+ )
+
async def _check_prerequisites(
self,
graph: GraphModel,
@@ -495,14 +609,29 @@ class RunAgentTool(BaseTool):
# Get or create library agent
library_agent = await get_or_create_library_agent(graph, user_id)
- # Execute
- execution = await execution_utils.add_graph_execution(
- graph_id=library_agent.graph_id,
- user_id=user_id,
- inputs=inputs,
- graph_credentials_inputs=graph_credentials,
- dry_run=dry_run,
- )
+ # Execute — ``add_graph_execution`` ultimately calls
+ # ``validate_and_construct_node_execution_input`` which raises
+ # ``GraphValidationError`` on missing/invalid credentials. The
+ # common case is caught by ``_check_prerequisites`` above, but
+ # defend against a race (creds deleted between prereq and
+ # execute) by turning credential errors back into the inline
+ # setup card.
+ try:
+ execution = await execution_utils.add_graph_execution(
+ graph_id=library_agent.graph_id,
+ user_id=user_id,
+ inputs=inputs,
+ graph_credentials_inputs=graph_credentials,
+ dry_run=dry_run,
+ )
+ except GraphValidationError as e:
+ return self._handle_graph_validation_race(
+ error=e,
+ graph=graph,
+ user_id=user_id,
+ session_id=session_id,
+ action_verb="running",
+ )
# Track successful run (dry runs don't count against the session limit)
if not dry_run:
@@ -665,17 +794,34 @@ class RunAgentTool(BaseTool):
user = await user_db().get_user_by_id(user_id)
user_timezone = get_user_timezone_or_utc(user.timezone if user else timezone)
- # Create schedule
- result = await get_scheduler_client().add_execution_schedule(
- user_id=user_id,
- graph_id=library_agent.graph_id,
- graph_version=library_agent.graph_version,
- name=schedule_name,
- cron=cron,
- input_data=inputs,
- input_credentials=graph_credentials,
- user_timezone=user_timezone,
- )
+ # Create schedule — the scheduler re-validates credentials via
+ # ``validate_and_construct_node_execution_input`` and will raise
+ # ``GraphValidationError`` if any required credential is missing
+ # or invalid. ``_check_prerequisites`` already catches the
+ # common case at the top of ``_execute``, but a race (creds
+ # deleted between prereq check and scheduler call) or any other
+ # validation drift could hit here — turn credential errors back
+ # into the inline ``SetupRequirementsResponse`` so the user
+ # sees the credential setup card instead of a generic error.
+ try:
+ result = await get_scheduler_client().add_execution_schedule(
+ user_id=user_id,
+ graph_id=library_agent.graph_id,
+ graph_version=library_agent.graph_version,
+ name=schedule_name,
+ cron=cron,
+ input_data=inputs,
+ input_credentials=graph_credentials,
+ user_timezone=user_timezone,
+ )
+ except GraphValidationError as e:
+ return self._handle_graph_validation_race(
+ error=e,
+ graph=graph,
+ user_id=user_id,
+ session_id=session_id,
+ action_verb="scheduling",
+ )
# Convert next_run_time to user timezone for display
if result.next_run_time:
diff --git a/autogpt_platform/backend/backend/copilot/tools/run_agent_test.py b/autogpt_platform/backend/backend/copilot/tools/run_agent_test.py
index efb1e32ab9..3c8b89b88e 100644
--- a/autogpt_platform/backend/backend/copilot/tools/run_agent_test.py
+++ b/autogpt_platform/backend/backend/copilot/tools/run_agent_test.py
@@ -4,12 +4,16 @@ from unittest.mock import AsyncMock, patch
import orjson
import pytest
+from backend.executor.utils import is_credential_validation_error_message
+from backend.util.exceptions import GraphValidationError
+
from ._test_data import (
make_session,
setup_firecrawl_test_data,
setup_llm_test_data,
setup_test_data,
)
+from .models import SetupRequirementsResponse
from .run_agent import RunAgentTool
# This is so the formatter doesn't remove the fixture imports
@@ -453,3 +457,365 @@ async def test_run_agent_rejects_unknown_input_fields(setup_test_data):
}
assert "inputs" in result_data # Contains the valid schema
assert "Agent was not executed" in result_data["message"]
+
+
+# ---------------------------------------------------------------------------
+# Credential-race-condition handling
+#
+# ``_check_prerequisites`` already catches the common "missing creds" case
+# at the top of ``_execute``, but the scheduler / executor re-validates and
+# can raise ``GraphValidationError`` if creds were deleted between the
+# prereq check and the actual call. The tool turns these credential
+# errors back into the inline ``SetupRequirementsResponse`` so the user
+# still gets the credential setup card instead of a generic error.
+# ---------------------------------------------------------------------------
+
+
+def test_is_credential_validation_error_message_recognises_credential_strings():
+ """Shared helper should match all credential error strings emitted by
+ ``backend.executor.utils._validate_node_input_credentials``."""
+ assert is_credential_validation_error_message("These credentials are required")
+ assert is_credential_validation_error_message("THESE CREDENTIALS ARE REQUIRED")
+ assert is_credential_validation_error_message("Invalid credentials: not found")
+ assert is_credential_validation_error_message("Credentials not available: github")
+ assert is_credential_validation_error_message("Unknown credentials #abc-123")
+
+
+def test_is_credential_validation_error_message_rejects_non_credential_strings():
+ """Shared helper should ignore unrelated graph validation messages."""
+ assert not is_credential_validation_error_message("Input field 'url' is required")
+ assert not is_credential_validation_error_message("Block configuration invalid")
+ assert not is_credential_validation_error_message("")
+ assert not is_credential_validation_error_message("credentials are fine")
+
+
[email protected](loop_scope="session")
+async def test_build_setup_requirements_from_credential_validation_error(
+ setup_firecrawl_test_data,
+):
+ """When the scheduler raises a credential-flavoured GraphValidationError,
+ the helper should rebuild the inline setup card from the graph schema."""
+ graph = setup_firecrawl_test_data["graph"]
+ tool = RunAgentTool()
+
+ # Construct an error in the same shape the executor produces.
+ error = GraphValidationError(
+ message="Graph is invalid",
+ node_errors={"some-node-id": {"credentials": "These credentials are required"}},
+ )
+
+ # Race path: all credential fields shown as missing.
+ response = tool._build_setup_requirements_from_validation_error(
+ graph=graph,
+ error=error,
+ session_id="test-session",
+ )
+
+ assert isinstance(response, SetupRequirementsResponse)
+ assert response.graph_id == graph.id
+ assert response.graph_version == graph.version
+ assert response.setup_info.user_readiness.has_all_credentials is False
+ assert response.setup_info.user_readiness.ready_to_run is False
+ # The firecrawl fixture defines exactly one credential field (firecrawl
+ # API key). Pin the count so fixture drift is caught immediately.
+ missing_credentials = response.setup_info.user_readiness.missing_credentials
+ assert len(missing_credentials) == 1, (
+ f"Expected exactly 1 credential from the firecrawl fixture, "
+ f"got {len(missing_credentials)}: {list(missing_credentials.keys())}"
+ )
+ assert "credentials" in response.message.lower()
+ # Message must be action-neutral: this helper is shared by the run
+ # path and the schedule path, so hardcoding "scheduling again" would
+ # mislead users on the run path.
+ assert "scheduling again" not in response.message.lower()
+
+
[email protected](loop_scope="session")
+async def test_build_setup_requirements_shows_all_creds_missing_in_race(
+ setup_firecrawl_test_data,
+):
+ """In the race scenario (prereq passed → creds deleted → executor raised),
+ the helper must show ALL credential fields as missing so the user knows
+ which accounts need to be reconnected — not an empty missing_credentials map."""
+ graph = setup_firecrawl_test_data["graph"]
+ tool = RunAgentTool()
+
+ error = GraphValidationError(
+ message="Graph is invalid",
+ node_errors={"some-node-id": {"credentials": "These credentials are required"}},
+ )
+
+ response = tool._build_setup_requirements_from_validation_error(
+ graph=graph,
+ error=error,
+ session_id="test-session",
+ )
+
+ assert isinstance(response, SetupRequirementsResponse)
+ # missing_credentials and requirements["credentials"] must both be non-empty
+ # and share the same field keys (both come from build_missing_credentials_from_graph).
+ missing = response.setup_info.user_readiness.missing_credentials
+ requirements_creds = response.setup_info.requirements["credentials"]
+ assert len(missing) > 0
+ assert set(missing.keys()) == {c["id"] for c in requirements_creds}
+
+
[email protected](loop_scope="session")
+async def test_build_setup_requirements_returns_none_for_empty_node_errors(
+ setup_firecrawl_test_data,
+):
+ """Empty node_errors={} should fall through (helper returns None) because
+ there are no messages to classify as credential-related."""
+ graph = setup_firecrawl_test_data["graph"]
+ tool = RunAgentTool()
+
+ error = GraphValidationError(
+ message="Graph is invalid",
+ node_errors={},
+ )
+
+ response = tool._build_setup_requirements_from_validation_error(
+ graph=graph,
+ error=error,
+ session_id="test-session",
+ )
+
+ assert response is None
+
+
[email protected](loop_scope="session")
+async def test_build_setup_requirements_returns_none_for_non_credential_error(
+ setup_firecrawl_test_data,
+):
+ """Non-credential validation errors should fall through to the plain
+ ErrorResponse path (helper returns None)."""
+ graph = setup_firecrawl_test_data["graph"]
+ tool = RunAgentTool()
+
+ error = GraphValidationError(
+ message="Graph is invalid",
+ node_errors={"some-node-id": {"url": "Input field 'url' is required"}},
+ )
+
+ response = tool._build_setup_requirements_from_validation_error(
+ graph=graph,
+ error=error,
+ session_id="test-session",
+ )
+
+ assert response is None
+
+
[email protected](loop_scope="session")
+async def test_build_setup_requirements_returns_none_for_mixed_errors(
+ setup_firecrawl_test_data,
+):
+ """Mixed credential + structural errors must fall through to the plain
+ ErrorResponse path so structural errors are not hidden from the user."""
+ graph = setup_firecrawl_test_data["graph"]
+ tool = RunAgentTool()
+
+ error = GraphValidationError(
+ message="Graph is invalid",
+ node_errors={
+ "node-a": {"credentials": "These credentials are required"},
+ "node-b": {"url": "Input field 'url' is required"},
+ },
+ )
+
+ response = tool._build_setup_requirements_from_validation_error(
+ graph=graph,
+ error=error,
+ session_id="test-session",
+ )
+
+ assert response is None
+
+
[email protected](loop_scope="session")
+async def test_run_agent_schedule_credential_race_returns_setup_card(
+ setup_test_data,
+):
+ """End-to-end: if the scheduler raises a credential GraphValidationError
+ after _check_prerequisites passed, the user should still see the
+ inline credentials-setup card (not a generic error)."""
+ user = setup_test_data["user"]
+ store_submission = setup_test_data["store_submission"]
+
+ tool = RunAgentTool()
+ agent_marketplace_id = f"{user.email.split('@')[0]}/{store_submission.slug}"
+ session = make_session(user_id=user.id)
+
+ fake_scheduler = AsyncMock()
+ fake_scheduler.add_execution_schedule.side_effect = GraphValidationError(
+ message="Graph is invalid",
+ node_errors={"some-node-id": {"credentials": "These credentials are required"}},
+ )
+
+ with patch(
+ "backend.copilot.tools.run_agent.get_scheduler_client",
+ return_value=fake_scheduler,
+ ):
+ response = await tool.execute(
+ user_id=user.id,
+ session_id=str(uuid.uuid4()),
+ tool_call_id=str(uuid.uuid4()),
+ username_agent_slug=agent_marketplace_id,
+ inputs={"test_input": "value"},
+ schedule_name="My Schedule",
+ cron="0 9 * * *",
+ dry_run=False,
+ session=session,
+ )
+
+ assert response is not None
+ assert isinstance(response.output, str)
+ result_data = orjson.loads(response.output)
+
+ # Should surface the inline credential card, NOT a generic error or a
+ # link redirecting to the Builder.
+ assert result_data.get("type") == "setup_requirements"
+ assert "setup_info" in result_data
+ assert result_data["setup_info"]["user_readiness"]["ready_to_run"] is False
+ # Verify that missing_credentials is present (may be empty for graphs
+ # where the DB-stored credential schema doesn't surface input-embedded
+ # credentials — the important thing is that the card renders instead of
+ # a generic error or Builder redirect).
+ assert "missing_credentials" in result_data["setup_info"]["user_readiness"]
+
+
[email protected](loop_scope="session")
+async def test_run_agent_schedule_structural_error_returns_error_response(
+ setup_test_data,
+):
+ """End-to-end: if the scheduler raises a GraphValidationError with purely
+ structural (non-credential) errors after _check_prerequisites passed, the
+ tool must return an ErrorResponse with error='graph_validation_failed' —
+ not a setup_requirements card."""
+ user = setup_test_data["user"]
+ store_submission = setup_test_data["store_submission"]
+
+ tool = RunAgentTool()
+ agent_marketplace_id = f"{user.email.split('@')[0]}/{store_submission.slug}"
+ session = make_session(user_id=user.id)
+
+ fake_scheduler = AsyncMock()
+ fake_scheduler.add_execution_schedule.side_effect = GraphValidationError(
+ message="Graph is invalid",
+ node_errors={"some-node-id": {"url": "Input field 'url' is required"}},
+ )
+
+ with patch(
+ "backend.copilot.tools.run_agent.get_scheduler_client",
+ return_value=fake_scheduler,
+ ):
+ response = await tool.execute(
+ user_id=user.id,
+ session_id=str(uuid.uuid4()),
+ tool_call_id=str(uuid.uuid4()),
+ username_agent_slug=agent_marketplace_id,
+ inputs={"test_input": "value"},
+ schedule_name="My Schedule",
+ cron="0 9 * * *",
+ dry_run=False,
+ session=session,
+ )
+
+ assert response is not None
+ assert isinstance(response.output, str)
+ result_data = orjson.loads(response.output)
+
+ # Structural errors must fall through to the plain error path — the
+ # user should see the validation error, not the credential setup card.
+ assert result_data.get("error") == "graph_validation_failed"
+ assert result_data.get("type") != "setup_requirements"
+
+
[email protected](loop_scope="session")
+async def test_run_agent_execution_credential_race_returns_setup_card(
+ setup_test_data,
+):
+ """End-to-end: if the executor raises a credential GraphValidationError
+ after _check_prerequisites passed, the user should still see the
+ inline credentials-setup card (not a generic error)."""
+ user = setup_test_data["user"]
+ store_submission = setup_test_data["store_submission"]
+
+ tool = RunAgentTool()
+ agent_marketplace_id = f"{user.email.split('@')[0]}/{store_submission.slug}"
+ session = make_session(user_id=user.id)
+
+ with patch(
+ "backend.copilot.tools.run_agent.execution_utils.add_graph_execution",
+ new_callable=AsyncMock,
+ side_effect=GraphValidationError(
+ message="Graph is invalid",
+ node_errors={
+ "some-node-id": {"credentials": "These credentials are required"}
+ },
+ ),
+ ):
+ response = await tool.execute(
+ user_id=user.id,
+ session_id=str(uuid.uuid4()),
+ tool_call_id=str(uuid.uuid4()),
+ username_agent_slug=agent_marketplace_id,
+ inputs={"test_input": "value"},
+ dry_run=False,
+ session=session,
+ )
+
+ assert response is not None
+ assert isinstance(response.output, str)
+ result_data = orjson.loads(response.output)
+
+ # Should surface the inline credential card, NOT a generic error or a
+ # link redirecting to the Builder.
+ assert result_data.get("type") == "setup_requirements"
+ assert "setup_info" in result_data
+ assert result_data["setup_info"]["user_readiness"]["ready_to_run"] is False
+
+
[email protected](loop_scope="session")
+async def test_run_agent_execution_structural_error_returns_error_response(
+ setup_test_data,
+):
+ """End-to-end: if the executor raises a GraphValidationError with purely
+ structural (non-credential) errors after _check_prerequisites passed, the
+ tool must return an ErrorResponse with error='graph_validation_failed' —
+ not a setup_requirements card and not a silent swallow."""
+ user = setup_test_data["user"]
+ store_submission = setup_test_data["store_submission"]
+
+ tool = RunAgentTool()
+ agent_marketplace_id = f"{user.email.split('@')[0]}/{store_submission.slug}"
+ session = make_session(user_id=user.id)
+
+ with patch(
+ "backend.copilot.tools.run_agent.execution_utils.add_graph_execution",
+ new_callable=AsyncMock,
+ side_effect=GraphValidationError(
+ message="Graph is invalid",
+ node_errors={
+ "some-node-id": {"url": "Input field 'url' is required"},
+ },
+ ),
+ ):
+ response = await tool.execute(
+ user_id=user.id,
+ session_id=str(uuid.uuid4()),
+ tool_call_id=str(uuid.uuid4()),
+ username_agent_slug=agent_marketplace_id,
+ inputs={"test_input": "value"},
+ dry_run=False,
+ session=session,
+ )
+
+ assert response is not None
+ assert isinstance(response.output, str)
+ result_data = orjson.loads(response.output)
+
+ # Structural errors must fall through to the plain error path — the
+ # user should see the validation error, not the credential setup card.
+ assert result_data.get("error") == "graph_validation_failed"
+ assert result_data.get("type") != "setup_requirements"
diff --git a/autogpt_platform/backend/backend/executor/utils.py b/autogpt_platform/backend/backend/executor/utils.py
index 0ee3e26479..8774ff03ef 100644
--- a/autogpt_platform/backend/backend/executor/utils.py
+++ b/autogpt_platform/backend/backend/executor/utils.py
@@ -4,7 +4,7 @@ import threading
import time
from collections import defaultdict
from concurrent.futures import Future
-from typing import Mapping, Optional, cast
+from typing import Literal, Mapping, Optional, cast
from pydantic import BaseModel, JsonValue, ValidationError
@@ -249,6 +249,65 @@ def validate_exec(
return data, node_block.name
+# ---------------------------------------------------------------------------
+# Credential validation error message templates.
+#
+# These constants are the single source of truth for the error messages
+# emitted by ``_validate_node_input_credentials``. Both the raise sites
+# below and the public matcher ``is_credential_validation_error_message``
+# reference them, so adding a new credential error means adding a
+# constant here — the matcher and tests stay in sync automatically.
+#
+# If you add a new credential error string, also add its constant to
+# ``_CREDENTIAL_ERROR_MARKERS`` below so the copilot's credential-race
+# fallback continues to recognise it.
+# ---------------------------------------------------------------------------
+CRED_ERR_REQUIRED = "These credentials are required"
+CRED_ERR_INVALID_PREFIX = "Invalid credentials:"
+CRED_ERR_INVALID_TYPE_MISMATCH = "Invalid credentials: type/provider mismatch"
+CRED_ERR_NOT_AVAILABLE_PREFIX = "Credentials not available:"
+CRED_ERR_UNKNOWN_PREFIX = "Unknown credentials #"
+
+# Markers used by ``is_credential_validation_error_message`` to classify a
+# message. Each entry is (match_mode, lowercased_marker) — "exact" means
+# the full message must equal the marker, "prefix" means it must start
+# with the marker.
+_MatchMode = Literal["exact", "prefix"]
+_CREDENTIAL_ERROR_MARKERS: tuple[tuple[_MatchMode, str], ...] = (
+ ("exact", CRED_ERR_REQUIRED.lower()),
+ # NOTE: CRED_ERR_INVALID_TYPE_MISMATCH is intentionally omitted here —
+ # the "prefix" entry for CRED_ERR_INVALID_PREFIX already covers it (since
+ # CRED_ERR_INVALID_TYPE_MISMATCH starts with "Invalid credentials:").
+ ("prefix", CRED_ERR_INVALID_PREFIX.lower()),
+ ("prefix", CRED_ERR_NOT_AVAILABLE_PREFIX.lower()),
+ ("prefix", CRED_ERR_UNKNOWN_PREFIX.lower()),
+)
+
+
+def is_credential_validation_error_message(message: str) -> bool:
+ """Return True if *message* came from the credential gate in
+ :func:`_validate_node_input_credentials`.
+
+ Kept as a public module-level helper so other layers (e.g. the
+ copilot tool that rebuilds the inline credentials setup card on a
+ credential race) can distinguish credential failures from other
+ graph validation errors without redefining the string list.
+
+ Drift prevention: raise sites and this matcher both reference the
+ ``CRED_ERR_*`` constants defined above, and
+ ``test_credential_error_markers_cover_all_raise_sites`` exercises
+ every branch of ``_validate_node_input_credentials`` to assert the
+ emitted messages are recognised.
+ """
+ lower = message.lower()
+ for mode, marker in _CREDENTIAL_ERROR_MARKERS:
+ if mode == "exact" and lower == marker:
+ return True
+ if mode == "prefix" and lower.startswith(marker):
+ return True
+ return False
+
+
async def _validate_node_input_credentials(
graph: GraphModel,
user_id: str,
@@ -311,9 +370,7 @@ async def _validate_node_input_credentials(
if field_is_optional:
continue # Don't add error, will be marked for skip after loop
else:
- credential_errors[node.id][
- field_name
- ] = "These credentials are required"
+ credential_errors[node.id][field_name] = CRED_ERR_REQUIRED
continue
credentials_meta = credentials_meta_type.model_validate(field_value)
@@ -321,7 +378,9 @@ async def _validate_node_input_credentials(
except ValidationError as e:
# Validation error means credentials were provided but invalid
# This should always be an error, even if optional
- credential_errors[node.id][field_name] = f"Invalid credentials: {e}"
+ credential_errors[node.id][
+ field_name
+ ] = f"{CRED_ERR_INVALID_PREFIX} {e}"
continue
try:
@@ -334,13 +393,13 @@ async def _validate_node_input_credentials(
# If credentials were explicitly configured but unavailable, it's an error
credential_errors[node.id][
field_name
- ] = f"Credentials not available: {e}"
+ ] = f"{CRED_ERR_NOT_AVAILABLE_PREFIX} {e}"
continue
if not credentials:
credential_errors[node.id][
field_name
- ] = f"Unknown credentials #{credentials_meta.id}"
+ ] = f"{CRED_ERR_UNKNOWN_PREFIX}{credentials_meta.id}"
continue
if (
@@ -353,9 +412,7 @@ async def _validate_node_input_credentials(
f"{credentials_meta.type}<>{credentials.type};"
f"{credentials_meta.provider}<>{credentials.provider}"
)
- credential_errors[node.id][
- field_name
- ] = "Invalid credentials: type/provider mismatch"
+ credential_errors[node.id][field_name] = CRED_ERR_INVALID_TYPE_MISMATCH
continue
# If node has optional credentials and any are missing, allow running without.
@@ -476,22 +533,11 @@ async def _construct_starting_node_execution_input(
# Dry runs simulate every block — missing credentials are irrelevant.
# Strip credential-only errors so the graph can proceed.
if dry_run and validation_errors:
-
- def _is_credential_error(msg: str) -> bool:
- """Match errors produced by _validate_node_input_credentials."""
- m = msg.lower()
- return (
- m == "these credentials are required"
- or m.startswith("invalid credentials:")
- or m.startswith("credentials not available:")
- or m.startswith("unknown credentials #")
- )
-
validation_errors = {
node_id: {
field: msg
for field, msg in errors.items()
- if not _is_credential_error(msg)
+ if not is_credential_validation_error_message(msg)
}
for node_id, errors in validation_errors.items()
}
diff --git a/autogpt_platform/backend/backend/executor/utils_test.py b/autogpt_platform/backend/backend/executor/utils_test.py
index e708673756..4b88cf9825 100644
--- a/autogpt_platform/backend/backend/executor/utils_test.py
+++ b/autogpt_platform/backend/backend/executor/utils_test.py
@@ -7,7 +7,15 @@ from pytest_mock import MockerFixture
from backend.data.dynamic_fields import merge_execution_input, parse_execution_output
from backend.data.execution import ExecutionStatus, GraphExecutionWithNodes
from backend.data.model import User
-from backend.executor.utils import add_graph_execution
+from backend.executor.utils import (
+ CRED_ERR_INVALID_PREFIX,
+ CRED_ERR_INVALID_TYPE_MISMATCH,
+ CRED_ERR_NOT_AVAILABLE_PREFIX,
+ CRED_ERR_REQUIRED,
+ CRED_ERR_UNKNOWN_PREFIX,
+ add_graph_execution,
+ is_credential_validation_error_message,
+)
from backend.util.mock import MockObject
@@ -1023,3 +1031,72 @@ async def test_stop_graph_execution_cascades_to_child_with_reviews(
# Verify both parent and child status updates
assert mock_execution_db.update_graph_execution_stats.call_count >= 1
+
+
+# ---------------------------------------------------------------------------
+# Credential validation error marker parity.
+#
+# ``is_credential_validation_error_message`` is shared by the executor
+# dry-run path and the copilot credential-race fallback. Adding a new
+# credential error string in ``_validate_node_input_credentials`` without
+# updating the matcher would silently regress the copilot UX to a plain
+# text error. These tests pin the contract:
+#
+# 1. Every ``CRED_ERR_*`` constant emitted by the raise sites is
+# recognised by the public matcher (including reasonable formatted
+# variants with runtime suffixes from ``f"{PREFIX} {e}"``).
+# 2. The matcher is case-insensitive and unaffected by trailing detail.
+# 3. Non-credential messages fall through.
+# ---------------------------------------------------------------------------
+
+
+def test_credential_error_markers_cover_all_raise_sites():
+ """Each credential error string emitted by
+ ``_validate_node_input_credentials`` must be recognised by
+ ``is_credential_validation_error_message``. This guards against
+ drift when a new credential error is introduced without updating
+ the matcher."""
+ # Exact-match raise sites
+ assert is_credential_validation_error_message(CRED_ERR_REQUIRED)
+ assert is_credential_validation_error_message(CRED_ERR_INVALID_TYPE_MISMATCH)
+
+ # Prefix raise sites with typical runtime suffixes (matching the
+ # f-strings inside ``_validate_node_input_credentials``)
+ assert is_credential_validation_error_message(
+ f"{CRED_ERR_INVALID_PREFIX} 1 validation error for ApiKeyCredentials"
+ )
+ assert is_credential_validation_error_message(
+ f"{CRED_ERR_NOT_AVAILABLE_PREFIX} connection refused"
+ )
+ assert is_credential_validation_error_message(
+ f"{CRED_ERR_UNKNOWN_PREFIX}abc-123-def"
+ )
+
+
+def test_credential_error_marker_matching_is_case_insensitive():
+ """The matcher lowercases inputs before comparing — ensure that
+ stays true for each marker so log-normalised copies still match."""
+ assert is_credential_validation_error_message(CRED_ERR_REQUIRED.upper())
+ assert is_credential_validation_error_message(CRED_ERR_REQUIRED.lower())
+ assert is_credential_validation_error_message(
+ f"{CRED_ERR_INVALID_PREFIX.upper()} BAD FIELD"
+ )
+ assert is_credential_validation_error_message(
+ f"{CRED_ERR_UNKNOWN_PREFIX.upper()}XYZ"
+ )
+
+
+def test_non_credential_errors_are_not_matched():
+ """Unrelated graph validation errors must not hit the credential
+ branch — otherwise the copilot would hide structural errors behind
+ the credential setup card."""
+ assert not is_credential_validation_error_message("")
+ assert not is_credential_validation_error_message(
+ "missing input {'required_field'}"
+ )
+ assert not is_credential_validation_error_message("Input field 'url' is required")
+ # A message that happens to contain "credentials" somewhere but
+ # doesn't start with any known prefix must not match.
+ assert not is_credential_validation_error_message(
+ "Block configuration says credentials are fine"
+ )
diff --git a/autogpt_platform/backend/backend/util/service.py b/autogpt_platform/backend/backend/util/service.py
index 459e46f01c..1139ecbee9 100644
--- a/autogpt_platform/backend/backend/util/service.py
+++ b/autogpt_platform/backend/backend/util/service.py
@@ -156,9 +156,30 @@ class BaseAppService(AppProcess, ABC):
super().cleanup()
+class RemoteCallExtras(BaseModel):
+ """Structured extras that can ride alongside a ``RemoteCallError``.
+
+ Each field here must be JSON-safe and explicitly typed — ``Any`` is
+ deliberately avoided so non-serializable payloads fail at model
+ validation time instead of inside FastAPI's JSON encoder. Add new
+ fields here (rather than re-typing to ``Any``) when a new exception
+ type needs to preserve structured state across RPC.
+ """
+
+ # GraphValidationError.node_errors — dict[node_id, dict[field, error_msg]]
+ node_errors: Optional[dict[str, dict[str, str]]] = None
+
+
class RemoteCallError(BaseModel):
type: str = "RemoteCallError"
args: Optional[Tuple[Any, ...]] = None
+ # Optional extras for exception types that carry structured attributes
+ # beyond ``exc.args``. When set, the client-side handler uses these to
+ # reconstruct the exception with the original attributes.
+ # Currently used by ``GraphValidationError.node_errors`` so the
+ # copilot's credential-race fallback can distinguish credential
+ # failures from other graph validation errors over RPC.
+ extras: Optional[RemoteCallExtras] = None
class UnhealthyServiceError(ValueError):
@@ -238,11 +259,30 @@ class AppService(BaseAppService, ABC):
f"{request.method} {request.url.path} failed: {exc}",
exc_info=exc,
)
+ extras: Optional[RemoteCallExtras] = None
+ if isinstance(exc, exceptions.GraphValidationError):
+ # ``exc.args`` only preserves the top-level message; the
+ # structured ``node_errors`` mapping needs to ride along
+ # in ``extras`` so the client can rebuild the original
+ # exception state (used by the copilot credential-race
+ # fallback to distinguish credential failures from other
+ # validation errors).
+ # Normalise to plain ``dict[str, dict[str, str]]`` so
+ # Pydantic validation enforces the JSON-safe shape —
+ # any non-serializable sneak-in fails here instead of
+ # inside the JSON encoder.
+ extras = RemoteCallExtras(
+ node_errors={
+ node_id: dict(errors)
+ for node_id, errors in exc.node_errors.items()
+ },
+ )
return responses.JSONResponse(
status_code=status_code,
content=RemoteCallError(
type=str(exc.__class__.__name__),
args=exc.args or (str(exc),),
+ extras=extras,
).model_dump(),
)
@@ -614,6 +654,25 @@ def get_service_client(
msg = str(args[0]) if args else str(e)
raise exception_class({"user_facing_error": {"message": msg}})
+ # GraphValidationError carries a structured ``node_errors``
+ # attribute that ``exc.args`` alone doesn't preserve.
+ # If the server included it in ``extras``, thread it
+ # back into the reconstructed exception.
+ #
+ # Identity check (``is``) is deliberate here — unlike the
+ # DataError path above which uses ``issubclass`` to catch
+ # all subclasses, GraphValidationError subclasses should
+ # fall through to the generic ``raise exception_class(*args)``
+ # below rather than silently losing their custom attributes.
+ if exception_class is exceptions.GraphValidationError:
+ msg = str(args[0]) if args else str(e)
+ node_errors = (
+ error_response.extras.node_errors
+ if error_response.extras
+ else None
+ )
+ raise exception_class(msg, node_errors=node_errors)
+
raise exception_class(*args)
# Otherwise categorize by HTTP status code
diff --git a/autogpt_platform/backend/backend/util/service_test.py b/autogpt_platform/backend/backend/util/service_test.py
index e314a47f74..c3d4589c07 100644
--- a/autogpt_platform/backend/backend/util/service_test.py
+++ b/autogpt_platform/backend/backend/util/service_test.py
@@ -7,16 +7,19 @@ from typing import Any, Protocol, cast
from unittest.mock import Mock
import httpx
+import orjson
import pytest
from prisma.errors import DataError, UniqueViolationError
from pydantic import TypeAdapter
from backend.data.model import User
+from backend.util.exceptions import GraphValidationError
from backend.util.service import (
AppService,
AppServiceClient,
HTTPClientError,
HTTPServerError,
+ RemoteCallError,
endpoint_to_async,
expose,
get_service_client,
@@ -29,6 +32,12 @@ class _SupportsGetReturn(Protocol):
def _get_return(self, expected_return: TypeAdapter | None, result: Any) -> Any: ...
+class _SupportsHandleCallMethodResponse(Protocol):
+ def _handle_call_method_response(
+ self, *, response: Any, method_name: str
+ ) -> Any: ...
+
+
class ServiceTest(AppService):
def __init__(self):
super().__init__()
@@ -489,6 +498,185 @@ class TestHTTPErrorRetryBehavior:
assert hasattr(exc_info.value, "data")
assert isinstance(exc_info.value.data, dict)
+ def test_graph_validation_error_preserves_node_errors(self):
+ """GraphValidationError carries a structured ``node_errors`` mapping
+ in addition to its top-level message. The server-side error handler
+ packs it into ``RemoteCallError.extras`` and the client-side handler
+ rebuilds the exception with ``node_errors`` preserved — without this
+ round-trip the copilot's credential-race fallback can't distinguish
+ credential failures from other validation errors, and users get a
+ generic error instead of the inline credentials setup card.
+ """
+ node_errors = {
+ "some-node-id": {
+ "credentials": "These credentials are required",
+ "api_key": "Invalid credentials: not found",
+ }
+ }
+ mock_response = Mock()
+ mock_response.status_code = 400
+ mock_response.json.return_value = {
+ "type": "GraphValidationError",
+ "args": ["Graph validation failed: 2 issues on 1 nodes"],
+ "extras": {"node_errors": node_errors},
+ }
+ mock_response.raise_for_status.side_effect = httpx.HTTPStatusError(
+ "400 Bad Request", request=Mock(), response=mock_response
+ )
+
+ client = cast(
+ _SupportsHandleCallMethodResponse,
+ get_service_client(ServiceTestClient),
+ )
+
+ with pytest.raises(GraphValidationError) as exc_info:
+ client._handle_call_method_response(
+ response=mock_response, method_name="test_method"
+ )
+
+ assert "Graph validation failed" in str(exc_info.value)
+ assert exc_info.value.node_errors == node_errors
+
+ def test_graph_validation_error_without_extras_still_deserializes(self):
+ """Backwards-compat: old server responses without ``extras`` should
+ still reconstruct a ``GraphValidationError`` — just with an empty
+ ``node_errors`` mapping (matches current pre-fix behaviour)."""
+ mock_response = Mock()
+ mock_response.status_code = 400
+ mock_response.json.return_value = {
+ "type": "GraphValidationError",
+ "args": ["Graph validation failed: 1 issues on 1 nodes"],
+ }
+ mock_response.raise_for_status.side_effect = httpx.HTTPStatusError(
+ "400 Bad Request", request=Mock(), response=mock_response
+ )
+
+ client = cast(
+ _SupportsHandleCallMethodResponse,
+ get_service_client(ServiceTestClient),
+ )
+
+ with pytest.raises(GraphValidationError) as exc_info:
+ client._handle_call_method_response(
+ response=mock_response, method_name="test_method"
+ )
+
+ assert "Graph validation failed" in str(exc_info.value)
+ assert exc_info.value.node_errors == {}
+
+ def test_graph_validation_error_with_extras_but_null_node_errors(self):
+ """When ``extras`` is present but ``node_errors`` is explicitly
+ ``None``, the guard ``error_response.extras.node_errors if
+ error_response.extras else None`` must still yield an empty
+ ``node_errors`` mapping on the reconstructed exception."""
+ mock_response = Mock()
+ mock_response.status_code = 400
+ mock_response.json.return_value = {
+ "type": "GraphValidationError",
+ "args": ["Graph validation failed: 1 issues on 1 nodes"],
+ "extras": {"node_errors": None},
+ }
+ mock_response.raise_for_status.side_effect = httpx.HTTPStatusError(
+ "400 Bad Request", request=Mock(), response=mock_response
+ )
+
+ client = cast(
+ _SupportsHandleCallMethodResponse,
+ get_service_client(ServiceTestClient),
+ )
+
+ with pytest.raises(GraphValidationError) as exc_info:
+ client._handle_call_method_response(
+ response=mock_response, method_name="test_method"
+ )
+
+ assert "Graph validation failed" in str(exc_info.value)
+ # node_errors should default to empty dict when extras.node_errors is None
+ assert exc_info.value.node_errors == {}
+
+ def test_graph_validation_error_server_handler_packs_node_errors(self):
+ """Server-side symmetry: ``_handle_internal_http_error`` must pack
+ ``GraphValidationError.node_errors`` into the ``extras`` field so
+ the client-side round-trip test above has something real to
+ decode. Without this parity test, dropping the
+ ``isinstance(exc, GraphValidationError)`` branch in the server
+ handler would go unnoticed — the client tests mock the wire
+ payload directly and wouldn't catch it.
+ """
+ node_errors = {
+ "node-a": {
+ "credentials": "These credentials are required",
+ "api_key": "Invalid credentials: bad shape",
+ },
+ "node-b": {"token": "Unknown credentials #xyz"},
+ }
+
+ # Build the FastAPI exception handler and invoke it with a
+ # real GraphValidationError.
+ handler = AppService._handle_internal_http_error(status_code=400)
+ exc = GraphValidationError(
+ "Graph validation failed: 3 issues on 2 nodes",
+ node_errors=node_errors,
+ )
+ # The handler signature takes (request, exc); request is unused
+ # by our code path, so a Mock() is fine.
+ json_response = handler(Mock(), exc)
+
+ # The body is bytes-encoded JSON — decode and validate the
+ # shape matches the RemoteCallError model.
+ decoded = orjson.loads(bytes(json_response.body))
+ rebuilt = RemoteCallError.model_validate(decoded)
+
+ assert rebuilt.type == "GraphValidationError"
+ assert rebuilt.args is not None
+ assert "Graph validation failed" in str(rebuilt.args[0])
+ assert rebuilt.extras is not None
+ assert rebuilt.extras.node_errors == node_errors
+
+ def test_graph_validation_error_round_trips_through_handlers(self):
+ """Full round-trip: server handler packs a real
+ ``GraphValidationError`` → client handler decodes and reconstructs
+ the original exception with ``node_errors`` preserved.
+
+ This closes the asymmetry between the server-packs and
+ client-unpacks tests — if either side drifts, this test fails
+ even when both one-sided tests pass.
+ """
+ node_errors = {
+ "node-x": {"credentials": "These credentials are required"},
+ }
+
+ # Server side.
+ handler = AppService._handle_internal_http_error(status_code=400)
+ exc = GraphValidationError(
+ "Graph validation failed: 1 issues on 1 nodes",
+ node_errors=node_errors,
+ )
+ json_response = handler(Mock(), exc)
+ wire_payload = orjson.loads(bytes(json_response.body))
+
+ # Client side — replay the wire payload through the real
+ # ``_handle_call_method_response``.
+ mock_response = Mock()
+ mock_response.status_code = 400
+ mock_response.json.return_value = wire_payload
+ mock_response.raise_for_status.side_effect = httpx.HTTPStatusError(
+ "400 Bad Request", request=Mock(), response=mock_response
+ )
+
+ client = cast(
+ _SupportsHandleCallMethodResponse,
+ get_service_client(ServiceTestClient),
+ )
+
+ with pytest.raises(GraphValidationError) as exc_info:
+ client._handle_call_method_response(
+ response=mock_response, method_name="test_method"
+ )
+
+ assert "Graph validation failed" in str(exc_info.value)
+ assert exc_info.value.node_errors == node_errors
+
def test_client_error_status_codes_coverage(self):
"""Test that various 4xx status codes are all wrapped as HTTPClientError."""
client_error_codes = [400, 401, 403, 404, 405, 409, 422, 429]