Add support of ReAct and builtin planner

agent/llmagent/llmagent.go

@@ -26,6 +26,7 @@ import (
 	icontext "google.golang.org/adk/internal/context"
 	"google.golang.org/adk/internal/llminternal"
 	"google.golang.org/adk/model"
+	"google.golang.org/adk/planner"
 	"google.golang.org/adk/session"
 	"google.golang.org/adk/tool"
 )
@@ -78,6 +79,7 @@ func New(cfg Config) (agent.Agent, error) {
 			GlobalInstruction:         cfg.GlobalInstruction,
 			GlobalInstructionProvider: llminternal.InstructionProvider(cfg.GlobalInstructionProvider),
 			OutputKey:                 cfg.OutputKey,
+			Planner:                   cfg.Planner,
 		},
 	}
 
@@ -255,6 +257,10 @@ type Config struct {
 	// - Extracts agent reply for later use, such as in tools, callbacks, etc.
 	// - Connects agents to coordinate with each other.
 	OutputKey string
+
+	// Planner allows the agent to generate plans for the queries to guide its action.
+	// If not provided, no planning will be performed.
+	Planner planner.BasePlanner
 }
 
 // BeforeModelCallback that is called before sending a request to the model.
@@ -386,6 +392,11 @@ func (a *llmAgent) maybeSaveOutputToState(event *session.Event) {
 	}
 }
 
+// Planner returns the planner instance for this agent, if any.
+func (a *llmAgent) Planner() planner.BasePlanner {
+	return a.State.Planner
+}
+
 // InstructionProvider allows to create instructions dynamically. It is called
 // on each agent invocation.
 //

internal/llminternal/agent.go

@@ -19,6 +19,7 @@ import (
 
 	"google.golang.org/adk/agent"
 	"google.golang.org/adk/model"
+	"google.golang.org/adk/planner"
 	"google.golang.org/adk/tool"
 )
 
@@ -49,6 +50,8 @@ type State struct {
 	OutputSchema *genai.Schema
 
 	OutputKey string
+
+	Planner planner.BasePlanner
 }
 
 type InstructionProvider func(ctx agent.ReadonlyContext) (string, error)

internal/llminternal/other_processors.go

@@ -16,7 +16,10 @@ package llminternal
 
 import (
 	"google.golang.org/adk/agent"
+	icontext "google.golang.org/adk/internal/context"
+	"google.golang.org/adk/internal/utils"
 	"google.golang.org/adk/model"
+	"google.golang.org/adk/planner"
 )
 
 func identityRequestProcessor(ctx agent.InvocationContext, req *model.LLMRequest) error {
@@ -25,7 +28,31 @@ func identityRequestProcessor(ctx agent.InvocationContext, req *model.LLMRequest
 }
 
 func nlPlanningRequestProcessor(ctx agent.InvocationContext, req *model.LLMRequest) error {
-	// TODO: implement (adk-python src/google/adk/flows/llm_flows/_nl_plnning.py)
+	p := getPlanner(ctx)
+	if p == nil {
+		return nil
+	}
+
+	switch planner := p.(type) {
+	case *planner.BuiltInPlanner:
+		planner.ApplyThinkingConfig(req)
+	case *planner.ReActPlanner:
+		readonlyContext := icontext.NewReadonlyContext(ctx)
+		if planningInstruction := planner.BuildPlanningInstruction(readonlyContext, req); planningInstruction != "" {
+			utils.AppendInstructions(req, planningInstruction)
+		}
+
+		for _, content := range req.Contents {
+			if content.Parts == nil {
+				continue
+			}
+			for _, part := range content.Parts {
+				part.Thought = false
+			}
+		}
+	default:
+		return nil
+	}
 	return nil
 }
 
@@ -40,11 +67,38 @@ func authPreprocessor(ctx agent.InvocationContext, req *model.LLMRequest) error
 }
 
 func nlPlanningResponseProcessor(ctx agent.InvocationContext, req *model.LLMRequest, resp *model.LLMResponse) error {
-	// TODO: implement (adk-python src/google/adk/_nl_planning.py)
+	if resp == nil || resp.Content == nil || len(resp.Content.Parts) == 0 {
+		return nil
+	}
+
+	p := getPlanner(ctx)
+	if p == nil {
+		return nil
+	}
+
+	// Skip built-in planner response processing
+	if _, ok := p.(*planner.BuiltInPlanner); ok {
+		return nil
+	}
+
+	callbackContext := icontext.NewCallbackContext(ctx)
+	if processedParts := p.ProcessPlanningResponse(callbackContext, resp.Content.Parts); processedParts != nil {
+		resp.Content.Parts = processedParts
+	}
 	return nil
 }
 
 func codeExecutionResponseProcessor(ctx agent.InvocationContext, req *model.LLMRequest, resp *model.LLMResponse) error {
 	// TODO: implement (adk-python src/google/adk_code_execution.py)
 	return nil
 }
