Skip to content

armgit / ax

Public Imported from GitHub
0

Agent Executor (AX) is Google's open agentic orchestration runtime

Go

Support a2a in substrate agent. (#286)

Junjie Wang80c38f2dcb41
diff --git a/internal/config/config.go b/internal/config/config.go
index b00ebc1..f741527 100644
--- a/internal/config/config.go
+++ b/internal/config/config.go
@@ -118,6 +118,9 @@ type ATEAgentConfig struct {
Port int `yaml:"port"` // Port the agent is listening on
Namespace string `yaml:"namespace"` // Namespace for actor
Template string `yaml:"template"` // Template for actor
+ Protocol string `yaml:"protocol,omitempty"` // "axp" (default) or "a2a"
+ Auth auth.Auth `yaml:"auth,omitempty"` // Optional auth
+ Headers auth.Headers `yaml:"headers,omitempty"` // Optional headers
Metadata map[string]string `yaml:"metadata,omitempty"` // Optional metadata
// TODO(jbd): Rename this struct before releasing.
}
diff --git a/internal/controller/registry.go b/internal/controller/registry.go
index e3f9ce0..535d934 100644
--- a/internal/controller/registry.go
+++ b/internal/controller/registry.go
@@ -17,6 +17,7 @@ package controller
import (
"context"
"fmt"
+ "strings"
"sync"
"github.com/google/ax/internal/agent"
@@ -73,9 +74,10 @@ func (r *Registry) RegisterLocal(cfg config.LocalAgentConfig) error {
}
// RegisterRemote registers a remote agent by creating a remote agent client.
-// The protocol field determines what kind of remote agent to register:
-// - axp/AXP (default): AX's proto.AgentService.
-// - a2a/A2A: A2A protocol.
+// The protocol field determines what kind of remote agent to register
+// (matched case-insensitively):
+// - "axp" (default): AX's proto.AgentService.
+// - "a2a": A2A protocol.
func (r *Registry) RegisterRemote(ctx context.Context, cfg config.RemoteAgentConfig) error {
r.mu.Lock()
defer r.mu.Unlock()
@@ -87,10 +89,10 @@ func (r *Registry) RegisterRemote(ctx context.Context, cfg config.RemoteAgentCon
return fmt.Errorf("agent %s already registered", cfg.ID)
}
- switch cfg.Protocol {
- case "", "axp", "AXP":
+ switch strings.ToLower(cfg.Protocol) {
+ case "", "axp":
return r.registerRemote(cfg)
- case "a2a", "A2A":
+ case "a2a":
return r.registerA2A(ctx, cfg)
default:
return fmt.Errorf("remote agent %s: invalid protocol %q (want \"axp\" or \"a2a\")", cfg.ID, cfg.Protocol)
diff --git a/internal/controller/registry_ate.go b/internal/controller/registry_ate.go
index 4f68d0f..c38b4e6 100644
--- a/internal/controller/registry_ate.go
+++ b/internal/controller/registry_ate.go
@@ -40,9 +40,13 @@ func (r *Registry) RegisterATE(ctx context.Context, ateTarget string, cfg config
// Create ATE agent client
ateAgent, err := expagent.NewATEAgent(ateTarget, expagent.ATEAgentConfig{
+ ID: cfg.ID,
Namespace: cfg.Namespace,
Template: cfg.Template,
Port: cfg.Port,
+ Protocol: cfg.Protocol,
+ Auth: cfg.Auth,
+ Headers: cfg.Headers,
})
if err != nil {
return fmt.Errorf("failed to create ATE agent: %w", err)
diff --git a/internal/experimental/a2abridge/card.go b/internal/experimental/a2abridge/card.go
new file mode 100644
index 0000000..5929725
--- /dev/null
+++ b/internal/experimental/a2abridge/card.go
@@ -0,0 +1,52 @@
+// Copyright 2026 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 a2abridge
+
+import (
+ "fmt"
+ "net/url"
+
+ "github.com/a2aproject/a2a-go/v2/a2a"
+)
+
+// OverrideCardHosts rewrites the host:port portion of every URL in
+// card.SupportedInterfaces[] to match the host:port of addr.
+// Used for A2A agents whose AgentCard typically declares localhost URLs
+// that must be redirected to the actual worker address discovered at
+// connect time.
+func OverrideCardHosts(card *a2a.AgentCard, addr string) error {
+ if card == nil {
+ return nil
+ }
+ addrURL, err := url.Parse(addr)
+ if err != nil {
+ return fmt.Errorf("OverrideCardHosts: parse addr %q: %w", addr, err)
+ }
+ if addrURL.Host == "" {
+ return fmt.Errorf("OverrideCardHosts: addr %q has no host", addr)
+ }
+ for i, iface := range card.SupportedInterfaces {
+ if iface == nil {
+ continue
+ }
+ u, err := url.Parse(iface.URL)
+ if err != nil {
+ return fmt.Errorf("OverrideCardHosts: parse SupportedInterfaces[%d].URL %q: %w", i, iface.URL, err)
+ }
+ u.Host = addrURL.Host
+ iface.URL = u.String()
+ }
+ return nil
+}
diff --git a/internal/experimental/a2abridge/card_test.go b/internal/experimental/a2abridge/card_test.go
new file mode 100644
index 0000000..36f222c
--- /dev/null
+++ b/internal/experimental/a2abridge/card_test.go
@@ -0,0 +1,116 @@
+// Copyright 2026 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 a2abridge
+
+import (
+ "strings"
+ "testing"
+
+ "github.com/a2aproject/a2a-go/v2/a2a"
+)
+
+func TestOverrideCardHosts_RewritesEverySupportedInterface(t *testing.T) {
+ card := &a2a.AgentCard{
+ SupportedInterfaces: []*a2a.AgentInterface{
+ {URL: "http://localhost:8080/jsonrpc"},
+ {URL: "http://localhost:8080/rest"},
+ {URL: "http://localhost:50051"},
+ },
+ }
+ if err := OverrideCardHosts(card, "http://10.0.1.5:8080"); err != nil {
+ t.Fatalf("got err=%v, want nil", err)
+ }
+ want := []string{
+ "http://10.0.1.5:8080/jsonrpc",
+ "http://10.0.1.5:8080/rest",
+ "http://10.0.1.5:8080",
+ }
+ for i, iface := range card.SupportedInterfaces {
+ if iface.URL != want[i] {
+ t.Errorf("SupportedInterfaces[%d].URL = %q, want %q", i, iface.URL, want[i])
+ }
+ }
+}
+
+func TestOverrideCardHosts_PreservesSchemeAndPath(t *testing.T) {
+ card := &a2a.AgentCard{
+ SupportedInterfaces: []*a2a.AgentInterface{
+ {URL: "https://example.com/v2/agent?foo=bar"},
+ },
+ }
+ if err := OverrideCardHosts(card, "https://1.2.3.4:443"); err != nil {
+ t.Fatalf("got err=%v, want nil", err)
+ }
+ got := card.SupportedInterfaces[0].URL
+ if got != "https://1.2.3.4:443/v2/agent?foo=bar" {
+ t.Errorf("URL = %q, want scheme/path/query preserved with new host", got)
+ }
+}
+
+func TestOverrideCardHosts_NilCardNoOp(t *testing.T) {
+ if err := OverrideCardHosts(nil, "http://10.0.1.5:8080"); err != nil {
+ t.Errorf("got err=%v, want nil for nil card", err)
+ }
+}
+
+func TestOverrideCardHosts_EmptyInterfacesNoOp(t *testing.T) {
+ card := &a2a.AgentCard{}
+ if err := OverrideCardHosts(card, "http://10.0.1.5:8080"); err != nil {
+ t.Errorf("got err=%v, want nil for empty interfaces", err)
+ }
+}
+
+func TestOverrideCardHosts_RejectsAddrWithoutHost(t *testing.T) {
+ card := &a2a.AgentCard{
+ SupportedInterfaces: []*a2a.AgentInterface{{URL: "http://localhost:8080"}},
+ }
+ err := OverrideCardHosts(card, "")
+ if err == nil {
+ t.Fatal("got nil err, want non-nil for empty addr")
+ }
+ if !strings.Contains(err.Error(), "no host") {
+ t.Errorf("err should mention missing host; got: %v", err)
+ }
+}
+
+func TestOverrideCardHosts_RejectsMalformedURL(t *testing.T) {
+ card := &a2a.AgentCard{
+ SupportedInterfaces: []*a2a.AgentInterface{
+ {URL: "://bad-url"},
+ },
+ }
+ err := OverrideCardHosts(card, "http://10.0.1.5:8080")
+ if err == nil {
+ t.Fatal("got nil err, want non-nil for malformed URL")
+ }
+ if !strings.Contains(err.Error(), "SupportedInterfaces[0]") {
+ t.Errorf("err should mention which interface failed; got: %v", err)
+ }
+}
+
+func TestOverrideCardHosts_SkipsNilInterface(t *testing.T) {
+ card := &a2a.AgentCard{
+ SupportedInterfaces: []*a2a.AgentInterface{
+ nil,
+ {URL: "http://localhost:8080"},
+ },
+ }
+ if err := OverrideCardHosts(card, "http://10.0.1.5:8080"); err != nil {
+ t.Fatalf("got err=%v, want nil", err)
+ }
+ if card.SupportedInterfaces[1].URL != "http://10.0.1.5:8080" {
+ t.Errorf("non-nil interface should be rewritten; got %q", card.SupportedInterfaces[1].URL)
+ }
+}
diff --git a/internal/experimental/agent/a2a.go b/internal/experimental/agent/a2a.go
index b887b69..1fd5b8e 100644
--- a/internal/experimental/agent/a2a.go
+++ b/internal/experimental/agent/a2a.go
@@ -18,6 +18,7 @@ import (
"context"
"errors"
"fmt"
+ "strings"
"github.com/a2aproject/a2a-go/v2/a2a"
"github.com/a2aproject/a2a-go/v2/a2aclient"
@@ -42,11 +43,12 @@ import (
// Use this when targeting an A2A agent that does not maintain its
// own per-context state.
type A2AAgentConfig struct {
- ID string
- Address string
- Auth auth.Auth
- Headers auth.Headers
- Stateless bool
+ ID string
+ Address string
+ Auth auth.Auth
+ Headers auth.Headers
+ Stateless bool
+ OverrideCardHosts bool
}
// A2AAgent bridges AX's Agent interface to an A2A-protocol agent.
@@ -62,11 +64,22 @@ func NewA2AAgent(ctx context.Context, config A2AAgentConfig) (*A2AAgent, error)
return nil, errors.New("a2a agent: address is required")
}
- card, err := agentcard.DefaultResolver.Resolve(ctx, config.Address)
+ addr := config.Address
+ if !strings.Contains(addr, "://") {
+ addr = "http://" + addr
+ }
+
+ card, err := agentcard.DefaultResolver.Resolve(ctx, addr)
if err != nil {
return nil, fmt.Errorf("a2a agent %s: resolve AgentCard: %w", config.ID, err)
}
+ if config.OverrideCardHosts {
+ if err := a2abridge.OverrideCardHosts(card, addr); err != nil {
+ return nil, fmt.Errorf("a2a agent %s: %w", config.ID, err)
+ }
+ }
+
interceptor, err := a2abridge.NewInterceptor(card, config.Auth, config.Headers)
if err != nil {
return nil, fmt.Errorf("a2a agent %s: %w", config.ID, err)
diff --git a/internal/experimental/agent/ate.go b/internal/experimental/agent/ate.go
index c9eb323..aa23148 100644
--- a/internal/experimental/agent/ate.go
+++ b/internal/experimental/agent/ate.go
@@ -20,9 +20,11 @@ import (
"context"
"fmt"
"log"
+ "strings"
"time"
"github.com/google/ax/internal/agent"
+ "github.com/google/ax/internal/auth"
"github.com/google/ax/internal/experimental/k8s/ate"
"github.com/google/ax/proto"
)
@@ -35,9 +37,13 @@ type ATEAgent struct {
// ATEAgentConfig configures an ATE agent client.
type ATEAgentConfig struct {
+ ID string
Namespace string
Template string
Port int // Port where agent runs in the worker
+ Protocol string
+ Auth auth.Auth
+ Headers auth.Headers
}
// NewATEAgent creates a new ATE agent client.
@@ -74,16 +80,32 @@ func (a *ATEAgent) Connect(ctx context.Context, conversationID string, execID st
return fmt.Errorf("worker has no IP address")
}
- remoteAddr := fmt.Sprintf("%s:%d", worker.Ip, a.config.Port)
- remoteAgent, err := agent.NewRemoteAgent(agent.RemoteAgentConfig{
- Address: remoteAddr,
- Reconnect: true,
- MaxRetries: 3,
- })
+ workerAddr := fmt.Sprintf("%s:%d", worker.Ip, a.config.Port)
+ // 2. Connect to the Actor.
+ var activeAgent agent.Agent
+ switch strings.ToLower(a.config.Protocol) {
+ case "", "axp":
+ activeAgent, err = agent.NewRemoteAgent(agent.RemoteAgentConfig{
+ Address: workerAddr,
+ Reconnect: true,
+ MaxRetries: 3,
+ })
+ case "a2a":
+ activeAgent, err = NewA2AAgent(ctx, A2AAgentConfig{
+ ID: a.config.ID,
+ Address: workerAddr,
+ Auth: a.config.Auth,
+ Headers: a.config.Headers,
+ Stateless: true,
+ OverrideCardHosts: true,
+ })
+ default:
+ return fmt.Errorf("ate agent %s: invalid protocol %q", a.config.ID, a.config.Protocol)
+ }
if err != nil {
return fmt.Errorf("failed to create remote agent connection: %w", err)
}
- defer remoteAgent.Close()
+ defer activeAgent.Close()
// 3. Suspend Actor when done.
defer func() {
@@ -98,7 +120,7 @@ func (a *ATEAgent) Connect(ctx context.Context, conversationID string, execID st
}
}()
- return remoteAgent.Connect(ctx, conversationID, execID, start, e, o)
+ return activeAgent.Connect(ctx, conversationID, execID, start, e, o)
}
// Close gracefully shuts down the ATE agent connection.