Merge branch 'main' into zzz-day-02-notes

Author: ZZhusihan

.github/workflows/lint-pr-title.yml

@@ -0,0 +1,23 @@
+name: "Lint PR Title"
+
+on:
+  pull_request:
+    types:
+      - opened
+      - edited
+      - synchronize
+
+jobs:
+  main:
+    name: Validate PR Title
+    runs-on: ubuntu-slim
+    steps:
+      - name: Semantic PR Title
+        uses: amannn/action-semantic-pull-request@v5
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          # Enforce that the subject starts with a lowercase letter.
+          subjectPattern: ^[a-z].*$
+          subjectPatternError: |
+            The subject "{subject}" must start with a lowercase letter.

agents/my_agent/agent.py

@@ -0,0 +1,45 @@
+from google.adk.agents.config_agent_utils import load_agent_from_config
+from google.adk.runners import Runner
+from google.adk.sessions import InMemorySessionService
+from google.genai import types
+import asyncio
+from pathlib import Path
+
+# CONFIGURATION
+APP_NAME = "simple_search_agent"
+USER_ID = "user_default"
+SESSION_ID = "session_01"
+
+# AGENT DEFINITION - Load from YAML using ADK's built-in method
+yaml_path = Path(__file__).parent / 'root_agent.yaml'
+root_agent = load_agent_from_config(str(yaml_path))
+
+
+# Session and Runner
+async def setup_session_and_runner():
+    session_service = InMemorySessionService()
+    session = await session_service.create_session(
+        app_name=APP_NAME, user_id=USER_ID, session_id=SESSION_ID
+    )
+    runner = Runner(
+        agent=root_agent, app_name=APP_NAME, session_service=session_service
+    )
+    return session, runner
+
+
+# Agent Interaction
+async def call_agent_async(query):
+    content = types.Content(role="user", parts=[types.Part(text=query)])
+    session, runner = await setup_session_and_runner()
+    events = runner.run_async(
+        user_id=USER_ID, session_id=SESSION_ID, new_message=content
+    )
+
+    async for event in events:
+        if event.is_final_response():
+            final_response = event.content.parts[0].text
+            print("Agent Response: ", final_response)
+
+
+if __name__ == "__main__":
+    asyncio.run(call_agent_async("what's the latest ai news?"))

agents/my_agent/root_agent.yaml

@@ -1,5 +1,11 @@
 # yaml-language-server: $schema=https://raw.githubusercontent.com/google/adk-python/refs/heads/main/src/google/adk/agents/config_schemas/AgentConfig.json
-name: root_agent
-description: A helpful assistant for user questions.
-instruction: Answer user questions to the best of your knowledge
+name: search_agent
+description: A helpful assistant that can search Google.
+instruction: |
+  You are a helpful assistant with access to Google Search.
+
+  If the user asks a question that requires current information or facts, use the 'google_search' tool.
+  Always cite your sources implicitly by providing the answer clearly based on the search results.
 model: gemini-2.5-flash
+tools:
+  - name: google_search

figs/day-03.png

@@ -20,6 +20,9 @@
 - 后续使用方便起见，这次直接安装了完整的 `google-adk` 包
 - 注意⚠️：其中的 `MCP` 组件强制要求Python版本在**3.10**以上，新建环境时要注意编译器的选择
 - 在Pycharm终端调用agent互动时，无法显式输出日志，只能通过prompt要求输出思考过程
+- 网站上给的 command 是错误的，运行 `uvx --from google-adk adk web` 时默认时读取 a directory of agents，而不是在 agent directory。
+- Tutorial: AI agent with Google Search(YAML) instruction 也是错的. `adk web` 运行的时候directory应该在agent的parent folder里。
+- Tutorial: Multi-agent app with MCP (YAML) 要安装Node.Js 是firecrawl的dependency。firecrawl需要注册，free tier不需要花钱，api key能在设置里找到。
 
 ## Code Examples
 
