함수 도구

ADK에서 지원Python v0.1.0Typescript v0.2.0Go v0.1.0Java v0.1.0Kotlin v0.1.0

사전 빌드된 ADK 도구가 요구 사항을 충족하지 않는 경우 사용자 지정 함수 도구를 만들 수 있습니다. 함수 도구를 빌드하면 독점 데이터베이스에 연결하거나 고유한 알고리즘을 구현하는 등 맞춤형 기능을 만들 수 있습니다. 예를 들어 함수 도구 myfinancetool은 특정 재무 지표를 계산하는 함수일 수 있습니다. ADK는 또한 장기 실행 함수를 지원하므로 해당 계산에 시간이 걸리는 경우 에이전트는 다른 작업을 계속할 수 있습니다.

ADK는 각각 다른 수준의 복잡성과 제어에 적합한 여러 가지 방법으로 함수 도구를 만들 수 있습니다.

• 함수 도구
• 장기 실행 함수 도구
• 도구로서의 에이전트

함수 도구

Python 함수를 도구로 변환하는 것은 사용자 지정 논리를 에이전트에 통합하는 간단한 방법입니다. 에이전트의 tools 목록에 함수를 할당하면 프레임워크가 자동으로 FunctionTool로 래핑합니다.

작동 방식

ADK 프레임워크는 이름, docstring, 매개변수, 유형 힌트 및 기본값을 포함하여 Python 함수의 서명을 자동으로 검사하여 스키마를 생성합니다. 이 스키마는 LLM이 도구의 목적, 사용 시기 및 필요한 인수를 이해하는 데 사용하는 것입니다.

함수 서명 정의

잘 정의된 함수 서명은 LLM이 도구를 올바르게 사용하는 데 중요합니다.

매개변수

매개변수는 도구가 호출될 때 수신할 것으로 예상되는 데이터를 결정합니다. 도구의 필요에 따라 필수 또는 선택사항으로 구성할 수 있습니다.

필수 매개변수

PythonGo

매개변수는 유형 힌트가 있지만 기본값이 없는 경우 필수로 간주됩니다. LLM은 도구를 호출할 때 이 인수에 대한 값을 제공해야 합니다. 매개변수의 설명은 함수의 docstring에서 가져옵니다.

예: 필수 매개변수

def get_weather(city: str, unit: str):
    """
    지정된 단위로 도시의 날씨를 검색합니다.

    인수:
        city (str): 도시 이름입니다.
        unit (str): '섭씨' 또는 '화씨' 중 하나인 온도 단위입니다.
    """
    # ... 함수 논리 ...
    return {"status": "success", "report": f"{city}의 날씨는 맑습니다."}

이 예에서 city와 unit은 모두 필수입니다. LLM이 둘 중 하나 없이 get_weather를 호출하려고 하면 ADK는 LLM에 오류를 반환하여 호출을 수정하도록 유도합니다.

Go에서는 구조체 태그를 사용하여 JSON 스키마를 제어합니다. 두 가지 기본 태그는 json과 jsonschema입니다.

매개변수는 구조체 필드의 json 태그에 omitempty 또는 omitzero 옵션이 없는 경우 필수로 간주됩니다.

jsonschema 태그는 인수의 설명을 제공하는 데 사용됩니다. 이는 LLM이 인수가 무엇인지 이해하는 데 중요합니다.

예: 필수 매개변수

// GetWeatherParams는 getWeather 도구의 인수를 정의합니다.
type GetWeatherParams struct {
    // 이 필드는 필수입니다("omitempty" 없음).
    // jsonschema 태그는 설명을 제공합니다.
    Location string `json:"location" jsonschema:"도시 및 주, 예: 샌프란시스코, CA"`

    // 이 필드도 필수입니다.
    Unit     string `json:"unit" jsonschema:"'섭씨' 또는 '화씨' 중 하나인 온도 단위"`
}

이 예에서 location과 unit은 모두 필수입니다.

선택적 매개변수

PythonGo

매개변수는 기본값을 제공하는 경우 선택 사항으로 간주됩니다. 이것이 선택적 인수를 정의하는 표준 Python 방식입니다. typing.Optional[SomeType] 또는 | None 구문(Python 3.10 이상)을 사용하여 매개변수를 선택 사항으로 표시할 수도 있습니다.

기본값은 실제로 선택 사항인 값에만 사용하세요. 모델이 사용자 요청에서 추론해야 하거나 사용자에게 물어봐야 하는 정보에는 기본값을 추가하지 마세요.

예: 선택적 매개변수

def search_flights(destination: str, departure_date: str, flexible_days: int = 0):
    """
    항공편을 검색합니다.

    인수:
        destination (str): 목적지 도시입니다.
        departure_date (str): 원하는 출발일입니다.
        flexible_days (int, optional): 검색에 대한 유연한 일수입니다. 기본값은 0입니다.
    """
    # ... 함수 논리 ...
    if flexible_days > 0:
        return {"status": "success", "report": f"{destination}으로 가는 유연한 항공편을 찾았습니다."}
    return {"status": "success", "report": f"{departure_date}에 {destination}으로 가는 항공편을 찾았습니다."}

여기서 flexible_days는 선택 사항입니다. LLM은 이를 제공하도록 선택할 수 있지만 필수는 아닙니다.

매개변수는 구조체 필드의 json 태그에 omitempty 또는 omitzero 옵션이 있는 경우 선택 사항으로 간주됩니다.

예: 선택적 매개변수

// GetWeatherParams는 getWeather 도구의 인수를 정의합니다.
type GetWeatherParams struct {
    // 위치는 필수입니다.
    Location string `json:"location" jsonschema:"도시 및 주, 예: 샌프란시스코, CA"`

    // 단위는 선택 사항입니다.
    Unit string `json:"unit,omitempty" jsonschema:"'섭씨' 또는 '화씨' 중 하나인 온도 단위"`

    // 일수는 선택 사항입니다.
    Days int `json:"days,omitzero" jsonschema:"반환할 예보 일수(기본값은 1)"`
}

여기서 unit과 days는 선택 사항입니다. LLM은 이를 제공하도록 선택할 수 있지만 필수는 아닙니다.

typing.Optional을 사용한 선택적 매개변수

typing.Optional[SomeType] 또는 | None 구문(Python 3.10 이상)을 사용하여 매개변수를 선택 사항으로 표시할 수도 있습니다. 이는 매개변수가 None일 수 있음을 나타냅니다. None의 기본값과 결합하면 표준 선택적 매개변수처럼 동작합니다.

예: typing.Optional

Python

from typing import Optional

def create_user_profile(username: str, bio: Optional[str] = None):
    """
    새 사용자 프로필을 만듭니다.

    인수:
        username (str): 사용자의 고유한 사용자 이름입니다.
        bio (str, optional): 사용자에 대한 짧은 약력입니다. 기본값은 None입니다.
    """
    # ... 함수 논리 ...
    if bio:
        return {"status": "success", "message": f"{username}에 대한 프로필이 약력과 함께 생성되었습니다."}
    return {"status": "success", "message": f"{username}에 대한 프로필이 생성되었습니다."}

가변 매개변수(*args 및 **kwargs)

다른 목적으로 함수 서명에 *args(가변 위치 인수) 및 **kwargs(가변 키워드 인수)를 포함할 수 있지만 LLM에 대한 도구 스키마를 생성할 때 ADK 프레임워크에서 무시됩니다. LLM은 이를 인식하지 못하며 인수를 전달할 수 없습니다. LLM에서 예상하는 모든 데이터에 대해 명시적으로 정의된 매개변수를 사용하는 것이 가장 좋습니다.

JSON 스키마 도구 선언 구성

Python용 ADK는 모델 함수 선언을 위해 Pydantic을 사용하여 함수 서명에서 JSON 스키마를 생성합니다. 이 기능(JSON_SCHEMA_FOR_FUNC_DECL)은 기본적으로 활성화되어 있습니다.

실험적 기능

JSON 스키마 도구 선언(JSON_SCHEMA_FOR_FUNC_DECL)은 Python용 ADK의 실험적 기능입니다. 이 기능은 기본적으로 활성화되어 있지만 동작 및 API가 변경될 수 있으며, 활성화된 동안 ADK는 [EXPERIMENTAL] 경고를 출력합니다.

옵션 1: 명령줄을 통해 구성

에이전트 프로세스를 시작하기 전에 터미널에서 적절한 환경 변수를 설정합니다.

macOS/LinuxWindows (명령 프롬프트)Windows (PowerShell)

export ADK_ENABLE_JSON_SCHEMA_FOR_FUNC_DECL=1

set ADK_ENABLE_JSON_SCHEMA_FOR_FUNC_DECL=1

$env:ADK_ENABLE_JSON_SCHEMA_FOR_FUNC_DECL="1"

JSON 스키마 생성을 비활성화하고 이전의 Schema 기반 선언 동작으로 대체(fallback)하려면 다음을 설정합니다.

macOS/LinuxWindows (명령 프롬프트)Windows (PowerShell)

export ADK_DISABLE_JSON_SCHEMA_FOR_FUNC_DECL=1

set ADK_DISABLE_JSON_SCHEMA_FOR_FUNC_DECL=1

$env:ADK_DISABLE_JSON_SCHEMA_FOR_FUNC_DECL="1"

옵션 2: Python 코드에서 구성

도구와 에이전트를 만들기 전에 ADK의 override_feature_enabled 함수를 사용합니다.

import asyncio
from google.adk.features import FeatureName, override_feature_enabled
from google.adk.agents import Agent
from google.adk.tools import FunctionTool

# 이 기능은 기본적으로 활성화되어 있으므로 이전 동작으로 돌아가려면 False를 전달합니다.
override_feature_enabled(FeatureName.JSON_SCHEMA_FOR_FUNC_DECL, False)

def get_current_weather(location: str, unit: str = "celsius") -> str:
    """Get the current weather for a given location.

    Args:
        location: The city and state, e.g. San Francisco, CA
        unit: Temperature unit ('celsius' or 'fahrenheit')
    """
    return f"Weather in {location}: 22° {unit.capitalize()}"

async def main():
    weather_tool = FunctionTool(func=get_current_weather)

    agent = Agent(
        model="gemini-2.5-flash",
        name="my_agent",
        instruction="You are a helpful assistant.",
        tools=[weather_tool]
    )
    # 실행 로직

if __name__ == "__main__":
    asyncio.run(main())

또는 에이전트 구성 요소를 초기화하기 전에 스크립트에서 환경 변수를 설정할 수도 있습니다.

import os
import asyncio

os.environ["ADK_ENABLE_JSON_SCHEMA_FOR_FUNC_DECL"] = "1"

from google.adk.agents import Agent
from google.adk.tools import FunctionTool

def get_current_weather(location: str) -> str:
    """Get the current weather for a given location."""
    return f"Weather in {location}: 20°C"

async def main():
    weather_tool = FunctionTool(func=get_current_weather)

    agent = Agent(
        model="gemini-2.5-flash",
        name="my_agent",
        instruction="You are a helpful assistant.",
        tools=[weather_tool]
    )
    # 실행 로직

if __name__ == "__main__":
    asyncio.run(main())

