Google Gemini & Anthropic Claude

Google Gemini and Anthropic Claude represent two of the most capable frontier model families for agentic workflows. chatflow-agent provides dedicated, native engines for both providers, optimized for low latency, zero SDK lock-in, and reliable tool calling.

Google Gemini EngineCopy Anchor Link

GeminiEngine communicates directly with Google's Gemini Developer API (v1beta) to execute multi-turn conversations and function calling.

Authentication and CredentialsCopy Anchor Link

The engine reads credentials from the following sources, in order of priority:

1. api_key passed directly to GeminiEngine(api_key="...") or Agent(api_key="...").
2. GEMINI_API_KEY environment variable.
3. GOOGLE_API_KEY environment variable.

By default, the API key is transmitted via the secure x-goog-api-key HTTP header. Passing api_key_in_query=True transmits the key as a ?key= query parameter instead:

import os
from chatflow_agent import Agent, Runner
from chatflow_agent.core.engines.gemini import GeminiEngine

# Recommended: Secure header authentication
gemini_engine = GeminiEngine(
    api_key=os.environ.get("GEMINI_API_KEY"),
    timeout_seconds=30.0,
    max_retries=3,
)

assistant = Agent(
    name="GeminiAssistant",
    model="gemini-2.5-flash",
    engine=gemini_engine,
    instructions="Provide concise, accurate answers.",
)

Connection Pooling & Zero-SDK ArchitectureCopy Anchor Link

The Gemini implementation underwent an architectural shift between releases:

• In v0.3.4 (Stable): The engine imported Google's official google-genai SDK (from google import genai), requiring external client library installation.
• In v0.4.0rc1 (Prerelease): The engine was completely rewritten using native asynchronous httpx against https://generativelanguage.googleapis.com/v1beta. This eliminates heavy dependencies and enables connection pooling across agent turns:

# [no-exec: requires real gemini api key]
import asyncio
from chatflow_agent import Agent, Runner

agent = Agent(name="Assistant", model="gemini-2.5-flash")
runner = Runner(starting_agent=agent)

async def main():
    # In v0.3.x, execute asynchronous turns directly on the runner
    res1 = await runner.run_async("session-1", "What is quantum computing?")
    res2 = await runner.run_async("session-1", "Summarize in 3 bullet points.")
    print(res2.text)

asyncio.run(main())

Custom Proxy ConfigurationCopy Anchor Link

To route Gemini requests through an enterprise proxy or gateway, set the GOOGLE_GEMINI_BASE_URL environment variable:

export GOOGLE_GEMINI_BASE_URL="https://gemini-proxy.internal.corp"

The engine automatically appends /v1beta to the base URL.

Anthropic Claude EngineCopy Anchor Link

AnthropicEngine provides native integration with Anthropic's Claude 3.5 Sonnet, Claude 3.5 Haiku, and Claude 3 Opus via the Messages API.

Authentication and HeadersCopy Anchor Link

Anthropic requests require the x-api-key header and the anthropic-version header (defaults to "2023-06-01").

The engine reads credentials from:

1. api_key passed explicitly to AnthropicEngine(api_key="...") or Agent(api_key="...").
2. ANTHROPIC_API_KEY environment variable.

import os
from chatflow_agent import Agent
from chatflow_agent.core.engines.anthropic import AnthropicEngine

claude_engine = AnthropicEngine(
    api_key=os.environ.get("ANTHROPIC_API_KEY"),
    timeout=60.0,
)

editor = Agent(
    name="Editor",
    model="claude-3-5-sonnet-20241022",
    engine=claude_engine,
    instructions="Edit and refine technical documentation.",
)

Automatic Retries and Jittered BackoffCopy Anchor Link

AnthropicEngine automatically handles rate limiting (429 Too Many Requests) and temporary gateway errors (500, 502, 503, 504) using exponential backoff:

• Max Retries: 3 attempts.
• Base Delay: 1.0 second.
• Max Delay: 10.0 seconds.

If a 429 response includes a Retry-After header, the engine honors the provider's requested delay before retrying.

Multi-Model Agent CollaborationCopy Anchor Link

A major advantage of chatflow-agent is composing swarms where different agents utilize different foundation models according to their strengths:

from chatflow_agent import Agent, Runner
from chatflow_agent.core.engines.gemini import GeminiEngine
from chatflow_agent.core.engines.anthropic import AnthropicEngine

gemini = GeminiEngine()
claude = AnthropicEngine()

researcher = Agent(
    name="Researcher",
    model="gemini-2.5-flash",
    engine=gemini,
    instructions="Gather facts quickly using Gemini's high-throughput processing.",
)

synthesizer = Agent(
    name="Synthesizer",
    model="claude-3-5-sonnet-20241022",
    engine=claude,
    instructions="Synthesize gathered facts into clear, well-structured prose.",
)

# Connect agents via handoffs
researcher.add_handoff(synthesizer)
synthesizer.add_handoff(researcher)

runner = Runner(starting_agent=researcher)

In this swarm:

1. The Researcher runs on Gemini 2.5 Flash for rapid ingestion and search.
2. Once data is collected, the session hands off to the Synthesizer on Claude 3.5 Sonnet.
3. Historical messages and tool call IDs are automatically normalized, preventing cross-provider format mismatches.