@@ -46,6 +49,20 @@ model: gemini-2.5-flash
 tools:
   - name: google_search
 ```
+### `adk api_server` 的使用
+以调取api的模式使用agent不能直接点击网页或者和UI直接交互。just in case有人和我一样不懂怎么调取api，下面是使用范例。
+
+输入`adk api_server` 之后新开一个terminal
+```bash
+curl -X POST http://localhost:8000/apps/my_agent/users/u_123/sessions/s_123 -H "Content-Type: application/json"
+```
+apps 后面是agent的名字，user后面是userId，session后面是sessionId.
+
+```bash
+curl -X POST http://localhost:8000/run -H "Content-Type: application/json" -d '{"appName":"my_agent", "userId":"u_123", "sessionId":"s_123", "newMessage": {"role": "user", "parts":[{"text": "hello"}]}}'
+```
+app_name、userId、sessionId需要和上文对应。text后输入user想说的话。
+你会在这个terminal看到model的回复。
 
 ## Resources
 

notes/day-02.md

@@ -0,0 +1,29 @@
+# Day 03 - 在 Python 代码中加载 YAML 配置的智能体
+
+**挑战链接**: [Advent of Agents - Day 03](https://adventofagents.com/day/03)
+
+![Day 03 Screenshot](figs/day-03.png)
+
+## 关键学习
+
+- Google ADK 提供了内置方法 `load_agent_from_config()` 来从 YAML 文件加载智能体配置
+- YAML 配置文件可以包含完整的智能体定义，包括名称、描述、指令、模型和工具
+- 工具可以在 YAML 文件中通过 `tools` 部分定义，例如 `google_search`
+- ADK Web Developer UI 可以自动检测并加载 Python 代码中定义的智能体
+- 使用 `Path(__file__).parent` 可以获取相对于当前脚本文件的路径，方便加载同目录下的 YAML 文件
+
+## 面临的挑战
+
+- 最初尝试手动解析 YAML 文件，但发现 ADK 有更优雅的内置方法
+- 需要了解 `Agent` 类和 `LlmAgent` 类的区别，以及何时使用 `load_agent_from_config`
+- 确保 YAML 文件中的工具名称与 ADK 提供的工具名称匹配
+
+## 资源
+
+- [ADK Config Agent Documentation](http://google.github.io/adk-docs/agent/config/) - 使用 YAML 配置构建智能体的官方文档
+- [ADK Agents API Reference](http://google.github.io/adk-docs/agents/) - 智能体 API 参考文档
+- [Google ADK Python Documentation](http://google.github.io/adk-docs/) - ADK Python 完整文档
+
+## 问题 / 开放话题
+
+- 不是必须要用 Gemini Pro 3，在 YAML 配置里把 model 模型改成 free tier 里提供的即可

notes/day-03.md

@@ -0,0 +1,47 @@
+# Day 04 - [源码部署]
+
+**挑战链接**: [Advent of Agents - Day 04](https://adventofagents.com/day/04)
+
+## 关键学习
+
+- **使用 agent-starter-pack 自动生成部署配置**：通过 `uvx agent-starter-pack enhance -d agent_engine` 命令，工具会自动生成所有 Vertex AI Agent Engine 部署所需的代码和配置（包括 `deploy.py`、`agent_engine_app.py`、Makefile 等）。部署时使用 `make deploy` 即可，工具会自动处理源代码打包、上传到云端、构建容器镜像等步骤，无需手动配置。
+
+## 面临的挑战
+
+- **Google Cloud SDK 安装和配置**：
+  - 需要安装 Google Cloud SDK (`gcloud`)
+  - 运行 `gcloud auth application-default login` 进行身份认证
+
+- **必须启用的 API**：
+  - Vertex AI API - 核心服务，用于部署 agent
+  - Cloud Resource Manager API - 用于项目资源管理
+
+- **项目 ID 配置**：
+  - 必须设置 Google Cloud 项目 ID，否则部署会失败
+  - 可以通过环境变量 `export GOOGLE_CLOUD_PROJECT=your-project-id` 设置
+  - 或通过 Makefile 参数 `make deploy PROJECT_ID=your-project-id` 传递
+  - 或使用 `gcloud config set project your-project-id` 设置默认项目
+
+- **成本优化配置**：
+  - 默认 `min-instances=1` 会导致持续计费（约 $50-100/月）
+  - 可以手动设置 `min-instances=0` 实现按需启动，空闲时缩容到零
+  - **Vertex AI Agent Engine Free Tier**（每月免费额度）：
+    - vCPU：前 180,000 vCPU秒（50 小时）免费
+    - RAM：前 360,000 GiB秒（100 小时）免费
+
+## 代码示例
+
+```python
+# 在此添加你的代码示例
+```
+
+## 资源
+
+- [Source-Based Deployment Tutorial(Video)](https://www.youtube.com/watch?v=8RjzMG3BKA0)
+- [Agent Starter Pack](https://github.com/GoogleCloudPlatform/agent-starter-pack)
+- [Agent Engine Deployment Docs](https://docs.cloud.google.com/agent-builder/agent-engine/deploy)
+
+## 问题 / 开放话题
+
+-
+-