Merge branch 'main' into main

Author: EItanya

DEVELOPMENT.md

@@ -72,7 +72,13 @@ loaded by the Makefile (via `-include .env`) to inject environment variables
 when you run `make` targets:
 
 ```shell
+# Set your provider (supported: openAI, anthropic, azureOpenAI, gemini, ollama)
+KAGENT_DEFAULT_MODEL_PROVIDER=openAI
+
+# Set the corresponding API key for your provider
 OPENAI_API_KEY=your-openai-api-key
+# ANTHROPIC_API_KEY=your-anthropic-api-key
+# GOOGLE_API_KEY=your-google-api-key
 ```
 
 1. Build images, load them into kind cluster and deploy everything using Helm:

Makefile

@@ -177,6 +177,7 @@ push-test-agent: buildx-create build-kagent-adk
 	kubectl apply --namespace kagent --context kind-$(KIND_CLUSTER_NAME) -f go/core/test/e2e/agents/kebab/agent.yaml
 	$(DOCKER_BUILDER) build --push $(BUILD_ARGS) $(TOOLS_IMAGE_BUILD_ARGS) -t $(DOCKER_REGISTRY)/poem-flow:latest -f python/samples/crewai/poem_flow/Dockerfile ./python
 	$(DOCKER_BUILDER) build --push $(BUILD_ARGS) $(TOOLS_IMAGE_BUILD_ARGS) -t $(DOCKER_REGISTRY)/basic-openai:latest -f python/samples/openai/basic_agent/Dockerfile ./python
+	$(DOCKER_BUILDER) build --push $(BUILD_ARGS) $(TOOLS_IMAGE_BUILD_ARGS) -t $(DOCKER_REGISTRY)/langgraph-currency:latest -f python/samples/langgraph/currency/Dockerfile ./python
 
 .PHONY: push-test-skill
 push-test-skill: buildx-create

docs/architecture/a2a-subagents.md

@@ -0,0 +1,61 @@
+# A2A Subagents
+
+Kagent allows users to add subagents (other agents running on Kagent or remotely) as tools to a main agent, connected via the A2A protocol. This feature is enabled by `KAgentRemoteA2ATool` (`python/packages/kagent-adk/src/kagent/adk/_remote_a2a_tool.py`), kagent's custom replacement for the upstream `AgentTool(RemoteA2aAgent(...))` pairing. 
+
+It directly manages the A2A conversation with a remote subagent and adds three things the upstream lacks: HITL propagation, live activity viewing, and user ID forwarding.
+
+See [human-in-the-loop.md](human-in-the-loop.md) for HITL details.
+
+---
+
+## How it works
+
+Each parent A2A request creates a fresh `Runner` and fresh tool instances. `KAgentRemoteA2ATool.__init__` generates a UUID (`_last_context_id`) that is used as the A2A `context_id` for every message sent to the subagent. On the subagent side, this `context_id` becomes the session ID.
+
+`run_async` has two phases:
+
+- **Phase 1** (normal call): sends the request to the subagent and handles the response — returning the result, pausing for HITL if the subagent returns `input_required`, or returning an error string.
+- **Phase 2** (HITL resume): reads the stored `task_id`/`context_id` from `tool_context.tool_confirmation.payload` and forwards the user's decision (approve / reject / batch / ask-user answers) to the subagent's pending task.
+
+On success, `run_async` returns:
+```python
+{"result": str, "subagent_session_id": str}           # normal
+{"result": str, "subagent_session_id": str,
+ "kagent_usage_metadata": dict}                        # with usage
+{"status": "pending", "waiting_for": "subagent_approval", ...}  # HITL pause
+```
+
+`KAgentRemoteA2AToolset` is a thin `BaseToolset` wrapper whose only job is ensuring the owned `httpx.AsyncClient` is closed when the runner shuts down — ADK's cleanup path only discovers `BaseToolset` instances, not bare `BaseTool` instances.
+
+---
+
+## User ID and session tagging
+
+`_SubagentInterceptor` is registered on the A2A client at construction time and injects two headers on every outgoing request:
+
+| Header | Value | Purpose |
+|---|---|---|
+| `x-user-id` | parent session's user ID | Scopes the subagent DB session to the same user |
+| `x-kagent-source` | `"agent"` | Hides the session from the agent's session history sidebar |
+
+> Interceptors must be passed to `ClientFactory.create(interceptors=[...])` — `A2AClient.add_request_middleware()` appends to a list that the transport never reads.
+
+On the subagent side, `KAgentRequestContextBuilder` reads these headers and passes them through to `_prepare_session`, which calls `KAgentSessionService.create_session()` with `source="subagent"`. The Go layer stores this in a `Source` column and excludes such sessions from `ListSessionsForAgent`.
+
+---
+
+## Live activity viewing
+
+The UI can show what a subagent is doing in a live panel before it finishes. This works because the session ID is known before the tool runs:
+
+Before the run loop, `A2aAgentExecutor` builds a `{tool_name → session_id}` map from all tools implementing the `SubagentSessionProvider` protocol (`subagent_session_id` property). The event converter stamps this as `kagent_subagent_session_id` metadata on each `function_call` DataPart as soon as the LLM emits the call. The UI reads it immediately and begins polling `/api/sessions/{id}` every 2 seconds, rendering the subagent's events as a nested chat thread. Nesting is capped at depth 3.
+
+The map is keyed by tool name because within one parent request, all calls to the same subagent tool intentionally share one `context_id` — giving the subagent conversation continuity across sequential invocations. A fresh `context_id` is generated on the next parent request when the runner rebuilds.
+
+When sending session requests to Go backend, take note that:
+
+| Session query | Includes subagent sessions? |
+|---|---|
+| `GET /api/sessions/agent/{ns}/{name}` | No — filtered by `source != 'agent'` |
+| `GET /api/sessions/{id}` | Yes |
+| `GET /api/sessions/{id}/tasks` | Yes |