+
+// getPlanner returns the planner from the invocation context, or nil if no planner is available.
+func getPlanner(ctx agent.InvocationContext) planner.BasePlanner {
+	if llmAgent, ok := ctx.Agent().(Agent); ok {
+		state := Reveal(llmAgent)
+		return state.Planner
+	}
+
+	return nil
+}

planner/base.go

@@ -0,0 +1,49 @@
+// 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 planner provides interfaces and implementations for AI agent planning capabilities.
+package planner
+
+import (
+	"google.golang.org/genai"
+
+	"google.golang.org/adk/agent"
+	"google.golang.org/adk/model"
+)
+
+// BasePlanner is the abstract base interface for all planners.
+//
+// The planner allows the agent to generate plans for the queries to guide its
+// action.
+type BasePlanner interface {
+	// BuildPlanningInstruction builds the system instruction to be appended to the LLM request for planning.
+	//
+	// Args:
+	//   readonlyContext: The readonly context of the invocation.
+	//   llmRequest: The LLM request. Readonly.
+	//
+	// Returns:
+	//   The planning system instruction, or empty string if no instruction is needed.
+	BuildPlanningInstruction(readonlyContext agent.ReadonlyContext, llmRequest *model.LLMRequest) string
+
+	// ProcessPlanningResponse processes the LLM response for planning.
+	//
+	// Args:
+	//   callbackContext: The callback context of the invocation.
+	//   responseParts: The LLM response parts. Readonly.
+	//
+	// Returns:
+	//   The processed response parts, or nil if no processing is needed.
+	ProcessPlanningResponse(callbackContext agent.CallbackContext, responseParts []*genai.Part) []*genai.Part
+}

planner/builtin.go

@@ -0,0 +1,69 @@
+// 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 planner
+
+import (
+	"google.golang.org/genai"
+
+	"google.golang.org/adk/agent"
+	"google.golang.org/adk/model"
+)
+
+// BuiltInPlanner is the built-in planner that uses model's built-in thinking features.
+type BuiltInPlanner struct {
+	// ThinkingConfig is the config for model built-in thinking features. An error
+	// will be returned if this field is set for models that don't support
+	// thinking.
+	ThinkingConfig *genai.ThinkingConfig
+}
+
+// NewBuiltInPlanner initializes the built-in planner.
+//
+// Args:
+//
+//	thinkingConfig: Config for model built-in thinking features. An error
+//	  will be returned if this field is set for models that don't support
+//	  thinking.
+func NewBuiltInPlanner(thinkingConfig *genai.ThinkingConfig) *BuiltInPlanner {
+	return &BuiltInPlanner{
+		ThinkingConfig: thinkingConfig,
+	}
+}
+
+// ApplyThinkingConfig applies the thinking config to the LLM request.
+//
+// Args:
+//
+//	llmRequest: The LLM request to apply the thinking config to.
+func (b *BuiltInPlanner) ApplyThinkingConfig(llmRequest *model.LLMRequest) {
+	if b.ThinkingConfig != nil {
+		if llmRequest.Config == nil {
+			llmRequest.Config = &genai.GenerateContentConfig{}
+		}
+		llmRequest.Config.ThinkingConfig = b.ThinkingConfig
+	}
+}
+
+// BuildPlanningInstruction implements BasePlanner.
+func (b *BuiltInPlanner) BuildPlanningInstruction(readonlyContext agent.ReadonlyContext, llmRequest *model.LLMRequest) string {
+	// Built-in planner doesn't add planning instructions
+	return ""
+}
+
+// ProcessPlanningResponse implements BasePlanner.
+func (b *BuiltInPlanner) ProcessPlanningResponse(callbackContext agent.CallbackContext, responseParts []*genai.Part) []*genai.Part {
+	// Built-in planner doesn't process planning response
+	return nil
+}