반환 유형

함수 도구의 기본 반환 유형은 Python에서는 사전이고 Java에서는 맵입니다. 이를 통해 키-값 쌍으로 응답을 구조화하여 LLM에 컨텍스트와 명확성을 제공할 수 있습니다. 함수가 사전 이외의 유형을 반환하는 경우 프레임워크는 자동으로 **"result"**라는 단일 키를 가진 사전으로 래핑합니다.

반환 값을 가능한 한 설명적으로 만드십시오. 예를 들어, 숫자 오류 코드를 반환하는 대신 사람이 읽을 수 있는 설명이 포함된 "error_message" 키가 있는 사전을 반환합니다. 코드가 아닌 LLM이 결과를 이해해야 한다는 점을 기억하세요. 모범 사례로 반환 사전에 "status" 키를 포함하여 전체 결과(예: "success", "error", "pending")를 나타내어 LLM에 작업 상태에 대한 명확한 신호를 제공합니다.

Docstrings

함수의 docstring은 도구의 설명 역할을 하며 LLM으로 전송됩니다. 따라서 잘 작성되고 포괄적인 docstring은 LLM이 도구를 효과적으로 사용하는 방법을 이해하는 데 중요합니다. 함수의 목적, 매개변수의 의미 및 예상 반환 값을 명확하게 설명하십시오.

도구 간 데이터 전달

에이전트가 여러 도구를 순서대로 호출할 때 한 도구에서 다른 도구로 데이터를 전달해야 할 수 있습니다. 권장되는 방법은 세션 상태에서 temp: 접두사를 사용하는 것입니다.

도구는 temp: 변수에 데이터를 쓸 수 있고 후속 도구는 이를 읽을 수 있습니다. 이 데이터는 현재 호출에만 사용할 수 있으며 이후에는 삭제됩니다.

공유 호출 컨텍스트

단일 에이전트 턴 내의 모든 도구 호출은 동일한 InvocationContext를 공유합니다. 즉, 동일한 임시(temp:) 상태를 공유하므로 도구 간에 데이터를 전달할 수 있습니다.

예

예

PythonGoJava

이 도구는 주어진 주식 시세/기호의 주가를 가져오는 파이썬 함수입니다.

참고: 이 도구를 사용하기 전에 pip install yfinance 라이브러리를 설치해야 합니다.

# 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.agents import Agent
from google.adk.runners import Runner
from google.adk.sessions import InMemorySessionService
from google.genai import types

import yfinance as yf


APP_NAME = "stock_app"
USER_ID = "1234"
SESSION_ID = "session1234"

def get_stock_price(symbol: str):
    """
    Retrieves the current stock price for a given symbol.

    Args:
        symbol (str): The stock symbol (e.g., "AAPL", "GOOG").

    Returns:
        float: The current stock price, or None if an error occurs.
    """
    try:
        stock = yf.Ticker(symbol)
        historical_data = stock.history(period="1d")
        if not historical_data.empty:
            current_price = historical_data['Close'].iloc[-1]
            return current_price
        else:
            return None
    except Exception as e:
        print(f"Error retrieving stock price for {symbol}: {e}")
        return None


stock_price_agent = Agent(
    model='gemini-2.0-flash',
    name='stock_agent',
    instruction= 'You are an agent who retrieves stock prices. If a ticker symbol is provided, fetch the current price. If only a company name is given, first perform a Google search to find the correct ticker symbol before retrieving the stock price. If the provided ticker symbol is invalid or data cannot be retrieved, inform the user that the stock price could not be found.',
    description='This agent specializes in retrieving real-time stock prices. Given a stock ticker symbol (e.g., AAPL, GOOG, MSFT) or the stock name, use the tools and reliable data sources to provide the most up-to-date price.',
    tools=[get_stock_price], # You can add Python functions directly to the tools list; they will be automatically wrapped as FunctionTools.
)


# 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=stock_price_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)


# Note: In Colab, you can directly use 'await' at the top level.
# If running this code as a standalone Python script, you'll need to use asyncio.run() or manage the event loop.
await call_agent_async("stock price of GOOG")

이 도구의 반환 값은 사전으로 래핑됩니다.

{"result": "$123"}

이 도구는 주가의 모의 값을 검색합니다.

import (
    "google.golang.org/adk/v2/agent"
    "google.golang.org/adk/v2/agent/llmagent"
    "google.golang.org/adk/v2/model/gemini"
    "google.golang.org/adk/v2/runner"
    "google.golang.org/adk/v2/session"
    "google.golang.org/adk/v2/tool"
    "google.golang.org/adk/v2/tool/functiontool"
    "google.golang.org/genai"
)

// 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.

package main

import (
    "context"
    "fmt"
    "log"
    "strings"

    "google.golang.org/adk/v2/agent"
    "google.golang.org/adk/v2/agent/llmagent"
    "google.golang.org/adk/v2/model/gemini"
    "google.golang.org/adk/v2/runner"
    "google.golang.org/adk/v2/session"
    "google.golang.org/adk/v2/tool"
    "google.golang.org/adk/v2/tool/agenttool"
    "google.golang.org/adk/v2/tool/functiontool"

    "google.golang.org/genai"
)

// mockStockPrices provides a simple in-memory database of stock prices
// to simulate a real-world stock data API. This allows the example to
// demonstrate tool functionality without making external network calls.
var mockStockPrices = map[string]float64{
    "GOOG": 300.6,
    "AAPL": 123.4,
    "MSFT": 234.5,
}

// getStockPriceArgs defines the schema for the arguments passed to the getStockPrice tool.
// Using a struct is the recommended approach in the Go ADK as it provides strong
// typing and clear validation for the expected inputs.
type getStockPriceArgs struct {
    Symbol string `json:"symbol" jsonschema:"The stock ticker symbol, e.g., GOOG"`
}

// getStockPriceResults defines the output schema for the getStockPrice tool.
type getStockPriceResults struct {
    Symbol string  `json:"symbol"`
    Price  float64 `json:"price,omitempty"`
    Error  string  `json:"error,omitempty"`
}

// getStockPrice is a tool that retrieves the stock price for a given ticker symbol
// from the mockStockPrices map. It demonstrates how a function can be used as a
// tool by an agent. If the symbol is found, it returns a struct containing the
// symbol and its price. Otherwise, it returns a struct with an error message.
func getStockPrice(ctx agent.Context, input getStockPriceArgs) (getStockPriceResults, error) {
    symbolUpper := strings.ToUpper(input.Symbol)
    if price, ok := mockStockPrices[symbolUpper]; ok {
        fmt.Printf("Tool: Found price for %s: %f\n", input.Symbol, price)
        return getStockPriceResults{Symbol: input.Symbol, Price: price}, nil
    }
    return getStockPriceResults{}, fmt.Errorf("no data found for symbol")
}

// createStockAgent initializes and configures an LlmAgent.
// This agent is equipped with the getStockPrice tool and is instructed
// on how to respond to user queries about stock prices. It uses the
// Gemini model to understand user intent and decide when to use its tools.
func createStockAgent(ctx context.Context) (agent.Agent, error) {
    stockPriceTool, err := functiontool.New(
        functiontool.Config{
            Name:        "get_stock_price",
            Description: "Retrieves the current stock price for a given symbol.",
        },
        getStockPrice)
    if err != nil {
        return nil, err
    }

    model, err := gemini.NewModel(ctx, "gemini-flash-latest", &genai.ClientConfig{})

    if err != nil {
        log.Fatalf("Failed to create model: %v", err)
    }

    return llmagent.New(llmagent.Config{
        Name:        "stock_agent",
        Model:       model,
        Instruction: "You are an agent who retrieves stock prices. If a ticker symbol is provided, fetch the current price. If only a company name is given, first perform a Google search to find the correct ticker symbol before retrieving the stock price. If the provided ticker symbol is invalid or data cannot be retrieved, inform the user that the stock price could not be found.",
        Description: "This agent specializes in retrieving real-time stock prices. Given a stock ticker symbol (e.g., AAPL, GOOG, MSFT) or the stock name, use the tools and reliable data sources to provide the most up-to-date price.",
        Tools: []tool.Tool{
            stockPriceTool,
        },
    })
}

// userID and appName are constants used to identify the user and application
// throughout the session. These values are important for logging, tracking,
// and managing state across different agent interactions.
const (
    userID  = "example_user_id"
    appName = "example_app"
)

// callAgent orchestrates the execution of the agent for a given prompt.
// It sets up the necessary services, creates a session, and uses a runner
// to manage the agent's lifecycle. It streams the agent's responses and
// prints them to the console, handling any potential errors during the run.
func callAgent(ctx context.Context, a agent.Agent, prompt string) {
    sessionService := session.InMemoryService()
    // Create a new session for the agent interactions.
    session, err := sessionService.Create(ctx, &session.CreateRequest{
        AppName: appName,
        UserID:  userID,
    })
    if err != nil {
        log.Fatalf("Failed to create the session service: %v", err)
    }
    config := runner.Config{
        AppName:        appName,
        Agent:          a,
        SessionService: sessionService,
    }

    // Create the runner to manage the agent execution.
    r, err := runner.New(config)

    if err != nil {
        log.Fatalf("Failed to create the runner: %v", err)
    }

    sessionID := session.Session.ID()

    userMsg := &genai.Content{
        Parts: []*genai.Part{
            genai.NewPartFromText(prompt),
        },
        Role: string(genai.RoleUser),
    }

    for event, err := range r.Run(ctx, userID, sessionID, userMsg, agent.RunConfig{
        StreamingMode: agent.StreamingModeNone,
    }) {
        if err != nil {
            fmt.Printf("\nAGENT_ERROR: %v\n", err)
        } else {
            for _, p := range event.Content.Parts {
                fmt.Print(p.Text)
            }
        }
    }
}

// RunAgentSimulation serves as the entry point for this example.
// It creates the stock agent and then simulates a series of user interactions
// by sending different prompts to the agent. This function showcases how the
// agent responds to various queries, including both successful and unsuccessful
// attempts to retrieve stock prices.
func RunAgentSimulation() {
    // Create the stock agent
    agent, err := createStockAgent(context.Background())
    if err != nil {
        panic(err)
    }

    fmt.Println("Agent created:", agent.Name())

    prompts := []string{
        "stock price of GOOG",
        "What's the price of MSFT?",
        "Can you find the stock price for an unknown company XYZ?",
    }

    // Simulate running the agent with different prompts
    for _, prompt := range prompts {
        fmt.Printf("\nPrompt: %s\nResponse: ", prompt)
        callAgent(context.Background(), agent, prompt)
        fmt.Println("\n---")
    }
}

// createSummarizerAgent creates an agent whose sole purpose is to summarize text.
func createSummarizerAgent(ctx context.Context) (agent.Agent, error) {
    model, err := gemini.NewModel(ctx, "gemini-flash-latest", &genai.ClientConfig{})
    if err != nil {
        return nil, err
    }
    return llmagent.New(llmagent.Config{
        Name:        "SummarizerAgent",
        Model:       model,
        Instruction: "You are an expert at summarizing text. Take the user's input and provide a concise summary.",
        Description: "An agent that summarizes text.",
    })
}

