interactions

README

Cloud Interactions SDK for Go

An unofficial Go SDK for the Google Cloud Vertex AI Interactions & Managed Agents API.

cloud-interactions-go provides a lightweight, dependency-free Go client for interacting with Gemini, Lyria 3, and Managed Agents via Google's Vertex AI Interactions REST API surface. Supports real-time SSE streaming, asynchronous background task polling, flat multimodal payload decoding, and diagnostic tracing headers.

---

Table of Contents

• Features
• Installation
• Quickstart
  • 1. Real-Time SSE Streaming
  • 2. Synchronous Media Generation & Header Decoding
• Examples & Documentation
• Local Development Setup
• Release Process
• Contributing
• License

---

Features

• Real-time SSE Streaming: High-performance scanner with buffer support up to 128MB for large base64 multimodal chunks.
• Flat & Nested Payload Decoding: Native support for flat media outputs (Content.Data, Content.MimeType) and nested part trees (Content.Content[]).
• Diagnostic Tracing: Captures Google Sherlog tracing links (x-goog-sherlog-link) and full HTTP response headers on every call.
• Asynchronous Background Tasks: Built-in polling helper (WaitForCompletion) for long-running models like gemini-omni-flash-preview.
• Zero Mandatory Dependencies: Built using only the Go standard library (net/http, encoding/json).

---

Installation

go get github.com/ghchinoy/cloud-interactions-go

Requires Go 1.23+.

---

Quickstart

1. Real-Time SSE Streaming

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/ghchinoy/cloud-interactions-go"
)

func main() {
	ctx := context.Background()
	baseURL := "https://aiplatform.googleapis.com/v1beta1/projects/my-project/locations/global/interactions"

	client := interactions.NewClient(baseURL).
		WithBearerToken("YOUR_ACCESS_TOKEN").
		WithUserProject("my-project")

	req := &interactions.InteractionRequest{
		Model:  "gemini-2.5-flash",
		Stream: true,
		Input: []interactions.Content{
			{
				Type: "user_input",
				Content: []interactions.Part{
					{Type: "text", Text: "Explain quantum computing in one short sentence."},
				},
			},
		},
	}

	err := client.StreamCreate(ctx, req, func(event, data string) error {
		fmt.Printf("Event: %-15s | Size: %d bytes\n", event, len(data))
		return nil
	})
	if err != nil {
		log.Fatalf("Stream failed: %v", err)
	}
}

2. Synchronous Media Generation & Header Decoding

// Create interaction turn and extract flat media output + Sherlog link
resp, err := client.Create(ctx, &interactions.InteractionRequest{
	Model: "lyria-3-clip-preview",
	Input: []interactions.Content{
		{Type: "text", Text: "An upbeat synthwave instrumental track"},
	},
})
if err != nil {
	log.Fatal(err)
}

fmt.Println("Sherlog Trace Link:", resp.SherlogLink)

for _, out := range resp.Outputs {
	if out.Data != "" {
		fmt.Printf("Generated flat media payload [%s]: %d base64 chars\n", out.MimeType, len(out.Data))
	}
}

---

Examples & Documentation

• Detailed User Guide: Deep dive on authentication, endpoint routing, API revisions, background execution, and model conventions.
• Runnable Examples:
  • examples/lyria-music: Synchronous music track generation using lyria-3-clip-preview.
  • examples/video-omni: Asynchronous text-to-video generation using gemini-omni-flash-preview.

---

Local Development Setup

To clone the repository and run tests locally:

# Clone the repository
git clone https://github.com/ghchinoy/cloud-interactions-go.git
cd cloud-interactions-go

# Run unit tests
go test -v ./...

# Verify formatting and linting
go vet ./...

---

Release Process

Releases are published via SemVer Git tags. Maintainers create and push signed tags:

git tag -a v0.2.0 -m "v0.2.0: support flat media outputs and expose response headers"
git push origin v0.2.0

---

Contributing

Pull requests are welcome! For major feature additions or schema changes, please open an issue first to discuss your proposal.

Ensure all unit tests pass before submitting a pull request:

go test -v ./...

---

License

Distributed under the Apache 2.0 License.

Documentation

Index

• Constants
• type AllowlistEntry
• type Blob
• type Client
  • func NewClient(baseURL string) *Client
  • func (c *Client) Create(ctx context.Context, req *InteractionRequest) (*InteractionResponse, error)
  • func (c *Client) Delete(ctx context.Context, id string) error
  • func (c *Client) Get(ctx context.Context, id string) (*InteractionResponse, error)
  • func (c *Client) StreamCreate(ctx context.Context, req *InteractionRequest, ...) error
  • func (c *Client) WaitForCompletion(ctx context.Context, id string, interval time.Duration) (*InteractionResponse, error)
  • func (c *Client) WithAPIKey(key string) *Client
  • func (c *Client) WithAPIRevision(revision string) *Client
  • func (c *Client) WithBearerToken(token string) *Client
  • func (c *Client) WithUserProject(projectID string) *Client
• type CodeExecutionCallContent
• type CodeExecutionResultContent
• type CodeExecutionTool
• type Content
• type Environment
  • func (e Environment) MarshalJSON() ([]byte, error)
  • func (e *Environment) UnmarshalJSON(data []byte) error
• type Error
• type File
• type FileSearchCallContent
• type FileSearchResultContent
• type FunctionCall
• type FunctionDeclaration
• type FunctionResponse
• type GenerationConfig
• type GoogleMapsCallContent
• type GoogleMapsResultContent
• type GoogleSearchCallContent
• type GoogleSearchResultContent
• type GoogleSearchTool
• type ImageConfig
• type InteractionRequest
  • func (r *InteractionRequest) MarshalJSON() ([]byte, error)
• type InteractionResponse
• type MCPServerToolCallContent
• type MCPServerToolResultContent
• type ModalityTokenCount
• type NetworkConf
• type Part
• type Role
• type Source
• type ThoughtContent
• type Tool
• type ToolCall
• type ToolResult
• type URLContextCallContent
• type URLContextResultContent
• type Usage
• type WebhookConfig

Constants

const DefaultAPIRevision = "2026-05-20"

DefaultAPIRevision is the pinned Interactions API revision sent via the "Api-Revision" header. This matches the production REST examples and guards against breaking schema drift on the Pre-GA surface.

Types

type AllowlistEntry

type AllowlistEntry struct {
	Domain string `json:"domain"`
}

type Blob

type Blob struct {
	MimeType string `json:"mime_type"`
	Data     string `json:"data"` // Base64 encoded
}

Blob represents inline binary data.

type Client

type Client struct {
	APIKey      string
	BearerToken string
	UserProject string
	APIRevision string
	BaseURL     string
	HTTPClient  *http.Client
}

Client is a Go wrapper for the Gemini/Vertex Interactions REST API.

func NewClient

func NewClient(baseURL string) *Client

NewClient creates a new Interactions API client.

func (*Client) Create

func (c *Client) Create(ctx context.Context, req *InteractionRequest) (*InteractionResponse, error)

Create initiates a new interaction turn.

func (*Client) Delete

func (c *Client) Delete(ctx context.Context, id string) error

Delete removes a stored interaction.

func (*Client) Get

func (c *Client) Get(ctx context.Context, id string) (*InteractionResponse, error)

Get retrieves the status and result of an existing interaction.

func (*Client) StreamCreate

func (c *Client) StreamCreate(ctx context.Context, req *InteractionRequest, onEvent func(event, data string) error) error

StreamCreate initiates a new interaction turn and streams back Server-Sent Events.

func (*Client) WaitForCompletion

func (c *Client) WaitForCompletion(ctx context.Context, id string, interval time.Duration) (*InteractionResponse, error)

WaitForCompletion polls an interaction until its status is a terminal state.

func (*Client) WithAPIKey

func (c *Client) WithAPIKey(key string) *Client

WithAPIKey sets an API key.

func (*Client) WithAPIRevision

func (c *Client) WithAPIRevision(revision string) *Client

WithAPIRevision overrides the pinned Api-Revision header value. Pass an empty string to omit the header entirely.

func (*Client) WithBearerToken

func (c *Client) WithBearerToken(token string) *Client

WithBearerToken sets a Bearer token (e.g. from gcloud auth).

func (*Client) WithUserProject

func (c *Client) WithUserProject(projectID string) *Client

WithUserProject sets the Google Cloud Project ID to use for the x-goog-user-project header.

type CodeExecutionCallContent

type CodeExecutionCallContent struct {
	ID        string `json:"id,omitempty"`
	Type      string `json:"type,omitempty"`
	Arguments any    `json:"arguments,omitempty"`
	Signature string `json:"signature,omitempty"`
}

type CodeExecutionResultContent

type CodeExecutionResultContent struct {
	ID      string `json:"id,omitempty"`
	Type    string `json:"type,omitempty"`
	Output  string `json:"output,omitempty"`
	Outcome string `json:"outcome,omitempty"`
}

type CodeExecutionTool

type CodeExecutionTool struct{}

CodeExecutionTool enables the built-in Code Execution tool.

type Content

type Content struct {
	Type     string `json:"type,omitempty"` // e.g. "user_input" or "model_output"
	Content  []Part `json:"content,omitempty"`
	Text     string `json:"text,omitempty"`      // Interactions API often flattens text here
	MimeType string `json:"mime_type,omitempty"` // flat media (e.g. Lyria audio)
	Data     string `json:"data,omitempty"`      // base64 payload for flat outputs
}

Content represents a single turn in an interaction, containing the role and the actual data (parts or text).

type Environment

type Environment struct {
	EnvID   string       `json:"env_id,omitzero"`
	Type    string       `json:"type,omitzero"`
	Sources []Source     `json:"sources,omitzero"`
	Network *NetworkConf `json:"network,omitzero"`
}

Environment specifies an environment to run the agent in.

The production Interactions API accepts two distinct shapes for the top-level "environment" field:

• A bare string (e.g. "env_CAEQ...") to reuse an existing sandbox.
• An object (e.g. {"type":"remote", ...}) to provision a new sandbox.

To reuse an environment, set only EnvID. To provision a new environment, set Type (and optionally Sources/Network) and leave EnvID empty.

func (Environment) MarshalJSON

func (e Environment) MarshalJSON() ([]byte, error)

MarshalJSON renders the Environment to match the production wire schema.

When only EnvID is populated, it serializes to a bare JSON string so the request body reads "environment": "env_...". Otherwise it serializes as a standard object (e.g. {"type":"remote", ...}).

func (*Environment) UnmarshalJSON

func (e *Environment) UnmarshalJSON(data []byte) error

UnmarshalJSON parses an Environment from either wire shape: a bare JSON string (reuse form, e.g. "env_CAEQ...", populating EnvID) or a JSON object (provisioning form, e.g. {"type":"remote", ...}). This is the mirror of MarshalJSON and makes round-tripping (e.g. decoding a request body a frontend sent) symmetric with what this package produces.

type Error

type Error struct {
	Code    int    `json:"code,omitzero"`
	Message string `json:"message,omitzero"`
	Status  string `json:"status,omitzero"`
}

Error represents an API error.

type File

type File struct {
	MimeType string `json:"mime_type"`
	FileURI  string `json:"file_uri"`
}

File represents a reference to a stored file.

type FileSearchCallContent

type FileSearchCallContent struct {
	ID        string `json:"id,omitempty"`
	Type      string `json:"type,omitempty"`
	Arguments any    `json:"arguments,omitempty"`
	Signature string `json:"signature,omitempty"`
}

type FileSearchResultContent

type FileSearchResultContent struct {
	ID     string `json:"id,omitempty"`
	Type   string `json:"type,omitempty"`
	Result any    `json:"result,omitempty"`
}

type FunctionCall

type FunctionCall struct {
	Name string         `json:"name"`
	Args map[string]any `json:"args"`
}

FunctionCall represents the actual function name and arguments.

type FunctionDeclaration

type FunctionDeclaration struct {
	Name        string `json:"name"`
	Description string `json:"description"`
	Parameters  any    `json:"parameters,omitempty"` // JSON Schema
}

FunctionDeclaration defines a tool that the model can call.

type FunctionResponse

type FunctionResponse struct {
	Name     string         `json:"name"`
	Response map[string]any `json:"response"`
}

FunctionResponse represents the output data from a function.

type GenerationConfig

type GenerationConfig struct {
	Temperature      *float32     `json:"temperature,omitempty"`
	TopP             *float32     `json:"top_p,omitempty"`
	TopK             *int         `json:"top_k,omitempty"`
	MaxOutputTokens  *int         `json:"max_output_tokens,omitempty"`
	StopSequences    []string     `json:"stop_sequences,omitempty"`
	ResponseMimeType string       `json:"response_mime_type,omitempty"`
	ImageConfig      *ImageConfig `json:"image_config,omitempty"`
}

GenerationConfig defines model sampling and output parameters.

type GoogleMapsCallContent

type GoogleMapsCallContent struct {
	ID        string `json:"id,omitempty"`
	Type      string `json:"type,omitempty"`
	Arguments any    `json:"arguments,omitempty"`
	Signature string `json:"signature,omitempty"`
}

type GoogleMapsResultContent

type GoogleMapsResultContent struct {
	ID     string `json:"id,omitempty"`
	Type   string `json:"type,omitempty"`
	Result any    `json:"result,omitempty"`
}

type GoogleSearchCallContent

type GoogleSearchCallContent struct {
	ID        string `json:"id,omitempty"`
	Type      string `json:"type,omitempty"`
	Arguments any    `json:"arguments,omitempty"`
	Signature string `json:"signature,omitempty"`
}

type GoogleSearchResultContent

type GoogleSearchResultContent struct {
	ID     string `json:"id,omitempty"`
	Type   string `json:"type,omitempty"`
	Result any    `json:"result,omitempty"`
}

type GoogleSearchTool

type GoogleSearchTool struct{}

GoogleSearchTool enables the Google Search tool.

type ImageConfig

type ImageConfig struct {
	AspectRatio string `json:"aspect_ratio,omitempty"`
	ImageSize   string `json:"image_size,omitempty"`
}

ImageConfig defines parameters for image generation.

type InteractionRequest

type InteractionRequest struct {
	Model                 string            `json:"model,omitempty"`
	Agent                 string            `json:"agent,omitempty"`
	AgentConfig           any               `json:"agent_config,omitempty"`
	Input                 any               `json:"input,omitempty"` // Can be string or []Content
	PreviousInteractionID string            `json:"previous_interaction_id,omitempty"`
	Store                 *bool             `json:"store,omitempty"`
	Background            bool              `json:"background,omitempty"`
	Stream                bool              `json:"stream,omitempty"`
	Environment           *Environment      `json:"environment,omitempty"`
	SystemInstruction     any               `json:"system_instruction,omitempty"` // Can be string or Content
	ResponseModalities    []string          `json:"response_modalities,omitempty"`
	ResponseFormat        any               `json:"response_format,omitempty"` // JSON Schema
	ServiceTier           string            `json:"service_tier,omitempty"`    // "flex", "standard", "priority"
	WebhookConfig         *WebhookConfig    `json:"webhook_config,omitempty"`
	GenerationConfig      *GenerationConfig `json:"generation_config,omitempty"`
	Tools                 []Tool            `json:"tools,omitempty"`
}

InteractionRequest defines the payload for creating a new interaction. It supports both standard model input and specialized agent execution.

func (*InteractionRequest) MarshalJSON

func (r *InteractionRequest) MarshalJSON() ([]byte, error)

UnmarshalJSON handles the dynamic 'input' field which can be string or array.

type InteractionResponse

type InteractionResponse struct {
	ID                    string      `json:"id"`
	Name                  string      `json:"name,omitempty"`
	Status                string      `json:"status"` // e.g., "COMPLETED", "WORKING"
	Object                string      `json:"object,omitempty"`
	EnvironmentID         string      `json:"environment_id,omitempty"`
	Outputs               []Content   `json:"outputs,omitempty"`
	Steps                 []Content   `json:"steps,omitempty"`
	Error                 *Error      `json:"error,omitempty"`
	Usage                 *Usage      `json:"usage,omitempty"`
	PreviousInteractionID string      `json:"previous_interaction_id,omitempty"`
	CreateTime            *time.Time  `json:"create_time,omitempty"`
	UpdateTime            *time.Time  `json:"update_time,omitempty"`
	SherlogLink           string      `json:"-"` // from x-goog-sherlog-link response header
	ResponseHeaders       http.Header `json:"-"` // full response headers
}

InteractionResponse defines the result of an interaction.

type MCPServerToolCallContent

type MCPServerToolCallContent struct {
	ID        string `json:"id,omitempty"`
	Type      string `json:"type,omitempty"`
	Arguments any    `json:"arguments,omitempty"`
	Signature string `json:"signature,omitempty"`
}

type MCPServerToolResultContent

type MCPServerToolResultContent struct {
	ID     string `json:"id,omitempty"`
	Type   string `json:"type,omitempty"`
	Result any    `json:"result,omitempty"`
}

type ModalityTokenCount

type ModalityTokenCount struct {
	Modality string `json:"modality,omitzero"`
	Tokens   int    `json:"tokens,omitzero"`
}

ModalityTokenCount reports token usage broken down by modality (e.g. text).

type NetworkConf

type NetworkConf struct {
	Allowlist []AllowlistEntry `json:"allowlist,omitzero"`
}

type Part

type Part struct {
	Type                string                      `json:"type,omitzero"`
	Text                string                      `json:"text,omitzero"`
	MimeType            string                      `json:"mime_type,omitzero"`
	URI                 string                      `json:"uri,omitzero"`
	Path                string                      `json:"path,omitzero"`
	Data                string                      `json:"data,omitzero"`
	Signature           string                      `json:"signature,omitzero"`
	Thought             *ThoughtContent             `json:"thought,omitzero"`
	Call                *ToolCall                   `json:"tool_call,omitzero"`
	Response            *ToolResult                 `json:"tool_response,omitzero"`
	CodeExecutionCall   *CodeExecutionCallContent   `json:"code_execution_call,omitzero"`
	CodeExecutionResult *CodeExecutionResultContent `json:"code_execution_result,omitzero"`
	GoogleSearchCall    *GoogleSearchCallContent    `json:"google_search_call,omitzero"`
	GoogleSearchResult  *GoogleSearchResultContent  `json:"google_search_result,omitzero"`
	URLContextCall      *URLContextCallContent      `json:"url_context_call,omitzero"`
	URLContextResult    *URLContextResultContent    `json:"url_context_result,omitzero"`
	MCPServerToolCall   *MCPServerToolCallContent   `json:"mcp_server_tool_call,omitzero"`
	MCPServerToolResult *MCPServerToolResultContent `json:"mcp_server_tool_result,omitzero"`
	FileSearchCall      *FileSearchCallContent      `json:"file_search_call,omitzero"`
	FileSearchResult    *FileSearchResultContent    `json:"file_search_result,omitzero"`
	GoogleMapsCall      *GoogleMapsCallContent      `json:"google_maps_call,omitzero"`
	GoogleMapsResult    *GoogleMapsResultContent    `json:"google_maps_result,omitzero"`
}

Part represents a single segment of an interaction input or output.

type Role

type Role string

Role defines the sender of a message part.

const (
	RoleUser  Role = "user"
	RoleModel Role = "model"
)

type Source

type Source struct {
	Type   string `json:"type"`            // "gcs" or "skill_registry"
	Source string `json:"source"`          // "gs://..." or "projects/.../skills/..."
	Target string `json:"target,omitzero"` // "./agent"
}

type ThoughtContent

type ThoughtContent struct {
	Text      string `json:"text,omitempty"`
	Signature string `json:"signature,omitempty"`
	Summary   string `json:"summary,omitempty"`
}

ThoughtContent represents the reasoning trace from the model.

type Tool

type Tool struct {
	Type                 string                `json:"type,omitzero"`
	URL                  string                `json:"url,omitzero"`
	Name                 string                `json:"name,omitzero"`
	Headers              map[string]string     `json:"headers,omitzero"`
	FunctionDeclarations []FunctionDeclaration `json:"function_declarations,omitzero"`
	GoogleSearch         *GoogleSearchTool     `json:"google_search,omitzero"`
	CodeExecution        *CodeExecutionTool    `json:"code_execution,omitzero"`
}

Tool represents an external capability the model can use.

type ToolCall

type ToolCall struct {
	FunctionCall *FunctionCall `json:"function_call,omitempty"`
}

ToolCall represents a request from the model to call a function.

type ToolResult

type ToolResult struct {
	FunctionResponse *FunctionResponse `json:"function_response,omitempty"`
}

ToolResult represents the result of a function call.

type URLContextCallContent

type URLContextCallContent struct {
	ID        string `json:"id,omitempty"`
	Type      string `json:"type,omitempty"`
	Arguments any    `json:"arguments,omitempty"`
	Signature string `json:"signature,omitempty"`
}

type URLContextResultContent

type URLContextResultContent struct {
	ID     string `json:"id,omitempty"`
	Type   string `json:"type,omitempty"`
	Result any    `json:"result,omitempty"`
}

type Usage

type Usage struct {
	TotalTokens            int                  `json:"total_tokens,omitzero"`
	TotalInputTokens       int                  `json:"total_input_tokens,omitzero"`
	TotalOutputTokens      int                  `json:"total_output_tokens,omitzero"`
	TotalThoughtTokens     int                  `json:"total_thought_tokens,omitzero"`
	InputTokensByModality  []ModalityTokenCount `json:"input_tokens_by_modality,omitzero"`
	OutputTokensByModality []ModalityTokenCount `json:"output_tokens_by_modality,omitzero"`
}

Usage represents token metrics for the interaction.

type WebhookConfig

type WebhookConfig struct {
	Url string `json:"url,omitempty"`
}

WebhookConfig defines optional callback configurations for long-running interactions.