go/api/database/models.go

@@ -57,6 +57,16 @@ func ParseMessages(messages []Event) ([]*protocol.Message, error) {
 	return result, nil
 }
 
+// SessionSource represents the origin of a session.
+type SessionSource string
+
+const (
+	// SessionSourceUser indicates the session was initiated by a user.
+	SessionSourceUser SessionSource = "user"
+	// SessionSourceAgent indicates the session was created by a parent agent's A2A call.
+	SessionSourceAgent SessionSource = "agent"
+)
+
 type Session struct {
 	ID        string         `gorm:"primaryKey;not null" json:"id"`
 	Name      *string        `gorm:"index" json:"name,omitempty"`
@@ -66,6 +76,9 @@ type Session struct {
 	DeletedAt gorm.DeletedAt `gorm:"index" json:"deleted_at"`
 
 	AgentID *string `gorm:"index" json:"agent_id"`
+	// Source indicates how this session was created.
+	// SessionSourceUser = user-initiated, SessionSourceAgent = created by a parent agent's A2A call.
+	Source *SessionSource `gorm:"index" json:"source,omitempty"`
 }
 
 type Task struct {

go/api/httpapi/types.go

@@ -100,9 +100,10 @@ type AgentResponse struct {
 
 // SessionRequest represents a session creation/update request
 type SessionRequest struct {
-	AgentRef *string `json:"agent_ref,omitempty"`
-	Name     *string `json:"name,omitempty"`
-	ID       *string `json:"id,omitempty"`
+	AgentRef *string                 `json:"agent_ref,omitempty"`
+	Name     *string                 `json:"name,omitempty"`
+	ID       *string                 `json:"id,omitempty"`
+	Source   *database.SessionSource `json:"source,omitempty"`
 }
 
 // Run types

go/core/internal/controller/reconciler/mcp_server_reconciler_test.go

@@ -85,7 +85,7 @@ func TestReconcileKagentMCPServer_ErrorPropagation(t *testing.T) {
 				WithObjects(tc.mcpServer).
 				Build()
 
-			dbManager, err := database.NewManager(&database.Config{
+			dbManager, err := database.NewManager(context.Background(), &database.Config{
 				PostgresConfig: &database.PostgresConfig{
 					URL:           connStr,
 					VectorEnabled: true,

go/core/internal/controller/translator/agent/adk_api_translator.go

@@ -1584,10 +1584,17 @@ func validateSubPath(p string) error {
 
 // skillsInitData holds the template data for the unified skills-init script.
 type skillsInitData struct {
-	AuthMountPath string       // "/git-auth" or "" (for git auth)
-	GitRefs       []gitRefData // git repos to clone
-	OCIRefs       []ociRefData // OCI images to pull
-	InsecureOCI   bool         // --insecure flag for krane
+	AuthMountPath string        // "/git-auth" or "" (for git auth)
+	GitRefs       []gitRefData  // git repos to clone
+	OCIRefs       []ociRefData  // OCI images to pull
+	InsecureOCI   bool          // --insecure flag for krane
+	SSHHosts      []sshHostData // extra hosts to add to known_hosts via ssh-keyscan
+}
+
+// sshHostData holds the host and optional port for an SSH known_hosts entry.
+type sshHostData struct {
+	Host string // hostname or IP
+	Port string // port number, empty means default (22)
 }
 
 // gitRefData holds pre-computed fields for each git skill ref, used by the script template.
@@ -1651,6 +1658,32 @@ func prepareSkillsInitData(
 
 	if authSecretRef != nil {
 		data.AuthMountPath = "/git-auth"
+		seenHosts := make(map[string]bool)
+		hostPattern := regexp.MustCompile(`^[A-Za-z0-9\.\-:]+$`)
+		portPattern := regexp.MustCompile(`^[0-9]+$`)
+		for _, ref := range gitRefs {
+			u, err := url.Parse(ref.URL)
+			if err != nil || u.Scheme != "ssh" {
+				continue
+			}
+			host := u.Hostname()
+			if host == "" || !hostPattern.MatchString(host) {
+				continue
+			}
+			port := u.Port()
+			if port == "22" {
+				port = "" // 22 is the SSH default; omit to avoid -p flag
+			}
+			if port != "" && !portPattern.MatchString(port) {
+				continue
+			}
+			key := host + ":" + port
+			if seenHosts[key] {
+				continue
+			}
+			seenHosts[key] = true
+			data.SSHHosts = append(data.SSHHosts, sshHostData{Host: host, Port: port})
+		}
 	}
 
 	seen := make(map[string]bool)

go/core/internal/controller/translator/agent/git_skills_test.go

@@ -2,6 +2,7 @@ package agent_test
 
 import (
 	"context"
+	"fmt"
 	"testing"
 
 	"github.com/stretchr/testify/assert"
@@ -44,13 +45,14 @@ func Test_AdkApiTranslator_Skills(t *testing.T) {
 		name  string
 		agent *v1alpha2.Agent
 		// assertions
-		wantSkillsInit     bool
-		wantSkillsVolume   bool
-		wantContainsBranch string
-		wantContainsCommit string
-		wantContainsPath   string
-		wantContainsKrane  bool
-		wantAuthVolume     bool
+		wantSkillsInit      bool
+		wantSkillsVolume    bool
+		wantContainsBranch  string
+		wantContainsCommit  string
+		wantContainsPath    string
+		wantContainsKrane   bool
+		wantAuthVolume      bool
+		wantSSHKeyscanHosts []string // substrings expected in the ssh-keyscan lines
 	}{
 		{
 			name: "no skills - no init containers",
@@ -215,6 +217,34 @@ func Test_AdkApiTranslator_Skills(t *testing.T) {
 			wantSkillsVolume: true,
 			wantAuthVolume:   true,
 		},
+		{
+			name: "git skills with SSH URL and auth secret scans custom host",
+			agent: &v1alpha2.Agent{
+				ObjectMeta: metav1.ObjectMeta{Name: "agent-ssh", Namespace: namespace},
+				Spec: v1alpha2.AgentSpec{
+					Type: v1alpha2.AgentType_Declarative,
+					Declarative: &v1alpha2.DeclarativeAgentSpec{
+						SystemMessage: "test",
+						ModelConfig:   modelName,
+					},
+					Skills: &v1alpha2.SkillForAgent{
+						GitAuthSecretRef: &corev1.LocalObjectReference{
+							Name: "gitea-ssh-credentials",
+						},
+						GitRefs: []v1alpha2.GitRepo{
+							{
+								URL: "ssh://git@gitea-ssh.gitea:22/gitops/ssh-skills-repo.git",
+								Ref: "main",
+							},
+						},
+					},
+				},
+			},
+			wantSkillsInit:      true,
+			wantSkillsVolume:    true,
+			wantAuthVolume:      true,
+			wantSSHKeyscanHosts: []string{"gitea-ssh.gitea"},
+		},
 		{
 			name: "git skill with custom name",
 			agent: &v1alpha2.Agent{
@@ -358,7 +388,7 @@ func Test_AdkApiTranslator_Skills(t *testing.T) {
 				for _, v := range deployment.Spec.Template.Spec.Volumes {
 					if v.Secret != nil && v.Name == "git-auth" {
 						hasAuthVolume = true
-						assert.Equal(t, "github-token", v.Secret.SecretName, "auth volume should reference the correct secret")
+						assert.Equal(t, tt.agent.Spec.Skills.GitAuthSecretRef.Name, v.Secret.SecretName, "auth volume should reference the correct secret")
 					}
 				}
 				assert.True(t, hasAuthVolume, "git-auth volume should exist")
@@ -378,6 +408,16 @@ func Test_AdkApiTranslator_Skills(t *testing.T) {
 				assert.Contains(t, script, "credential.helper")
 			}
 
+			// Verify custom SSH hosts are scanned
+			if len(tt.wantSSHKeyscanHosts) > 0 {
+				require.NotNil(t, skillsInitContainer)
+				script := skillsInitContainer.Command[2]
+				for _, host := range tt.wantSSHKeyscanHosts {
+					expected := fmt.Sprintf("ssh-keyscan %s", host)
+					assert.Contains(t, script, expected, "script should ssh-keyscan custom host %q", host)
+				}
+			}
+
 			// Verify insecure flag for OCI skills
 			if tt.agent.Spec.Skills != nil && tt.agent.Spec.Skills.InsecureSkipVerify {
 				require.NotNil(t, skillsInitContainer)

go/core/internal/controller/translator/agent/skills-init.sh.tmpl

@@ -9,6 +9,13 @@ if [ -f "${_auth_mount}/ssh-privatekey" ]; then
   cp "${_auth_mount}/ssh-privatekey" ~/.ssh/id_rsa
   chmod 600 ~/.ssh/id_rsa
   ssh-keyscan github.com gitlab.com bitbucket.org >> ~/.ssh/known_hosts
+{{- range .SSHHosts }}
+  {{- if .Port }}
+  ssh-keyscan -p {{ .Port }} {{ .Host }} >> ~/.ssh/known_hosts
+  {{- else }}
+  ssh-keyscan {{ .Host }} >> ~/.ssh/known_hosts
+  {{- end }}
+{{- end }}
 elif [ -f "${_auth_mount}/token" ]; then
   git config --global credential.helper "!f() { echo username=x-access-token; echo password=\$(cat ${_auth_mount}/token); }; f"
 fi

go/core/internal/database/client.go

@@ -162,9 +162,16 @@ func (c *clientImpl) ListTasksForSession(ctx context.Context, sessionID string)
 }
 
 func (c *clientImpl) ListSessionsForAgent(ctx context.Context, agentID string, userID string) ([]dbpkg.Session, error) {
-	return list[dbpkg.Session](c.db.WithContext(ctx),
-		Clause{Key: "agent_id", Value: agentID},
-		Clause{Key: "user_id", Value: userID})
+	var sessions []dbpkg.Session
+	err := c.db.WithContext(ctx).
+		Where("agent_id = ? AND user_id = ?", agentID, userID).
+		Where("source IS NULL OR source != ?", dbpkg.SessionSourceAgent).
+		Order("created_at ASC").
+		Find(&sessions).Error
+	if err != nil {
+		return nil, fmt.Errorf("failed to list sessions for agent: %w", err)
+	}
+	return sessions, nil
 }
 
 // ListSessions lists all sessions for a user