// createMainAgent creates the primary agent that will use the summarizer agent as a tool.
func createMainAgent(ctx context.Context, tools ...tool.Tool) (agent.Agent, error) {
    model, err := gemini.NewModel(ctx, "gemini-flash-latest", &genai.ClientConfig{})
    if err != nil {
        return nil, err
    }
    return llmagent.New(llmagent.Config{
        Name:  "MainAgent",
        Model: model,
        Instruction: "You are a helpful assistant. If you are asked to summarize a long text, use the 'summarize' tool. " +
            "After getting the summary, present it to the user by saying 'Here is a summary of the text:'.",
        Description: "The main agent that can delegate tasks.",
        Tools:       tools,
    })
}

func RunAgentAsToolSimulation() {
    ctx := context.Background()

    // 1. Create the Tool Agent (Summarizer)
    summarizerAgent, err := createSummarizerAgent(ctx)
    if err != nil {
        log.Fatalf("Failed to create summarizer agent: %v", err)
    }

    // 2. Wrap the Tool Agent in an AgentTool
    summarizeTool := agenttool.New(summarizerAgent, &agenttool.Config{
        SkipSummarization: true,
    })

    // 3. Create the Main Agent and provide it with the AgentTool
    mainAgent, err := createMainAgent(ctx, summarizeTool)
    if err != nil {
        log.Fatalf("Failed to create main agent: %v", err)
    }

    // 4. Run the main agent
    prompt := `
        Please summarize this text for me:
        Quantum computing represents a fundamentally different approach to computation,
        leveraging the bizarre principles of quantum mechanics to process information. Unlike classical computers
        that rely on bits representing either 0 or 1, quantum computers use qubits which can exist in a state of superposition - effectively
        being 0, 1, or a combination of both simultaneously. Furthermore, qubits can become entangled,
        meaning their fates are intertwined regardless of distance, allowing for complex correlations. This parallelism and
        interconnectedness grant quantum computers the potential to solve specific types of incredibly complex problems - such
        as drug discovery, materials science, complex system optimization, and breaking certain types of cryptography - far
        faster than even the most powerful classical supercomputers could ever achieve, although the technology is still largely in its developmental stages.
    `
    fmt.Printf("\nPrompt: %s\nResponse: ", prompt)
    callAgent(context.Background(), mainAgent, prompt)
    fmt.Println("\n---")
}


func main() {
    fmt.Println("Attempting to run the agent simulation...")
    RunAgentSimulation()
    fmt.Println("\nAttempting to run the agent-as-a-tool simulation...")
    RunAgentAsToolSimulation()
}

이 도구의 반환 값은 getStockPriceResults 인스턴스가 됩니다.

입력 `{"symbol": "GOOG"}`의 경우: {"price":300.6,"symbol":"GOOG"}

이 도구는 주가의 모의 값을 검색합니다.

import com.google.adk.agents.LlmAgent;
import com.google.adk.events.Event;
import com.google.adk.runner.InMemoryRunner;
import com.google.adk.sessions.Session;
import com.google.adk.tools.Annotations.Schema;
import com.google.adk.tools.FunctionTool;
import com.google.genai.types.Content;
import com.google.genai.types.Part;
import io.reactivex.rxjava3.core.Flowable;
import java.util.Map;
import yahoofinance.Stock;
import yahoofinance.YahooFinance;
import java.math.BigDecimal;

public class StockPriceAgent {

  private static final String APP_NAME = "stock_agent";
  private static final String USER_ID = "user1234";

  // No longer using mock stock data - we fetch it live!

  @Schema(description = "Retrieves the current stock price for a given symbol.")
  public static Map<String, Object> getStockPrice(
      @Schema(description = "The stock symbol (e.g., \"AAPL\", \"GOOG\")",
        name = "symbol")
      String symbol) {

    try {
      Stock stock = YahooFinance.get(symbol.toUpperCase());
      if (stock != null && stock.getQuote().getPrice() != null) {
        BigDecimal currentPrice = stock.getQuote().getPrice();
        System.out.println("Tool: Found live price for " + symbol + ": " + currentPrice);
        return Map.of("symbol", symbol, "price", currentPrice.doubleValue());
      } else {
        return Map.of("symbol", symbol, "error", "No data found for symbol");
      }
    } catch (Exception e) {
      return Map.of("symbol", symbol, "error", e.getMessage());
    }
  }

  public static void callAgent(String prompt) {
    // Create the FunctionTool from the Java method
    FunctionTool getStockPriceTool = FunctionTool.create(StockPriceAgent.class, "getStockPrice");

    LlmAgent stockPriceAgent =
        LlmAgent.builder()
            .model("gemini-2.0-flash")
            .name("stock_agent")
            .instruction(
                "You are an agent who retrieves stock prices. If a ticker symbol is provided, fetch the current price. If only a company name is given, first perform a Google search to find the correct ticker symbol before retrieving the stock price. If the provided ticker symbol is invalid or data cannot be retrieved, inform the user that the stock price could not be found.")
            .description(
                "This agent specializes in retrieving real-time stock prices. Given a stock ticker symbol (e.g., AAPL, GOOG, MSFT) or the stock name, use the tools and reliable data sources to provide the most up-to-date price.")
            .tools(getStockPriceTool) // Add the Java FunctionTool
            .build();

    // Create an InMemoryRunner
    InMemoryRunner runner = new InMemoryRunner(stockPriceAgent, APP_NAME);
    // InMemoryRunner automatically creates a session service. Create a session using the service
    Session session = runner.sessionService().createSession(APP_NAME, USER_ID).blockingGet();
    Content userMessage = Content.fromParts(Part.fromText(prompt));

    // Run the agent
    Flowable<Event> eventStream = runner.runAsync(USER_ID, session.id(), userMessage);

    // Stream event response
    eventStream.blockingForEach(
        event -> {
          if (event.finalResponse()) {
            System.out.println(event.stringifyContent());
          }
        });
  }

  public static void main(String[] args) {
    callAgent("stock price of GOOG");
    callAgent("What's the price of MSFT?");
    callAgent("Can you find the stock price for an unknown company XYZ?");
  }
}

이 도구의 반환 값은 Map으로 래핑됩니다.

입력 `GOOG`의 경우: {"symbol": "GOOG", "price": "1.0"}

모범 사례

함수를 정의하는 데 상당한 유연성이 있지만 단순성이 LLM의 사용성을 향상시킨다는 점을 기억하세요. 다음 지침을 고려하세요.

• 매개변수가 적을수록 좋습니다: 복잡성을 줄이기 위해 매개변수 수를 최소화하십시오.
• 단순한 데이터 유형: 가능한 경우 사용자 지정 클래스보다 str 및 int와 같은 기본 데이터 유형을 선호하십시오.
• 의미 있는 이름: 함수의 이름과 매개변수 이름은 LLM이 도구를 해석하고 활용하는 방식에 큰 영향을 미칩니다. 함수의 목적과 입력의 의미를 명확하게 반영하는 이름을 선택하세요. do_stuff() 또는 beAgent()와 같은 일반적인 이름은 피하십시오.
• 병렬 실행을 위한 빌드: 여러 도구가 실행될 때 비동기 작업을 위해 빌드하여 함수 호출 성능을 향상시킵니다. 도구에 대한 병렬 실행을 활성화하는 방법에 대한 정보는 병렬 실행으로 도구 성능 향상을 참고하세요.

장기 실행 함수 도구

이 도구는 에이전트 워크플로 작업 외부에서 처리되고 에이전트 실행을 차단하지 않고 상당한 처리 시간이 필요한 작업을 시작하고 관리하는 데 도움이 되도록 설계되었습니다. 이 도구는 FunctionTool의 하위 클래스입니다.

LongRunningFunctionTool을 사용할 때 함수는 장기 실행 작업을 시작하고 선택적으로 장기 실행 작업 ID와 같은 초기 결과를 반환할 수 있습니다. 장기 실행 함수 도구가 호출되면 에이전트 실행기는 에이전트 실행을 일시 중지하고 에이전트 클라이언트가 장기 실행 작업이 완료될 때까지 계속할지 또는 기다릴지 결정하도록 합니다. 에이전트 클라이언트는 장기 실행 작업의 진행 상황을 쿼리하고 중간 또는 최종 응답을 다시 보낼 수 있습니다. 그러면 에이전트는 다른 작업을 계속할 수 있습니다. 예를 들어 에이전트가 작업을 진행하기 전에 사람의 승인이 필요한 인간 참여 시나리오가 있습니다.

경고: 실행 처리

장기 실행 함수 도구는 에이전트 워크플로의 일부로 장기 실행 작업을 시작하고 관리하는 데 도움이 되도록 설계되었지만 실제 장기 작업을 수행하지는 않습니다. 완료하는 데 상당한 시간이 필요한 작업의 경우 작업을 수행할 별도의 서버를 구현해야 합니다.

팁: 병렬 실행

빌드하는 도구 유형에 따라 비동기 작업을 위해 설계하는 것이 장기 실행 도구를 만드는 것보다 더 나은 솔루션일 수 있습니다. 자세한 내용은 병렬 실행으로 도구 성능 향상을 참고하세요.

작동 방식

Python에서는 함수를 LongRunningFunctionTool로 래핑합니다. Java에서는 메서드 이름을 LongRunningFunctionTool.create()에 전달합니다.

1. 시작: LLM이 도구를 호출하면 함수가 장기 실행 작업을 시작합니다.

2. 초기 업데이트: 함수는 선택적으로 초기 결과(예: 장기 실행 작업 ID)를 반환해야 합니다. ADK 프레임워크는 결과를 가져와 FunctionResponse 내에 패키징하여 LLM에 다시 보냅니다. 이를 통해 LLM은 사용자에게 알릴 수 있습니다(예: 상태, 완료율, 메시지). 그런 다음 에이전트 실행이 종료/일시 중지됩니다.

3. 계속 또는 대기: 각 에이전트 실행이 완료된 후. 에이전트 클라이언트는 장기 실행 작업의 진행 상황을 쿼리하고 중간 응답으로 에이전트 실행을 계속할지(진행 상황을 업데이트하기 위해) 또는 최종 응답이 검색될 때까지 기다릴지 결정할 수 있습니다. 에이전트 클라이언트는 다음 실행을 위해 중간 또는 최종 응답을 에이전트에 다시 보내야 합니다.

4. 프레임워크 처리: ADK 프레임워크는 실행을 관리합니다. 에이전트 클라이언트가 보낸 중간 또는 최종 FunctionResponse를 LLM에 보내 사용자 친화적인 메시지를 생성합니다.

도구 만들기

도구 함수를 정의하고 LongRunningFunctionTool 클래스를 사용하여 래핑합니다.

PythonGoJava

from typing import Any
from google.adk.tools import LongRunningFunctionTool

# 1. Define the long running function
def ask_for_approval(
    purpose: str, amount: float
) -> dict[str, Any]:
    """Ask for approval for the reimbursement."""
    # create a ticket for the approval
    # Send a notification to the approver with the link of the ticket
    return {'status': 'pending', 'approver': 'Sean Zhou', 'purpose' : purpose, 'amount': amount, 'ticket-id': 'approval-ticket-1'}

