Skip to content

docs(callbacks): align callback contracts with runtime behavior - #7022

Open
jaywang172 wants to merge 1 commit into
google:mainfrom
jaywang172:docs/callback-short-circuit-semantics
Open

docs(callbacks): align callback contracts with runtime behavior#7022
jaywang172 wants to merge 1 commit into
google:mainfrom
jaywang172:docs/callback-short-circuit-semantics

Conversation

@jaywang172

Copy link
Copy Markdown
Contributor

Link to Issue or Description of Change

Companion user guide: google/adk-docs#2207

The callback API docstrings have drifted from the runtime: before/after agent
and model callbacks stop on truthy responses, and agent callbacks support
positional argument fallback even though the docs require a particular name.

Align the existing docstrings with the current contracts:

  • Describe keyword-first binding, positional fallback, and the requirement to
    use canonical names for keyword-only parameters.
  • Document truthy stopping for before/after agent and model callbacks.
  • Specify LlmResponse for model responses and error recovery.
  • Make non-None stopping explicit for tool callbacks, including {} as a
    valid response that skips the tool, replaces its result, or handles an error.

Only docstrings change; callback execution and public signatures are unchanged.
This is independent of #7008.

Testing Plan

  • Python 3.11: 214 existing tests passed across the callback pipeline, agent
    fields, base agent, model callbacks, and regular/live tool callbacks.
  • Executed the companion guide's four callback signature examples against the
    current helper: canonical names, positional aliases, and canonical
    keyword-only parameters work; a renamed keyword-only parameter raises
    TypeError as documented.
  • Compared both files' ASTs after removing docstrings: executable AST unchanged.
  • pre-commit run --files src/google/adk/agents/base_agent.py src/google/adk/agents/llm_agent.py: passed.
  • git diff --check: passed.

No model requests or Google credentials were needed. No new runtime tests were
added for this documentation-only change.

Checklist

  • Read CONTRIBUTING.md and performed a self-review.
  • Verified the documentation against the implementation and existing tests.
  • Updated the user-facing callback guide in a companion adk-docs PR.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants