feat: add GeminiAgent, GeminiClassifier, QdrantRetriever

[inamdarmihir]

Issue Link (REQUIRED)

Fixes #376

---

Summary

Changes

This PR adds Google Gemini support and a Qdrant retriever to the agent squad Python framework.

New files

• python/src/agent_squad/agents/gemini_agent.py
GeminiAgent, GeminiAgentOptions

  • Supports streaming and non streaming via google-generativeai
  • Maps ConversationMessage to Gemini role format
  • Optional retriever support through the existing interface
  • Hooks into all agent callbacks
  • Default model gemini-2.0-flash

• python/src/agent_squad/classifiers/gemini_classifier.py
GeminiClassifier, GeminiClassifierOptions

  • Uses Gemini tool calling for routing
  • analyzePrompt matches existing classifier schema
  • Falls back to JSON parsing when needed
  • Default model gemini-2.0-flash

• python/src/agent_squad/retrievers/qdrant_retriever.py
QdrantRetriever, QdrantRetrieverOptions

  • Implements the Retriever interface
  • Uses Gemini text-embedding-004 for embeddings
  • Works with local Qdrant and Qdrant Cloud
  • Includes index_documents() helper

Modified files

• agents/__init__.py registers Gemini agent
• classifiers/__init__.py registers Gemini classifier
• retrievers/__init__.py registers Qdrant retriever
• setup.cfg adds gemini and qdrant extras, both included in all

Tests

• test_gemini_agent.py
  Covers validation, defaults, responses, role mapping, retriever use
• test_qdrant_retriever.py
  Covers retrieval and indexing with mocked calls

Example

• examples/python/gemini_qdrant_example.py
  End to end example with classifier, retriever, and two agents

---

Known issue in first commit

The initial push included the agent-squad directory as a submodule instead of regular files.

This has been fixed. The submodule was removed, the nested .git directory deleted, and all files committed normally. The diff now only contains the expected source, tests, config, and example files.

---

User experience

Before

No built in Gemini agent or classifier.
Only retriever required AWS Bedrock.
Gemini workflows required custom code.

After

A full Gemini setup works in about 15 lines:

from agent_squad.orchestrator import AgentSquad
from agent_squad.agents import GeminiAgent, GeminiAgentOptions
from agent_squad.classifiers import GeminiClassifier, GeminiClassifierOptions
from agent_squad.retrievers import QdrantRetriever, QdrantRetrieverOptions

orchestrator = AgentSquad(
    classifier=GeminiClassifier(GeminiClassifierOptions(api_key=GEMINI_KEY))
)

orchestrator.add_agent(
    GeminiAgent(
        GeminiAgentOptions(
            api_key=GEMINI_KEY,
            name="Tech Agent",
            description="Answers software and cloud questions.",
        )
    )
)

Install options:

pip install "agent-squad[gemini]"
pip install "agent-squad[qdrant]"
pip install "agent-squad[all]"

No impact to existing AWS, Anthropic, or OpenAI users.

---

Checklist

• Self review completed
• Tests added and passing
• Documentation updated
• Linked to issue

Is this a breaking change?

RFC issue: N/A

• Migration needed
• Warnings required

Not a breaking change. All additions are optional and guarded by import checks. Existing behavior remains unchanged.

---

Acknowledgment

By submitting this PR, I agree that this contribution can be used, modified, and redistributed under the project’s terms.

[Copilot]

Pull request overview