def reimburse(purpose: str, amount: float) -> dict[str, Any]:
    """Reimburse the amount of money to the employee."""
    # send the reimbrusement request to payment vendor
    return {'status': 'ok'}

# 2. Wrap the function with LongRunningFunctionTool
long_running_tool = LongRunningFunctionTool(func=ask_for_approval)

import (
    "google.golang.org/adk/v2/agent"
    "google.golang.org/adk/v2/agent/llmagent"
    "google.golang.org/adk/v2/model/gemini"
    "google.golang.org/adk/v2/tool"
    "google.golang.org/adk/v2/tool/functiontool"
    "google.golang.org/genai"
)

// CreateTicketArgs defines the arguments for our long-running tool.
type CreateTicketArgs struct {
    Urgency string `json:"urgency" jsonschema:"The urgency level of the ticket."`
}

// CreateTicketResults defines the *initial* output of our long-running tool.
type CreateTicketResults struct {
    Status   string `json:"status"`
    TicketId string `json:"ticket_id"`
}

// createTicketAsync simulates the *initiation* of a long-running ticket creation task.
func createTicketAsync(ctx agent.Context, args CreateTicketArgs) (CreateTicketResults, error) {
    log.Printf("TOOL_EXEC: 'create_ticket_long_running' called with urgency: %s (Call ID: %s)\n", args.Urgency, ctx.FunctionCallID())

    // "Generate" a ticket ID and return it in the initial response.
    ticketID := "TICKET-ABC-123"
    log.Printf("ACTION: Generated Ticket ID: %s for Call ID: %s\n", ticketID, ctx.FunctionCallID())

    // In a real application, you would save the association between the
    // FunctionCallID and the ticketID to handle the async response later.
    return CreateTicketResults{
        Status:   "started",
        TicketId: ticketID,
    }, nil
}

func createTicketAgent(ctx context.Context) (agent.Agent, error) {
    ticketTool, err := functiontool.New(
        functiontool.Config{
            Name:        "create_ticket_long_running",
            Description: "Creates a new support ticket with a specified urgency level.",
        },
        createTicketAsync,
    )
    if err != nil {
        return nil, fmt.Errorf("failed to create long running tool: %w", err)
    }

    model, err := gemini.NewModel(ctx, "gemini-flash-latest", &genai.ClientConfig{})
    if err != nil {
        return nil, fmt.Errorf("failed to create model: %v", err)
    }

    return llmagent.New(llmagent.Config{
        Name:        "ticket_agent",
        Model:       model,
        Instruction: "You are a helpful assistant for creating support tickets. Provide the status of the ticket at each interaction.",
        Tools:       []tool.Tool{ticketTool},
    })
}

import com.google.adk.agents.LlmAgent;
import com.google.adk.tools.LongRunningFunctionTool;
import java.util.HashMap;
import java.util.Map;

public class ExampleLongRunningFunction {

  // 장기 실행 함수를 정의합니다.
  // 상환에 대한 승인을 요청합니다.
  public static Map<String, Object> askForApproval(String purpose, double amount) {
    // 티켓 생성 및 알림 전송 시뮬레이션
    System.out.println(
        "목적에 대한 티켓 생성 시뮬레이션: " + purpose + ", 금액: " + amount);

    // 티켓 링크와 함께 승인자에게 알림 보내기
    Map<String, Object> result = new HashMap<>();
    result.put("status", "pending");
    result.put("approver", "Sean Zhou");
    result.put("purpose", purpose);
    result.put("amount", amount);
    result.put("ticket-id", "approval-ticket-1");
    return result;
  }

  public static void main(String[] args) throws NoSuchMethodException {
    // 메서드를 LongRunningFunctionTool.create에 전달
    LongRunningFunctionTool approveTool =
        LongRunningFunctionTool.create(ExampleLongRunningFunction.class, "askForApproval");

    // 에이전트에 도구 포함
    LlmAgent approverAgent =
        LlmAgent.builder()
            // ...
            .tools(approveTool)
            .build();
  }
}

중간/최종 결과 업데이트

에이전트 클라이언트는 장기 실행 함수 호출과 함께 이벤트를 수신하고 티켓 상태를 확인합니다. 그런 다음 에이전트 클라이언트는 중간 또는 최종 응답을 다시 보내 진행 상황을 업데이트할 수 있습니다. 프레임워크는 이 값(None인 경우에도)을 LLM에 다시 보내는 FunctionResponse의 내용에 패키징합니다.

참고: 재개 기능이 있는 장기 실행 함수 응답

ADK 에이전트 워크플로가 재개 기능으로 구성된 경우 장기 실행 함수 응답과 함께 호출 ID(invocation_id) 매개변수도 포함해야 합니다. 제공하는 호출 ID는 장기 실행 함수 요청을 생성한 것과 동일한 호출이어야 합니다. 그렇지 않으면 시스템이 응답으로 새 호출을 시작합니다. 에이전트가 재개 기능을 사용하는 경우 응답에 포함될 수 있도록 장기 실행 함수 요청과 함께 호출 ID를 매개변수로 포함하는 것을 고려하세요. 재개 기능 사용에 대한 자세한 내용은 중지된 에이전트 재개를 참고하세요.

Kotlin에서는 러너가 함수 응답 자체의 호출 ID로부터 호출을 확인하므로 runAsync에 invocationId를 전달할 필요가 없습니다. 세션의 함수 호출과 일치하는 ID가 없는 응답은 대신 예외를 발생시킵니다.

Java ADK에만 적용

함수 도구와 함께 ToolContext를 전달할 때 다음 중 하나가 참인지 확인하세요.

• 스키마가 함수 서명의 ToolContext 매개변수와 함께 전달됩니다. 예:

  @com.google.adk.tools.Annotations.Schema(name = "toolContext") ToolContext toolContext
  

  또는

• 다음 -parameters 플래그가 mvn 컴파일러 플러그인에 설정됩니다.

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.14.0</version> <!-- 또는 최신 버전 -->
            <configuration>
                <compilerArgs>
                    <arg>-parameters</arg>
                </compilerArgs>
            </configuration>
        </plugin>
    </plugins>
</build>

PythonGoJavaKotlin

# Agent Interaction
async def call_agent_async(query):

    def get_long_running_function_call(event: Event) -> types.FunctionCall:
        # Get the long running function call from the event
        if not event.long_running_tool_ids or not event.content or not event.content.parts:
            return
        for part in event.content.parts:
            if (
                part
                and part.function_call
                and event.long_running_tool_ids
                and part.function_call.id in event.long_running_tool_ids
            ):
                return part.function_call

    def get_function_response(event: Event, function_call_id: str) -> types.FunctionResponse:
        # Get the function response for the function call with specified id.
        if not event.content or not event.content.parts:
            return
        for part in event.content.parts:
            if (
                part
                and part.function_response
                and part.function_response.id == function_call_id
            ):
                return part.function_response

    content = types.Content(role='user', parts=[types.Part(text=query)])
    session, runner = await setup_session_and_runner()

    print("\nRunning agent...")
    events_async = runner.run_async(
        session_id=session.id, user_id=USER_ID, new_message=content
    )


    long_running_function_call, long_running_function_response, ticket_id = None, None, None
    async for event in events_async:
        # Use helper to check for the specific auth request event
        if not long_running_function_call:
            long_running_function_call = get_long_running_function_call(event)
        else:
            _potential_response = get_function_response(event, long_running_function_call.id)
            if _potential_response: # Only update if we get a non-None response
                long_running_function_response = _potential_response
                ticket_id = long_running_function_response.response['ticket-id']
        if event.content and event.content.parts:
            if text := ''.join(part.text or '' for part in event.content.parts):
                print(f'[{event.author}]: {text}')


    if long_running_function_response:
        # query the status of the corresponding ticket via ticket_id
        # send back an intermediate / final response
        updated_response = long_running_function_response.model_copy(deep=True)
        updated_response.response = {'status': 'approved'}
        async for event in runner.run_async(
          session_id=session.id, user_id=USER_ID, new_message=types.Content(parts=[types.Part(function_response = updated_response)], role='user')
        ):
            if event.content and event.content.parts:
                if text := ''.join(part.text or '' for part in event.content.parts):
                    print(f'[{event.author}]: {text}')

다음 예는 다중 턴 워크플로를 보여줍니다. 먼저 사용자는 에이전트에게 티켓을 만들도록 요청합니다. 에이전트는 장기 실행 도구를 호출하고 클라이언트는 FunctionCall ID를 캡처합니다. 그런 다음 클라이언트는 티켓 ID와 최종 상태를 제공하기 위해 후속 FunctionResponse 메시지를 에이전트에 다시 보내 비동기 작업 완료를 시뮬레이션합니다.

// runTurn executes a single turn with the agent and returns the captured function call ID.
func runTurn(ctx context.Context, r *runner.Runner, sessionID, turnLabel string, content *genai.Content) string {
    var funcCallID atomic.Value // Safely store the found ID.

    fmt.Printf("\n--- %s ---\n", turnLabel)
    for event, err := range r.Run(ctx, userID, sessionID, content, agent.RunConfig{
        StreamingMode: agent.StreamingModeNone,
    }) {
        if err != nil {
            fmt.Printf("\nAGENT_ERROR: %v\n", err)
            continue
        }
        // Print a summary of the event for clarity.
        printEventSummary(event, turnLabel)

        // Capture the function call ID from the event.
        for _, part := range event.Content.Parts {
            if fc := part.FunctionCall; fc != nil {
                if fc.Name == "create_ticket_long_running" {
                    funcCallID.Store(fc.ID)
                }
            }
        }
    }

    if id, ok := funcCallID.Load().(string); ok {
        return id
    }
    return ""
}

func main() {
    ctx := context.Background()
    ticketAgent, err := createTicketAgent(ctx)
    if err != nil {
        log.Fatalf("Failed to create agent: %v", err)
    }

    // Setup the runner and session.
    sessionService := session.InMemoryService()
    session, err := sessionService.Create(ctx, &session.CreateRequest{AppName: appName, UserID: userID})
    if err != nil {
        log.Fatalf("Failed to create session: %v", err)
    }
    r, err := runner.New(runner.Config{AppName: appName, Agent: ticketAgent, SessionService: sessionService})
    if err != nil {
        log.Fatalf("Failed to create runner: %v", err)
    }

    // --- Turn 1: User requests to create a ticket. ---
    initialUserMessage := genai.NewContentFromText("Create a high urgency ticket for me.", genai.RoleUser)
    funcCallID := runTurn(ctx, r, session.Session.ID(), "Turn 1: User Request", initialUserMessage)
    if funcCallID == "" {
        log.Fatal("ERROR: Tool 'create_ticket_long_running' not called in Turn 1.")
    }
    fmt.Printf("ACTION: Captured FunctionCall ID: %s\n", funcCallID)

    // --- Turn 2: App provides the final status of the ticket. ---
    // In a real application, the ticketID would be retrieved from a database
    // using the funcCallID. For this example, we'll use the same ID.
    ticketID := "TICKET-ABC-123"
    willContinue := false // Signal that this is the final response.
    ticketStatusResponse := &genai.FunctionResponse{
        Name: "create_ticket_long_running",
        ID:   funcCallID,
        Response: map[string]any{
            "status":    "approved",
            "ticket_id": ticketID,
        },
        WillContinue: &willContinue,
    }
    appResponseWithStatus := &genai.Content{
        Role:  string(genai.RoleUser),
        Parts: []*genai.Part{{FunctionResponse: ticketStatusResponse}},
    }
    runTurn(ctx, r, session.Session.ID(), "Turn 2: App provides ticket status", appResponseWithStatus)
    fmt.Println("Long running function completed successfully.")
}

// printEventSummary provides a readable log of agent and LLM interactions.
func printEventSummary(event *session.Event, turnLabel string) {
    for _, part := range event.Content.Parts {
        // Check for a text part.
        if part.Text != "" {
            fmt.Printf("[%s][%s_TEXT]: %s\n", turnLabel, event.Author, part.Text)
        }
        // Check for a function call part.
        if fc := part.FunctionCall; fc != nil {
            fmt.Printf("[%s][%s_CALL]: %s(%v) ID: %s\n", turnLabel, event.Author, fc.Name, fc.Args, fc.ID)
        }
    }
}

import com.google.adk.agents.LlmAgent;
import com.google.adk.events.Event;
import com.google.adk.runner.InMemoryRunner;
import com.google.adk.runner.Runner;
import com.google.adk.sessions.Session;
import com.google.adk.tools.Annotations.Schema;
import com.google.adk.tools.LongRunningFunctionTool;
import com.google.adk.tools.ToolContext;
import com.google.common.collect.ImmutableList;
import com.google.common.collect.ImmutableMap;
import com.google.genai.types.Content;
import com.google.genai.types.FunctionCall;
import com.google.genai.types.FunctionResponse;
import com.google.genai.types.Part;
import java.util.Optional;
import java.util.UUID;
import java.util.concurrent.atomic.AtomicReference;
import java.util.stream.Collectors;

public class LongRunningFunctionExample {

  private static String USER_ID = "user123";

  @Schema(
      name = "create_ticket_long_running",
      description = """
          Creates a new support ticket with a specified urgency level.
          Examples of urgency are 'high', 'medium', or 'low'.
          The ticket creation is a long-running process, and its ID will be provided when ready.
      """)
  public static void createTicketAsync(
      @Schema(
              name = "urgency",
              description =
                  "The urgency level for the new ticket, such as 'high', 'medium', or 'low'.")
          String urgency,
      @Schema(name = "toolContext") // Ensures ADK injection
          ToolContext toolContext) {
    System.out.printf(
        "TOOL_EXEC: 'create_ticket_long_running' called with urgency: %s (Call ID: %s)%n",
        urgency, toolContext.functionCallId().orElse("N/A"));
  }

  public static void main(String[] args) {
    LlmAgent agent =
        LlmAgent.builder()
            .name("ticket_agent")
            .description("Agent for creating tickets via a long-running task.")
            .model("gemini-2.0-flash")
            .tools(
                ImmutableList.of(
                    LongRunningFunctionTool.create(
                        LongRunningFunctionExample.class, "createTicketAsync")))
            .build();

    Runner runner = new InMemoryRunner(agent);
    Session session =
        runner.sessionService().createSession(agent.name(), USER_ID, null, null).blockingGet();

    // --- Turn 1: User requests ticket ---
    System.out.println("\n--- Turn 1: User Request ---");
    Content initialUserMessage =
        Content.fromParts(Part.fromText("Create a high urgency ticket for me."));

    AtomicReference<String> funcCallIdRef = new AtomicReference<>();
    runner
        .runAsync(USER_ID, session.id(), initialUserMessage)
        .blockingForEach(
            event -> {
              printEventSummary(event, "T1");
              if (funcCallIdRef.get() == null) { // Capture the first relevant function call ID
                event.content().flatMap(Content::parts).orElse(ImmutableList.of()).stream()
                    .map(Part::functionCall)
                    .flatMap(Optional::stream)
                    .filter(fc -> "create_ticket_long_running".equals(fc.name().orElse("")))
                    .findFirst()
                    .flatMap(FunctionCall::id)
                    .ifPresent(funcCallIdRef::set);
              }
            });

    if (funcCallIdRef.get() == null) {
      System.out.println("ERROR: Tool 'create_ticket_long_running' not called in Turn 1.");
      return;
    }
    System.out.println("ACTION: Captured FunctionCall ID: " + funcCallIdRef.get());

    // --- Turn 2: App provides initial ticket_id (simulating async tool completion) ---
    System.out.println("\n--- Turn 2: App provides ticket_id ---");
    String ticketId = "TICKET-" + UUID.randomUUID().toString().substring(0, 8).toUpperCase();
    FunctionResponse ticketCreatedFuncResponse =
        FunctionResponse.builder()
            .name("create_ticket_long_running")
            .id(funcCallIdRef.get())
            .response(ImmutableMap.of("ticket_id", ticketId))
            .build();
    Content appResponseWithTicketId =
        Content.builder()
            .parts(
                ImmutableList.of(
                    Part.builder().functionResponse(ticketCreatedFuncResponse).build()))
            .role("user")
            .build();

    runner
        .runAsync(USER_ID, session.id(), appResponseWithTicketId)
        .blockingForEach(event -> printEventSummary(event, "T2"));
    System.out.println("ACTION: Sent ticket_id " + ticketId + " to agent.");

    // --- Turn 3: App provides ticket status update ---
    System.out.println("\n--- Turn 3: App provides ticket status ---");
    FunctionResponse ticketStatusFuncResponse =
        FunctionResponse.builder()
            .name("create_ticket_long_running")
            .id(funcCallIdRef.get())
            .response(ImmutableMap.of("status", "approved", "ticket_id", ticketId))
            .build();
    Content appResponseWithStatus =
        Content.builder()
            .parts(
                ImmutableList.of(Part.builder().functionResponse(ticketStatusFuncResponse).build()))
            .role("user")
            .build();

    runner
        .runAsync(USER_ID, session.id(), appResponseWithStatus)
        .blockingForEach(event -> printEventSummary(event, "T3_FINAL"));
    System.out.println("Long running function completed successfully.");
  }

  private static void printEventSummary(Event event, String turnLabel) {
    event
        .content()
        .ifPresent(
            content -> {
              String text =
                  content.parts().orElse(ImmutableList.of()).stream()
                      .map(part -> part.text().orElse(""))
                      .filter(s -> !s.isEmpty())
                      .collect(Collectors.joining(" "));
              if (!text.isEmpty()) {
                System.out.printf("[%s][%s_TEXT]: %s%n", turnLabel, event.author(), text);
              }
              content.parts().orElse(ImmutableList.of()).stream()
                  .map(Part::functionCall)
                  .flatMap(Optional::stream)
                  .findFirst() // Assuming one function call per relevant event for simplicity
                  .ifPresent(
                      fc ->
                          System.out.printf(
                              "[%s][%s_CALL]: %s(%s) ID: %s%n",
                              turnLabel,
                              event.author(),
                              fc.name().orElse("N/A"),
                              fc.args().orElse(ImmutableMap.of()),
                              fc.id().orElse("N/A")));
            });
  }
}

private fun printText(event: Event) {
    val text = event.content?.parts?.mapNotNull { it.text }?.joinToString("").orEmpty()
    if (text.isNotEmpty()) println("[${event.author}]: $text")
}

suspend fun callReimbursementAgent(
    runner: InMemoryRunner,
    userId: String,
    sessionId: String,
    query: String,
) {
    var pendingCallId: String? = null
    var pendingResponse: FunctionResponse? = null

    runner
        .runAsync(
            userId = userId,
            sessionId = sessionId,
            newMessage = Content(role = "user", parts = listOf(Part(text = query))),
        ).collect { event ->
            val callId = pendingCallId
            if (callId == null) {
                // A long-running call is the one whose id the event lists in longRunningToolIds.
                pendingCallId =
                    event
                        .functionCalls()
                        .firstOrNull { it.id != null && it.id in event.longRunningToolIds }
                        ?.id
            } else {
                event
                    .functionResponses()
                    .firstOrNull { it.id == callId }
                    ?.let { pendingResponse = it }
            }
            printText(event)
        }

    // The tool returned "pending" and the invocation paused. Resume it by sending the
    // outcome back as a FunctionResponse carrying the same id.
    val paused = pendingResponse ?: return
    val updated = paused.copy(response = mapOf("status" to "approved"))
    runner
        .runAsync(
            userId = userId,
            sessionId = sessionId,
            newMessage = Content(role = "user", parts = listOf(Part(functionResponse = updated))),
        ).collect(::printText)
}

Python 전체 예: 파일 처리 시뮬레이션

# 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.

import asyncio
from google.adk.agents import Agent
from google.adk.events import Event
from google.adk.runners import Runner
from google.adk.sessions import InMemorySessionService
from google.genai import types


from typing import Any
from google.adk.tools import LongRunningFunctionTool

# 1. Define the long running function
def ask_for_approval(
    purpose: str, amount: float
) -> dict[str, Any]:
    """Ask for approval for the reimbursement."""
    # create a ticket for the approval
    # Send a notification to the approver with the link of the ticket
    return {'status': 'pending', 'approver': 'Sean Zhou', 'purpose' : purpose, 'amount': amount, 'ticket-id': 'approval-ticket-1'}

def reimburse(purpose: str, amount: float) -> dict[str, Any]:
    """Reimburse the amount of money to the employee."""
    # send the reimbrusement request to payment vendor
    return {'status': 'ok'}

# 2. Wrap the function with LongRunningFunctionTool
long_running_tool = LongRunningFunctionTool(func=ask_for_approval)


# 3. Use the tool in an Agent
file_processor_agent = Agent(
    # Use a model compatible with function calling
    model="gemini-2.0-flash",
    name='reimbursement_agent',
    instruction="""
      You are an agent whose job is to handle the reimbursement process for
      the employees. If the amount is less than $100, you will automatically
      approve the reimbursement.

      If the amount is greater than $100, you will
      ask for approval from the manager. If the manager approves, you will
      call reimburse() to reimburse the amount to the employee. If the manager
      rejects, you will inform the employee of the rejection.
    """,
    tools=[reimburse, long_running_tool]
)


APP_NAME = "human_in_the_loop"
USER_ID = "1234"
SESSION_ID = "session1234"

# 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=file_processor_agent, app_name=APP_NAME, session_service=session_service)
    return session, runner


# Agent Interaction
async def call_agent_async(query):

    def get_long_running_function_call(event: Event) -> types.FunctionCall:
        # Get the long running function call from the event
        if not event.long_running_tool_ids or not event.content or not event.content.parts:
            return
        for part in event.content.parts:
            if (
                part
                and part.function_call
                and event.long_running_tool_ids
                and part.function_call.id in event.long_running_tool_ids
            ):
                return part.function_call

    def get_function_response(event: Event, function_call_id: str) -> types.FunctionResponse:
        # Get the function response for the function call with specified id.
        if not event.content or not event.content.parts:
            return
        for part in event.content.parts:
            if (
                part
                and part.function_response
                and part.function_response.id == function_call_id
            ):
                return part.function_response

    content = types.Content(role='user', parts=[types.Part(text=query)])
    session, runner = await setup_session_and_runner()

    print("\nRunning agent...")
    events_async = runner.run_async(
        session_id=session.id, user_id=USER_ID, new_message=content
    )


    long_running_function_call, long_running_function_response, ticket_id = None, None, None
    async for event in events_async:
        # Use helper to check for the specific auth request event
        if not long_running_function_call:
            long_running_function_call = get_long_running_function_call(event)
        else:
            _potential_response = get_function_response(event, long_running_function_call.id)
            if _potential_response: # Only update if we get a non-None response
                long_running_function_response = _potential_response
                ticket_id = long_running_function_response.response['ticket-id']
        if event.content and event.content.parts:
            if text := ''.join(part.text or '' for part in event.content.parts):
                print(f'[{event.author}]: {text}')


    if long_running_function_response:
        # query the status of the corresponding ticket via ticket_id
        # send back an intermediate / final response
        updated_response = long_running_function_response.model_copy(deep=True)
        updated_response.response = {'status': 'approved'}
        async for event in runner.run_async(
          session_id=session.id, user_id=USER_ID, new_message=types.Content(parts=[types.Part(function_response = updated_response)], role='user')
        ):
            if event.content and event.content.parts:
                if text := ''.join(part.text or '' for part in event.content.parts):
                    print(f'[{event.author}]: {text}')


# Note: In Colab, you can directly use 'await' at the top level.
# If running this code as a standalone Python script, you'll need to use asyncio.run() or manage the event loop.

# reimbursement that doesn't require approval
# asyncio.run(call_agent_async("Please reimburse 50$ for meals"))
await call_agent_async("Please reimburse 50$ for meals") # For Notebooks, uncomment this line and comment the above line
# reimbursement that requires approval
# asyncio.run(call_agent_async("Please reimburse 200$ for meals"))
await call_agent_async("Please reimburse 200$ for meals") # For Notebooks, uncomment this line and comment the above line

이 예의 주요 측면

• LongRunningFunctionTool: 제공된 메서드/함수를 래핑합니다. 프레임워크는 생성된 업데이트와 최종 반환 값을 순차적인 FunctionResponses로 보내는 것을 처리합니다.
• 에이전트 지침: LLM에 도구를 사용하고 사용자 업데이트를 위해 들어오는 FunctionResponse 스트림(진행률 대 완료)을 이해하도록 지시합니다.
• 최종 반환: 함수는 최종 결과 사전을 반환하며, 이는 완료를 나타내기 위해 마지막 FunctionResponse에서 전송됩니다.
• Kotlin에는 LongRunningFunctionTool 클래스가 없음: 함수에 @Tool(isLongRunning = true)을 어노테이션하거나 BaseTool 서브클래스에 isLongRunning = true를 전달합니다.
• Kotlin 턴 수: 위 도구는 Unit 대신 값을 반환하므로, 재개할 수 없는(non-resumable) 앱은 해당 플레이스홀더를 모델에 보내고 두 번째로 호출하여 중간 응답으로 턴 1을 종료합니다. 재개 가능한(resumable) 앱은 두 번째 모델 호출 없이 함수 호출에서 일시 중지됩니다. Unit을 반환하면 플레이스홀더 응답이 완전히 억제되어 어느 모드에서든 함수 호출에서 턴이 종료됩니다.

도구로서의 에이전트

이 기능을 사용하면 시스템 내의 다른 에이전트의 기능을 도구로 호출하여 활용할 수 있습니다. 도구로서의 에이전트를 사용하면 다른 에이전트를 호출하여 특정 작업을 수행하도록 하여 효과적으로 책임을 위임할 수 있습니다. 이는 개념적으로 다른 에이전트를 호출하고 에이전트의 응답을 함수의 반환 값으로 사용하는 Python 함수를 만드는 것과 유사합니다.

하위 에이전트와의 주요 차이점

도구로서의 에이전트와 하위 에이전트를 구별하는 것이 중요합니다.

• 도구로서의 에이전트: 에이전트 A가 에이전트 B를 도구로 호출하면(도구로서의 에이전트 사용) 에이전트 B의 답변은 에이전트 A로 다시 전달되며, 에이전트 A는 답변을 요약하고 사용자에게 응답을 생성합니다. 에이전트 A는 제어권을 유지하고 향후 사용자 입력을 계속 처리합니다.
• 하위 에이전트: 에이전트 A가 에이전트 B를 하위 에이전트로 호출하면 사용자에게 응답하는 책임이 완전히 에이전트 B로 이전됩니다. 에이전트 A는 사실상 루프에서 벗어납니다. 모든 후속 사용자 입력은 에이전트 B에서 응답합니다.

AgentTool 사용

에이전트를 도구로 사용하려면 AgentTool 클래스로 에이전트를 래핑합니다.

PythonGoJava

tools=[AgentTool(agent=agent_b)]

agenttool.New(agent, &agenttool.Config{...})

AgentTool.create(agent)

사용자 지정

AgentTool 클래스는 동작을 사용자 지정하기 위한 다음 속성을 제공합니다.

• skip_summarization (Python/TypeScript) / skipSummarization (Kotlin/Java): (boolean) True로 설정하면 프레임워크는 도구 에이전트의 응답에 대한 LLM 기반 요약을 건너뜁니다. 이는 도구의 응답이 이미 잘 형식화되어 있고 추가 처리가 필요하지 않은 경우에 유용할 수 있습니다.

예

PythonGoJava

# 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.agents import Agent
from google.adk.runners import Runner
from google.adk.sessions import InMemorySessionService
from google.adk.tools.agent_tool import AgentTool
from google.genai import types

APP_NAME="summary_agent"
USER_ID="user1234"
SESSION_ID="1234"

summary_agent = Agent(
    model="gemini-2.0-flash",
    name="summary_agent",
    instruction="""You are an expert summarizer. Please read the following text and provide a concise summary.""",
    description="Agent to summarize text",
)

root_agent = Agent(
    model='gemini-2.0-flash',
    name='root_agent',
    instruction="""You are a helpful assistant. When the user provides a text, use the 'summarize' tool to generate a summary. Always forward the user's message exactly as received to the 'summarize' tool, without modifying or summarizing it yourself. Present the response from the tool to the user.""",
    tools=[AgentTool(agent=summary_agent, skip_summarization=True)]
)

# 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)


long_text = """Quantum computing represents a fundamentally different approach to computation, 
leveraging the bizarre principles of quantum mechanics to process information. Unlike classical computers 
that rely on bits representing either 0 or 1, quantum computers use qubits which can exist in a state of superposition - effectively 
being 0, 1, or a combination of both simultaneously. Furthermore, qubits can become entangled, 
meaning their fates are intertwined regardless of distance, allowing for complex correlations. This parallelism and 
interconnectedness grant quantum computers the potential to solve specific types of incredibly complex problems - such 
as drug discovery, materials science, complex system optimization, and breaking certain types of cryptography - far 
faster than even the most powerful classical supercomputers could ever achieve, although the technology is still largely in its developmental stages."""


# Note: In Colab, you can directly use 'await' at the top level.
# If running this code as a standalone Python script, you'll need to use asyncio.run() or manage the event loop.
await call_agent_async(long_text)

import (
    "google.golang.org/adk/v2/agent"
    "google.golang.org/adk/v2/agent/llmagent"
    "google.golang.org/adk/v2/model/gemini"
    "google.golang.org/adk/v2/tool"
    "google.golang.org/adk/v2/tool/agenttool"
    "google.golang.org/genai"
)

// createSummarizerAgent creates an agent whose sole purpose is to summarize text.
func createSummarizerAgent(ctx context.Context) (agent.Agent, error) {
    model, err := gemini.NewModel(ctx, "gemini-flash-latest", &genai.ClientConfig{})
    if err != nil {
        return nil, err
    }
    return llmagent.New(llmagent.Config{
        Name:        "SummarizerAgent",
        Model:       model,
        Instruction: "You are an expert at summarizing text. Take the user's input and provide a concise summary.",
        Description: "An agent that summarizes text.",
    })
}

// createMainAgent creates the primary agent that will use the summarizer agent as a tool.
func createMainAgent(ctx context.Context, tools ...tool.Tool) (agent.Agent, error) {
    model, err := gemini.NewModel(ctx, "gemini-flash-latest", &genai.ClientConfig{})
    if err != nil {
        return nil, err
    }
    return llmagent.New(llmagent.Config{
        Name:  "MainAgent",
        Model: model,
        Instruction: "You are a helpful assistant. If you are asked to summarize a long text, use the 'summarize' tool. " +
            "After getting the summary, present it to the user by saying 'Here is a summary of the text:'.",
        Description: "The main agent that can delegate tasks.",
        Tools:       tools,
    })
}

func RunAgentAsToolSimulation() {
    ctx := context.Background()

    // 1. Create the Tool Agent (Summarizer)
    summarizerAgent, err := createSummarizerAgent(ctx)
    if err != nil {
        log.Fatalf("Failed to create summarizer agent: %v", err)
    }

    // 2. Wrap the Tool Agent in an AgentTool
    summarizeTool := agenttool.New(summarizerAgent, &agenttool.Config{
        SkipSummarization: true,
    })

    // 3. Create the Main Agent and provide it with the AgentTool
    mainAgent, err := createMainAgent(ctx, summarizeTool)
    if err != nil {
        log.Fatalf("Failed to create main agent: %v", err)
    }

    // 4. Run the main agent
    prompt := `
        Please summarize this text for me:
        Quantum computing represents a fundamentally different approach to computation,
        leveraging the bizarre principles of quantum mechanics to process information. Unlike classical computers
        that rely on bits representing either 0 or 1, quantum computers use qubits which can exist in a state of superposition - effectively
        being 0, 1, or a combination of both simultaneously. Furthermore, qubits can become entangled,
        meaning their fates are intertwined regardless of distance, allowing for complex correlations. This parallelism and
        interconnectedness grant quantum computers the potential to solve specific types of incredibly complex problems - such
        as drug discovery, materials science, complex system optimization, and breaking certain types of cryptography - far
        faster than even the most powerful classical supercomputers could ever achieve, although the technology is still largely in its developmental stages.
    `
    fmt.Printf("\nPrompt: %s\nResponse: ", prompt)
    callAgent(context.Background(), mainAgent, prompt)
    fmt.Println("\n---")
}

import com.google.adk.agents.LlmAgent;
import com.google.adk.events.Event;
import com.google.adk.runner.InMemoryRunner;
import com.google.adk.sessions.Session;
import com.google.adk.tools.AgentTool;
import com.google.genai.types.Content;
import com.google.genai.types.Part;
import io.reactivex.rxjava3.core.Flowable;

public class AgentToolCustomization {

  private static final String APP_NAME = "summary_agent";
  private static final String USER_ID = "user1234";

  public static void initAgentAndRun(String prompt) {

    LlmAgent summaryAgent =
        LlmAgent.builder()
            .model("gemini-2.0-flash")
            .name("summaryAgent")
            .instruction(
                "You are an expert summarizer. Please read the following text and provide a concise summary.")
            .description("Agent to summarize text")
            .build();

    // Define root_agent
    LlmAgent rootAgent =
        LlmAgent.builder()
            .model("gemini-2.0-flash")
            .name("rootAgent")
            .instruction(
                "You are a helpful assistant. When the user provides a text, always use the 'summaryAgent' tool to generate a summary. Always forward the user's message exactly as received to the 'summaryAgent' tool, without modifying or summarizing it yourself. Present the response from the tool to the user.")
            .description("Assistant agent")
            .tools(AgentTool.create(summaryAgent, true)) // Set skipSummarization to true
            .build();

    // Create an InMemoryRunner
    InMemoryRunner runner = new InMemoryRunner(rootAgent, APP_NAME);
    // InMemoryRunner automatically creates a session service. Create a session using the service
    Session session = runner.sessionService().createSession(APP_NAME, USER_ID).blockingGet();
    Content userMessage = Content.fromParts(Part.fromText(prompt));

    // Run the agent
    Flowable<Event> eventStream = runner.runAsync(USER_ID, session.id(), userMessage);

    // Stream event response
    eventStream.blockingForEach(
        event -> {
          if (event.finalResponse()) {
            System.out.println(event.stringifyContent());
          }
        });
  }

  public static void main(String[] args) {
    String longText =
        """
            Quantum computing represents a fundamentally different approach to computation,
            leveraging the bizarre principles of quantum mechanics to process information. Unlike classical computers
            that rely on bits representing either 0 or 1, quantum computers use qubits which can exist in a state of superposition - effectively
            being 0, 1, or a combination of both simultaneously. Furthermore, qubits can become entangled,
            meaning their fates are intertwined regardless of distance, allowing for complex correlations. This parallelism and
            interconnectedness grant quantum computers the potential to solve specific types of incredibly complex problems - such
            as drug discovery, materials science, complex system optimization, and breaking certain types of cryptography - far
            faster than even the most powerful classical supercomputers could ever achieve, although the technology is still largely in its developmental stages.""";

    initAgentAndRun(longText);
  }
}

작동 방식

1. root_agent가 긴 텍스트를 받으면 지침에 따라 긴 텍스트에 대해 'summarize' 도구를 사용하도록 지시합니다.
2. 프레임워크는 'summarize'를 summary_agent를 래핑하는 AgentTool로 인식합니다.
3. 내부적으로 root_agent는 긴 텍스트를 입력으로 summary_agent를 호출합니다.
4. summary_agent는 지침에 따라 텍스트를 처리하고 요약을 생성합니다.
5. summary_agent의 응답은 root_agent로 다시 전달됩니다.
6. 그런 다음 root_agent는 요약을 가져와 사용자에게 최종 응답을 공식화할 수 있습니다(예: "텍스트 요약은 다음과 같습니다. ...")

Kotlin 함수 도구 예제 보강

영어 원문에 추가된 Kotlin 함수 도구 예제를 아래에 함께 제공합니다.

필수 매개변수

class WeatherService {
    /**
     * Retrieves the weather for a city in the specified unit.
     */
    @Tool
    fun getWeather(
        @Param("The city and state, e.g., San Francisco, CA") location: String,
        @Param("The temperature unit, either 'Celsius' or 'Fahrenheit'") unit: String,
    ): String {
        // ... function logic ...
        return "Weather for $location is sunny in $unit."
    }
}

선택적 매개변수

class FlightService {
    /**
     * Searches for flights.
     */
    @Tool
    fun searchFlights(
        @Param("The destination city.") destination: String,
        @Param("The desired departure date.") departureDate: String,
        @Param("Number of flexible days for the search. Defaults to 0.") flexibleDays: Int? = 0,
    ): String {
        // ... function logic ...
        val days = flexibleDays ?: 0
        if (days > 0) {
            return "Found flexible flights to $destination."
        }
        return "Found flights to $destination on $departureDate."
    }
}

전체 함수 도구 예제

data class StockPrice(val symbol: String, val price: Double)

class StockService {
    /**
     * Retrieves the stock price for a given symbol.
     */
    @Tool
    fun getStockPrice(
        @Param("The stock symbol, e.g. GOOG") symbol: String,
    ): StockPrice {
        // In a real app, you would call a stock price API here.
        return StockPrice(symbol = symbol, price = 123.45)
    }
}

fun main() =
    runBlocking {
        val stockService = StockService()

        val agent =
            LlmAgent(
                name = "stock_agent",
                model = Gemini(name = "gemini-flash-latest"),
                instruction = Instruction("You are a helpful stock assistant."),
                // .generatedTools() is used to get the tools from the annotated class.
                tools = stockService.generatedTools(),
            )

        // ... use the agent ...
    }

장기 실행 도구

data class ReimbursementApproval(
    val status: String,
    val approver: String,
    val purpose: String,
    val amount: Double,
    val ticketId: String,
)

class ReimbursementService {
    /**
     * Asks for approval for the reimbursement.
     */
    @Tool(isLongRunning = true)
    fun askForApproval(
        @Param("The purpose of the reimbursement.") purpose: String,
        @Param("The amount to be reimbursed.") amount: Double,
    ): ReimbursementApproval {
        // Simulate creating a ticket and sending a notification.
        // This tool returns the initial result and then the agent pauses.
        return ReimbursementApproval(
            status = "pending",
            approver = "Sean Zhou",
            purpose = purpose,
            amount = amount,
            ticketId = "approval-ticket-1",
        )
    }
}

fun main() {
    val service = ReimbursementService()
    val agent =
        LlmAgent(
            name = "approver_agent",
            model = Gemini(name = "gemini-flash-latest"),
            instruction = Instruction("You are a helpful reimbursement assistant."),
            tools = service.generatedTools(),
        )
}

AgentTool

import com.google.adk.kt.agents.Instruction
import com.google.adk.kt.agents.LlmAgent
import com.google.adk.kt.models.Gemini
import com.google.adk.kt.runners.InMemoryRunner
import com.google.adk.kt.tools.AgentTool
import com.google.adk.kt.types.Content
import com.google.adk.kt.types.Part
import kotlinx.coroutines.runBlocking

fun main() =
    runBlocking {
        val appName = "summary_agent"
        val userId = "user1234"

        // Define a specialized agent to be used as a tool
        val summaryAgent =
            LlmAgent(
                name = "summary_agent",
                model = Gemini(name = "gemini-flash-latest"),
                description = "Agent to summarize text",
                instruction =
                    Instruction(
                        "You are an expert summarizer. Please read the following text and provide a concise summary.",
                    ),
            )

        // Wrap the agent in an AgentTool with skipSummarization = true
        val summaryTool =
            AgentTool(
                agent = summaryAgent,
                skipSummarization = true,
            )

        // Define the root agent that uses the summary tool
        val rootAgent =
            LlmAgent(
                name = "root_agent",
                model = Gemini(name = "gemini-flash-latest"),
                instruction =
                    Instruction(
                        "You are a helpful assistant. When the user provides a text, use the 'summary_agent' tool to generate a summary. Always forward the user's message exactly as received to the 'summary_agent' tool. Present the response from the tool to the user.",
                    ),
                tools = listOf(summaryTool),
            )

        // Create an InMemoryRunner
        val runner = InMemoryRunner(agent = rootAgent, appName = appName)

        val sessionId = "session_001"

        val longText =
            """
            Quantum computing represents a fundamentally different approach to computation, 
            leveraging the bizarre principles of quantum mechanics to process information. Unlike classical computers 
            that rely on bits representing either 0 or 1, quantum computers use qubits which can exist in a state of superposition - effectively 
            being 0, 1, or a combination of both simultaneously. Furthermore, qubits can become entangled, 
            meaning their fates are intertwined regardless of distance, allowing for complex correlations. This parallelism and 
            interconnectedness grant quantum computers the potential to solve specific types of incredibly complex problems - such 
            as drug discovery, materials science, complex system optimization, and breaking certain types of cryptography - far 
            faster than even the most powerful classical supercomputers could ever achieve, although the technology is still largely in its developmental stages.
            """.trimIndent()

        val userMessage = Content(parts = listOf(Part(text = longText)))

        // Run the agent and collect events
        runner.runAsync(userId = userId, sessionId = sessionId, newMessage = userMessage).collect {
                event ->
            if (event.isFinalResponse) {
                val finalResponse = event.content?.parts?.firstOrNull()?.text
                println("Agent Response: $finalResponse")
            }
        }
    }

TypeScript 함수 도구 예제 보강

영어 원문에 포함된 TypeScript 함수 도구 예제를 아래에 함께 제공합니다.

기본 함수 도구

/**
 * 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.
 */
import {Content, Part, createUserContent} from '@google/genai';
import { stringifyContent, FunctionTool, InMemoryRunner, LlmAgent } from '@google/adk';
import {z} from 'zod';

// Define the function to get the stock price
async function getStockPrice({ticker}: {ticker: string}): Promise<Record<string, unknown>> {
  console.log(`Getting stock price for ${ticker}`);
  // In a real-world scenario, you would fetch the stock price from an API
  const price = (Math.random() * 1000).toFixed(2);
  return {price: `$${price}`};
}

async function main() {
  // Define the schema for the tool's parameters using Zod
  const getStockPriceSchema = z.object({
    ticker: z.string().describe('The stock ticker symbol to look up.'),
  });

  // Create a FunctionTool from the function and schema
  const stockPriceTool = new FunctionTool({
    name: 'getStockPrice',
    description: 'Gets the current price of a stock.',
    parameters: getStockPriceSchema,
    execute: getStockPrice,
  });

  // Define the agent that will use the tool
  const stockAgent = new LlmAgent({
    name: 'stock_agent',
    model: 'gemini-2.5-flash',
    instruction: 'You can get the stock price of a company.',
    tools: [stockPriceTool],
  });

  // Create a runner for the agent
  const runner = new InMemoryRunner({agent: stockAgent});

  // Create a new session
  const session = await runner.sessionService.createSession({
    appName: runner.appName,
    userId: 'test-user',
  });

  const userContent: Content = createUserContent('What is the stock price of GOOG?');

  // Run the agent and get the response
  const response = [];
  for await (const event of runner.runAsync({
    userId: session.userId,
    sessionId: session.id,
    newMessage: userContent,
  })) {
    response.push(event);
  }

  // Print the final response from the agent
  const finalResponse = response[response.length - 1];
  if (finalResponse?.content?.parts?.length) {
    console.log(stringifyContent(finalResponse));
  }
}

main();

장기 실행 함수 정의

// 1. Define the long-running function
function askForApproval(args: {purpose: string; amount: number}) {
  /**
   * Ask for approval for the reimbursement.
   */
  // create a ticket for the approval
  // Send a notification to the approver with the link of the ticket
  return {
    "status": "pending",
    "approver": "Sean Zhou",
    "purpose": args.purpose,
    "amount": args.amount,
    "ticket-id": "approval-ticket-1",
  };
}

