Merge branch 'main' into raflFaisal/generaliseContainerEnvForAgent

Author: raflFaisal

.github/workflows/pyink.yml

@@ -1,3 +1,17 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 name: Check Pyink Formatting
 
 on:

.github/workflows/python-unit-tests.yml

@@ -1,3 +1,17 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 name: Python Unit Tests
 
 on:

CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 0.5.0
+
+### ⚠ BREAKING CHANGES
+
+* Updated artifact and memory service interface to be async. Agents that
+  interact with these services through callbacks or tools will now need to
+  adjust their invocation methods to be async (using await), or ensure calls
+  are wrapped in an asynchronous executor like asyncio.run(). Any service that
+  extends the base interface must also be updated.
+
+### Features
+
+* Introduced the ability to chain model callbacks.
+* Added support for async agent and model callbacks.
+* Added input transcription support for live/streaming.
+* Captured all agent code error and display on UI.
+* Set param required tag to False by default in openapi_tool.
+* Updated evaluation functions to be asynchronous.
+
+### Bug Fixes
+
+* Ensured a unique ID is generated for every event.
+* Fixed the issue when openapi_specparser has parameter.required as None.
+* Updated the 'type' value on the items/properties nested structures for Anthropic models to adhere to JSON schema.
+* Fix litellm error issues.
+
+### Miscellaneous Chores
+
+* Regenerated API docs.
+* Created a `developer` folder and added samples.
+* Updated the contributing guide.
+* Docstring improvements, typo fixings, GitHub action to enforce code styles on formatting and imports, etc.
+
 ## 0.4.0
 
 ### ⚠ BREAKING CHANGES

CONTRIBUTING.md

@@ -4,21 +4,21 @@ We'd love to accept your patches and contributions to this project.
 
 ## Table of Contents
 
-- [Before you begin](#before-you-begin)  
-  - [Sign our Contributor License Agreement](#sign-our-contributor-license-agreement)  
+- [Before you begin](#before-you-begin)
+  - [Sign our Contributor License Agreement](#sign-our-contributor-license-agreement)
   - [Review our community guidelines](#review-our-community-guidelines)
-- [Contribution workflow](#contribution-workflow)  
-  - [Finding Issues to Work On](#finding-issues-to-work-on)  
-  - [Requirement for PRs](#requirement-for-prs)  
-  - [Large or Complex Changes](#large-or-complex-changes)  
-  - [Testing Requirements](#testing-requirements)  
-  - [Unit Tests](#unit-tests)  
-  - [End-to-End (E2E) Tests](#manual-end-to-end-e2e-tests)  
-  - [Documentation](#documentation)  
-  - [Development Setup](#development-setup)  
+- [Contribution workflow](#contribution-workflow)
+  - [Finding Issues to Work On](#finding-issues-to-work-on)
+  - [Requirement for PRs](#requirement-for-prs)
+  - [Large or Complex Changes](#large-or-complex-changes)
+  - [Testing Requirements](#testing-requirements)
+  - [Unit Tests](#unit-tests)
+  - [End-to-End (E2E) Tests](#manual-end-to-end-e2e-tests)
+  - [Documentation](#documentation)
+  - [Development Setup](#development-setup)
 - [Code reviews](#code-reviews)
 
-  
+
 ## Before you begin
 
 ### Sign our Contributor License Agreement
@@ -44,13 +44,13 @@ This project follows
 
 ### Finding Issues to Work On
 
-- Browse issues labeled **`good first issue`** (newcomer-friendly) or **`help wanted`** (general contributions).  
+- Browse issues labeled **`good first issue`** (newcomer-friendly) or **`help wanted`** (general contributions).
 - For other issues, please kindly ask before contributing to avoid duplication.
 
 
 ### Requirement for PRs
 
-- All PRs, other than small documentation or typo fixes, should have a Issue assoicated. If not, please create one. 
+- All PRs, other than small documentation or typo fixes, should have a Issue assoicated. If not, please create one.
 - Small, focused PRs. Keep changes minimal—one concern per PR.
 - For bug fixes or features, please provide logs or screenshot after the fix is applied to help reviewers better understand the fix.
 - Please include a `testing plan` section in your PR to talk about how you will test. This will save time for PR review. See `Testing Requirements` section for more details.
@@ -72,12 +72,12 @@ Please add or update unit tests for your change. Please include a summary of pas
 
 Requirements for unit tests:
 
-- **Coverage:** Cover new features, edge cases, error conditions, and typical use cases.  
-- **Location:** Add or update tests under `tests/unittests/`, following existing naming conventions (e.g., `test_<module>_<feature>.py`).  
-- **Framework:** Use `pytest`. Tests should be:  
-  - Fast and isolated.  
-  - Written clearly with descriptive names.  
-  - Free of external dependencies (use mocks or fixtures as needed).  
+- **Coverage:** Cover new features, edge cases, error conditions, and typical use cases.
+- **Location:** Add or update tests under `tests/unittests/`, following existing naming conventions (e.g., `test_<module>_<feature>.py`).
+- **Framework:** Use `pytest`. Tests should be:
+  - Fast and isolated.
+  - Written clearly with descriptive names.
+  - Free of external dependencies (use mocks or fixtures as needed).
 - **Quality:** Aim for high readability and maintainability; include docstrings or comments for complex scenarios.
 
 #### Manual End-to-End (E2E) Tests
@@ -86,15 +86,15 @@ Manual E2E tests ensure integrated flows work as intended. Your tests should cov
 
 Depending on your change:
 
-- **ADK Web:**  
-  - Use the `adk web` to verify functionality.  
-  - Capture and attach relevant screenshots demonstrating the UI/UX changes or outputs.  
+- **ADK Web:**
+  - Use the `adk web` to verify functionality.
+  - Capture and attach relevant screenshots demonstrating the UI/UX changes or outputs.
   - Label screenshots clearly in your PR description.
 
 - **Runner:**
   - Provide the testing setup. For example, the agent definition, and the runner setup.
-  - Execute the `runner` tool to reproduce workflows.  
-  - Include the command used and console output showing test results.  
+  - Execute the `runner` tool to reproduce workflows.
+  - Include the command used and console output showing test results.
   - Highlight sections of the log that directly relate to your change.
 
 ### Documentation
@@ -112,13 +112,21 @@ For any changes that impact user-facing documentation (guides, API reference, tu
 
     ```shell
     python -m venv .venv
+    ```
+
+    ```shell
     source .venv/bin/activate
-    pip install uv
+    ```
+
+    **windows**
+    ```shell
+    source .\.venv\Scripts\activate
     ```
 
 3.  **Install dependencies:**
 
     ```shell
+    pip install uv
     uv sync --all-extras
     ```
 4.  **Run unit tests:**
@@ -131,8 +139,23 @@ For any changes that impact user-facing documentation (guides, API reference, tu
     ```shell
     uv run pyink  --config pyproject.toml ./src
     ```
-    
-## Code reviews
+
+6. **Build the package**
+    ```shell
+    uv build
+    ```
+
+7. **Local Testing**
+    Have a simple testing folder setup as mentioned in the [quickstart](https://google.github.io/adk-docs/get-started/quickstart/)
+    then install the local package with changes after building it using the below command to test the changes.
+
+    ```shell
+    uv pip install <YOUR_WHL_FILE_PATH>
+
+    [eg]: uv pip install <ADK_PROJECT_PATH>/dist/google_adk-0.4.0-py3-none-any.whl
+    ```
+
+### Code reviews
 
 All submissions, including submissions by project members, require review. We
 use GitHub pull requests for this purpose. Consult

contributing/samples/application_integration_agent/README.md

@@ -0,0 +1,39 @@
+# Application Integration Agent Sample
+
+## Introduction
+
+This sample demonstrates how to use the `ApplicationIntegrationToolset` within an ADK agent to interact with external applications, specifically Jira in this case. The agent (`agent.py`) is configured to manage Jira issues using a pre-configured Application Integration connection.
+
+## Prerequisites
+
+1.  **Set up Integration Connection:**
+    *   You need an existing [Integration connection](https://cloud.google.com/integration-connectors/docs/overview) configured to interact with your Jira instance. Follow the [documentation](https://google.github.io/adk-docs/tools/google-cloud-tools/#use-integration-connectors) to provision the Integration Connector in Google Cloud and then use this [documentation](https://cloud.google.com/integration-connectors/docs/connectors/jiracloud/configure) to create an JIRA connection. Note the `Connection Name`, `Project ID`, and `Location` of your connection.
+    * 
+
+2.  **Configure Environment Variables:**
+    *   Create a `.env` file in the same directory as `agent.py` (or add to your existing one).
+    *   Add the following variables to the `.env` file, replacing the placeholder values with your actual connection details:
+
+      ```dotenv
+      CONNECTION_NAME=<YOUR_JIRA_CONNECTION_NAME>
+      CONNECTION_PROJECT=<YOUR_GOOGLE_CLOUD_PROJECT_ID>
+      CONNECTION_LOCATION=<YOUR_CONNECTION_LOCATION>
+      ```
+
+## How to Use
+
+1.  **Install Dependencies:** Ensure you have the necessary libraries installed (e.g., `google-adk`, `python-dotenv`).
+2.  **Run the Agent:** Execute the agent script from your terminal:
+    ```bash
+    python agent.py
+    ```
+3.  **Interact:** Once the agent starts, you can interact with it by typing prompts related to Jira issue management.
+
+## Sample Prompts
+
+Here are some examples of how you can interact with the agent:
+
+*   `Can you list me all the issues ?`
+*   `Can you list me all the projects ?`
+*   `Can you create an issue: "Bug in product XYZ" in project ABC ?`
+

contributing/samples/application_integration_agent/__init__.py

@@ -0,0 +1,15 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from . import agent

contributing/samples/application_integration_agent/agent.py

@@ -0,0 +1,50 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Sample agent using Application Integration toolset."""
+
+import os
+
+from dotenv import load_dotenv
+from google.adk.agents.llm_agent import LlmAgent
+from google.adk.tools.application_integration_tool import ApplicationIntegrationToolset
+
+
+# Load environment variables from .env file
+load_dotenv()
+
+connection_name = os.getenv("CONNECTION_NAME")
+connection_project = os.getenv("CONNECTION_PROJECT")
+connection_location = os.getenv("CONNECTION_LOCATION")
+
+
+jira_tool = ApplicationIntegrationToolset(
+    project=connection_project,
+    location=connection_location,
+    connection=connection_name,
+    entity_operations={"Issues": [], "Projects": []},
+    tool_name="jira_issue_manager",
+)
+
+root_agent = LlmAgent(
+    model="gemini-2.0-flash",
+    name="Issue_Management_Agent",
+    instruction="""
+    You are an agent that helps manage issues in a JIRA instance.
+    Be accurate in your responses based on the tool response. You can perform any formatting in the response that is appropriate or if asked by the user.
+    If there is an error in the tool response, understand the error and try and see if you can fix the error and then  and execute the tool again. For example if a variable or parameter is missing, try and see if you can find it in the request or user query or default it and then execute the tool again or check for other tools that could give you the details.
+    If there are any math operations like count or max, min in the user request, call the tool to get the data and perform the math operations and then return the result in the response. For example for maximum, fetch the list and then do the math operation.
+    """,
+    tools=jira_tool.get_tools(),
+)

contributing/samples/artifact_save_text/__init__.py

@@ -0,0 +1,15 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from . import agent

contributing/samples/artifact_save_text/agent.py

@@ -0,0 +1,41 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+from google.adk import Agent
+from google.adk.tools.tool_context import ToolContext
+from google.genai import types
+
+
+async def log_query(tool_context: ToolContext, query: str):
+  """Roll a die with the specified number of sides."""
+  await tool_context.save_artifact('query', types.Part(text=query))
+
+
+root_agent = Agent(
+    model='gemini-2.0-flash-exp',
+    name='log_agent',
+    description='Log user query.',
+    instruction="""Always log the user query and reploy "kk, I've logged."
+    """,
+    tools=[log_query],
+    generate_content_config=types.GenerateContentConfig(
+        safety_settings=[
+            types.SafetySetting(  # avoid false alarm about rolling dice.
+                category=types.HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT,
+                threshold=types.HarmBlockThreshold.OFF,
+            ),
+        ]
+    ),
+)