ADK-Python 如何用 get_fast_api_app 构建自托管 FastAPI 应用并挂载自己的路由【免费下载链接】adk-pythonAn open-source, code-first Python toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.项目地址: https://gitcode.com/GitHub_Trending/ad/adk-python当你需要自托管 ADK agents 时adk api_server命令会先遇到天花板它是一个完整的服务器你无法给它加路由、无法套上自己的鉴权中间件、无法把它挂到已有的 FastAPI 应用下也无法把它交给一个只要 ASGI callable 的进程管理器。ADK 为此提供了get_fast_api_app它返回一个已经装配好全部 ADK 路由的FastAPI应用对象你可以像操作普通 FastAPI 实例一样在它上面添加自己的路由、中间件和 lifespan然后用 uvicorn 这类 ASGI 服务器去跑它。这个函数与adk api_server内部使用的是同一套逻辑区别只在于你拿到的是应用对象而不是命令行。前提与 agents 目录布局先按 README 安装pip install google-adkagents_dir指向一个 agents 目录每个子目录是一个可导入的 Python 包agents/ home_automation/ __init__.py agent.py # defines root_agent support_bot/ __init__.py agent.py如果你把agents_dir指向单个 agent 的目录而不是包含多个 agent 的目录函数会自动检测到这一点它把父目录当作 agents 根目录并把该 agent 设为默认 app之后发请求时可以不带 app 名。构建应用并挂载自己的路由get_fast_api_app有两个必选的 keyword-only 参数agents_dir和web。下面的写法来自官方文档docs/guides/cli/fast_api/index.md其中的/build-info路由是文档给出的示例from google.adk.cli.fast_api import get_fast_api_app app get_fast_api_app(agents_dir./agents, webFalse) app.get(/build-info) async def build_info() - dict[str, str]: return {commit: abc123, environment: staging}拿到app后添加自己的路由、中间件都和普通 FastAPI 一致。然后用 ASGI 服务器启动uvicorn main:app --host 0.0.0.0 --port 8080注意参数名是agents_dir复数。写成agent_dir会直接报TypeError: get_fast_api_app() got an unexpected keyword argument agent_dir. Did you mean agents_dir?。启动后如何验证返回的 app 上已经带了状态端点不需要你自己加/healthGET /health返回{status: ok}GET /version返回 ADK 版本号文档示例中为 version、language、language_version 字段。webFalse时即文档所说的 production-safe 路由集底层是ApiServerapp 上还包含四组路由三种运行 agent 的方式/run、/run_sse、/run_live、session 与 artifact 的 CRUD 端点、/list-apps以及上述两个状态端点。JSON 线格式全程是 camelCase。可以用GET /list-apps确认目录中的 agent 被加载出来了。选择 webFalse 还是 webTruewebFalse只暴露上面列出的生产安全路由。webTrue返回DevServer在同样的路由之上附加 Angular UI 和/dev/...端点tracing、evaluation、agent builder路由数量大约增至三倍同时会为 config 定义的 agent 启用 YAML 键 denylist。部分生产发行包不包含开发服务器此时webTrue只会打一条警告并回退到ApiServerUI 和 eval 端点会静默消失。自托管上线一般用webFalse需要开发调试界面时再切webTrue。多副本部署时选择状态后端get_fast_api_app在返回 app 之前会解析 session、artifact、memory 三项服务credential 服务固定为InMemoryCredentialService没有对应参数。一旦部署超过一个副本、session 和 artifact 需要跨进程存活就要设置对应的 URI参数内置 schemesession_service_urimemory://、sqlite://、postgresql://、mysql://、agentengine://artifact_service_urimemory://、gs://Cloud Storage、file://memory_service_urimemory://、rag://Vertex RAG corpus、agentengine://task_store_uri仅a2aTrue时读取memory://、postgresqlasyncpg://、mysqlaiomysql://、sqliteaiosqlite://不设置 URI 时use_local_storage默认True决定行为session 落到agents_dir/agent/.adk/下的每 agent SQLite 文件artifact 落到本地文件memory 始终为内存。use_local_storageFalse则改用内存版 session 和 artifact。这里有一个文档明确警告的坑agents_dir不存在或不可写时不会报错函数只打一条警告并回退到内存服务——也就是说路径拼错时服务照常启动重启后全部丢失。启动后务必用/list-apps和一次真实的/run请求确认 agent 真的加载了、状态真的持久化了。session 还有一个额外行为未注册的 scheme 会回退成DatabaseSessionService把整个 URI 当作 SQLAlchemy URL 使用AlloyDB、Cloud Spanner 就是这么接入的artifact 和 memory 没有这种回退未识别的 scheme 会抛异常而且抛出的类型是click.ClickException而不是ValueError。bind_host 与 host一个安全开关host和port只用于展示CLI banner 打印不绑定任何端口真正绑定的是你用来 serve 这个 app 的进程例如 uvicorn。bind_host则是安全相关参数告诉函数你打算绑定到什么地址。如果该值是 loopback如127.0.0.1app 会开启 DNS-rebinding 保护——Host头指向非 loopback 地址、且不在allow_origins名单内的请求会被拒绝返回403 Forbidden: host not allowed。它防的是网页把自身域名解析到127.0.0.1再从浏览器里访问你的本地 agent。app get_fast_api_app( agents_dir./agents, webTrue, bind_host127.0.0.1, port8000 )三种情况会关掉这个保护bind_host保持None反代后面自托管的正确默认否则代理的域名会被拒传allow_origins[*]字面*被当作主动退出bind_host是非 loopback 值如0.0.0.0因为网络可达的服务器不能用必须从 loopback 到达我作为信号。可选分支lifespan、前缀挂载与自定义服务lifespan传一个 async context manager作为 app 的 lifespan用于数据库连接池、后台任务这类需要随启动打开、随关闭释放的资源。当a2aTrue且 task store 持有数据库引擎时ADK 会在你的 lifespan 外面再包一层保证引擎在你的 lifespan 退出后才 dispose。挂到已有应用的路径前缀下url_prefix不会给路由加前缀它只是告诉内置 UI 后端在哪个前缀下。要真正把 API 挂到前缀下应把返回的 appmount到父应用上。extra_plugins接完全限定名列表不是插件对象这些插件会加载到服务器创建的每个 runner 里。自定义 agent 来源实现BaseAgentLoader两个方法load_agent、list_agents并通过agent_loader传入可让 agent 从数据库、包或服务加载。注意agents_dir仍然是必填的因为服务注册和本地存储都从它查找。自定义 URI scheme在 agents 目录放一个services.py或services.yamlget_fast_api_app会在构造任何服务之前导入它们所以文件里注册的 scheme 在你传参时已经可用。YAML 形式适合类能按MyService(uri..., **kwargs)直接构建的场景type取session、artifact、memory、task_store之一两个文件同时存在时都加载YAML 先执行scheme 冲突时services.py获胜。示例见 services.py 和 services.yaml完整规则见 ServiceRegistry 指南。已知限制以下限制直接来自 官方文档自托管前需要心里有数返回的是 ASGI 应用host/port和这个 app 本身都不绑定端口必须有 uvicorn 之类的东西去 serve 它。credential 服务无法替换永远是InMemoryCredentialService工具凭证不跨重启存活也不跨进程共享。agents_dir拼错或目录只读时不会失败而是悄悄退化成内存存储。不支持的 artifact/memory URI 抛click.ClickException命令行异常类型泄漏到了库调用里。A2A 设置失败会被吞掉某个 agent 的agent.json损坏时只记日志并跳过服务器照常启动。a2aTrue时agents 根目录下每个含agent.json的子目录都会挂载/a2a/agent_name路由。函数签名的完整定义见 src/google/adk/cli/fast_api.py。【免费下载链接】adk-pythonAn open-source, code-first Python toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.项目地址: https://gitcode.com/GitHub_Trending/ad/adk-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ADK-Python 如何用 get_fast_api_app 构建自托管 FastAPI 应用并挂载自己的路由
ADK-Python 如何用 get_fast_api_app 构建自托管 FastAPI 应用并挂载自己的路由【免费下载链接】adk-pythonAn open-source, code-first Python toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.项目地址: https://gitcode.com/GitHub_Trending/ad/adk-python当你需要自托管 ADK agents 时adk api_server命令会先遇到天花板它是一个完整的服务器你无法给它加路由、无法套上自己的鉴权中间件、无法把它挂到已有的 FastAPI 应用下也无法把它交给一个只要 ASGI callable 的进程管理器。ADK 为此提供了get_fast_api_app它返回一个已经装配好全部 ADK 路由的FastAPI应用对象你可以像操作普通 FastAPI 实例一样在它上面添加自己的路由、中间件和 lifespan然后用 uvicorn 这类 ASGI 服务器去跑它。这个函数与adk api_server内部使用的是同一套逻辑区别只在于你拿到的是应用对象而不是命令行。前提与 agents 目录布局先按 README 安装pip install google-adkagents_dir指向一个 agents 目录每个子目录是一个可导入的 Python 包agents/ home_automation/ __init__.py agent.py # defines root_agent support_bot/ __init__.py agent.py如果你把agents_dir指向单个 agent 的目录而不是包含多个 agent 的目录函数会自动检测到这一点它把父目录当作 agents 根目录并把该 agent 设为默认 app之后发请求时可以不带 app 名。构建应用并挂载自己的路由get_fast_api_app有两个必选的 keyword-only 参数agents_dir和web。下面的写法来自官方文档docs/guides/cli/fast_api/index.md其中的/build-info路由是文档给出的示例from google.adk.cli.fast_api import get_fast_api_app app get_fast_api_app(agents_dir./agents, webFalse) app.get(/build-info) async def build_info() - dict[str, str]: return {commit: abc123, environment: staging}拿到app后添加自己的路由、中间件都和普通 FastAPI 一致。然后用 ASGI 服务器启动uvicorn main:app --host 0.0.0.0 --port 8080注意参数名是agents_dir复数。写成agent_dir会直接报TypeError: get_fast_api_app() got an unexpected keyword argument agent_dir. Did you mean agents_dir?。启动后如何验证返回的 app 上已经带了状态端点不需要你自己加/healthGET /health返回{status: ok}GET /version返回 ADK 版本号文档示例中为 version、language、language_version 字段。webFalse时即文档所说的 production-safe 路由集底层是ApiServerapp 上还包含四组路由三种运行 agent 的方式/run、/run_sse、/run_live、session 与 artifact 的 CRUD 端点、/list-apps以及上述两个状态端点。JSON 线格式全程是 camelCase。可以用GET /list-apps确认目录中的 agent 被加载出来了。选择 webFalse 还是 webTruewebFalse只暴露上面列出的生产安全路由。webTrue返回DevServer在同样的路由之上附加 Angular UI 和/dev/...端点tracing、evaluation、agent builder路由数量大约增至三倍同时会为 config 定义的 agent 启用 YAML 键 denylist。部分生产发行包不包含开发服务器此时webTrue只会打一条警告并回退到ApiServerUI 和 eval 端点会静默消失。自托管上线一般用webFalse需要开发调试界面时再切webTrue。多副本部署时选择状态后端get_fast_api_app在返回 app 之前会解析 session、artifact、memory 三项服务credential 服务固定为InMemoryCredentialService没有对应参数。一旦部署超过一个副本、session 和 artifact 需要跨进程存活就要设置对应的 URI参数内置 schemesession_service_urimemory://、sqlite://、postgresql://、mysql://、agentengine://artifact_service_urimemory://、gs://Cloud Storage、file://memory_service_urimemory://、rag://Vertex RAG corpus、agentengine://task_store_uri仅a2aTrue时读取memory://、postgresqlasyncpg://、mysqlaiomysql://、sqliteaiosqlite://不设置 URI 时use_local_storage默认True决定行为session 落到agents_dir/agent/.adk/下的每 agent SQLite 文件artifact 落到本地文件memory 始终为内存。use_local_storageFalse则改用内存版 session 和 artifact。这里有一个文档明确警告的坑agents_dir不存在或不可写时不会报错函数只打一条警告并回退到内存服务——也就是说路径拼错时服务照常启动重启后全部丢失。启动后务必用/list-apps和一次真实的/run请求确认 agent 真的加载了、状态真的持久化了。session 还有一个额外行为未注册的 scheme 会回退成DatabaseSessionService把整个 URI 当作 SQLAlchemy URL 使用AlloyDB、Cloud Spanner 就是这么接入的artifact 和 memory 没有这种回退未识别的 scheme 会抛异常而且抛出的类型是click.ClickException而不是ValueError。bind_host 与 host一个安全开关host和port只用于展示CLI banner 打印不绑定任何端口真正绑定的是你用来 serve 这个 app 的进程例如 uvicorn。bind_host则是安全相关参数告诉函数你打算绑定到什么地址。如果该值是 loopback如127.0.0.1app 会开启 DNS-rebinding 保护——Host头指向非 loopback 地址、且不在allow_origins名单内的请求会被拒绝返回403 Forbidden: host not allowed。它防的是网页把自身域名解析到127.0.0.1再从浏览器里访问你的本地 agent。app get_fast_api_app( agents_dir./agents, webTrue, bind_host127.0.0.1, port8000 )三种情况会关掉这个保护bind_host保持None反代后面自托管的正确默认否则代理的域名会被拒传allow_origins[*]字面*被当作主动退出bind_host是非 loopback 值如0.0.0.0因为网络可达的服务器不能用必须从 loopback 到达我作为信号。可选分支lifespan、前缀挂载与自定义服务lifespan传一个 async context manager作为 app 的 lifespan用于数据库连接池、后台任务这类需要随启动打开、随关闭释放的资源。当a2aTrue且 task store 持有数据库引擎时ADK 会在你的 lifespan 外面再包一层保证引擎在你的 lifespan 退出后才 dispose。挂到已有应用的路径前缀下url_prefix不会给路由加前缀它只是告诉内置 UI 后端在哪个前缀下。要真正把 API 挂到前缀下应把返回的 appmount到父应用上。extra_plugins接完全限定名列表不是插件对象这些插件会加载到服务器创建的每个 runner 里。自定义 agent 来源实现BaseAgentLoader两个方法load_agent、list_agents并通过agent_loader传入可让 agent 从数据库、包或服务加载。注意agents_dir仍然是必填的因为服务注册和本地存储都从它查找。自定义 URI scheme在 agents 目录放一个services.py或services.yamlget_fast_api_app会在构造任何服务之前导入它们所以文件里注册的 scheme 在你传参时已经可用。YAML 形式适合类能按MyService(uri..., **kwargs)直接构建的场景type取session、artifact、memory、task_store之一两个文件同时存在时都加载YAML 先执行scheme 冲突时services.py获胜。示例见 services.py 和 services.yaml完整规则见 ServiceRegistry 指南。已知限制以下限制直接来自 官方文档自托管前需要心里有数返回的是 ASGI 应用host/port和这个 app 本身都不绑定端口必须有 uvicorn 之类的东西去 serve 它。credential 服务无法替换永远是InMemoryCredentialService工具凭证不跨重启存活也不跨进程共享。agents_dir拼错或目录只读时不会失败而是悄悄退化成内存存储。不支持的 artifact/memory URI 抛click.ClickException命令行异常类型泄漏到了库调用里。A2A 设置失败会被吞掉某个 agent 的agent.json损坏时只记日志并跳过服务器照常启动。a2aTrue时agents 根目录下每个含agent.json的子目录都会挂载/a2a/agent_name路由。函数签名的完整定义见 src/google/adk/cli/fast_api.py。【免费下载链接】adk-pythonAn open-source, code-first Python toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.项目地址: https://gitcode.com/GitHub_Trending/ad/adk-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考