函数工具¶

=== "Python"

    此工具是一个 Python 函数，用于获取给定股票代码/符号的股票价格。

    <u>注意</u>：在使用此工具之前，你需要先安装 `yfinance` 库（`pip install yfinance`）。

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

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

    ```

    此工具的返回值会被包装为字典。

    ```json
    {"result": "$123"}
    ```

=== "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();


    ```

    此工具的返回值将是一个对象。

    ```json
    对于输入 `GOOG`: {"price": 2800.0, "currency": "USD"}
    ```

=== "Go"

    此工具检索模拟的股票价格值。

    ```go
    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` 实例。

    ```json
    对于输入 `{"symbol": "GOOG"}`: {"price":300.6,"symbol":"GOOG"}
    ```

=== "Java"

    此工具检索模拟的股票价格值。

    ```java

    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<String, Object>。

    ```json
    对于输入 `GOOG`: {"symbol": "GOOG", "price": "1.0"}
    ```

=== "Kotlin"

    此工具检索模拟的股票价格值。

    ```kotlin
    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 ...
        }
    ```

    此工具的返回值将是一个 Map。

    ```json
    对于输入 `GOOG`: {"symbol": "GOOG", "price": 123.45}
    ```