Skip to content

armgit / ax

Public Imported from GitHub
0

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

Go

Run Antigravity Interactions as substrate actors (#287)

Junjie Wangfea5d230db6d
diff --git a/cmd/ax/harness.go b/cmd/ax/harness.go
index 19b62d8..1985696 100644
--- a/cmd/ax/harness.go
+++ b/cmd/ax/harness.go
@@ -12,9 +12,9 @@
// See the License for the specific language governing permissions and
// limitations under the License.
-// Package main: the `ax harness` command. It supervises the Antigravity Python
-// sidecar server (which serves the HarnessService and gRPC health), forking it
-// as a child process and forwarding termination signals.
+// Package main: the `ax harness` command. It runs one harness in-process,
+// selected by the optional [harness-id] argument: "antigravity" (default)
+// or "antigravity-interactions"
package main
import (
@@ -29,6 +29,7 @@ import (
"syscall"
"time"
+ "github.com/google/ax/internal/config"
"github.com/google/ax/internal/harness/antigravityinteractions"
"github.com/google/ax/internal/pythonsidecar"
"github.com/spf13/cobra"
@@ -46,8 +47,9 @@ var (
const harnessReadyzPort = 8081
var harnessCmd = &cobra.Command{
- Use: "harness",
+ Use: "harness [harness-id]",
Short: "Run the harness gRPC server",
+ Args: cobra.MaximumNArgs(1),
Hidden: true,
RunE: runHarness,
}
@@ -73,10 +75,28 @@ func setHarnessWorkDir() error {
return nil
}
-// runHarness forks the Antigravity Python sidecar server, which serves the
-// HarnessService (and gRPC health) on the configured port. ax harness supervises
-// the child: it forwards termination signals and exits with the child's status.
+// runHarness runs the harness selected by the optional [harness-id] argument:
+// "antigravity" (default) or "antigravity-interactions".
func runHarness(cmd *cobra.Command, args []string) error {
+ harnessID := config.AntigravityHarnessID
+ if len(args) > 0 {
+ harnessID = args[0]
+ }
+ switch harnessID {
+ case config.AntigravityInteractionsHarnessID:
+ return runAntigravityInteractionsHarness(cmd.Context())
+ case config.AntigravityHarnessID:
+ return runAntigravityHarness(cmd)
+ default:
+ return fmt.Errorf("unknown harness %q (want %q or %q)",
+ harnessID, config.AntigravityHarnessID, config.AntigravityInteractionsHarnessID)
+ }
+}
+
+// runAntigravityHarness forks the Antigravity Python sidecar server, which serves
+// the HarnessService (and gRPC health) on the configured port. ax harness
+// supervises the child: it forwards termination signals and exits with its status.
+func runAntigravityHarness(cmd *cobra.Command) error {
if err := setHarnessWorkDir(); err != nil {
return err
}
@@ -116,7 +136,9 @@ func runHarness(cmd *cobra.Command, args []string) error {
return nil
}
-func runAntigravityInteractionsHarness(ctx context.Context, systemInstructions string) error {
+// runAntigravityInteractionsHarness runs the Go Antigravity Interactions harness
+// server (HarnessService + gRPC health + HTTP /readyz) on the configured ports.
+func runAntigravityInteractionsHarness(ctx context.Context) error {
if err := setHarnessWorkDir(); err != nil {
return err
}
@@ -125,8 +147,8 @@ func runAntigravityInteractionsHarness(ctx context.Context, systemInstructions s
return err
}
cfg := antigravityinteractions.AntigravityInteractionsConfig{
- SystemInstruction: systemInstructions,
- StateDir: stateDir,
+ Agent: antigravityinteractions.DefaultAgent,
+ StateDir: stateDir,
}
return antigravityinteractions.Serve(ctx, cfg, harnessHost, harnessPort, harnessReadyzPort)
}
diff --git a/cmd/ax/internal/cliutil/cliutil.go b/cmd/ax/internal/cliutil/cliutil.go
index 3e99c75..9e63e2e 100644
--- a/cmd/ax/internal/cliutil/cliutil.go
+++ b/cmd/ax/internal/cliutil/cliutil.go
@@ -77,7 +77,7 @@ func NewControllerFromConfig(ctx context.Context, cfg *Config) (*controller.Cont
return nil, fmt.Errorf("antigravity harness: %w", err)
}
} else {
- antigravityHarness, err = substrate.New(config.AntigravityHarnessID, "", "", "", 80)
+ antigravityHarness, err = substrate.New(config.AntigravityHarnessID, "", "", config.AntigravityHarnessTemplate, 80)
if err != nil {
return nil, fmt.Errorf("antigravity harness: %w", err)
}
@@ -108,7 +108,7 @@ func NewControllerFromConfig(ctx context.Context, cfg *Config) (*controller.Cont
StateDir: stateDir,
})
} else {
- antigravityInteractionsHarness, err = substrate.New(config.AntigravityInteractionsHarnessID, "", "", "", 80)
+ antigravityInteractionsHarness, err = substrate.New(config.AntigravityInteractionsHarnessID, "", "", config.AntigravityInteractionsTemplate, 80)
}
if err != nil {
return nil, fmt.Errorf("antigravity-interactions harness: %w", err)
diff --git a/hack/install-ax.sh b/hack/install-ax.sh
index 77c99b0..c383f20 100755
--- a/hack/install-ax.sh
+++ b/hack/install-ax.sh
@@ -236,6 +236,7 @@ deploy_ax_server() {
-e "s|\${AX_SNAPSHOTS_BUCKET}|${AX_SNAPSHOTS_BUCKET}|g"
-e "s|\${AX_IMAGE}|${ax_image}|g"
-e "s|\${ATEOM_IMAGE}|${ateom_image}|g"
+ -e "s|\${PROJECT_ID}|${PROJECT_ID:-}|g"
)
# Render and apply the core manifest (namespace, harnesses, ax-server, ConfigMap).
@@ -267,16 +268,22 @@ deploy_ax_server() {
fi
# Wait for the antigravity ActorTemplate's golden snapshot to be ready.
- log_step "wait for actortemplate/ax-harness-template to be Ready"
- wait_with_spinner "waiting for golden snapshot (timeout ${AX_WAIT_TIMEOUT:-5m})" \
- run_kubectl wait --for=condition=Ready actortemplate/ax-harness-template \
+ log_step "wait for actortemplate/ax-harness-antigravity-template to be Ready"
+ wait_with_spinner "waiting for antigravity golden snapshot (timeout ${AX_WAIT_TIMEOUT:-5m})" \
+ run_kubectl wait --for=condition=Ready actortemplate/ax-harness-antigravity-template \
+ -n ax --timeout="${AX_WAIT_TIMEOUT:-5m}"
+
+ # Wait for the interactions ActorTemplate's golden snapshot to be ready.
+ log_step "wait for actortemplate/ax-harness-interactions-template to be Ready"
+ wait_with_spinner "waiting for interactions golden snapshot (timeout ${AX_WAIT_TIMEOUT:-5m})" \
+ run_kubectl wait --for=condition=Ready actortemplate/ax-harness-interactions-template \
-n ax --timeout="${AX_WAIT_TIMEOUT:-5m}"
echo ""
echo "Forward the AX server by running the following command (optional)"
echo "kubectl port-forward -n ax rs/ax-server 8494:8494"
echo ""
- echo "Then, run: ax exec --server localhost:8494"
+ echo "Then, run: ax exec --server localhost:8494 [--harness antigravity|antigravity-interactions]"
}
# delete_ax_server removes the AX server and harness resources but preserves the
@@ -289,7 +296,8 @@ delete_ax_server() {
run_kubectl -n ax delete --ignore-not-found \
replicaset/ax-server \
configmap/ax-server-config \
- actortemplate/ax-harness-template \
+ actortemplate/ax-harness-antigravity-template \
+ actortemplate/ax-harness-interactions-template \
workerpool/ax-harness-workerpool
}
diff --git a/internal/config/config.go b/internal/config/config.go
index 66a9a48..c8d82ed 100644
--- a/internal/config/config.go
+++ b/internal/config/config.go
@@ -34,6 +34,12 @@ const (
// Harness IDs reserved for AX's built-in harnesses.
AntigravityHarnessID = "antigravity"
AntigravityInteractionsHarnessID = "antigravity-interactions"
+ // AntigravityHarnessTemplate is the substrate ActorTemplate that runs the
+ // Antigravity harness.
+ AntigravityHarnessTemplate = "ax-harness-antigravity-template"
+ // AntigravityInteractionsTemplate is the substrate ActorTemplate that runs
+ // the Antigravity Interactions harness.
+ AntigravityInteractionsTemplate = "ax-harness-interactions-template"
)
// Config represents the main configuration for the AX harness server.
diff --git a/internal/harness/antigravityinteractions/antigravityinteractions.go b/internal/harness/antigravityinteractions/antigravityinteractions.go
index 430ed5a..f2aeeaf 100644
--- a/internal/harness/antigravityinteractions/antigravityinteractions.go
+++ b/internal/harness/antigravityinteractions/antigravityinteractions.go
@@ -77,7 +77,7 @@ const (
// Cloud project and location are read from these standard environment
// variables (see https://github.com/google/ax#authentication).
- envCloudProject = "GOOGLE_CLOUD_PROJECT"
+ envCloudProject = "PROJECT_ID"
envCloudLocation = "GOOGLE_CLOUD_LOCATION"
// defaultLocation is used when GOOGLE_CLOUD_LOCATION is unset.
defaultLocation = "global"
@@ -94,7 +94,7 @@ var _ harness.Execution = (*antigravityInteractionsExecution)(nil)
// AntigravityInteractionsConfig configures an AntigravityInteractionsHarness.
// Use New, which fills sensible defaults.
//
-// Cloud project and location come from the standard GOOGLE_CLOUD_PROJECT and
+// Cloud project and location come from the standard PROJECT_ID and
// GOOGLE_CLOUD_LOCATION environment variables.
type AntigravityInteractionsConfig struct {
// --- Required ---
@@ -145,7 +145,7 @@ func (c *AntigravityInteractionsConfig) withDefaults() {
}
}
-// cloudProject returns the Cloud project id from GOOGLE_CLOUD_PROJECT.
+// cloudProject returns the Cloud project id from PROJECT_ID.
func cloudProject() string {
return os.Getenv(envCloudProject)
}
diff --git a/internal/harness/substrate/substrate.go b/internal/harness/substrate/substrate.go
index 84d7b45..b1e8403 100644
--- a/internal/harness/substrate/substrate.go
+++ b/internal/harness/substrate/substrate.go
@@ -64,7 +64,7 @@ func New(harnessID string, endpoint string, namespace string, template string, p
namespace = "ax"
}
if template == "" {
- template = "ax-harness-template"
+ template = "ax-harness-antigravity-template"
}
controlCreds := grpc.WithTransportCredentials(credentials.NewTLS(&tls.Config{InsecureSkipVerify: true}))
client, err := ate.NewClient(namespace, template, endpoint, controlCreds)
diff --git a/manifests/README.md b/manifests/README.md
index 90efed1..6fc4962 100644
--- a/manifests/README.md
+++ b/manifests/README.md
@@ -79,6 +79,31 @@ The bundled Postgres uses an auto-generated password. To get its DSN:
kubectl get secret ax-eventlog-postgres -n ax -o go-template='{{.data.dsn | base64decode}}'
```
+#### Vertex AI access for the Antigravity Interactions harness
+
+> [!NOTE]
+> You may skip this if you only use the default harness.
+
+The Antigravity **Interactions** harness (`ax harness antigravity-interactions`,
+ActorTemplate `ax-harness-interactions-template`) calls the Vertex AI GenAI API
+and authenticates with the actor's Google Cloud credentials — unlike the default
+Antigravity harness, which uses `GEMINI_API_KEY`.
+
+The worker pods (WorkerPool `ax-harness-workerpool`, namespace `ax`) have no GSA
+annotation, so with Workload Identity the actor authenticates **directly as the
+Kubernetes ServiceAccount principal** `ax/default`. Grant that principal
+`roles/aiplatform.user` on the project the harness reads from `PROJECT_ID`, or
+Vertex calls fail with `PermissionDenied (403)`. IAM changes can take a minute or two to propagate.
+
+```bash
+PROJECT_NUMBER="$(gcloud projects describe "${PROJECT_ID}" --format='value(projectNumber)')"
+
+gcloud projects add-iam-policy-binding "${PROJECT_ID}" \
+ --role=roles/aiplatform.user \
+ --member="principal://iam.googleapis.com/projects/${PROJECT_NUMBER}/locations/global/workloadIdentityPools/${PROJECT_ID}.svc.id.goog/subject/ns/ax/sa/default" \
+ --condition=None
+```
+
### 2. Port-Forward Services
```bash
diff --git a/manifests/ax-deployment.yaml b/manifests/ax-deployment.yaml
index 49035cc..17bc95e 100644
--- a/manifests/ax-deployment.yaml
+++ b/manifests/ax-deployment.yaml
@@ -41,7 +41,7 @@ spec:
apiVersion: ate.dev/v1alpha1
kind: ActorTemplate
metadata:
- name: ax-harness-template
+ name: ax-harness-antigravity-template
namespace: ax
spec:
workerSelector:
@@ -49,12 +49,13 @@ spec:
workload: ax-harness
pauseImage: "gcr.io/gke-release/pause@sha256:bcbd57ba5653580ec647b16d8163cdd1112df3609129b01f912a8032e48265da"
containers:
- - name: "axharness"
+ - name: "axantigravity"
image: ${AX_IMAGE}
# Substrate ignores the image CMD/ENV/WORKDIR, so the harness command and
- # environment are specified here. `ax harness` forks the Antigravity Python
- # sidecar, which serves on port 80 because substrate DNATs workerPodIP:80.
- command: ["/ax-app/ax", "harness",
+ # environment are specified here. `ax harness antigravity` forks the
+ # Antigravity Python sidecar, which serves on port 80 because substrate
+ # DNATs workerPodIP:80.
+ command: ["/ax-app/ax", "harness", "antigravity",
"--host", "0.0.0.0", "--port", "80"]
env:
- name: GEMINI_API_KEY
@@ -72,7 +73,37 @@ spec:
path: /readyz
port: 8081
snapshotsConfig:
- location: gs://${AX_SNAPSHOTS_BUCKET}/axharness/
+ location: gs://${AX_SNAPSHOTS_BUCKET}/axantigravity/
+---
+apiVersion: ate.dev/v1alpha1
+kind: ActorTemplate
+metadata:
+ name: ax-harness-interactions-template
+ namespace: ax
+spec:
+ workerSelector:
+ matchLabels:
+ workload: ax-harness
+ pauseImage: "gcr.io/gke-release/pause@sha256:bcbd57ba5653580ec647b16d8163cdd1112df3609129b01f912a8032e48265da"
+ containers:
+ - name: "axinteractions"
+ image: ${AX_IMAGE}
+ # Substrate ignores the image CMD/ENV/WORKDIR, so the harness command and
+ # environment are specified here. `ax harness antigravity-interactions` runs
+ # the Go Interactions harness on port 80 because substrate DNATs workerPodIP:80.
+ command: ["/ax-app/ax", "harness", "antigravity-interactions",
+ "--host", "0.0.0.0", "--port", "80"]
+ env:
+ - name: PROJECT_ID
+ value: "${PROJECT_ID}"
+ - name: AX_HARNESS_WORKDIR
+ value: "/workspace"
+ readyz:
+ httpGet:
+ path: /readyz
+ port: 8081
+ snapshotsConfig:
+ location: gs://${AX_SNAPSHOTS_BUCKET}/axinteractions/
---
# ---------------------------------------------------------------------------