// 2. Instantiate the LongRunningFunctionTool class with the long-running function
const longRunningTool = new LongRunningFunctionTool({
  name: "ask_for_approval",
  description: "Ask for approval for the reimbursement.",
  parameters: z.object({
    purpose: z.string().describe("The purpose of the reimbursement."),
    amount: z.number().describe("The amount to reimburse."),
  }),
  execute: askForApproval,
});

장기 실행 함수 도구 전체 예제

/**
 * 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.
 */

import { LlmAgent, Runner, FunctionTool, LongRunningFunctionTool, InMemorySessionService, Event, stringifyContent } from '@google/adk';
import {z} from "zod";
import {Content, FunctionCall, FunctionResponse, createUserContent} from "@google/genai";

// 1. Define the long-running function
function askForApproval(args: {purpose: string; amount: number}) {
  /**
   * Ask for approval for the reimbursement.
   */
  // create a ticket for the approval
  // Send a notification to the approver with the link of the ticket
  return {
    "status": "pending",
    "approver": "Sean Zhou",
    "purpose": args.purpose,
    "amount": args.amount,
    "ticket-id": "approval-ticket-1",
  };
}

// 2. Instantiate the LongRunningFunctionTool class with the long-running function
const longRunningTool = new LongRunningFunctionTool({
  name: "ask_for_approval",
  description: "Ask for approval for the reimbursement.",
  parameters: z.object({
    purpose: z.string().describe("The purpose of the reimbursement."),
    amount: z.number().describe("The amount to reimburse."),
  }),
  execute: askForApproval,
});

function reimburse(args: {purpose: string; amount: number}) {
  /**
   * Reimburse the amount of money to the employee.
   */
  // send the reimbursement request to payment vendor
  return {status: "ok"};
}

const reimburseTool = new FunctionTool({
  name: "reimburse",
  description: "Reimburse the amount of money to the employee.",
  parameters: z.object({
    purpose: z.string().describe("The purpose of the reimbursement."),
    amount: z.number().describe("The amount to reimburse."),
  }),
  execute: reimburse,
});

// 3. Use the tool in an Agent
const reimbursementAgent = new LlmAgent({
  model: "gemini-2.5-flash",
  name: "reimbursement_agent",
  instruction: `
      You are an agent whose job is to handle the reimbursement process for
      the employees. If the amount is less than $100, you will automatically
      approve the reimbursement.

      If the amount is greater than $100, you will
      ask for approval from the manager. If the manager approves, you will
      call reimburse() to reimburse the amount to the employee. If the manager
      rejects, you will inform the employee of the rejection.
    `,
  tools: [reimburseTool, longRunningTool],
});

const APP_NAME = "human_in_the_loop";
const USER_ID = "1234";
const SESSION_ID = "session1234";

// Session and Runner
async function setupSessionAndRunner() {
  const sessionService = new InMemorySessionService();
  const session = await sessionService.createSession({
    appName: APP_NAME,
    userId: USER_ID,
    sessionId: SESSION_ID,
  });
  const runner = new Runner({
    agent: reimbursementAgent,
    appName: APP_NAME,
    sessionService: sessionService,
  });
  return {session, runner};
}

function getLongRunningFunctionCall(event: Event): FunctionCall | undefined {
  // Get the long-running function call from the event
  if (
    !event.longRunningToolIds ||
    !event.content ||
    !event.content.parts?.length
  ) {
    return;
  }
  for (const part of event.content.parts) {
    if (
      part &&
      part.functionCall &&
      event.longRunningToolIds &&
      part.functionCall.id &&
      event.longRunningToolIds.includes(part.functionCall.id)
    ) {
      return part.functionCall;
    }
  }
}

function getFunctionResponse(
  event: Event,
  functionCallId: string
): FunctionResponse | undefined {
  // Get the function response for the function call with specified id.
  if (!event.content || !event.content.parts?.length) {
    return;
  }
  for (const part of event.content.parts) {
    if (
      part &&
      part.functionResponse &&
      part.functionResponse.id === functionCallId
    ) {
      return part.functionResponse;
    }
  }
}

// Agent Interaction
async function callAgentAsync(query: string) {
  let longRunningFunctionCall: FunctionCall | undefined;
  let longRunningFunctionResponse: FunctionResponse | undefined;
  let ticketId: string | undefined;
  const content: Content = createUserContent(query);
  const {session, runner} = await setupSessionAndRunner();

  console.log("\nRunning agent...");
  const events = runner.runAsync({
    sessionId: session.id,
    userId: USER_ID,
    newMessage: content,
  });

  for await (const event of events) {
    // Use helper to check for the specific auth request event
    if (!longRunningFunctionCall) {
      longRunningFunctionCall = getLongRunningFunctionCall(event);
    } else {
      const _potentialResponse = getFunctionResponse(
        event,
        longRunningFunctionCall.id!
      );
      if (_potentialResponse) {
        // Only update if we get a non-None response
        longRunningFunctionResponse = _potentialResponse;
        ticketId = (
          longRunningFunctionResponse.response as {[key: string]: any}
        )[`ticket-id`];
      }
    }
    const text = stringifyContent(event);
    if (text) {
      console.log(`[${event.author}]: ${text}`);
    }
  }

  if (longRunningFunctionResponse) {
    // query the status of the corresponding ticket via ticket_id
    // send back an intermediate / final response
    const updatedResponse = JSON.parse(
      JSON.stringify(longRunningFunctionResponse)
    );
    updatedResponse.response = {status: "approved"};
    for await (const event of runner.runAsync({
      sessionId: session.id,
      userId: USER_ID,
      newMessage: createUserContent(JSON.stringify({functionResponse: updatedResponse})),
    })) {
      const text = stringifyContent(event);
      if (text) {
        console.log(`[${event.author}]: ${text}`);
      }
    }
  }
}

async function main() {
  // reimbursement that doesn't require approval
  await callAgentAsync("Please reimburse 50$ for meals");
  // reimbursement that requires approval
  await callAgentAsync("Please reimburse 200$ for meals");
}

main();

도구로서의 에이전트

/**
 * 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.
 */
import { AgentTool, InMemoryRunner, LlmAgent } from '@google/adk';
import {Part, createUserContent} from '@google/genai';

/**
 * This example demonstrates how to use an agent as a tool.
 */
async function main() {
  // Define the summarization agent that will be used as a tool
  const summaryAgent = new LlmAgent({
    name: 'summary_agent',
    model: 'gemini-2.5-flash',
    description: 'Agent to summarize text',
    instruction:
      'You are an expert summarizer. Please read the following text and provide a concise summary.',
  });

  // Define the main agent that uses the summarization agent as a tool.
  // skipSummarization is set to true, so the main_agent will directly output
  // the result from the summary_agent without further processing.
  const mainAgent = new LlmAgent({
    name: 'main_agent',
    model: 'gemini-2.5-flash',
    instruction:
      "You are a helpful assistant. When the user provides a text, use the 'summary_agent' tool to generate a summary. Always forward the user's message exactly as received to the 'summary_agent' tool, without modifying or summarizing it yourself. Present the response from the tool to the user.",
    tools: [new AgentTool({agent: summaryAgent, skipSummarization: true})],
  });

  const appName = 'agent-as-a-tool-app';
  const runner = new InMemoryRunner({agent: mainAgent, appName});

  const longText = `Quantum computing represents a fundamentally different approach to computation, 
leveraging the bizarre principles of quantum mechanics to process information. Unlike classical computers 
that rely on bits representing either 0 or 1, quantum computers use qubits which can exist in a state of superposition - effectively 
being 0, 1, or a combination of both simultaneously. Furthermore, qubits can become entangled, 
meaning their fates are intertwined regardless of distance, allowing for complex correlations. This parallelism and 
interconnectedness grant quantum computers the potential to solve specific types of incredibly complex problems - such 
as drug discovery, materials science, complex system optimization, and breaking certain types of cryptography - far 
faster than even the most powerful classical supercomputers could ever achieve, although the technology is still largely in its developmental stages.`;

  // Create the session before running the agent
  await runner.sessionService.createSession({
    appName,
    userId: 'user1',
    sessionId: 'session1',
  });

  // Run the agent with the long text to summarize
  const events = runner.runAsync({
    userId: 'user1',
    sessionId: 'session1',
    newMessage: createUserContent(longText),
  });

  // Print the final response from the agent
  console.log('Agent Response:');
  for await (const event of events) {
    if (event.content?.parts?.length) {
      const responsePart = event.content.parts.find((p: Part) => p.functionResponse);
      if (responsePart && responsePart.functionResponse) {
        console.log(responsePart.functionResponse.response);
      }
    }
  }
}

main();

그라운딩 메타데이터 전파

propagate_grounding_metadata (boolean, 기본값: False) True로 설정하면 하위 에이전트가 생성한 Google Search 출처(citation)와 같은 그라운딩 메타데이터를 상위 에이전트의 세션 상태로 자동 전달합니다. 이 사용자 지정을 통해 전문 검색 에이전트를 도구로 사용할 때 출처 정보가 보존되도록 보장합니다.

Python

from google.adk.agents import Agent
from google.adk.tools import AgentTool

search_specialist_agent = Agent(
    # 제너레이티브 모델 지정
    model="gemini-flash-latest",
    name="search_specialist_agent",
    instruction=(
        "You are a search expert. Find and "
        "compile citations on requested topics."
    ),
    # 여기에 검색 도구 추가
)

search_agent_tool = AgentTool(
    agent=search_specialist_agent,
    # 출처 정보를 루트 에이전트까지 온전히 유지
    propagate_grounding_metadata=True
)

root_agent = Agent(
    model="gemini-flash-latest",
    name="root_agent",
    description=(
        "A central coordinator that delegates "
        "to specialist agents."
    ),
    tools=[search_agent_tool]
)

플러그인 상속 제어

에이전트를 AgentTool로 감쌀 때 include_plugins 파라미터를 사용하여 상위 러너로부터 플러그인을 상속받을지 여부를 제어할 수 있습니다.

• include_plugins=True (기본값): 하위 에이전트는 상위 에이전트의 모든 플러그인을 상속받아 추적 스팬(trace spans) 및 이벤트 스트리밍을 유지합니다.
• include_plugins=False: 하위 에이전트는 상위 에이전트의 플러그인 환경을 상속받지 않고 격리된 환경에서 실행됩니다. 에이전트의 실행을 자립적(self-contained)으로 유지하고 상위 에이전트의 플러그인 환경에 영향을 받지 않도록 하려면 이 설정을 사용하세요.

Python

from google.adk.tools import agent_tool

# MyImageAgent를 위한 플레이스홀더 정의
class MyImageAgent:
    def __init__(
        self, name="My Agent", description="A simple image agent."
    ):
        self.name = name
        # description 속성 추가
        self.description = description 

# 예시 1: 상위 플러그인으로부터 MyImageAgent 격리
my_isolated_tool = agent_tool.AgentTool(
    agent=MyImageAgent(), # MyImageAgent 인스턴스화
    include_plugins=False
)

# 예시 2: 플러그인 상속
my_observable_tool = agent_tool.AgentTool(
    agent=MyImageAgent(), # MyImageAgent 인스턴스화
    include_plugins=True
)