docs(config): add examples for config agents

PiperOrigin-RevId: 793871778

Author: wuliang229

contributing/samples/core_basic/README.md

@@ -0,0 +1,7 @@
+# Basic Confg-based Agent
+
+This sample only covers:
+
+* name
+* description
+* model

contributing/samples/core_basic/root_agent.yaml

@@ -0,0 +1,9 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/google/adk-python/refs/heads/main/src/google/adk/agents/config_schemas/AgentConfig.json
+name: assistant_agent
+model: gemini-2.5-flash
+description: A helper agent that can answer users' questions.
+instruction: |
+  You are an agent to help answer users' various questions.
+
+  1. If the user's intention is not clear, ask clarifying questions to better understand their needs.
+  2. Once the intention is clear, provide accurate and helpful answers to the user's questions.

contributing/samples/core_callback/callbacks.py

@@ -0,0 +1,79 @@
+from google.genai import types
+
+
+async def before_agent_callback(callback_context):
+  print('@before_agent_callback')
+  return None
+
+
+async def after_agent_callback(callback_context):
+  print('@after_agent_callback')
+  return None
+
+
+async def before_model_callback(callback_context, llm_request):
+  print('@before_model_callback')
+  return None
+
+
+async def after_model_callback(callback_context, llm_response):
+  print('@after_model_callback')
+  return None
+
+
+def after_agent_callback1(callback_context):
+  print('@after_agent_callback1')
+
+
+def after_agent_callback2(callback_context):
+  print('@after_agent_callback2')
+  # ModelContent (or Content with role set to 'model') must be returned.
+  # Otherwise, the event will be excluded from the context in the next turn.
+  return types.ModelContent(
+      parts=[
+          types.Part(
+              text='(stopped) after_agent_callback2',
+          ),
+      ],
+  )
+
+
+def after_agent_callback3(callback_context):
+  print('@after_agent_callback3')
+
+
+def before_agent_callback1(callback_context):
+  print('@before_agent_callback1')
+
+
+def before_agent_callback2(callback_context):
+  print('@before_agent_callback2')
+
+
+def before_agent_callback3(callback_context):
+  print('@before_agent_callback3')
+
+
+def before_tool_callback1(tool, args, tool_context):
+  print('@before_tool_callback1')
+
+
+def before_tool_callback2(tool, args, tool_context):
+  print('@before_tool_callback2')
+
+
+def before_tool_callback3(tool, args, tool_context):
+  print('@before_tool_callback3')
+
+
+def after_tool_callback1(tool, args, tool_context, tool_response):
+  print('@after_tool_callback1')
+
+
+def after_tool_callback2(tool, args, tool_context, tool_response):
+  print('@after_tool_callback2')
+  return {'test': 'after_tool_callback2', 'response': tool_response}
+
+
+def after_tool_callback3(tool, args, tool_context, tool_response):
+  print('@after_tool_callback3')

contributing/samples/core_callback/root_agent.yaml

@@ -0,0 +1,43 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/google/adk-python/refs/heads/main/src/google/adk/agents/config_schemas/AgentConfig.json
+name: hello_world_agent
+model: gemini-2.0-flash
+description: hello world agent that can roll a dice and check prime numbers.
+instruction: |
+  You roll dice and answer questions about the outcome of the dice rolls.
+  You can roll dice of different sizes.
+  You can use multiple tools in parallel by calling functions in parallel(in one request and in one round).
+  It is ok to discuss previous dice roles, and comment on the dice rolls.
+  When you are asked to roll a die, you must call the roll_die tool with the number of sides. Be sure to pass in an integer. Do not pass in a string.
+  You should never roll a die on your own.
+  When checking prime numbers, call the check_prime tool with a list of integers. Be sure to pass in a list of integers. You should never pass in a string.
+  You should not check prime numbers before calling the tool.
+  When you are asked to roll a die and check prime numbers, you should always make the following two function calls:
+  1. You should first call the roll_die tool to get a roll. Wait for the function response before calling the check_prime tool.
+  2. After you get the function response from roll_die tool, you should call the check_prime tool with the roll_die result.
+    2.1 If user asks you to check primes based on previous rolls, make sure you include the previous rolls in the list.
+  3. When you respond, you must include the roll_die result from step 1.
+  You should always perform the previous 3 steps when asking for a roll and checking prime numbers.
+  You should not rely on the previous history on prime results.
+tools:
+  - name: callbacks.tools.roll_die
+  - name: callbacks.tools.check_prime
+before_agent_callbacks:
+  - name: callbacks.callbacks.before_agent_callback1
+  - name: callbacks.callbacks.before_agent_callback2
+  - name: callbacks.callbacks.before_agent_callback3
+after_agent_callbacks:
+  - name: callbacks.callbacks.after_agent_callback1
+  - name: callbacks.callbacks.after_agent_callback2
+  - name: callbacks.callbacks.after_agent_callback3
+before_model_callbacks:
+  - name: callbacks.callbacks.before_model_callback
+after_model_callbacks:
+  - name: callbacks.callbacks.after_model_callback
+before_tool_callbacks:
+  - name: callbacks.callbacks.before_tool_callback1
+  - name: callbacks.callbacks.before_tool_callback2
+  - name: callbacks.callbacks.before_tool_callback3
+after_tool_callbacks:
+  - name: callbacks.callbacks.after_tool_callback1
+  - name: callbacks.callbacks.after_tool_callback2
+  - name: callbacks.callbacks.after_tool_callback3

