docs(live): add live agent guardrails guide and Model Armor plugin - #2223
Conversation
✅ Deploy Preview for adk-docs-preview ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
kazunori279
left a comment
kazunori279
left a comment
There was a problem hiding this comment.
Verified the two new pages against adk-python 460715b6. Nice to see the live guardrail story written down in one place. Four things I think should be addressed before merge: two code/behavior errors and two gaps around live-specific behavior. Details inline.
I also have a few medium-priority notes (output blocking is best-effort once audio has streamed, the upstream guide's Limitations section isn't carried over, and the function_response description is slightly off) — happy to add those if useful.
The example used (callback_context, tool_name, tool_args), which matches neither the agent-level nor the plugin-level tool callback signature, so it would fail at call time. Use the agent-level form documented by _SingleBeforeToolCallback: (tool, args, tool_context).
joefernandez
left a comment
joefernandez
left a comment
There was a problem hiding this comment.
RISK REVIEW: Content risk review — 🟡 Medium (score 87). The technical substance checks out: ModelArmorConfig fields and defaults, the ValueError on region mismatch, custom_metadata['model_armor_blocked'], the three live callback sites, the RunConfig transcription defaults, and the Python v2.8.0 tag all match adk-python, and all external links resolve. The remaining issues are wording on a security page: absolute guarantee and latency claims, and one output-screening claim that does not hold for the live audio path. Inline suggestions below.
joefernandez
left a comment
joefernandez
left a comment
There was a problem hiding this comment.
CODE REVIEW: Content risk assessment — score 91 / 🟡 Medium risk. Approve with changes.
Every API-level claim checks out against the released v2.8.0 / v2.9.0 tags of google/adk-python: module paths, ModelArmorConfig fields and defaults, the ValueError conditions, the gcp extra, custom_metadata['model_armor_blocked'], the RunConfig transcription defaults, and safety-settings forwarding into the live connect config. Nothing unreleased is referenced.
The remaining issues are behavioral descriptions of the live callback sites. Two are worth fixing before merge:
docs/callbacks/types-of-callbacks.md:175— "a block resets the connection" is wrong for the typed-text site and contradicts the new guardrails page.docs/live/guardrails.md:127and:195— the liveafter_model_callbackis never invoked with a finished transcription, so "evaluate the complete turn transcription" is not achievable.
Plus three smaller ones: spoken input is screened after the model has the audio, the callback sees accumulated rather than incremental text, and none of the three examples is wired to an agent.
joefernandez
left a comment
joefernandez
left a comment
There was a problem hiding this comment.
Content style review — 78/100, 🟡 Medium risk
Both new pages follow the repo templates (integrations front matter, sentence-case headings, Use cases / Prerequisites / Installation / Use with agent), and the nav, plugin-list, and safety-page cross-links all match existing convention. Approve with the changes below.
The one item that should not merge as written is the unqualified security claim in the intro at docs/live/guardrails.md#L7-L10 — house style does not assert that a feature makes something safe or secure.
Also worth a look:
- Code formatting — all three Python blocks in docs/live/guardrails.md#L101-L176 use 2-space indentation against the repo's 4-space convention, and single-quoted strings where the docs mostly use double.
- Factual contradiction — docs/callbacks/types-of-callbacks.md#L175 says a block "resets the connection", while docs/live/guardrails.md#L84-L86 says blocking keeps the connection open.
- Smaller items: an absolute "ensures", four passive constructions, a superlative heading, and two bits of flowery phrasing, all flagged inline.
No instances of "we"/"us", "e.g.", or banned AI phrasing were found.
Co-authored-by: Joe Fernandez <931947+joefernandez@users.noreply.github.com>
Co-authored-by: Joe Fernandez <931947+joefernandez@users.noreply.github.com>
Co-authored-by: Joe Fernandez <931947+joefernandez@users.noreply.github.com>
Co-authored-by: Joe Fernandez <931947+joefernandez@users.noreply.github.com>
Co-authored-by: Joe Fernandez <931947+joefernandez@users.noreply.github.com>
Co-authored-by: Joe Fernandez <931947+joefernandez@users.noreply.github.com>
Co-authored-by: Joe Fernandez <931947+joefernandez@users.noreply.github.com>
Co-authored-by: Joe Fernandez <931947+joefernandez@users.noreply.github.com>
Co-authored-by: Joe Fernandez <931947+joefernandez@users.noreply.github.com>
joefernandez
left a comment
joefernandez
left a comment
There was a problem hiding this comment.
Thanks for the updates. please address a few of these resolved comments (now marked as unresolved)
joefernandez
left a comment
joefernandez
left a comment
There was a problem hiding this comment.
Thanks for this contribution! Approved.
…oogle#2223) * docs(live): add live agent guardrails guide and Model Armor plugin * docs(live): fix before_tool_callback signature in guardrails example The example used (callback_context, tool_name, tool_args), which matches neither the agent-level nor the plugin-level tool callback signature, so it would fail at call time. Use the agent-level form documented by _SingleBeforeToolCallback: (tool, args, tool_context). * Update docs/live/guardrails.md Co-authored-by: Joe Fernandez <931947+joefernandez@users.noreply.github.com> * Update docs/integrations/model-armor.md Co-authored-by: Joe Fernandez <931947+joefernandez@users.noreply.github.com> * Update docs/integrations/model-armor.md Co-authored-by: Joe Fernandez <931947+joefernandez@users.noreply.github.com> * Update docs/live/guardrails.md Co-authored-by: Joe Fernandez <931947+joefernandez@users.noreply.github.com> * Update docs/live/guardrails.md Co-authored-by: Joe Fernandez <931947+joefernandez@users.noreply.github.com> * Update docs/live/guardrails.md Co-authored-by: Joe Fernandez <931947+joefernandez@users.noreply.github.com> * Update docs/callbacks/types-of-callbacks.md Co-authored-by: Joe Fernandez <931947+joefernandez@users.noreply.github.com> * Update docs/live/guardrails.md Co-authored-by: Joe Fernandez <931947+joefernandez@users.noreply.github.com> * Update docs/live/guardrails.md Co-authored-by: Joe Fernandez <931947+joefernandez@users.noreply.github.com> * docs(live): address code and style feedback --------- Co-authored-by: Joe Fernandez <931947+joefernandez@users.noreply.github.com>
3 participants
Adds comprehensive documentation for live voice agent guardrails and the Model Armor plugin shipped in ADK Python v2.8.0.
docs/live/guardrails.md: product-oriented guide covering multi-layered defense (system instructions, platform safety filters, user input validation, agent response validation, and tool execution guardrails).docs/integrations/model-armor.md: guide forModelArmorPlugin, covering template configuration, single-region requirements, failure handling, and block markers.docs/callbacks/,docs/safety/,docs/plugins/,docs/live/, andmkdocs.yml.