feat: harden deep-search runtime and evaluation workflow

[engdahlz]

What

• Refactors the Python deep-search sample into clearer modules with dedicated research models, agent wiring, and callback logic.
• Adds runtime guardrails and configuration controls for Gemini model selection, Vertex location handling, context caching, and context compaction.
• Improves operational documentation in the deep-search README and architecture notes.
• Adds a focused evaluation suite (evals/core) and callback unit tests.

Why

• Reduce runtime failures caused by preview model and endpoint mismatches.
• Make the agent flow easier to reason about and safer to run in iterative research loops.
• Provide reproducible quality checks for key callback behaviours.

Changes

• Updated deep-search runtime and configuration:
  • python/agents/deep-search/app/config.py
  • python/agents/deep-search/app/research_agents.py
  • python/agents/deep-search/app/research_callbacks.py
  • python/agents/deep-search/app/research_models.py
  • python/agents/deep-search/app/agent.py
• Documentation updates:
  • python/agents/deep-search/README.md
  • python/agents/deep-search/app/ARCHITECTURE.md
• Added evaluation and tests:
  • python/agents/deep-search/evals/core/*
  • python/agents/deep-search/tests/test_research_callbacks.py

Testing

• uv run pytest tests/test_research_callbacks.py -q (4 passed)
• printf 'hello\nexit\n' | uv run adk run app (manual smoke run, successful)

References

• NO-JIRA

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.