feat(integrations-py): forward FastAPI route kwargs from the endpoint helpers - #2645
Merged
Merged
Conversation
… helpers Every Python endpoint helper except add_strands_fastapi_endpoint registered its agent route with a bare decorator, so an application embedding an agent route in an existing API could not set the route's name, tags, summary, operation_id, dependencies or include_in_schema. The derived operation_id in particular is unstable and collides between two agent routes, which breaks OpenAPI client generators. Each helper now takes **kwargs and forwards it to app.post for the agent route only. The health, capabilities and /agents/state routes keep their own identity, because FastAPI requires a unique operation_id and name per operation and a health probe usually has to stay reachable without the agent route's dependencies. Every helper also accepts an APIRouter, which ag-ui-adk already did, and create_adk_app / create_langroid_app forward **kwargs to the helper they wrap. add_langroid_fastapi_endpoint already accepted **kwargs and dropped them; they now reach the route. Defaults are unchanged, so this is additive for current callers. Reported downstream as CopilotKit/CopilotKit#1270, with the duplicate operationId half reported separately as CopilotKit/CopilotKit#2672. Closes #2644 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Contributor
Python Preview PackagesVersion
Install with uvAdd the TestPyPI index to your [[tool.uv.index]]
name = "testpypi"
url = "https://test.pypi.org/simple/"
explicit = trueThen install the packages you need: # Core SDK
uv add 'ag-ui-protocol==0.0.0.dev1788543215' --index testpypi
# Integrations (each already depends on the matching ag-ui-protocol preview)
uv add 'ag-ui-langgraph==0.0.0.dev1788543215' --index testpypi
uv add 'ag-ui-crewai==0.0.0.dev1788543215' --index testpypi
# NOTE: ag-ui-agent-spec depends on pyagentspec (git-only, not on PyPI).
# You will need to install pyagentspec separately from its git repo.
uv add 'ag-ui-agent-spec==0.0.0.dev1788543215' --index testpypi
uv add 'ag_ui_adk==0.0.0.dev1788543215' --index testpypi
uv add 'ag_ui_strands==0.0.0.dev1788543215' --index testpypiInstall with pippip install \
--index-url https://test.pypi.org/simple/ \
--extra-index-url https://pypi.org/simple/ \
ag-ui-protocol==0.0.0.dev1788543215
Commit: e21405f |
@ag-ui/a2a-middleware
@ag-ui/a2ui-middleware
@ag-ui/event-throttle-middleware
@ag-ui/mcp-apps-middleware
@ag-ui/mcp-middleware
@ag-ui/a2a
@ag-ui/adk
@ag-ui/ag2
@ag-ui/agno
@ag-ui/aws-strands
@ag-ui/claude-agent-sdk
@ag-ui/claude-managed-agents
@ag-ui/crewai
@ag-ui/langchain
@ag-ui/langgraph
@ag-ui/llamaindex
@ag-ui/mastra
@ag-ui/pydantic-ai
@ag-ui/vercel-ai-sdk
@ag-ui/watsonx
@ag-ui/a2ui-toolkit
create-ag-ui-app
@ag-ui/client
@ag-ui/core
@ag-ui/encoder
@ag-ui/proto
commit: |
MikeRyanDev
approved these changes
Sep 4, 2026
MikeRyanDev
left a comment
MikeRyanDev
left a comment
Contributor
There was a problem hiding this comment.
Cursory review: no critical issues found.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #2644. Reported downstream as CopilotKit/CopilotKit#1270 (Jan 2025, second reporter Jun 2025); the duplicate-
operationIdhalf was reported separately as CopilotKit/CopilotKit#2672 and closed with a codegen workaround.Problem
Every Python endpoint helper except
add_strands_fastapi_endpointregistered its agent route with a bare decorator:An application that mounts an agent route inside an existing API could not set:
operation_id— FastAPI derives it from the handler name and path, so it is unstable and two agent routes in one app collide. OpenAPI client generators break on it.dependencies— the app's own auth or rate-limit dependency could not be attached. The only workaround was global middleware, which then also covers routes that must stay open.include_in_schema— the agent route could not be hidden from a public/docs.name— noapp.url_path_for(...)reverse lookup.tags,summary,description— no grouping in/docs, and an API governance lint gate that requires a tag on every operation could not pass.Change
Each helper takes
**kwargs: Anyand forwards it toapp.postfor the agent route only:add_langgraph_fastapi_endpointag-ui-langgraphadd_crewai_flow_fastapi_endpoint,add_crewai_crew_fastapi_endpointag-ui-crewaiadd_adk_fastapi_endpoint,create_adk_appag-ui-adkadd_agentspec_fastapi_endpointag-ui-agent-specadd_claude_fastapi_endpointag-ui-claude-sdkadd_managed_agents_fastapi_endpointag-ui-claude-managed-agentsadd_watsonx_fastapi_endpointag-ui-watsonxadd_langroid_fastapi_endpoint,create_langroid_appag_ui_langroidAlso in this PR:
appasFastAPI | APIRouter, whichag-ui-adkalready did. Mounting on a router is how an existing app gives the agent route a prefix.create_adk_appandcreate_langroid_appforward**kwargsto the helper they wrap.add_langroid_fastapi_endpointalready accepted**kwargsand silently dropped them. They now reach the route.ag-ui-strandsis untouched: it already forwards route kwargs, and this PR follows its precedent.Defaults are unchanged, so the change is additive for current callers.
Design note: the agent route only
Metadata is not copied onto the other routes a helper registers (
<path>/health,<path>/capabilities,/agents/state), for two reasons:operation_idandnameper operation. Copying them would recreate the duplicate-operationIdbug this PR is meant to fix.dependencies.Both are asserted by tests, so the decision is pinned rather than implied.
Testing
New test module per package (
tests/test_endpoint_route_kwargs.py), each covering: metadata on the agent route,include_in_schema,dependencieson the agent route only, registration on anAPIRouter, an unchanged default registration, and — where a second route exists — that the health route keeps its ownoperationIdand tags.Every suite run locally from a clean worktree at
origin/main(uv sync --frozen, thenuv run pytest):New tests only:
Mutation-checked, so the tests fail for the intended reason:
@app.post(path, **kwargs)to@app.post(path): langgraph 4 failed / 2 passed, adk 3 failed / 2 passed, langroid 4/2, watsonx 4/2, claude-agent-sdk 4/2, claude-managed-agents 4/2, agent-spec 4/1, crew-ai 5/1.test_health_route_keeps_its_own_identity.**kwargsforwarding fromcreate_adk_app:test_create_adk_app_forwards_route_kwargsfailed.Pre-existing failure, unrelated to this change:
integrations/langgraph/python/examples/tests/test_deepagents_subagents_contract.py::test_deepagents_subagents_graph_imports_without_openai_key. Verified on a pristineorigin/maincheckout with this PR's files reverted — it fails there too.🤖 Generated with Claude Code
CI coverage note
unit-python-sdk.ymlhas no job forintegrations/agent-spec/pythonorintegrations/claude-agent-sdk/python, so the test modules those two packages already carry — and the two added here — never run in CI. The runs above are the only verification for them. Worth a follow-up; I did not add the jobs in this PR.