This PR aims to add optional Google Gemini support (agent + classifier) and a Qdrant-based retriever to the Python agent_squad framework (Fixes #376), including new extras in packaging, tests, and an end-to-end example.

Changes:

• Add GeminiAgent / GeminiClassifier implementations and register them in package __init__.py modules.
• Add QdrantRetriever implementation and register it under retrievers.
• Add gemini/qdrant extras (and include them in all), plus tests and an example.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[cornelcroi]

@claude check this PR, check this new implementation against the other agents, how the code is written, how clean is it and how inline is with the existing code.

[claude]

Claude finished @cornelcroi's task in 2m 18s —— View job

---

PR Code Review

• Load tools
• Gather context: read existing agent implementations for comparison
• Read new GeminiAgent implementation
• Read new GeminiClassifier implementation
• Read new QdrantRetriever implementation
• Compare with existing patterns and write review

---

Review Summary

⚠️ Critical: This PR cannot be merged in its current state. The single commit in this branch only records agent-squad | 1 + — a dangling gitlink (orphaned submodule pointer). The actual source files (gemini_agent.py, gemini_classifier.py, qdrant_retriever.py, tests, example, setup.cfg changes) do not exist on this branch. The PR description acknowledges a submodule accident, but the stated fix (delete the .git dir and commit normally) was never completed and pushed. Running git diff origin/main...HEAD --stat confirms only 1 line changed in 1 file.

The review below evaluates the design and code quality based on the PR description and the patterns established in the existing codebase.

---

1. Critical: Broken Branch State

The commit history shows:

agent-squad | 1 +
1 file changed, 1 insertion(+)

This is a git submodule pointer, not source files. Before any code review can matter, the author needs to:

1. Remove the agent-squad gitlink entry from the tree
2. Re-add all described files as regular tracked files
3. Force-push a corrected commit to this branch

---

2. Agent Design: Alignment with Existing Patterns

Based on the PR description and comparing against anthropic_agent.py and openai_agent.py:

AnthropicAgentOptions pattern (correct approach):

@dataclass
class AnthropicAgentOptions(AgentOptions):
    api_key: Optional[str] = None
    client: Optional[Any] = None
    model_id: str = "claude-3-5-sonnet-20240620"
    streaming: Optional[bool] = False
    inference_config: Optional[dict[str, Any]] = None
    retriever: Optional[Retriever] = None
    ...

The PR description proposes GeminiAgentOptions using the same field names (api_key, model_id, streaming, retriever, inference_config). This is correct. However, several concerns arise from what the description implies:

Concerns (from PR description text):

• Callback coverage: The PR claims "Hooks into all agent callbacks." The full callback chain in AnthropicAgent calls on_agent_start, on_llm_start, on_llm_new_token, and on_llm_end — each with structured usage/input/inferenceConfig kwargs. If GeminiAgent omits any of these or doesn't pass the same structured kwargs, observability integrations will silently break. Cannot verify without the actual file.

• handle_single_response / handle_streaming_response split: Both AnthropicAgent and OpenAIAgent separate raw API calls into handle_single_response / handle_streaming_response methods — this makes them individually testable and mockable. The PR description doesn't confirm this split exists.

• is_streaming_enabled(): Must be implemented returning self.streaming is True. This is a contract the orchestrator depends on.

• set_system_prompt / update_system_prompt / replace_placeholders: All existing agents implement these for template variable injection. These should be present in GeminiAgent too.

---

3. Classifier Design

OpenAIClassifier / AnthropicClassifier patterns:

• Options class uses __init__ (plain class), NOT @dataclass
• process_request(input_text, chat_history) returns ClassifierResult
• Uses analyzePrompt function-calling with identical schema: {userinput, selected_agent, confidence}
• Calls self.get_agent_by_id(...) to resolve the agent

The PR description says GeminiClassifier uses "Gemini tool calling for routing" and "falls back to JSON parsing when needed." The JSON fallback is a risk:

⚠️ Concern — JSON fallback in classifier: The AnthropicClassifier and OpenAIClassifier do NOT include a JSON fallback — they raise on missing tool calls. A fallback introduces ambiguity: if Gemini's tool-calling is unreliable enough to need a fallback, the confidence value may be fabricated from unstructured text. This could silently route to wrong agents without any error signal. Either enforce tool-calling with tool_choice forcing, or raise explicitly like the other classifiers do.

⚠️ Concern — ClassifierCallbacks missing: AnthropicClassifier accepts and calls ClassifierCallbacks (on_classifier_start, on_classifier_stop). The PR description does not mention this for GeminiClassifier. Without it, classifier-level tracing won't work.

---

4. Retriever Design

Retriever ABC requires three methods:

async def retrieve(self, text: str) -> Any: ...
async def retrieve_and_combine_results(self, text: str) -> Any: ...
async def retrieve_and_generate(self, text: str) -> Any: ...

The PR description only mentions retrieve_and_combine_results and an index_documents() helper. If retrieve_and_generate is not implemented (even as pass like AmazonKnowledgeBasesRetriever does), QdrantRetriever will fail to instantiate with a TypeError.

⚠️ Concern — Coupling embeddings to Gemini API: QdrantRetriever uses text-embedding-004 (Gemini's embedding model) for vector generation. This means the retriever requires a GEMINI_API_KEY even in non-Gemini agent setups. The AmazonKnowledgeBasesRetriever is self-contained via boto3/Bedrock. Consider making the embedding function pluggable, or clearly documenting that this retriever is Gemini-only.

⚠️ Concern — retrievers/__init__.py unconditional import: Unlike agents/__init__.py and classifiers/__init__.py, the current retrievers/__init__.py does NOT use try/except ImportError guards. If the PR simply appends from .qdrant_retriever import ... without guarding it, installing agent-squad without the qdrant extra will break the entire retrievers module import. Fix this →

---

5. Packaging (setup.cfg)

The PR says it adds gemini and qdrant extras and includes both in all. The current setup.cfg does not include strands-agents in all — so if the PR follows that precedent and adds only gemini/qdrant to all but not strands-agents, it creates an inconsistency. Check whether strands-agents should also be added to all as part of this cleanup (or explicitly note the intentional omission).

---

6. Code Style / Repo Conventions

• Python agents use @dataclass for *Options — the classifier *Options classes use plain __init__. Be consistent with whichever pattern the new code follows.
• ruff.toml targets py311 with only A and B rules. No blocking style issues expected, but import ordering should match (standard lib → third-party → local).
• The OpenAIAgent has a misplaced import re inside replace_placeholders — the new agent should not replicate that; keep import re at the module top (as AnthropicAgent does).

---

7. Tests

The PR description mentions test_gemini_agent.py and test_qdrant_retriever.py with mocked calls. Since the files don't exist on the branch, these cannot be verified. When the branch is fixed, confirm:

• Tests mock google-generativeai at the right patch path
• Both streaming and non-streaming paths are covered
• Classifier routing with tool-call response AND the fallback path are both tested
• QdrantRetriever.index_documents() has a test

---

Action Required

1. Fix the branch: Remove the agent-squad gitlink, commit the actual source files, push.
2. Guard the retriever import in retrievers/__init__.py with try/except ImportError.
3. Remove or harden the JSON fallback in GeminiClassifier — either enforce tool-calling or raise explicitly.
4. Add ClassifierCallbacks support to GeminiClassifier.
5. Implement retrieve_and_generate in QdrantRetriever (even as pass) to satisfy the ABC.
6. Once files are on the branch, run make code-quality (ruff) and make test from python/.

[cornelcroi]

Hi @inamdarmihir can you review these findings ? One thing that is very important is that every agent should come with an optional package so that the user to install it only if he uses this agent.