Hyang-Ah Hana Kim

This commit performs a **general code modernization and refactoring** across the codebase by applying `go fix ./...`. Key updates include replacing `reflect.Ptr` with `reflect.Pointer` for type checks within **LLM internal processing** (`internal/llminternal/basic_processor.go`) and **function tool initialization** (`tool/functiontool/function.go`). Additionally, the **Vertex AI client**'s `waitForOperation` retry logic (`session/vertexai/vertexai_client.go`) is modernized, and a test helper in `plugin/functioncallmodifier/plugin_test.go` now uses `maps.Copy`. This **maintenance task** enhances code readability and aligns with current Go idioms, improving overall code quality without altering existing functionality.

This commit performs a significant **refactoring** of the **`adkgo` command's internal package structure**. It **relocates several subpackages**, including those responsible for **deployment logic** like `deploy` and `cloudrun`, into an `internal` directory within `cmd/adkgo`. This architectural change effectively **hides these components from external import**, signaling that they are not part of the public API and are subject to internal modification. The `adkgo.go` file and the moved files (`cloudrun.go`, `deploy.go`) are updated with new import paths and package comments to reflect this new organization, improving the maintainability and clarity of the `adkgo` codebase.

This commit **extends the `ReadonlyContext` and `CallbackContext` interfaces** across the `agent` and `internal/context` packages to expose crucial metadata such as **user ID, application name, session ID, and branch**. This **feature enhancement** aligns the Go implementation with planned changes in Python's context structures, providing more granular information to agents and tools. Additionally, it **refactors `internal/toolinternal/context.go`** to embed `agent.CallbackContext` and explicitly *prevent direct access to `InvocationContext`*, ensuring proper context delegation. New tests have been added to validate these context type assertions and functionality.

This commit **fixes a bug** in the **LLM agent** (`agent/llmagent`) by ensuring the `GenerateContentConfig` is correctly passed during initialization, resolving an issue where generative AI settings were previously dropped. To validate this fix and enhance coverage, a **new test case**, `TestLLMAgentStreamingModeSSE`, has been added to verify the agent's handling of streaming GenAI API with thinking mode, including proper configuration application. Supporting this, the `internal/testutil` package was **refactored** to introduce `RunContentWithConfig`, enabling more flexible testing of agent configurations. This work improves the reliability and configurability of the LLM agent's generative AI interactions.

This commit performs a **critical dependency update**, upgrading `jsonschema-go` to `v0.3.0` and `github.com/modelcontextprotocol/go-sdk` to `v0.7.0` to resolve compatibility issues with the newer `jsonschema-go` version. Alongside this, it includes a **bug fix** within the `internal/typeutil` package, specifically in the `ConvertToWithJSONSchema` function. This fix addresses incorrect JSON schema validation for `map[string]any` types, `omitempty` fields, and custom marshalling, ensuring more robust data conversion and schema adherence. The update also includes corresponding test adjustments in `tool/mcptool` to reflect these dependency and logic changes.

This commit **replaces the existing `jsonschema` library with `github.com/google/jsonschema-go`**, constituting a significant **dependency update and refactoring**. The change primarily impacts the **`tool/function` module**, where import paths were updated and calls to `jsonschema.For` were adapted to the new library's API. Consequently, **recorded HTTP test data** within `agent/llmagent/testdata` and `tool/testdata` required updates to reflect the new library's JSON schema serialization output, specifically changes in `additionalProperties` format and other dynamic values. This ensures the system continues to generate and handle JSON schemas correctly with the updated underlying library.

This commit undertakes a significant **refactoring** effort to enhance **code organization** by centralizing all core type definitions into a new `types` package. Previously, fundamental types for **agents**, **artifacts**, **callbacks**, **events**, **LLMs**, **sessions**, and **tools** were defined directly within the root `adk` package. This change involved relocating files like `agent.go` and `event.go` into the `types/` directory and updating all corresponding import paths and type references across various modules, including **agent processors**, **runner logic**, **model implementations**, and **service definitions**. The primary impact is improved **modularity** and **maintainability**, making the codebase clearer and easier to navigate for future development.

This commit **refactors** the project's dependencies by updating all import paths for the **ADK library**. Specifically, the path `github.com/google/adk-go` has been changed to `google.golang.org/adk` across numerous files. This **maintenance** task affects core modules like `agent`, `artifact`, `model`, `runner`, and `session`, as well as their corresponding test files. The change ensures the project uses the canonical import path for the ADK library, improving consistency and future compatibility with the upstream project.

This commit introduces a **new feature** by implementing an **in-memory artifact service**, providing a non-persistent storage solution for artifacts. It defines the `ArtifactService` interface in `artifact.go`, outlining core operations such as `Save`, `Load`, `Delete`, `List`, and `Versions`. The primary contribution is the `InMemoryArtifactService` implementation in `artifact/artifact.go`, which enables temporary storage and retrieval of artifacts using an in-memory map. This foundational component for the **artifact management subsystem** is crucial for development, testing, and scenarios where persistent storage is not required.

This commit introduces a major **refactoring** of the **agent core**, replacing the `BaseAgent` concept with a new `AgentSpec` struct and significantly simplifying the `Agent` interface. It **consolidates common agent properties** such as `Name`, `Parent`, and `Description` into `AgentSpec`, reducing the `Agent` interface to primarily `Spec()` and `Run()`. This architectural change impacts the entire **`agent` package**, including `agent.go`, `agent/agent_transfer.go`, and `agent/contents_processor.go`, and necessitates updates across various utility functions and tests. Notably, the **`LLMAgent`** is refactored to utilize `AgentSpec` and now supports a flexible variadic option pattern for its configuration. This enhancement improves the **modularity and extensibility** of the agent system, making future additions to agent properties non-breaking for custom agent implementations.

This commit performs a **maintenance fix** within the **`agent`** module by correcting a **typographical error** in the `LLMAgent` struct. Specifically, the `InputSchema` field in `agent/llm_agent.go` has been corrected. Although this field is not yet actively used, this change ensures the structural correctness of the agent definition, preventing potential issues and improving code quality for future development.

This commit **introduces a new `BaseAgent` struct** within the **`agent` package**, providing common functionalities like `Name`, `Description`, `Parent`, and `SubAgents` management for all `adk.Agent` implementations. This **architectural refactoring** updates the `Agent` interface with `Parent` and `SubAgents` methods and refactors `LLMAgent` to embed `BaseAgent` and utilize a new constructor pattern with `agent.Option` types. The change centralizes core agent features, simplifying future agent development and ensuring consistency across the system. Consequently, existing and future custom agents must now use a constructor function to correctly initialize the `BaseAgent`'s fields. This establishes a foundational component, significantly impacting the **agent architecture**.

This commit **refactors** the **Agent interface** and its implementations to streamline event stream handling. Specifically, the `Run` method signature across the `Agent` interface, `LLMAgent`, and `internal/runner/runner.go` is updated to return `iter.Seq2[*adk.Event, error]`, replacing the previous `EventStream` type and removing a separate error return. This change simplifies the API by embedding potential errors directly within the event sequence, ensuring that consumers receive a unified stream of events and their associated outcomes. The update impacts how agent execution results are consumed, standardizing the approach for all agent runs.

This commit **implements the actual agent transfer logic** within the **LLM agent** module, enabling an agent to hand off control to another specified agent. This **new capability** is achieved by introducing `newInvocationContext` and `agentToRun` functions and modifying `Run` and `runOneStep` in `agent/llm_agent.go` to handle and execute transfers. The transfer mechanism involves looking up the target agent by name and invoking its `Run` method, potentially leading to recursive calls, and includes initial support for automatic transfer reversal. **Comprehensive test cases** are added in `agent/llm_agent_test.go`, temporarily extending `testAgentRunner` to validate the transfer and reversal mechanics until the full `Runner` implementation is complete. **Documentation** in `agent/agent_transfer.go` is also updated to reflect these new conditions.

This commit **introduces the foundational `transfer_to_agent` tool** within the **`agent` module**, enabling agents to delegate tasks to other agents. It implements the `agentTransferRequestProcessor` to dynamically configure instructions and content generation based on the agent hierarchy and disallow flags, effectively replacing the previous `singleFlow` versus `autoFlow` distinction with a more integrated approach. Additionally, this change **fixes a potential nil pointer error** by ensuring `LLMRequest.GenerateConfig` is initialized when instructions are appended. This work establishes the core infrastructure for complex multi-agent handoffs and improves the robustness of LLM request generation, with the actual agent transfer mechanism to be completed in a subsequent update.

This commit introduces **`FunctionTool` handling** within the **`LLMAgent`**, enabling it to process and respond to function call requests from the Large Language Model. It implements new post-processing steps in `agent/llm_agent.go`, specifically `postprocessHandleFunctionCalls` and `handleFunctionCalls`, to execute requested tools and append their responses as events for the next LLM iteration. This **new capability** significantly enhances the agent's ability to interact with external systems, moving beyond text generation to perform actions based on LLM directives. A new test case in `agent/llm_agent_test.go` validates this integration, ensuring robust tool execution and response merging.

This commit **enhances the LLM Agent's reliability** by addressing a critical dependency on `genai.FunctionCall` and `FunctionResponse` IDs, which are optional but required for the agent's internal matching. New utility functions, `populateClientFunctionCallID` and `removeClientFunctionCallID`, are introduced in `agent/utils.go` to **populate missing client-side function call IDs** during the **agent's content processing** (`agent/contents_processor.go`). These IDs are subsequently **cleared from the content before being sent to the LLM** to prevent model confusion. This **bug fix** ensures the agent correctly tracks and matches function calls and responses, improving the robustness of its interaction with function calling.

This commit **implements a new `LLMRequest.AppendTools` method** to centralize and improve **tool management** within LLM requests, allowing for better registration and duplicate detection of tools. This involves **refactoring** the `tool.FunctionTool.ProcessRequest` to leverage this new method and introducing an **internal `itype` package** for defining tool interfaces. Additionally, it **fixes critical bugs** in `agent.go` by correctly initializing the `Agent` field in `NewInvocationContext` and in `event.go` by refining `IsFinalResponse` logic. These changes enhance the robustness of **LLM request processing**, **tool invocation**, and **agent context management**. The overall impact is a more reliable and structured approach to handling tools and agent interactions.

This commit **refactors** the `Run` method within the **agent**'s `baseFlow` to ensure it correctly loops through multiple `runOneStep` iterations until a final LLM response is obtained, particularly for sequences involving **function tool calls**. It **fixes** a misuse of `yield` within this loop, ensuring proper control flow, and introduces explicit error handling for unexpected partial content responses from the LLM. This change enhances the robustness of the **LLM agent**'s conversational logic, preventing premature termination and improving its ability to manage complex interaction patterns.

This commit **refactors the `SessionService` interface** and its `InMemorySessionService` implementation by changing the `AppendEvent` method signature to directly accept `*Session` and `*Event` objects. Crucially, it **modifies the semantic behavior** of `AppendEvent` to now **mutate the provided `Session` object's `Events` field** in place, aligning the Go ADK with the established behavior of its Python and Java SDKs. This **clarifies the `SessionService` interface** by removing the `SessionAppendEventRequest` struct, simplifying the API for **session event management**. Associated **test cases** have been updated to reflect these changes and verify the new in-place modification.