fix(docs): improve demo a2a agent docs

[marekdano]

📚 Documentation PR

Closes #3709

Summary

Fixes the demo A2A agent to correctly handle ContextForge's request formats and adds missing prerequisites to the documentation.

Changes

Documentation (docs/docs/using/agents/a2a.md)

• Added Prerequisites section documenting required setup:
  • SSRF_ALLOW_LOCALHOST=true requirement with explanation
  • PLATFORM_ADMIN_EMAIL runtime requirement
• Fixed token generation command - removed unnecessary --secret parameter (uses config default)
• Updated API test examples to show correct request format with parameters wrapper
• Consolidated running instructions into clear Option 1 and Option 2
• Fixed Admin UI test steps to include agent registration step
• Fixed MCP tool name from a2a_demo-calculator-agent to a2a-demo-calculator-agent

Demo Agent (scripts/demo_a2a_agent.py)

• Fixed request parsing - replaced failing Pydantic models with direct JSON dict parsing
• Added JSONRPC format support for endpoints ending with /
• Added nested message structure handling for Admin UI test button
• Added comprehensive debug logging showing raw request body and extraction path
• Fixed Pydantic models to use Optional[str] = None instead of str = ""
• Added typing.Optional import for proper type hints
• Made handler async and added Request import for raw body access

Testing

Tested with:
1. Ran all curl request listed in the docs
2. Admin UI test button with queries like calc: 100/4+25 and weather: Dallas
3. MCP tool invocation via /rpc endpoint

All three methods now work correctly.

Fixes

• Resolves demo agent returning "Hello" instead of processing queries
• Addresses three failure modes: missing jti claim, wrong token subject, SSRF rejection
• Fixes AttributeError when Admin UI sends nested message structure

[a-effort]

Good fixes for blockers users may run into when trying to run the demo!

Here are a few cleanup requests / pieces of feedback from 🤖

---

What's fixed correctly:

• SSRF_ALLOW_LOCALHOST=true prerequisite was a silent blocker. Good fix ✅
• --secret removed from token generation command: good, as it reads from .env ✅
• Tool name typo fixed: a2a_demo-calculator-agent ✅
• Admin UI steps now include the agent registration step that was missing ✅
• Optional [str] = None on Pydantic fields is the right fix (empty string "" is falsy, which broke the or chain) ✅

---

Changes to consider:

1. demo_a2a_agent.py run_agent rewrite: the Optional[str] = None fix already solves the root cause. The raw json.loads + manual key-walking approach is harder to maintain than the Pydantic model. Keep the Pydantic path (with Optional) or, if JSONRPC format is genuinely needed, add it as a fallback on top of the Pydantic parse rather than replacing it entirely.
2. Debug print() statements: several print(f"Raw request body: ...") / print(f"Extracted from ...") lines were left in production code. Move them to logger.debug() or remove them.
3. import json inside the handler: should be a top-level import.
4. demo_a2a_agent_auth.py not updated. It has the same str = "" issue on Parameters and A2ARequest (lines 337–349). Apply the same Optional[str] = None fix so both scripts stay consistent.
5. Minor doc nit: Option 2 generates a token into $TOKEN but the next line, uv run python scripts/demo_a2a_agent.py, doesn't use it. Either pass it in BEARER_TOKEN=$TOKEN or clarify the token is for the curl test commands, not the script startup.

[marekdano]

@a-effort reviewing items have been addressed:

• json import: Moved to top-level (cleaner code structure)
• print() statements: Kept as-is for local demo (appropriate for non-production script)
• demo_a2a_agent_auth.py: Applied Optional[str] = None fix for consistency
• Documentation: Clarified token usage to avoid confusion

[vishu-bh]

LGTM 👍

[vishu-bh]

Something I noticed in scripts/demo_a2a_agent.py:167

The new debug print() statements log the full raw request body and extracted query text verbatim. That leaks prompt/request contents into logs and also allows unsanitized user-controlled text into log output.

For local debugging this may be convenient, but it is still a security-quality regression. If logging is needed, it should be reduced, sanitized, and preferably routed through structured debug logging rather than unconditional print() calls.

[marekdano]

@vishu-bh - reviewed it and removed the print statement with the full raw request body. I replaced the other print statements with the hardcoded strings.
There is no point in introducing the logging system in this demo_a2a_agents.py script since we do not log the sensitive data, and the print statements are already used there only.
The script is for demo purposes and will never be run on production.

[vishu-bh]

Thanks @marekdano LGTM 🚀

[crivetimihai]

Thanks for the contribution, @marekdano — the prerequisites section and JSONRPC/nested-message parsing are solid additions.

I rebased, squashed the commits, and made a few review fixes on top:

Bug fix — MCP tool name prefix: The docs changed a2a_demo-calculator-agent to a2a-demo-calculator-agent, but tool_service.py uses f"a2a_{agent.slug}" (underscore). Reverted to the correct name.

PLATFORM_ADMIN_EMAIL env var: The docs referenced it but the script hardcoded admin@example.com. Updated create_jwt_token() to read os.environ.get("PLATFORM_ADMIN_EMAIL", "admin@example.com") and clarified the docs to describe environment variables (not .env file loading, since the script doesn't use python-dotenv).

Dead code cleanup: Removed the now-unused Parameters and A2ARequest Pydantic models (and the Optional import) from demo_a2a_agent.py since run_agent parses raw JSON directly.

Error handling: Added try/except around json.loads(body) so malformed requests get a clean error instead of a 500.

Docs simplification: Consolidated the Option 1/Option 2 pattern into a single clear flow.

Tests: Added 23 unit tests (tests/unit/scripts/test_demo_a2a_agent.py) covering all request format paths — JSONRPC simple, JSONRPC nested message parts, A2A protocol, simple query/message, empty body, invalid JSON, calculator ops, agent routing, and health endpoint. 100% coverage of the new/changed code.

[crivetimihai]

Looks good — rebased, fixes verified, tests added. Approving.