interactions

README

Cloud Interactions SDK for Go

An unofficial Go GenAI SDK port for the Vertex AI Interactions & Managed Agents API.

This package provides a high-performance, lightweight, and highly concurrent Go client tailored explicitly for the real-time streaming SSE (Server-Sent Events) architectures of the Gemini Interactions platform.

---

Features

• High-Performance SSE Stream Scanner: Out-of-the-box support for massive streaming buffers (up to 128MB) optimized specifically to handle raw interleaved multimodal payloads (large video, audio, or image base64 bytes) without memory fragmentation.
• Managed Agents & Tool Integration: Complete support for provisioning, executing, and managing enterprise workflows on the Google Cloud Managed Agents Platform.
• Dynamic MCP Injection: Inline override structures allowing developers to attach or re-bind custom Model Context Protocol (MCP) servers at runtime.
• Sanitized Multi-Tenant Environments: Provision network access policies and custom source allowlists dynamically per-interaction.

---

Installation

Include the package in your Go application:

go get github.com/sourcerepo-genai-sa/cloud-interactions-go

---

Quickstart

Here is how you initialize the client and stream a simple conversational agent turn:

package main

import (
	"context"
	"fmt"
	"log"
	"net/http"
	"time"

	"github.com/sourcerepo-genai-sa/cloud-interactions-go"
)

func main() {
	ctx := context.Background()
	
	// Initialize pointing to the Vertex Interactions regional gateway
	baseURL := "https://us-central1-aiplatform.googleapis.com/v1beta1/projects/my-project/locations/us-central1/interactions"
	
	client := interactions.NewClient(baseURL)
	client.WithBearerToken("YOUR_ACCESS_TOKEN")

	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: %s | Chunk Size: %d bytes\n", event, len(data))
		return nil
	})
	if err != nil {
		log.Fatalf("Stream failed: %v", err)
	}
}

---

Standard Types & Future Compatibility

This client has been designed to strictly mimic the casing, parameter structures, and snake_case tags of the official Google USDK releases:

• Uses omitzero tag annotations natively.
• Structures mirror the underlying Interaction, Step, and Usage specifications, ensuring that migrating to the official SDK in the future will require zero rewrite of downstream logic.

Documentation

Index

• 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) WithBearerToken(token string) *Client
• type CodeExecutionCallContent
• type CodeExecutionResultContent
• type CodeExecutionTool
• type Content
• type Environment
• 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 NetworkConf
• type Part
• type Role
• type Source
• type ThoughtContent
• type Tool
• type ToolCall
• type ToolResult
• type URLContextCallContent
• type URLContextResultContent
• type Usage
• type WebhookConfig

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
	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) WithBearerToken

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

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

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
}

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.

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"`
	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"`
}

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 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"`
}

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.