Skip to content

armgit / ax

Public Imported from GitHub
0

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

Go

support headless gar trigger (#18)

JoyceLiu741becd66bb2
diff --git a/README.md b/README.md
index f22516e..1b43961 100644
--- a/README.md
+++ b/README.md
@@ -54,22 +54,22 @@ go run examples/local_agent/main.go
### 2. Run Remote Agent with GAR Server
-This example demonstrates how the gar server triggers remote agents through the
-AgentService.Process RPC.
+This example demonstrates how the GAR server triggers remote agents through the `AgentService.Process` RPC. You can run this in two ways:
+
+#### [Option A] Client-Server Mode
+This is the standard way to run GAR, separating the controller from the trigger client.
**Terminal 1** - Start the remote agent server:
```bash
go run examples/remote_agent/main.go
```
+The remote agent runs as a gRPC server implementing `AgentService` on port `:50051`.
-The remote agent runs as a gRPC server implementing AgentService on port :50051.
-
-**Terminal 2** - Start the gar controller server:
+**Terminal 2** - Start the GAR controller server:
```bash
gar serve
```
-
-The gar server exposes the GARService on port :8494.
+The GAR server exposes the `GARService` on port `:8494`.
**Terminal 3** - Register the remote agent and trigger a session:
```bash
@@ -80,7 +80,7 @@ gar register \
--agent-description "Echoes input in uppercase" \
--agent-addr localhost:50051
-# Trigger a session - gar will trigger the remote agent via Process RPC
+# Trigger a session - gar will coordinate the remote agent via Process RPC
gar trigger \
--session session123 \
--input "Hello remote agent"
@@ -89,6 +89,26 @@ gar trigger \
gar inspect --session session123
```
+#### [Option B] Headless Mode (Simplified)
+Run everything in a single command. The trigger starts its own internal controller.
+
+**Terminal 1** - Start the remote agent server:
+```bash
+go run examples/remote_agent/main.go
+```
+(Same as Option A, the agent must be running to receive requests)
+
+**Terminal 2** - Trigger directly:
+```bash
+# Using default gar.yaml
+gar trigger --headless --input "Hello from headless mode"
+
+# Using a custom configuration
+gar trigger --headless --input "Hello" --config my-config.yaml
+
+```
+The `trigger` command starts its own internal controller, reads the specified configuration file (default: `gar.yaml`) to discover agents, and executes the session locally.
+
## Usage
### GAR CLI
@@ -112,6 +132,8 @@ Options:
- `--session`: Unique session identifier (optional, generates UUID if not provided, or resumes if exists)
- `--checkpoint`: Resume from specific checkpoint (empty for latest)
- `--server`: gRPC controller server address (default: "localhost:8494")
+- `--headless`: Run in headless mode with a built-in GAR server
+- `--config`: Path to YAML configuration file (only used in headless mode, default: "gar.yaml")
**Examples:**
@@ -126,6 +148,9 @@ gar trigger --session abc123 --input "Continue processing"
gar trigger --session abc123 \
--checkpoint "550e8400-e29b-41d4-a716-446655440000" \
--input "Try a different approach"
+
+# Trigger using headless mode (local controller)
+gar trigger --headless --input "Quick test to upper case"
```
#### Inspect a Session
diff --git a/cmd/gar/trigger.go b/cmd/gar/trigger.go
index 7cbdebf..183fdd1 100644
--- a/cmd/gar/trigger.go
+++ b/cmd/gar/trigger.go
@@ -22,6 +22,8 @@ import (
"os/signal"
"syscall"
+ "github.com/google/gar/agent"
+ "github.com/google/gar/internal/config"
"github.com/google/gar/proto"
"github.com/google/uuid"
"github.com/spf13/cobra"
@@ -32,6 +34,8 @@ var (
triggerInput string
triggerCheckpoint string
triggerServerAddr string
+ triggerHeadless bool
+ triggerConfigFile string
)
var triggerCmd = &cobra.Command{
@@ -44,13 +48,12 @@ Use --checkpoint to resume from a specific checkpoint.`,
}
func init() {
- // TODO(jbd): Enable a -headless option that can run
- // the controller without a gar server.
-
triggerCmd.Flags().StringVar(&triggerSessionID, "session", "", "Session ID (optional, generates UUID if not provided)")
triggerCmd.Flags().StringVar(&triggerInput, "input", "", "Input message to send (required)")
triggerCmd.Flags().StringVar(&triggerCheckpoint, "checkpoint", "", "Resume from specific checkpoint UUID (empty for latest)")
triggerCmd.Flags().StringVar(&triggerServerAddr, "server", "localhost:8494", "gRPC controller server address (default: localhost:8494)")
+ triggerCmd.Flags().BoolVar(&triggerHeadless, "headless", false, "Run in headless mode with a built-in Controller")
+ triggerCmd.Flags().StringVar(&triggerConfigFile, "config", "gar.yaml", "Path to YAML configuration file (only used in headless mode)")
triggerCmd.MarkFlagRequired("input")
}
@@ -88,6 +91,10 @@ func runTrigger(cmd *cobra.Command, args []string) error {
cancel()
}()
+ if triggerHeadless {
+ return runHeadless(ctx, triggerSessionID, inputs)
+ }
+
conn, err := connect(triggerServerAddr)
if err != nil {
return err
@@ -122,3 +129,44 @@ func runTrigger(cmd *cobra.Command, args []string) error {
}
return nil
}
+
+func runHeadless(ctx context.Context, sessionID string, inputs []*proto.Content) error {
+ // Load configuration from YAML file
+ cfg, err := config.LoadFromFile(triggerConfigFile)
+ if err != nil {
+ return fmt.Errorf("error loading config file '%s': %w", triggerConfigFile, err)
+ }
+
+ // Validate configuration
+ if err := cfg.Validate(); err != nil {
+ return fmt.Errorf("invalid configuration: %w", err)
+ }
+
+ c, err := newControllerFromConfig(ctx, cfg)
+ if err != nil {
+ return fmt.Errorf("error creating controller: %w", err)
+ }
+ defer c.Close()
+
+ // TODO(lhuan): Allow a default local agent to be registered in headless mode.
+
+ // Create output handler to print streaming results to stdout
+ outputHandler := agent.OutputHandler(func(resp *proto.ProcessResponse) error {
+ for _, content := range resp.Contents {
+ fmt.Printf("[RUNNING] %s\n", content.Data)
+ }
+ return nil
+ })
+
+ req := &proto.ProcessRequest{
+ Contents: inputs,
+ CheckpointId: triggerCheckpoint,
+ }
+
+ if err := c.TriggerSession(ctx, sessionID, req, outputHandler); err != nil {
+ return fmt.Errorf("error triggering session in headless mode: %w", err)
+ }
+
+ fmt.Println("[COMPLETED]")
+ return nil
+}
diff --git a/gar.yaml b/gar.yaml
index eac0d4a..b8a2ee7 100644
--- a/gar.yaml
+++ b/gar.yaml
@@ -57,7 +57,6 @@ health_check:
# Remote agents configuration (optional)
# List of remote agents to register on startup.
# Remote agents run as separate gRPC servers.
-#
# remote_agents:
# - id: "python-agent"
# name: "Python Agent"
diff --git a/internal/controller/registry.go b/internal/controller/registry.go
index 3ac5102..f58908b 100644
--- a/internal/controller/registry.go
+++ b/internal/controller/registry.go
@@ -120,7 +120,7 @@ func (r *Registry) RegisterRemote(cfg config.RemoteAgentConfig) error {
Name: cfg.Name,
Description: cfg.Description,
Type: AgentTypeRemote,
- Healthy: (r.monitor == nil), // Optimistic if no health check, pessimistic if health check is enabled
+ Healthy: true, // default to healthy with an assumption that the agent is healthy when it's registered.
LastHealthCheck: time.Time{},
Metadata: cfg.Metadata,
}
@@ -203,7 +203,6 @@ func (r *Registry) ListHealthy() []string {
return ids
}
-
// healthCheck performs a health check on a specific agent.
func (r *Registry) healthCheck(id string) error {
a, err := r.Get(id)
@@ -228,7 +227,6 @@ func (r *Registry) healthCheck(id string) error {
return err
}
-
// Close stops the registry and closes all agents.
func (r *Registry) Close() error {
// Stop health checks before acquiring the lock to avoid deadlock