contributing/samples/core_callback/tools.py

@@ -0,0 +1,48 @@
+import random
+
+from google.adk.tools.tool_context import ToolContext
+
+
+def roll_die(sides: int, tool_context: ToolContext) -> int:
+  """Roll a die and return the rolled result.
+
+  Args:
+    sides: The integer number of sides the die has.
+
+  Returns:
+    An integer of the result of rolling the die.
+  """
+  result = random.randint(1, sides)
+  if not 'rolls' in tool_context.state:
+    tool_context.state['rolls'] = []
+
+  tool_context.state['rolls'] = tool_context.state['rolls'] + [result]
+  return result
+
+
+def check_prime(nums: list[int]) -> str:
+  """Check if a given list of numbers are prime.
+
+  Args:
+    nums: The list of numbers to check.
+
+  Returns:
+    A str indicating which number is prime.
+  """
+  primes = set()
+  for number in nums:
+    number = int(number)
+    if number <= 1:
+      continue
+    is_prime = True
+    for i in range(2, int(number**0.5) + 1):
+      if number % i == 0:
+        is_prime = False
+        break
+    if is_prime:
+      primes.add(number)
+  return (
+      'No prime numbers found.'
+      if not primes
+      else f"{', '.join(str(num) for num in primes)} are prime numbers."
+  )

contributing/samples/core_config/root_agent.yaml

@@ -0,0 +1,10 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/google/adk-python/refs/heads/main/src/google/adk/agents/config_schemas/AgentConfig.json
+name: search_agent
+model: gemini-2.0-flash
+description: 'an agent whose job it is to perform Google search queries and answer questions about the results.'
+instruction: You are an agent whose job is to perform Google search queries and answer questions about the results.
+tools:
+  - name: google_search
+generate_content_config:
+  temperature: 0.1
+  max_output_tokens: 2000

contributing/samples/core_custom_agent/__init__.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from keyword import kwlist
+from typing import Any
+from typing import AsyncGenerator
+from typing import ClassVar
+from typing import Dict
+from typing import Type
+
+from google.adk.agents import BaseAgent
+from google.adk.agents.base_agent_config import BaseAgentConfig
+from google.adk.agents.invocation_context import InvocationContext
+from google.adk.events.event import Event
+from google.genai import types
+from pydantic import ConfigDict
+from typing_extensions import override
+
+
+class MyCustomAgentConfig(BaseAgentConfig):
+  model_config = ConfigDict(
+      extra="forbid",
+  )
+  agent_class: str = "core_cutom_agent.my_agents.MyCustomAgent"
+  my_field: str = ""
+
+
+class MyCustomAgent(BaseAgent):
+  my_field: str = ""
+
+  config_type: ClassVar[type[BaseAgentConfig]] = MyCustomAgentConfig
+
+  @override
+  @classmethod
+  def _parse_config(
+      cls: Type[MyCustomAgent],
+      config: MyCustomAgentConfig,
+      config_abs_path: str,
+      kwargs: Dict[str, Any],
+  ) -> Dict[str, Any]:
+    if config.my_field:
+      kwargs["my_field"] = config.my_field
+    return kwargs
+
+  async def _run_async_impl(
+      self, ctx: InvocationContext
+  ) -> AsyncGenerator[Event, None]:
+    yield Event(
+        invocation_id=ctx.invocation_id,
+        author=self.name,
+        content=types.ModelContent(
+            parts=[
+                types.Part(
+                    text=f"I feel good! value in my_field: `{self.my_field}`"
+                )
+            ]
+        ),
+    )

contributing/samples/core_custom_agent/my_agents.py

@@ -0,0 +1,5 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/google/adk-python/refs/heads/main/src/google/adk/agents/config_schemas/AgentConfig.json
+name: working_agent
+agent_class: core_custom_agent.my_agents.MyCustomAgent
+description: Handles all the work.
+my_field: my_field_value

contributing/samples/core_custom_agent/root_agent.yaml

@@ -0,0 +1,3 @@
+# Config-based Agent Sample - LLM multi-agent
+
+http://google3/third_party/py/google/adk/open_source_workspace/contributing/samples/hello_world_ma/