Skip to content

Add authenticated email agent recipe - #2493

Closed
jiashuoz wants to merge 3 commits into
google:mainfrom
jiashuoz:codex/add-e2a-email-agent
Closed

jiashuoz wants to merge 3 commits into
google:mainfrom
jiashuoz:codex/add-e2a-email-agent

Conversation

@jiashuoz

@jiashuoz jiashuoz commented Aug 9, 2026

Copy link
Copy Markdown

Summary

Adds a runnable Python recipe that connects a Google ADK agent to one
authenticated e2a email inbox through the hosted Streamable HTTP MCP endpoint.

The recipe demonstrates:

  • agent-scoped authentication and an explicit MCP tool allowlist;
  • safe handling of untrusted email content;
  • separate new-message and threaded-reply workflows;
  • stable idempotency keys for ambiguous retries; and
  • correct handling of pending_review as a held outcome that must not be
    resent.

Recipe

contrib/python/authenticated-email-agent

Validation

  • uv run validate all contrib/python/authenticated-email-agent
  • uvx ruff check app tests
  • uvx ruff format --check app tests
  • uv run pytest --ignore=tests/integration --ignore-glob="**/test_integration.py"

All checks pass locally (4 tests). The test suite is offline and does not use
live Gemini or e2a credentials.

Contributor

Human contributor and recipe owner: Josh Zhang (@jiashuoz), Token Canopy.

The Google Contributor License Agreement may still need confirmation before
this draft is marked ready for review.

@google-cla

google-cla Bot commented Aug 9, 2026

Copy link
Copy Markdown

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.

@jiashuoz
jiashuoz marked this pull request as ready for review August 9, 2026 03:28
@jiashuoz
jiashuoz requested a review from happyhuman as a code owner August 9, 2026 03:28
@happyhuman

Copy link
Copy Markdown
Collaborator

Please take a look at the failed github workflows and address the issues. I will review your PR after.

@happyhuman happyhuman left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please fix the formatting issues first.

@github-actions

Copy link
Copy Markdown
Contributor

This pull request has had no activity for 60 days, so it has been labelled stale.

If it is still wanted, a comment or a push is enough to reset the clock. Otherwise it will be closed automatically in 30 days.

Nothing about this is final — a closed pull request reopens with one click, and your commits are untouched on your own branch.

Maintainers: apply keep-open to exempt this permanently. Thresholds live in .github/policy.yml under stale_policy.

@github-actions github-actions Bot added the stale No activity for the period set in .github/policy.yml label Oct 12, 2026
@tommywagz
tommywagz self-requested a review as a code owner October 23, 2026 02:36
@github-actions github-actions Bot added the status/not-ready-for-review Review requests held until checks pass and bot comments are resolved label Oct 23, 2026
@github-actions

github-actions Bot commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor

This pull request isn't ready for review yet.

I removed the review request for tommywagz until the items below are fixed.

Failing checks (4)

Fix the failing checks. Once everything is green I will re-request the review automatically, so there is no need to ping anyone. This is re-checked every 15 minutes.

Applied by the review gate (.github/review-gate-config.yml); the status/not-ready-for-review label is removed on release.

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Automated House Rules review — 1 finding(s).

Also, on lines this PR does not change:

  • contrib/python/authenticated-email-agent/Dockerfile:1 — [CRITICAL] required file missing: Dockerfile (.github/policy.yml required_files)

import importlib
import os

os.environ.setdefault("E2A_API_KEY", "synthetic-agent-scoped-key")

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[MINOR] env read carries a hardcoded default (second argument is a hardcoded default); 6 occurrence(s) across 2 file(s). Defaults belong in .env.example, not in the code (contrib/python/authenticated-email-agent/tests/test_runnability.py:19; and 5 more)

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Automated Hygiene review — 3 finding(s).


Round 1 · 0 of this PR's 25 automated comments used · this round is capped at 20 across all reviewers.

GOOGLE_API_KEY=<your-google-api-key>

# ADK model configuration.
MODEL_NAME=gemini-3.5-flash

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[MINOR] Perhaps this should be gemini-3.7-flash? AGENTS.md:40 lists that as the current default, and gemini-3.5-flash appears across three places in this recipe.

@@ -0,0 +1,8 @@
# Agent-scoped credential for one e2a inbox.
E2A_API_KEY=<your-agent-scoped-e2a-api-key>

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[MINOR] Can we use <TODO: update-this-value> for this placeholder?

E2A_API_KEY=<your-agent-scoped-e2a-api-key>

# Google AI Studio credential used by ADK.
GOOGLE_API_KEY=<your-google-api-key>

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[MINOR] same issue as above

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Automated Maintainability review — 3 finding(s).


Round 1 · 0 of this PR's 25 automated comments used · this round is capped at 20 across all reviewers.

connection_params=StreamableHTTPConnectionParams(
url=E2A_MCP_URL,
headers=_authorization_headers(),
timeout=30,

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[MINOR] Is there a reason 30 is hardcoded inline here instead of being defined as a named constant?

toolset = agent.root_agent.tools[0]
assert toolset.tool_filter == list(agent.E2A_TOOL_FILTER)
assert agent._authorization_headers() == {
"Authorization": "Bearer synthetic-agent-scoped-key"

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[MINOR] Perhaps this should use os.environ["E2A_API_KEY"] instead of hardcoding the synthetic key string?

"credential scope is `agent`",
"explicit instruction",
"verify a domain, not a person",
"list_messages",

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[MINOR] duplicate tool names from agent.E2A_TOOL_FILTER

@tommywagz

Copy link
Copy Markdown
Collaborator

Thank you for the contribution jjashouz, but the repo is moving to be more feature oriented than use case oriented. We are moving away from holding numerous use case samples that use the same core features and use a larger range of ADK and GCP features and tools.

@tommywagz tommywagz closed this Oct 23, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

stale No activity for the period set in .github/policy.yml status/not-ready-for-review Review requests held until checks pass and bot comments are resolved

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants