Skip to content

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

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

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.

@adk-bot

adk-bot commented Sep 9, 2026

Copy link
Copy Markdown
Collaborator

Thank you @jaywang172 for your contribution! 🎉

Your changes have been successfully imported and merged via Copybara in commit 6a811d2.

Closing this PR as the changes are now in the main branch.

@adk-bot adk-bot added the merged [Status] This PR is merged label Sep 9, 2026
@adk-bot adk-bot closed this Sep 9, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

merged [Status] This PR is merged

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants