Recap

In the first three articles of the "Agent Platform in Action" series, we step-by-step pushed the LINE AI Business Card Assistant (line-card-assistant) from a conceptual prototype to a cloud-native architecture:

[Agent Platform in Action (1)] Building a LINE AI Business Card Assistant with Go and Google ADK 2.0 Graph Workflow: We used google.golang.org/adk/v2/workflow to build a 12-node business card processing graph (Graph Workflow), covering Vision OCR, AddFanOut / AddFanIn parallel background investigations, and the HITL (Human-in-the-Loop) pause and modification loop of NewRequestInputEvent.
[Agent Platform in Action (2)] From Monolithic Cloud Run to Google Cloud Agent Runtime: Refactoring LINE AI Business Card Assistant with agents-cli and ADK Go: Completed Phase 1 (PR #10), introducing the agents-cli (adk_go) standard dual-channel architecture, allowing the project to support LINE Webhook, ADK WebUI Playground, and the A2A protocol simultaneously.
[Agent Platform in Action (3)] Solving HITL Amnesia in Stateless Containers: Implementing Cross-Instance Business Card Recognition and Pause/Resume with ADK 2.0 GCS Artifact Service and Agent Platform Sessions: Completed the first half of Phase 2 (PR #11), using artifact/gcsartifact to move multi-MB business card photos out of Session.State, and combining session/vertexai to implement resolvePendingHITL, allowing stateless containers to seamlessly continue HITL modification and saving even if scaled to 0 or instances are switched.

In today's fourth episode of the series, we will complete the final piece of Phase 2 (Issue #5) and the Phase 3 core architecture upgrade (Issue #6) (corresponding to PR #12):

Cloud Business Card Database Persistence (PostgresStore / Cloud SQL): Officially upgrading the business card library, which was originally stored in local memory or container temporary files, to a relational and JSON hybrid storage supporting Cloud SQL PostgreSQL, and enabling HybridSearch and token-scoring fault-tolerant BroadSearch.
Two-Tier Decoupled Call Architecture (Cloud Run LINE Webhook Gateway $\rightarrow$ Agent Runtime): Completely decoupling the lightweight edge layer (Edge Layer) responsible for "LINE verification and image downloading" from the execution layer (Execution Layer) responsible for "ADK 2.0 Graph Workflow multimodal inference and search"!

1. Why Do We Need the "Cloud Persistence Iron Triangle" and "Two-Tier Decoupled Architecture"?

When we deploy line-card-assistant to a Google Cloud production environment, a careful examination of the responsibilities of every piece of data and component in the system reveals two key problems that must be solved:

1. The Last Remaining "Local State": `CardStore` Business Card Database

In the previous post (PR #11), we already placed the "original business card photos" in Google Cloud Storage (GCSArtifactService) and the "workflow execution state and HITL breakpoints" in Vertex AI / Cloud SQL (SessionService). However, when a user clicks "✅ Confirm Save" in LINE and reaches SaveCardNode, if the final confirmed business card data (models.BusinessCard) is still written to local memory MemoryStore or a local SQLite file inside the container:

Cleared on container restart or Scale-to-Zero: Once the Agent Runtime instance scales to 0, the hard-earned network business card library will evaporate instantly.
Multiple instances cannot share search results: When a user saves a business card on Instance A, and a search request is routed to Instance B a second later, HybridSearchNode won't find the card just saved in Instance B's memory!

Therefore, we must complete the final corner of the "Cloud-Native Persistence Triad" — Cloud SQL PostgreSQL (PostgresStore):

Persistence Dimension	Content Responsible for Storing	Cloud Backend Service	ADK / Go Implementation Package
1. Binary Large Files (Artifacts)	Original business card photos (`business_card.jpg` v1, v2…)	Google Cloud Storage (GCS)	`sessions.NewArtifactService` (`artifact/gcsartifact`)
2. Conversation and Graph Breakpoints (Sessions)	Graph Checkpoints, `active_interrupt_id`, `draft_card`	Vertex AI Agent Engine / Cloud SQL	`sessions.NewService` (`session/vertexai`, `session/database`)
3. Structured Business Data (Domain DB)	Verified `BusinessCard` official records, JSON industry tags, hybrid retrieval	Cloud SQL for PostgreSQL	`store.NewStore` (`internal/store/postgres.go`)

2. Why Decouple LINE Webhook Gateway and Agent Runtime into a Two-Tier Architecture?

In monolithic (All-in-One) mode, cmd/server receives LINE Webhooks, runs Vision OCR, and executes three parallel Grounding search nodes in the same process. However, in an enterprise-grade Google Cloud Agent Platform architecture, splitting the system into "Cloud Run LINE Webhook Gateway (Edge Layer)" and "Google Cloud Agent Runtime (Agent Execution Layer)" offers three major advantages:

Isolation of Public Webhook Verification and Internal IAM Permissions:
- LINE Messaging API requires a public HTTPS Endpoint (POST /webhook) to push events, uses LINE_CHANNEL_SECRET to verify the X-Line-Signature, and must immediately return 200 OK within 1-2 seconds.
- Meanwhile, the actual Agent Runtime only needs internal authorization via Google Cloud IAM / Application Default Credentials (ADC), without needing exposure to unauthenticated public traffic or holding the LINE Channel Secret.
Multiple Channels Sharing the Same Session-backed Remote Agent:
- After decoupling, whether a user sends a business card photo from LINE Bot, queries contacts from internal Gemini Enterprise (A2A), or a developer tests from ADK WebUI, they all call the same app.NewRootAgent hosted on the Agent Runtime!
Extreme Deployment Flexibility (One-click switch between All-in-One vs. Decoupled):
- During local development or small projects, if AGENT_RUNTIME_URL is not set, cmd/server automatically runs in All-in-One monolithic mode.
- In production, simply setting AGENT_RUNTIME_URL=https://... in Cloud Run automatically switches cmd/server to a lightweight stateless LINE Webhook Gateway!

Let's look at the cross-layer interaction under the two-tier decoupled architecture with a complete system sequence diagram:

sequenceDiagram
    autonumber
    actor User as LINE User
    participant GW as Cloud Run<br/>LINE Webhook Gateway<br/>(cmd/server + gateway.Client)
    participant AR as Google Cloud Agent Runtime<br/>(adkrest.Server / app.NewRootAgent)
    participant GCS as Cloud Storage<br/>(GCSArtifactService)
    participant Sess as Vertex AI / Cloud SQL<br/>(SessionService)
    participant PG as Cloud SQL PostgreSQL<br/>(PostgresStore)

    User->>GW: 1. Send business card photo (POST /webhook)
    GW-->>User: 2. Verify X-Line-Signature and immediately return HTTP 200 OK
    GW->>GW: 3. Download image from LINE Blob API []byte
    GW->>AR: 4. POST /api/apps/app/users/{user}/sessions/{id}<br/>+ POST /api/run (With Google Cloud ADC ID Token and image InlineData)
    AR->>GCS: 5. RouterNode automatically saves image to GCS Artifact ("business_card.jpg" v1)
    AR->>AR: 6. VisionOCRNode -> AddFanOut (Deduplication / Google Search company background / Conversation context) -> BuildPreviewNode
    AR->>Sess: 7. HITLConfirmNode triggers NewRequestInputEvent<br/>Persist active_interrupt_id="hitl_confirm_1"
    AR-->>GW: 8. Return Events and Session State (including flex_preview_json)
    GW-->>User: 9. Push LINE Flex Message business card preview card (⏸️ Waiting for user confirmation)

    Note over GW,AR: ☁️ Gateway is completely stateless; the next request can land on any Gateway instance

    User->>GW: 10. Input modification: "Change title to CTO" or click "✅ Confirm Save"
    GW->>AR: 11. HasPendingHITL -> GET /api/apps/app/users/{user}/sessions<br/>Automatically retrieve remote paused {SessionID, active_interrupt_id}
    GW->>AR: 12. POST /api/run (Send adk_request_input FunctionResponse)
    AR->>PG: 13. If confirming save: SaveCardNode calls PostgresStore.Save() Upsert to write to Cloud SQL
    AR->>Sess: 14. Clear active_interrupt_id="" and record saved_card_id
    AR-->>GW: 15. Return save success and AI icebreaker follow-up draft
    GW-->>User: 16. Push save confirmation and icebreaker to user!

2. Implementation Breakdown (1): Building the Cloud SQL PostgreSQL Business Card Library (`internal/store/postgres.go`) — Issue #5

In our project, since sessions/sessions.go already introduced gorm.io/gorm and gorm.io/driver/postgres to support SESSION_TYPE=cloud_sql, we can directly use GORM to build a production-grade PostgresStore for CardStore without extra dependency bloat!

1. Extending the `store.CardStore` Interface: Native `BroadSearch` Support for All Backends

While checking the original internal/workflow/nodes_search.go, we found a type assertion for *store.MemoryStore in BroadSearchNode:

// ❌ Old way: Only MemoryStore supports BroadSearch; other Stores fall back to ListByUser
if memStore, ok := cardStore.(*store.MemoryStore); ok {
    cards, err = memStore.BroadSearch(ctx, userID, keywords)
} else {
    cards, err = cardStore.ListByUser(ctx, userID)
}

To ensure PostgresStore and MemoryStore share a consistent hybrid retrieval and fuzzy fallback experience, we officially included BroadSearch in the CardStore standard interface in internal/store/store.go:

// CardStore defines the persistence and search interface for business cards.
type CardStore interface {
    Save(ctx context.Context, card *models.BusinessCard) error
    GetByID(ctx context.Context, id string) (*models.BusinessCard, error)
    CheckDuplicate(ctx context.Context, userID, name, company, email string) (*models.BusinessCard, bool, error)
    HybridSearch(ctx context.Context, filter models.SearchFilter) ([]*models.BusinessCard, error)
    BroadSearch(ctx context.Context, userID string, keywords []string) ([]*models.BusinessCard, error)
    ListByUser(ctx context.Context, userID string) ([]*models.BusinessCard, error)
}

This way, BroadSearchNode only needs to cleanly call one line: cardStore.BroadSearch(ctx, userID, keywords)!

2. Designing GORM Schema and Upsert Mechanism (`BusinessCardRecord`)

In internal/store/postgres.go, we defined BusinessCardRecord corresponding to the PostgreSQL business_cards table, added indexes to common query fields (user_id, name, company, email, met_date, updated_at), and stored Tags []string as a JSON string in tags_json:

// BusinessCardRecord is the GORM database model for persisting a models.BusinessCard
// in PostgreSQL / Cloud SQL.
type BusinessCardRecord struct {
    ID string `gorm:"primaryKey;size:128"`
    UserID string `gorm:"index;size:128;not null"`
    Name string `gorm:"index;size:255"`
    Title string `gorm:"size:255"`
    Company string `gorm:"index;size:255"`
    Email string `gorm:"index;size:255"`
    Phone string `gorm:"size:64"`
    Address string `gorm:"type:text"`
    TaxID string `gorm:"size:32"`
    Website string `gorm:"size:512"`
    RawOCR string `gorm:"type:text"`
    CompanySummary string `gorm:"type:text"`
    CompanyInfo string `gorm:"type:text"`
    TagsJSON string `gorm:"column:tags_json;type:text"`
    MetContext string `gorm:"type:text"`
    RawImageURL string `gorm:"type:text"`
    MetDate time.Time `gorm:"index"`
    CreatedAt time.Time `gorm:"index"`
    UpdatedAt time.Time `gorm:"index"`
}

When a user takes a photo of an existing contact's business card (e.g., the person was promoted from "Senior Engineer" to "VP of Engineering", and CleanAndDedupNode identifies the duplicate and reuses the original card.ID), PostgresStore.Save performs an atomic Upsert using PostgreSQL's native ON CONFLICT (id) DO UPDATE (clause.OnConflict{UpdateAll: true}):

if err := s.db.WithContext(ctx).Clauses(clause.OnConflict{
    Columns: []clause.Column,
    UpdateAll: true,
}).Create(rec).Error; err != nil {
    return fmt.Errorf("upsert business card %q: %w", cp.ID, err)
}

3. The `store.NewStore(ctx)` Factory: Auto-sensing Cloud SQL Unix Sockets and Environment Variables

When connecting to Cloud SQL from Cloud Run or Agent Runtime, the official recommendation is to use the Unix Domain Socket (/cloudsql/<PROJECT>:<REGION>:<INSTANCE>) established by the Cloud SQL Auth Proxy; locally or on GKE, DATABASE_URL or DB_HOST are common. We support all three modes in BuildPostgresDSNFromEnv() and store.NewStore(ctx), and automatically fall back seamlessly to MemoryStore preloaded with 4 Taiwan sample business cards when no database environment variables are set:

// BuildPostgresDSNFromEnv resolves a PostgreSQL / Cloud SQL connection string from environment variables.
// Priority:
// 1. CARD_STORE_DSN / DATABASE_URL / POSTGRES_DSN
// 2. Cloud SQL Unix socket when INSTANCE_CONNECTION_NAME + DB_PASS are set
// 3. Standard TCP host when DB_HOST + DB_PASS are set
func BuildPostgresDSNFromEnv() string {
    for _, key := range []string{"CARD_STORE_DSN", "DATABASE_URL", "POSTGRES_DSN"} {
        if v := strings.TrimSpace(os.Getenv(key)); v != "" {
            return v
        }
    }

    dbUser := envOrDefault("DB_USER", "postgres")
    dbName := envOrDefault("DB_NAME", "postgres")
    dbPass := strings.TrimSpace(os.Getenv("DB_PASS"))
    instanceConn := strings.TrimSpace(os.Getenv("INSTANCE_CONNECTION_NAME"))
    if instanceConn != "" && dbPass != "" {
        return fmt.Sprintf(
            "host=/cloudsql/%s user=%s password=%s dbname=%s sslmode=disable",
            instanceConn, dbUser, dbPass, dbName,
        )
    }
    // ...
}

This way, as long as your environment has INSTANCE_CONNECTION_NAME and DB_PASS set for SESSION_TYPE=cloud_sql, SessionService and CardStore can share the same Cloud SQL PostgreSQL instance, without spending an extra penny on database costs!

3. Implementation Breakdown (2): Building a Stateless LINE Webhook Gateway and Remote `AgentRuntimeClient` (`internal/gateway/client.go`) — Issue #6

Next is the core engineering of Phase 3: How to make the cmd/server LINE Bot Webhook Handler forward all business card recognition, HITL recovery, search, and icebreaker requests to a remote Agent Runtime via HTTP instead of running workflow.Engine locally?

Remember how we had the foresight to separate the Webhook Handler and Workflow Engine with a linebot.WorkflowRunner interface in the first version of internal/linebot/handler.go?

// internal/linebot/handler.go
type WorkflowRunner interface {
    HasPendingHITL(userID string) bool
    RecordUserMessage(userID, text string)
    StartIngest(ctx context.Context, userID string, imageBytes []byte, recentMessages []string) (*WorkflowResponse, error)
    ResumeHITL(ctx context.Context, userID string, userReply string) (*WorkflowResponse, error)
    RunSearch(ctx context.Context, userID string, query string) (*WorkflowResponse, error)
    RunEmailDraft(ctx context.Context, userID string, cardID string) (*WorkflowResponse, error)
}

Because of this clean interface, we don't need to change a single line of code in linebot.Handler! We just need to implement a gateway.Client that satisfies the linebot.WorkflowRunner interface in internal/gateway/client.go!

1. `gateway.NewClient` Supporting Automatic Google Cloud ADC Token Issuance

When the LINE Webhook Gateway on Cloud Run needs to call an IAM-protected remote Agent Runtime (or another ADK REST Server on an internal Cloud Run), gateway.NewClient automatically obtains the current Service Account's Google Cloud ADC credentials via google.golang.org/api/idtoken (or golang.org/x/oauth2/google) and attaches them to the Authorization: Bearer <token> header of every HTTP request:

func NewClient(ctx context.Context, baseURL string, useADC bool, opts ...ClientOption) (*Client, error) {
    trimmed := strings.TrimRight(strings.TrimSpace(baseURL), "/")
    if trimmed == "" {
        return nil, fmt.Errorf("agent runtime baseURL cannot be empty")
    }
    if !strings.HasSuffix(trimmed, "/api") {
        trimmed += "/api"
    }

    hc := &http.Client{Timeout: 60 * time.Second}
    if useADC {
        if idClient, err := idtoken.NewClient(ctx, strings.TrimSuffix(trimmed, "/api")); err == nil {
            hc = idClient
        } else if oauthClient, err := google.DefaultClient(ctx, "https://www.googleapis.com/auth/cloud-platform"); err == nil {
            hc = oauthClient
        }
    }
    // ...
}

2. Cross-Layer Image Forwarding: Gateway Downloads Image $\rightarrow$ Agent Runtime Automatically Writes to GCS Artifact

When a user uploads a business card photo on LINE:

Gateway downloads imageBytes from LINE Blob API.
gateway.Client.StartIngest calls the remote ADK REST API POST /api/apps/{appName}/users/{userID}/sessions/{sessionID} to create a session.
Then it calls POST /api/run, wrapping imageBytes in the InlineData of newMessage.Parts to send to the remote Agent Runtime:

func (c *Client) StartIngest(ctx context.Context, userID string, imageBytes []byte, recentMessages []string) (*linebot.WorkflowResponse, error) {
    sessionID := "ingest-" + uuid.NewString()
    initialState := map[string]any{
        workflow.StateKeyInputType: workflow.RouteIngest,
        workflow.StateKeyUserID: userID,
        workflow.StateKeyRecentMessages: recentMessages,
    }
    if err := c.createSession(ctx, userID, sessionID, initialState); err != nil {
        return nil, err
    }

    parts := []*genai.Part{
        {Text: workflow.RouteIngest},
    }
    if len(imageBytes) > 0 {
        parts = append(parts, &genai.Part{
            InlineData: &genai.Blob{
                MIMEType: "image/jpeg",
                Data: imageBytes,
            },
        })
    }
    msg := &genai.Content{
        Role: genai.RoleUser,
        Parts: parts,
    }

    res, err := c.runTurn(ctx, userID, sessionID, msg, initialState)
    // ...
}

At this point, the logic we wrote for RouterNode in Phase 2 works like magic: when the remote Agent Runtime's RouterNode receives this request with InlineData, it automatically calls ctx.Artifacts().Save(ctx, "business_card.jpg", ...) to store the image in the GCS Artifact Bucket, leaving only lightweight card_image_artifact and card_image_version in Session.State! This means the LINE Webhook Gateway doesn't even need direct write permissions to the GCS Bucket for the remote Agent Runtime to complete versioned GCS Artifact archiving!

3. Cross-Layer Stateless HITL Breakpoint Discovery and Recovery (`resolvePendingHITL` + `ResumeHITL`)

The most exciting part: when a user sees the LINE Flex preview card and inputs "Change title to CTO" 5 minutes later, and this Webhook request lands on another completely new Cloud Run Gateway instance, how does gateway.Client know this user has a pending HITL Session on the remote Agent Runtime?

We use the GET /api/apps/{appName}/users/{userID}/sessions endpoint via the ADK REST API in gateway.Client.resolvePendingHITL to query the remote Agent Runtime for the user's session status and check state["active_interrupt_id"]:

func (c *Client) resolvePendingHITL(ctx context.Context, userID string) (pendingHITL, bool) {
    // 1. If local cache has SessionID, call remote GET /sessions/{id} to get the latest active_interrupt_id
    // (Important! Because after each Edit loop, hitl_seq increments to hitl_confirm_2, hitl_confirm_3...)
    c.mu.RLock()
    cached, hasCached := c.pendingSession[userID]
    c.mu.RUnlock()
    if hasCached && cached.SessionID != "" {
        if fullSess, err := c.getSession(ctx, userID, cached.SessionID); err == nil && fullSess != nil {
            if activeID := readStringFromMap(fullSess.State, workflow.StateKeyActiveInterruptID); activeID != "" {
                found := pendingHITL{SessionID: cached.SessionID, InterruptID: activeID}
                c.mu.Lock()
                c.pendingSession[userID] = found
                c.mu.Unlock()
                return found, true
            }
        }
    }

    // 2. If this is a brand-new stateless Gateway instance, call remote GET /sessions to find sessions with active_interrupt_id
    sessions, err := c.listSessions(ctx, userID)
    if err != nil {
        return pendingHITL{}, false
    }
    for _, sess := range sessions {
        activeID := readStringFromMap(sess.State, workflow.StateKeyActiveInterruptID)
        if activeID == "" && sess.ID != "" {
            if fullSess, err := c.getSession(ctx, userID, sess.ID); err == nil && fullSess != nil {
                activeID = readStringFromMap(fullSess.State, workflow.StateKeyActiveInterruptID)
            }
        }
        if activeID != "" {
            found := pendingHITL{SessionID: sess.ID, InterruptID: activeID}
            c.mu.Lock()
            c.pendingSession[userID] = found
            c.mu.Unlock()
            return found, true
        }
    }
    return pendingHITL{}, false
}

Here is a real bug and key detail we caught while writing integration tests:

When the user uploads a business card in Turn 1, the first breakpoint ID generated by HITLConfirmNode is hitl_confirm_1.
When the user inputs "Change title to CTO" in Turn 2 (possibly handled by Gateway Instance 2), ApplyEditNode modifies the title and loops back to HITLConfirmNode to pause again, incrementing the breakpoint ID to hitl_confirm_2!
If Turn 3 (user clicks "✅ Confirm Save") happens to go back to Gateway Instance 1, and Instance 1 blindly trusts its old local cache (hitl_confirm_1), the sent FunctionResponse won't match the latest breakpoint hitl_confirm_2!
Therefore, in resolvePendingHITL, we ensure that even if the local cache hits a SessionID, it synchronizes the latest active_interrupt_id from the remote via getSession. This way, no matter how many times the request jumps between Gateway instances or how many fields are modified, it always aligns perfectly with the latest InterruptID!

4. `cmd/server/main.go`: Seamless Switching Between Monolithic and Two-Tier Gateway Modes

Finally, we added mode detection in cmd/server/main.go:

    var runner linebot.WorkflowRunner
    if cfg.AgentRuntimeURL != "" {
        // 🌐 Mode A: Decoupled Two-Tier LINE Webhook Gateway Mode (Forwarding to remote Agent Runtime)
        gwClient, err := gateway.NewClient(
            ctx,
            cfg.AgentRuntimeURL,
            cfg.AgentRuntimeUseADC,
            gateway.WithAppName(cfg.AgentRuntimeAppName),
        )
        if err != nil {
            slog.Error("failed to initialize remote Agent Runtime gateway client", "url", cfg.AgentRuntimeURL, "err", err)
            os.Exit(1)
        }
        slog.Info("running in decoupled LINE Webhook Gateway mode",
            "agent_runtime_url", cfg.AgentRuntimeURL,
            "agent_runtime_app", cfg.AgentRuntimeAppName,
            "use_adc", cfg.AgentRuntimeUseADC,
        )
        runner = gwClient
    } else {
        // 🚀 Mode B: All-in-One Local Engine Mode (Default for local development and single container deployment)
        cardStore, err := store.NewStore(ctx)
        // ... Initialize local workflow.NewEngine ...
        runner = engine.LinebotRunner()
    }

    botHandler, err := linebot.NewHandler(cfg, runner)

4. End-to-End Two-Tier Architecture Integration Testing (`internal/gateway/client_test.go`)

To ensure gateway.Client is 100% compatible with the official ADK Go v2.6.0 server/adkrest REST server, we started a real adkrest.NewServer (mounting our app.NewRootAgentWithDeps) using httptest.NewServer in internal/gateway/client_test.go and established two completely independent Gateway Clients (client1 and client2) for a five-stage end-to-end test:

Turn 1 (client1.StartIngest): Upload business card photo via HTTP $\rightarrow$ Verify remote ArtifactService successfully writes business_card.jpg $\rightarrow$ Verify return of WaitingHITL=true (hitl_confirm_1) and LINE Flex Preview JSON containing "Wang Daming".
Cross-Instance State Probing (client2.HasPendingHITL): The brand-new stateless client2 probes the paused session created by client1 via GET /api/apps/app/users/{user}/sessions.
Turn 2 (client2.ResumeHITL — Natural Language Modification): client2 sends "Change title to CTO" $\rightarrow$ Verify remote execution of ApplyEditNode, updating DraftCard.Title == "CTO", and pausing again at hitl_confirm_2.
Turn 3 (client1.ResumeHITL — Confirm Save): Switch back to client1 and send "action=confirm_save" $\rightarrow$ client1 automatically synchronizes the latest breakpoint hitl_confirm_2 and wakes up SaveCardNode $\rightarrow$ Verify business card successfully written to remote CardStore and returns AI icebreaker.
Turn 4 & Turn 5 (client2.RunSearch & client2.RunEmailDraft): Call remote hybrid search and individual icebreaker drafting via HTTP, verifying return of Flex Carousel JSON and icebreaker content.

Running the full test suite:

$ go test -race -v ./...
=== RUN TestGatewayClient_EndToEndDecoupledIngestHITLAndSearch
--- PASS: TestGatewayClient_EndToEndDecoupledIngestHITLAndSearch (0.01s)
=== RUN TestBusinessCardRecordRoundTrip
--- PASS: TestBusinessCardRecordRoundTrip (0.00s)
=== RUN TestBuildPostgresDSNFromEnv
--- PASS: TestBuildPostgresDSNFromEnv (0.00s)
=== RUN TestNewStoreFactoryFallback
--- PASS: TestNewStoreFactoryFallback (0.00s)
=== RUN TestRankCardsByKeywords
--- PASS: TestRankCardsByKeywords (0.00s)
PASS

All unit tests and cross-layer integration tests passed with green lights under -race detector!

5. Summary and Roadmap Progress Check

After completing PR #12, looking back at the five stages of Roadmap Issue #9, Phase 1, Phase 2, and Phase 3 are now 100% complete!

Phase 1 (agents-cli & adk_go Scaffolding): Completed Issues #1, #2 (PR #10)
Phase 2 (Agent Runtime Adaptation and Cloud Persistence Iron Triangle): Completed Issues #3, #4 (PR #11) and Issue #5 (PR #12)
Phase 3 (LINE Webhook Gateway and Agent Runtime Two-Tier Decoupled Architecture): Completed Issue #6 (PR #12)
Phase 4 (agents-cli eval Automated Evaluation and Benchmarking): Issue #7
Phase 5 (Agent Runtime Official Deployment, Terraform IaC, and Cloud Trace Observability): Issue #8

In the upcoming articles of this series, we will enter Phase 4 and Phase 5, using agents-cli eval to establish a Quality Flywheel for this 12-node Graph Workflow, and officially deploy the entire system using agents-cli deploy and OpenTelemetry. Stay tuned!

Resources and Further Reading

"Agent Platform in Action" Series Articles:
Project Open Source Code and PRs:
- GitHub Repository: kkdai/line-card-assistant
- Phase 2 & 3 Implementation Pull Request: PR #12: feat(phase2-3): Cloud SQL PostgresStore (#5) & Decoupled LINE Webhook Gateway (#6)
- Completed Issues: Issue #5, Issue #6, Roadmap #9
Google ADK and Agent Platform Official Documentation:
- ADK Documentation (llms.txt)
- Getting Started - agents-cli

[Agent Platform in Practice (4)] Towards Cloud Two-layer Decoupling and Full Persistence: Completing the LINE AI Business Card M

Recap

1. Why Do We Need the "Cloud Persistence Iron Triangle" and "Two-Tier Decoupled Architecture"?

1. The Last Remaining "Local State": `CardStore` Business Card Database

2. Why Decouple LINE Webhook Gateway and Agent Runtime into a Two-Tier Architecture?

2. Implementation Breakdown (1): Building the Cloud SQL PostgreSQL Business Card Library (`internal/store/postgres.go`) — Issue #5

1. Extending the `store.CardStore` Interface: Native `BroadSearch` Support for All Backends

2. Designing GORM Schema and Upsert Mechanism (`BusinessCardRecord`)

3. The `store.NewStore(ctx)` Factory: Auto-sensing Cloud SQL Unix Sockets and Environment Variables

3. Implementation Breakdown (2): Building a Stateless LINE Webhook Gateway and Remote `AgentRuntimeClient` (`internal/gateway/client.go`) — Issue #6

1. `gateway.NewClient` Supporting Automatic Google Cloud ADC Token Issuance

2. Cross-Layer Image Forwarding: Gateway Downloads Image $\rightarrow$ Agent Runtime Automatically Writes to GCS Artifact

3. Cross-Layer Stateless HITL Breakpoint Discovery and Recovery (`resolvePendingHITL` + `ResumeHITL`)

4. `cmd/server/main.go`: Seamless Switching Between Monolithic and Two-Tier Gateway Modes

4. End-to-End Two-Tier Architecture Integration Testing (`internal/gateway/client_test.go`)

5. Summary and Roadmap Progress Check

Resources and Further Reading

Tags

Author

Stats

Published

You Might Also Like

My Agent Turned "I Haven't Decided" Into "Not Yet." Now the Model Isn't Allowed to Write Its Own Memory.

State of AI Instruction Quality: Files With Persona Lines Score Lower

Building a Multi-Agent Token Usage Widget in Under 500 KB

One Dev, Four Specialists: My Agent Team for OpenCode 🧑‍💻

The Agentic Manifesto: What Should the Agile Manifesto Look Like in the Age of AI?

On-Behalf-Of Is a Pattern. Token Exchange Is the Standard.

[Agent Platform in Practice (4)] Towards Cloud Two-layer Decoupling and Full Persistence: Completing the LINE AI Business Card M

Recap

1. Why Do We Need the "Cloud Persistence Iron Triangle" and "Two-Tier Decoupled Architecture"?

1. The Last Remaining "Local State": CardStore Business Card Database

2. Why Decouple LINE Webhook Gateway and Agent Runtime into a Two-Tier Architecture?

2. Implementation Breakdown (1): Building the Cloud SQL PostgreSQL Business Card Library (internal/store/postgres.go) — Issue #5

1. Extending the store.CardStore Interface: Native BroadSearch Support for All Backends

2. Designing GORM Schema and Upsert Mechanism (BusinessCardRecord)

3. The store.NewStore(ctx) Factory: Auto-sensing Cloud SQL Unix Sockets and Environment Variables

3. Implementation Breakdown (2): Building a Stateless LINE Webhook Gateway and Remote AgentRuntimeClient (internal/gateway/client.go) — Issue #6

1. gateway.NewClient Supporting Automatic Google Cloud ADC Token Issuance

2. Cross-Layer Image Forwarding: Gateway Downloads Image $\rightarrow$ Agent Runtime Automatically Writes to GCS Artifact

3. Cross-Layer Stateless HITL Breakpoint Discovery and Recovery (resolvePendingHITL + ResumeHITL)

4. cmd/server/main.go: Seamless Switching Between Monolithic and Two-Tier Gateway Modes

4. End-to-End Two-Tier Architecture Integration Testing (internal/gateway/client_test.go)

5. Summary and Roadmap Progress Check

Resources and Further Reading

Tags

Author

Stats

Published

You Might Also Like

My Agent Turned "I Haven't Decided" Into "Not Yet." Now the Model Isn't Allowed to Write Its Own Memory.

State of AI Instruction Quality: Files With Persona Lines Score Lower

Building a Multi-Agent Token Usage Widget in Under 500 KB

One Dev, Four Specialists: My Agent Team for OpenCode 🧑‍💻

The Agentic Manifesto: What Should the Agile Manifesto Look Like in the Age of AI?

On-Behalf-Of Is a Pattern. Token Exchange Is the Standard.

1. The Last Remaining "Local State": `CardStore` Business Card Database

2. Implementation Breakdown (1): Building the Cloud SQL PostgreSQL Business Card Library (`internal/store/postgres.go`) — Issue #5

1. Extending the `store.CardStore` Interface: Native `BroadSearch` Support for All Backends

2. Designing GORM Schema and Upsert Mechanism (`BusinessCardRecord`)

3. The `store.NewStore(ctx)` Factory: Auto-sensing Cloud SQL Unix Sockets and Environment Variables

3. Implementation Breakdown (2): Building a Stateless LINE Webhook Gateway and Remote `AgentRuntimeClient` (`internal/gateway/client.go`) — Issue #6

1. `gateway.NewClient` Supporting Automatic Google Cloud ADC Token Issuance

3. Cross-Layer Stateless HITL Breakpoint Discovery and Recovery (`resolvePendingHITL` + `ResumeHITL`)

4. `cmd/server/main.go`: Seamless Switching Between Monolithic and Two-Tier Gateway Modes

4. End-to-End Two-Tier Architecture Integration Testing (`internal/gateway/client_test.go`)