planner/builtin_test.go

@@ -0,0 +1,115 @@
+// 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 planner
+
+import (
+	"testing"
+
+	"google.golang.org/genai"
+)
+
+func TestBuiltInPlanner_New(t *testing.T) {
+	p := NewBuiltInPlanner(nil)
+	if p == nil {
+		t.Fatal("NewBuiltInPlanner returned nil")
+	}
+	if p.ThinkingConfig != nil {
+		t.Errorf("Expected ThinkingConfig to be nil, got %+v", p.ThinkingConfig)
+	}
+
+	config := &genai.ThinkingConfig{IncludeThoughts: true}
+	p = NewBuiltInPlanner(config)
+	if p == nil {
+		t.Fatal("NewBuiltInPlanner returned nil")
+	}
+	if p.ThinkingConfig == nil {
+		t.Fatal("Expected ThinkingConfig to be set, got nil")
+	}
+	if p.ThinkingConfig.IncludeThoughts != true {
+		t.Errorf("Expected IncludeThoughts true, got %v", p.ThinkingConfig.IncludeThoughts)
+	}
+}
+
+func TestBuiltInPlanner_BuildPlanningInstruction(t *testing.T) {
+	p := NewBuiltInPlanner(&genai.ThinkingConfig{
+		IncludeThoughts: true,
+	})
+
+	instruction := p.BuildPlanningInstruction(nil, nil)
+	if instruction != "" {
+		t.Errorf("BuiltInPlanner should return empty instruction, got: %q", instruction)
+	}
+}
+
+func TestBuiltInPlanner_ProcessPlanningResponse(t *testing.T) {
+	p := NewBuiltInPlanner(&genai.ThinkingConfig{
+		IncludeThoughts: true,
+	})
+
+	parts := []*genai.Part{
+		{Text: "Hello world"},
+		{Text: "Another part"},
+	}
+
+	result := p.ProcessPlanningResponse(nil, parts)
+	if result != nil {
+		t.Errorf("BuiltInPlanner should return nil for response processing, got: %+v", result)
+	}
+}
+
+func TestBuiltInPlanner_ApplyThinkingConfig(t *testing.T) {
+	req := &struct {
+		Config *genai.GenerateContentConfig
+	}{
+		Config: nil,
+	}
+
+	if req.Config != nil && req.Config.ThinkingConfig != nil {
+		t.Error("Expected ThinkingConfig to not be set")
+	}
+
+	thinkingConfig := &genai.ThinkingConfig{IncludeThoughts: true}
+	req = &struct {
+		Config *genai.GenerateContentConfig
+	}{
+		Config: nil,
+	}
+
+	if req.Config == nil {
+		req.Config = &genai.GenerateContentConfig{}
+	}
+	req.Config.ThinkingConfig = thinkingConfig
+
+	if req.Config == nil {
+		t.Error("Expected Config to be set")
+	} else if req.Config.ThinkingConfig == nil {
+		t.Error("Expected ThinkingConfig to be set")
+	} else if req.Config.ThinkingConfig.IncludeThoughts != true {
+		t.Errorf("Expected IncludeThoughts true, got %v", req.Config.ThinkingConfig.IncludeThoughts)
+	}
+
+	req = &struct {
+		Config *genai.GenerateContentConfig
+	}{
+		Config: &genai.GenerateContentConfig{},
+	}
+	req.Config.ThinkingConfig = thinkingConfig
+
+	if req.Config.ThinkingConfig == nil {
+		t.Error("Expected ThinkingConfig to be set")
+	} else if req.Config.ThinkingConfig.IncludeThoughts != true {
+		t.Errorf("Expected IncludeThoughts true, got %v", req.Config.ThinkingConfig.IncludeThoughts)
+	}
+}

planner/doc.go

@@ -0,0 +1,22 @@
+// 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 planner provides planning capabilities for AI agents.
+//
+// Planners allow agents to generate structured plans for user queries to guide their actions.
+// This package includes implementations for:
+//   - BasePlanner: The core planner interface
+//   - BuiltInPlanner: Uses model's built-in thinking features
+//   - ReActPlanner: Plan-Re-Act planner that constrains LLM response to generate plans before actions
+package planner