From 612ab0b02a12e344eae1f3bf4b6b4a17d70fccad Mon Sep 17 00:00:00 2001 From: joycel-github Date: Wed, 15 Jul 2026 04:10:52 +0000 Subject: [PATCH 1/7] docs(readme): refresh install, auth, and Antigravity quick start - Installation: note local Antigravity needs Python 3 + pip; AX starts the Python sidecar and installs pinned SDK deps automatically on first use. - Promote Authentication to a top-level section covering AI Studio and Vertex AI (ADC). - Quick Start / Usage: use the built-in `antigravity` harness consistently, document the `--harness-config` / `--harness-config-json` flags, and add a per-request Antigravity configuration example (incl. the /config command). - Fix the exec example that referenced a nonexistent "coding" harness. --- README.md | 101 +++++++++++++++++++++++++++++++++++------------------- 1 file changed, 66 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index 2129d88..57972b7 100644 --- a/README.md +++ b/README.md @@ -88,6 +88,11 @@ We highly encourage you to give us feedback. ## Installation +### Local Antigravity requirements + +Local Antigravity execution requires Python 3 with `pip`. AX starts the Python +sidecar and installs its pinned SDK dependencies automatically on first use. + Install the ax CLI directly from the repository: ```bash @@ -114,19 +119,39 @@ use. For more details on setup and configuration, see the Read more about [this new layer](https://cloud.google.com/blog/products/containers-kubernetes/bringing-you-agent-sandbox-on-gke-and-agent-substrate) that provides higher density to agentic workloads on Kubernetes. +## Authentication + +The built-in Antigravity harness supports Google AI Studio and Vertex AI. + +For Google AI Studio, set a Gemini API key: + +```bash +export GEMINI_API_KEY="your-api-key" +``` + +For Vertex AI, configure Application Default Credentials and the target project +and location: + +```bash +gcloud auth application-default login +export GOOGLE_CLOUD_PROJECT="your-project-id" +export GOOGLE_CLOUD_LOCATION="us-central1" +export GOOGLE_GENAI_USE_VERTEXAI=true +``` + ## Quick Start -### 1. Execute +### Execute -The CLI provides an easy way to execute by using the -agents and built-in tools already linked into the AX binary. +The CLI starts the built-in Antigravity harness automatically when it is +selected. No separate harness server setup is required. ```bash -# Using default ax.yaml -ax exec --input "Can you list me this directory?" +# Run the built-in Antigravity harness locally +ax exec --harness antigravity --input "Can you list this directory?" # Using exec with an AX server -ax exec --input "Can you list me this directory?" --server localhost:8494 +ax exec --harness antigravity --input "Can you list this directory?" --server localhost:8494 ``` Conversations can be continued any time: @@ -134,6 +159,7 @@ Conversations can be continued any time: ```bash ax exec \ --conversation d85a4b4e-c53b-4c84-b879-f10d905bce40 \ + --harness antigravity \ --input "Show me the contents of README.md" ``` @@ -146,20 +172,12 @@ In this example, we catch up a client from sequence number 12: ```bash ax exec \ --conversation d85a4b4e-c53b-4c84-b879-f10d905bce40 \ + --harness antigravity \ --last-seq 12 \ --resume ``` -Instead of running the default harness, you can start executing -any registered harness: - -```bash -ax exec \ - --harness antigravity \ - --input "Can you write me a simple HTTP server in Python?" -``` - -If anything goes wrong during the execution of an agent, +If anything goes wrong during the execution of a harness, you can resume an incomplete execution in a conversation: ```bash ax exec \ @@ -180,6 +198,8 @@ ax exec \ [--input ] \ [--conversation ] \ [--harness ] \ + [--harness-config ] \ + [--harness-config-json ] \ [--server
] \ [--config ] \ [--resume] \ @@ -192,24 +212,50 @@ Options: - `--input`: Input message to send to agents (optional if `--resume` is set, otherwise required) - `--conversation`: Conversation ID (optional, generates UUID if not provided, or resumes if exists) - `--harness`: Harness ID to use (optional, defaults to the default harness) +- `--harness-config`: Path to a JSON file with per-request harness configuration (optional) +- `--harness-config-json`: Per-request harness configuration as an inline JSON string (optional, mutually exclusive with `--harness-config`) - `--server`: gRPC controller server address (optional. If not provided, runs with a local built-in AX server) - `--config`: Path to YAML configuration file (only used with a local built-in AX server, default: "ax.yaml") - `--resume`: Resume a conversation without inputs (optional, mutually exclusive with `--input`) - `--last-seq`: Last sequence number seen by the client to resume from (optional). The server replays any later events so the client can catch up after a disconnect. +#### Per-request Antigravity configuration + +The Antigravity harness accepts an optional JSON configuration object for a +single request. Pass it inline with `--harness-config-json`: + +```bash +ax exec \ + --harness antigravity \ + --harness-config-json '{"system_instructions":"Answer in one sentence.","model":"gemini-2.5-pro"}' \ + --input "Explain durable execution." +``` + +To keep the same JSON in a file, use `--harness-config` instead: + +```bash +ax exec \ + --harness antigravity \ + --harness-config antigravity.json \ + --input "Explain durable execution." +``` + +The two flags are mutually exclusive. In an interactive session, enter +`/config` to set the configuration for the next request. + **Examples:** ```bash # Execute a new execution -ax exec --input "Hello agents!" +ax exec --harness antigravity --input "Hello agents!" # Resume an existing execution with new input -ax exec --conversation a53d4db3-1165-4925-87da-be6c72bbdeb1 --input "Ok, now let's do something else..." +ax exec --conversation a53d4db3-1165-4925-87da-be6c72bbdeb1 --harness antigravity --input "Ok, now let's do something else..." # Execute using server mode -ax exec --server localhost:8494 --input "Hello agents!" +ax exec --server localhost:8494 --harness antigravity --input "Hello agents!" -# Execute using a specific harness +# Execute using the built-in Antigravity harness ax exec --harness antigravity --input "Write me a cool Go program!" ``` @@ -245,21 +291,6 @@ ax serve ax serve --config my-config.yaml ``` -### Authentication - -The built-in Antigravity agent supports authentication using either Google AI Studio or Vertex AI: - -```bash -# AI Studio API key based authentication. -export GEMINI_API_KEY="your-api-key" - -# Vertex AI based authentication, ensure application -# default credentials are set up, gcloud auth application-default login. -export GOOGLE_CLOUD_PROJECT="your-project-id" -export GOOGLE_CLOUD_LOCATION="us-central1" -export GOOGLE_GENAI_USE_VERTEXAI=True -``` - ## Extensions ### Harnesses From ad322ff402bfc9eaabe6a512aaab08bd3da7c13e Mon Sep 17 00:00:00 2001 From: joycel-github Date: Wed, 15 Jul 2026 04:51:25 +0000 Subject: [PATCH 2/7] docs(readme): tidy Antigravity harness docs and examples - Move the local Antigravity requirements into a dedicated "Built-in Antigravity harness" section and note it is the default harness. - Simplify Quick Start / Examples to rely on the default harness. - Restore the "run any registered harness" example. - Fold the per-request harness-config examples into the Examples block. --- README.md | 67 +++++++++++++++++++++++-------------------------------- 1 file changed, 28 insertions(+), 39 deletions(-) diff --git a/README.md b/README.md index 57972b7..2a4bcf1 100644 --- a/README.md +++ b/README.md @@ -88,11 +88,6 @@ We highly encourage you to give us feedback. ## Installation -### Local Antigravity requirements - -Local Antigravity execution requires Python 3 with `pip`. AX starts the Python -sidecar and installs its pinned SDK dependencies automatically on first use. - Install the ax CLI directly from the repository: ```bash @@ -119,6 +114,10 @@ use. For more details on setup and configuration, see the Read more about [this new layer](https://cloud.google.com/blog/products/containers-kubernetes/bringing-you-agent-sandbox-on-gke-and-agent-substrate) that provides higher density to agentic workloads on Kubernetes. +### Built-in Antigravity harness + +Antigravity SDK is the default harness and its local execution requires Python 3 with `pip` and Antigravity SDK wheel. When you run the ax exec command for the first time, AX starts the harness server as a Python sidecar and installs its pinned SDK dependencies automatically on first use. + ## Authentication The built-in Antigravity harness supports Google AI Studio and Vertex AI. @@ -143,15 +142,14 @@ export GOOGLE_GENAI_USE_VERTEXAI=true ### Execute -The CLI starts the built-in Antigravity harness automatically when it is -selected. No separate harness server setup is required. +The CLI starts the built-in Antigravity harness automatically. No separate harness server setup is required. ```bash # Run the built-in Antigravity harness locally -ax exec --harness antigravity --input "Can you list this directory?" +ax exec --input "Can you list this directory?" # Using exec with an AX server -ax exec --harness antigravity --input "Can you list this directory?" --server localhost:8494 +ax exec --input "Can you list this directory?" --server localhost:8494 ``` Conversations can be continued any time: @@ -159,7 +157,6 @@ Conversations can be continued any time: ```bash ax exec \ --conversation d85a4b4e-c53b-4c84-b879-f10d905bce40 \ - --harness antigravity \ --input "Show me the contents of README.md" ``` @@ -172,11 +169,19 @@ In this example, we catch up a client from sequence number 12: ```bash ax exec \ --conversation d85a4b4e-c53b-4c84-b879-f10d905bce40 \ - --harness antigravity \ --last-seq 12 \ --resume ``` +Instead of running the default harness, you can start executing +any registered harness: + +```bash +ax exec \ + --harness antigravity \ + --input "Can you write me a simple HTTP server in Python?" +``` + If anything goes wrong during the execution of a harness, you can resume an incomplete execution in a conversation: ```bash @@ -219,44 +224,28 @@ Options: - `--resume`: Resume a conversation without inputs (optional, mutually exclusive with `--input`) - `--last-seq`: Last sequence number seen by the client to resume from (optional). The server replays any later events so the client can catch up after a disconnect. -#### Per-request Antigravity configuration - -The Antigravity harness accepts an optional JSON configuration object for a -single request. Pass it inline with `--harness-config-json`: - -```bash -ax exec \ - --harness antigravity \ - --harness-config-json '{"system_instructions":"Answer in one sentence.","model":"gemini-2.5-pro"}' \ - --input "Explain durable execution." -``` - -To keep the same JSON in a file, use `--harness-config` instead: - -```bash -ax exec \ - --harness antigravity \ - --harness-config antigravity.json \ - --input "Explain durable execution." -``` - -The two flags are mutually exclusive. In an interactive session, enter -`/config` to set the configuration for the next request. - **Examples:** ```bash # Execute a new execution -ax exec --harness antigravity --input "Hello agents!" +ax exec --input "Hello agents!" # Resume an existing execution with new input -ax exec --conversation a53d4db3-1165-4925-87da-be6c72bbdeb1 --harness antigravity --input "Ok, now let's do something else..." +ax exec --conversation a53d4db3-1165-4925-87da-be6c72bbdeb1 --input "Ok, now let's do something else..." # Execute using server mode -ax exec --server localhost:8494 --harness antigravity --input "Hello agents!" +ax exec --server localhost:8494 --input "Hello agents!" # Execute using the built-in Antigravity harness -ax exec --harness antigravity --input "Write me a cool Go program!" +ax exec --input "Write me a cool Go program!" + +# Execute using the built-in Antigravity harness with per-request config +ax exec \ + --harness-config-json '{"system_instructions":"Answer in one sentence.","model":"gemini-2.5-pro"}' \ + --input "Explain durable execution." + +#To keep the same JSON in a file, use `--harness-config` instead: +ax exec --harness-config antigravity.json --input "Explain durable execution." ``` ### Serve From 7aaa533c31663f3193bcef82f21ead0120646051 Mon Sep 17 00:00:00 2001 From: joycel-github Date: Wed, 15 Jul 2026 04:57:49 +0000 Subject: [PATCH 3/7] docs(readme): clarify default-harness assumption in Quick Start - Note that the Quick Start examples omit --harness and assume an ax.yaml with a default harness; otherwise pass --harness antigravity explicitly. - Reword the built-in harness blurb (Antigravity SDK as a reference harness implementation) and fix `ax exec` formatting. --- README.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 2a4bcf1..f67f195 100644 --- a/README.md +++ b/README.md @@ -116,7 +116,7 @@ that provides higher density to agentic workloads on Kubernetes. ### Built-in Antigravity harness -Antigravity SDK is the default harness and its local execution requires Python 3 with `pip` and Antigravity SDK wheel. When you run the ax exec command for the first time, AX starts the harness server as a Python sidecar and installs its pinned SDK dependencies automatically on first use. +Antigravity SDK is a reference harness implementation. Its local execution requires Python 3 with `pip` and Antigravity SDK wheel. When you run the `ax exec` command for the first time, AX starts the harness server as a Python sidecar and installs its pinned SDK dependencies automatically on first use. ## Authentication @@ -144,6 +144,11 @@ export GOOGLE_GENAI_USE_VERTEXAI=true The CLI starts the built-in Antigravity harness automatically. No separate harness server setup is required. +> [!NOTE] +> The examples below omit `--harness` and assume an `ax.yaml` that marks a +> default harness (e.g. `antigravity: { default: true }`). Without a default +> harness configured, pass `--harness antigravity` explicitly. + ```bash # Run the built-in Antigravity harness locally ax exec --input "Can you list this directory?" From a10da901d51a6d67e0062bf76f10282e39d4dfd7 Mon Sep 17 00:00:00 2001 From: joycel-github Date: Wed, 15 Jul 2026 05:00:32 +0000 Subject: [PATCH 4/7] docs(readme): note examples use default ax.yaml for Antigravity harness Drop the callout block and clarify inline that the Quick Start examples rely on the default ax.yaml which runs the built-in Antigravity harness. --- README.md | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/README.md b/README.md index f67f195..a23174d 100644 --- a/README.md +++ b/README.md @@ -144,13 +144,8 @@ export GOOGLE_GENAI_USE_VERTEXAI=true The CLI starts the built-in Antigravity harness automatically. No separate harness server setup is required. -> [!NOTE] -> The examples below omit `--harness` and assume an `ax.yaml` that marks a -> default harness (e.g. `antigravity: { default: true }`). Without a default -> harness configured, pass `--harness antigravity` explicitly. - ```bash -# Run the built-in Antigravity harness locally +# Using default ax.yaml which runs built-in Antigravity harness ax exec --input "Can you list this directory?" # Using exec with an AX server From a18945cf6b8843bdc5aa6182ea8ff0bf513fb167 Mon Sep 17 00:00:00 2001 From: joycel-github Date: Wed, 15 Jul 2026 05:06:26 +0000 Subject: [PATCH 5/7] docs(readme): tighten Antigravity harness wording and fix comments - Trim the built-in harness blurb and drop a trailing space. - Clarify the Quick Start example uses the checked-in ax.yaml that sets Antigravity as the default harness. - Fix the "# To keep the same JSON in a file" comment spacing. --- README.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index a23174d..1bdb8e5 100644 --- a/README.md +++ b/README.md @@ -116,7 +116,8 @@ that provides higher density to agentic workloads on Kubernetes. ### Built-in Antigravity harness -Antigravity SDK is a reference harness implementation. Its local execution requires Python 3 with `pip` and Antigravity SDK wheel. When you run the `ax exec` command for the first time, AX starts the harness server as a Python sidecar and installs its pinned SDK dependencies automatically on first use. +Antigravity SDK is a reference harness implementation. Local execution requires Python 3 with `pip`. +AX starts the harness server as a Python sidecar and installs its pinned SDK dependencies automatically on first use. ## Authentication @@ -145,7 +146,7 @@ export GOOGLE_GENAI_USE_VERTEXAI=true The CLI starts the built-in Antigravity harness automatically. No separate harness server setup is required. ```bash -# Using default ax.yaml which runs built-in Antigravity harness +# Using the checked-in ax.yaml, which sets Antigravity as the default harness. ax exec --input "Can you list this directory?" # Using exec with an AX server @@ -244,7 +245,7 @@ ax exec \ --harness-config-json '{"system_instructions":"Answer in one sentence.","model":"gemini-2.5-pro"}' \ --input "Explain durable execution." -#To keep the same JSON in a file, use `--harness-config` instead: +# To keep the same JSON in a file, use `--harness-config` instead: ax exec --harness-config antigravity.json --input "Explain durable execution." ``` From 7b0ec142a10aae4ad5fe5808e7cf369d220324ae Mon Sep 17 00:00:00 2001 From: joycel-github Date: Wed, 15 Jul 2026 05:18:01 +0000 Subject: [PATCH 6/7] docs(readme): clarify AX auto-installs the Antigravity SDK deps The prior wording ("requires Python 3 with pip" next to "installs automatically") read as a contradiction. Make explicit that python3/pip are the only prerequisite and AX installs the pinned SDK dependencies for the user on first `ax exec`. --- README.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 1bdb8e5..a0cf2dc 100644 --- a/README.md +++ b/README.md @@ -116,8 +116,10 @@ that provides higher density to agentic workloads on Kubernetes. ### Built-in Antigravity harness -Antigravity SDK is a reference harness implementation. Local execution requires Python 3 with `pip`. -AX starts the harness server as a Python sidecar and installs its pinned SDK dependencies automatically on first use. +Antigravity SDK is a reference harness implementation. Local execution needs +`python3` and `pip` available on your `PATH`. AX handles the rest: on first +`ax exec` it starts the harness server as a Python sidecar and installs the +pinned Antigravity SDK dependencies for you. ## Authentication From 1e0cf018a4396b617595930f550cd451debd43ac Mon Sep 17 00:00:00 2001 From: joycel-github Date: Wed, 15 Jul 2026 05:22:18 +0000 Subject: [PATCH 7/7] docs(readme): use explicit harness in example and tidy config comment Show `--harness antigravity` explicitly in the "specific harness" example and shorten the per-request harness-config comment. --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index a0cf2dc..fdc8203 100644 --- a/README.md +++ b/README.md @@ -239,10 +239,10 @@ ax exec --conversation a53d4db3-1165-4925-87da-be6c72bbdeb1 --input "Ok, now let # Execute using server mode ax exec --server localhost:8494 --input "Hello agents!" -# Execute using the built-in Antigravity harness -ax exec --input "Write me a cool Go program!" +# Execute using a specific harness +ax exec --harness antigravity --input "Write me a cool Go program!" -# Execute using the built-in Antigravity harness with per-request config +# Execute with per-request harness config ax exec \ --harness-config-json '{"system_instructions":"Answer in one sentence.","model":"gemini-2.5-pro"}' \ --input "Explain durable execution."