fix(a2a): cascade agent state changes to associated MCP tools

[crivetimihai]

Note: This PR was re-created from #3073 due to repository maintenance. Your code and branch are intact. @marekdano please verify everything looks good.

🐛 Bug-fix PR

---

📌 Summary

When an A2A agent is deactivated, its associated tool remains active in the database — appearing in virtual server tool listings and still invocable. This is inconsistent with gateway deactivation, which cascades to all child tools, prompts, and resources.

This PR cascades A2A agent activation/deactivation to the associated MCP tool, adds the missing "Enable/Disable A2A Agent" API documentation, and brings a2a_service.py unit test coverage to 100%.

Closes #2997

🔁 Reproduction Steps

1. Go to http://localhost:8080/admin/?agents_inactive=true&agents_page=1#a2a-agents
2. Set as Inactive an Agent
3. Check Tools and Virtual Server

🐞 Root Cause

The root cause was that set_agent_state() in a2a_service.py only updated the agent's own enabled field and never touched the associated tool record. Unlike gateway_service.py:set_gateway_state(), which bulk-updates all child tools/prompts/resources when a gateway is toggled, the A2A code path simply didn't have any cascade logic — the tool's enabled column stayed unchanged regardless of the agent's state.

💡 Fix Description

deactive_a2a_agents_flow.mov

Bug fix

• mcpgateway/services/a2a_service.py: After toggling agent.enabled in set_agent_state(), cascade the new state to the agent's associated tool via a single UPDATE statement. The WHERE DbTool.enabled != activate guard avoids redundant commits when the tool already matches the desired state. This mirrors the existing pattern in gateway_service.py:set_gateway_state().

Test fixes

• tests/unit/mcpgateway/services/test_a2a_service.py: Added tool_id=None to two existing SimpleNamespace agent mocks (test_set_state_permission_allowed, test_set_state_with_reachable) that broke because the new cascade code accesses agent.tool_id.

New Unit Tests (12 tests, coverage 94% → 100%)

• TestSetAgentStateToolCascade (4 tests): Deactivation cascades to tool, activation cascades to tool, no-op when tool_id is None, no commit when tool already matches state.
• TestUpdateAgentQueryParamAuth (7 tests): Switching away from query_param clears params, switching to query_param encrypts key/value, value-only rotation reuses existing key, masked placeholder with same/different key, None value no-op, plain string value path.
• TestListAgentsCacheAttributeError (1 test): AttributeError during cache set is silently skipped.
• Add extra tests to get 100% coverage on a2a_service.py

Documentation

• docs/docs/using/agents/a2a.md: New "Lifecycle Management > Agent-Tool State Cascade" section explaining the linked lifecycle between A2A agents and their tools.
• docs/docs/manage/api-usage.md: New "Enable/Disable A2A Agent" subsection with API examples and a "State Cascade" admonition note.

🧪 Verification

Check	Command	Status
Lint suite	make lint	✅
Unit tests	make test	✅
Coverage ≥ 80 %	make coverage	✅
Manual regression no longer fails	steps / screenshots

📐 MCP Compliance (if relevant)

• Matches current MCP spec
• No breaking change to MCP clients

✅ Checklist

• Code formatted (make black isort pre-commit)
• No secrets/credentials committed

[Lang-Akshay]

Acceptance Criteria Breakdown:

Criterion	Status	Evidence
Deactivating an A2A agent should hide its tool from Tools panel	✅ Done	Tool cascade logic (a2a_service.py L1256-L1268) sets enabled=activate on DbTool
Deactivating an A2A agent should hide it from Virtual Servers panel	✅ Done	Tool's enabled=False means it won't appear in virtual server tool listings (existing filtering)
Behavior should match MCP Server (gateway) deactivation pattern	✅ Done	Pattern mirrors gateway_service.set_gateway_state() appropriately (1:1 vs 1:many relationship)
Reactivating should restore visibility	✅ Done	Cascade works bidirectionally (activate=True/False)

Overall Issue Coverage: 4 of 4 requirements addressed.

Strengths

1. Idempotent cascade: The WHERE DbTool.enabled != activate guard avoids redundant commits — well-tested via test_cascade_tool_already_matching_no_commit.
2. Best-effort semantics: The try/except Exception around the cascade ensures an agent state-change is never blocked by a tool-update failure — appropriate for a non-critical cascade.
3. Comprehensive test coverage: All branches covered — happy path (activate/deactivate), no tool_id, no gateway_id, already-matching state, and cascade failure.
4. Cache invalidation: Both registry cache and tool lookup cache are invalidated, preventing stale data.

The fix is well-scoped, correctly mirrors the existing gateway cascade pattern (adapted for 1:1 relationship), is thoroughly tested with 15 new tests (100% coverage on a2a_service.py), and includes clear documentation.

[msureshkumar88]

✅ PR #3173 — Approved

[BUG][UI]: Inactive A2A agents still visible in Tools and Virtual Servers panels by @author

This PR successfully implements state cascade functionality where deactivating an A2A agent automatically deactivates its associated tool, ensuring inactive agents no longer appear in Tools and Virtual Servers panels. The implementation follows the same pattern as MCP server deactivation and includes comprehensive test coverage.

Security: 🟢 No issues found
Issue Coverage: Fully addresses issue #2997
Quality: Well-tested with proper cache management

The changes are production-ready and align with the expected behavior described in the issue.

[crivetimihai]

Maintainer Review — Changes Made During Rebase

Rebased onto main (clean, no conflicts) and made the following fixes on top of the original 3 commits:

fix: apply black formatting and correct stale docstring path

• Ran black on test_a2a_service.py — the new test code had several lines exceeding the formatter's limit.
• Fixed test_a2a_agent.py docstring Location: path which still referenced the pre-rename filename test_issue_840_a2a_agent.py.

fix: tighten docs and stale docstring per code review feedback

• Updated test_a2a_agent.py module docstring to reference both [BUG]: A2A Agent test not working #840 and [BUG][UI]: Inactive A2A agents still visible in Tools and Virtual Servers panels #2997 instead of the stale "will fail until issues are fixed" wording.
• Clarified docs/docs/using/agents/a2a.md cascade section: invocation of disabled A2A tools was already rejected by tool_service.py; this PR's actual fix is ensuring the tool's enabled flag stays in sync so it no longer appears in listings.

fix: let cascade failures propagate instead of swallowing them

• Removed the try/except around the tool cascade in set_agent_state() so DB failures surface to the caller. This aligns with gateway_service.py:set_gateway_state() which also commits the parent first (line 2773) then cascades to child tools/prompts/resources without catching exceptions.
• The previous best-effort pattern silently returned success when the tool UPDATE failed, leaving the agent disabled but its tool still enabled — the exact inconsistency this PR is meant to fix.
• Updated the failure-path test from asserting "warning logged + success returned" to asserting pytest.raises(RuntimeError).

Verification

• All 73 unit tests pass, 99% coverage on a2a_service.py (5 uncovered lines are pre-existing).
• E2E tested against localhost:8080 (docker-compose): created agent, deactivated via API and Admin UI, verified tool disappears from virtual server listings, reactivated, verified tool reappears. Idempotency and cleanup verified.
• No regressions in gateways, tools, prompts, resources, or virtual servers.