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/