client

package
v0.0.0-...-7202591 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 22, 2026 License: Apache-2.0 Imports: 11 Imported by: 0

README

KAgent Client

HTTP Client to interact with the KAgent API.

Installation

import "github.com/kagent-dev/kagent/go/pkg/client"

Basic Usage

The client library provides a modular, interface-based design with sub-clients for different API areas:

package main

import (
    "context"
    "fmt"
    "log"

    "github.com/kagent-dev/kagent/go/pkg/client"
    "github.com/kagent-dev/kagent/go/pkg/client/api"
    "github.com/kagent-dev/kagent/go/controller/api/v1alpha2"
    metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
)

func main() {
    // Create a new client set
    c := client.New("http://localhost:8080",
        client.WithUserID("your-user-id"))

    // Check server health
    if err := c.Health.Get(context.Background()); err != nil {
        log.Fatal("Server is not healthy:", err)
    }

    // Get version information
    version, err := c.Version.GetVersion(context.Background())
    if err != nil {
        log.Fatal("Failed to get version:", err)
    }
    fmt.Printf("Server version: %s\n", version.KAgentVersion)
}

Client Architecture

The client is organized into sub-clients, each responsible for a specific API area:

  • Health: c.Health - Server health checks
  • Version: c.Version - Version information
  • ModelConfigs: c.ModelConfig - Model configuration management
  • Sessions: c.Session - Session management
  • Agents: c.Agent - Agent management
  • Tools: c.Tool - Tool listing
  • ToolServers: c.ToolServer - Tool server management
  • Memories: c.Memory - Memory management
  • Providers: c.Provider - Provider information
  • Models: c.Model - Model information
  • Namespaces: c.Namespace - Namespace listing
  • Feedback: c.Feedback - Feedback management

Configuration

Client Options
// With custom HTTP client
httpClient := &http.Client{Timeout: 60 * time.Second}
c := client.New("http://localhost:8080",
    client.WithHTTPClient(httpClient),
    client.WithUserID("your-user-id"))
User ID

Many endpoints require a user ID. You can either:

  1. Set a default user ID when creating the client:
c := client.New("http://localhost:8080", client.WithUserID("user123"))
  1. Pass it explicitly to methods that require it:
sessions, err := c.Sessions().ListSessions(ctx, "user123")

API Methods

Health and Version
// Health check
err := c.Health.Get(ctx)

// Get version information
version, err := c.Version.GetVersion(ctx)
Model Configurations
// List all model configurations
configs, err := c.ModelConfig.ListModelConfigs(ctx)

// Get a specific model configuration
config, err := c.ModelConfig.GetModelConfig(ctx, "namespace", "config-name")

// Create a new model configuration
request := &client.CreateModelConfigRequest{
    Ref:      "default/my-config",
    Provider: client.Provider{Type: "OpenAI"},
    Model:    "gpt-4",
    APIKey:   "your-api-key",
    OpenAIParams: &v1alpha2.OpenAIConfig{
        Temperature: "0.7",
        MaxTokens:   1000,
    },
}
config, err := c.ModelConfig.CreateModelConfig(ctx, request)

// Update a model configuration
updateReq := &client.UpdateModelConfigRequest{
    Provider: client.Provider{Type: "OpenAI"},
    Model:    "gpt-4-turbo",
    OpenAIParams: &v1alpha2.OpenAIConfig{
        Temperature: "0.8",
    },
}
config, err := c.ModelConfig.UpdateModelConfig(ctx, "namespace", "config-name", updateReq)

// Delete a model configuration
err := c.ModelConfig.DeleteModelConfig(ctx, "namespace", "config-name")
Sessions
// List sessions for a user
sessions, err := c.Session.ListSessions(ctx, "user123")

// Create a new session
sessionReq := &client.SessionRequest{
    Name:     "My Session",
    UserID:   "user123",
    AgentRef: &agentRef, // optional
}
session, err := c.Session.CreateSession(ctx, sessionReq)

// Get a specific session
session, err := c.Session.GetSession(ctx, "session-name", "user123")

// Update a session
sessionReq.AgentRef = &newAgentRef
session, err := c.Session.UpdateSession(ctx, sessionReq)

// Delete a session
err := c.Session.DeleteSession(ctx, "session-name", "user123")

// List runs for a session
runs, err := c.Session.ListSessionRuns(ctx, "session-name", "user123")
Agents
// List agents for a user
agents, err := c.Agent.ListAgents(ctx, "user123")

// Create a new agent
agent := &v1alpha2.Agent{
    ObjectMeta: metav1.ObjectMeta{
        Name:      "my-agent",
        Namespace: "default",
    },
    Spec: v1alpha2.AgentSpec{
        Description:   "My agent description",
        SystemMessage: "You are a helpful assistant",
        ModelConfig:   "default/gpt-4-config",
    },
}
createdAgent, err := c.Agent.CreateAgent(ctx, agent)

// Get a specific agent
agentResponse, err := c.Agent.GetAgent(ctx, "default/my-agent")

// Update an agent
agent.Spec.Description = "Updated description"
updatedAgent, err := c.Agent.UpdateAgent(ctx, agent)

// Delete an agent
err := c.Agent.DeleteAgent(ctx, "default/my-agent")
Providers
// List supported model providers
modelProviders, err := c.Provider.ListSupportedModelProviders(ctx)

// List supported memory providers
memoryProviders, err := c.Provider.ListSupportedMemoryProviders(ctx)
Models
// List supported models
models, err := c.Model.ListSupportedModels(ctx)
Namespaces
// List namespaces
namespaces, err := c.Namespace.ListNamespaces(ctx)
Feedback
// Create feedback
feedback := &client.Feedback{
    MessageID:    123,
    IsPositive:   true,
    FeedbackText: "Great response!",
    IssueType:    nil, // optional
}
err := c.Feedback.CreateFeedback(ctx, feedback, "user123")

// List feedback for a user
feedback, err := c.Feedback.ListFeedback(ctx, "user123")

Error Handling

The client returns structured errors that implement the error interface:

configs, err := c.ListModelConfigs(ctx)
if err != nil {
    if clientErr, ok := err.(*client.ClientError); ok {
        fmt.Printf("HTTP %d: %s\n", clientErr.StatusCode, clientErr.Message)
        fmt.Printf("Response body: %s\n", clientErr.Body)
    } else {
        fmt.Printf("Client error: %v\n", err)
    }
}

Client Constructor

The client is created using the New() function:

// Standard usage
c := client.New("http://localhost:8080", client.WithUserID("user123"))

Examples

Complete Session Management
package main

import (
    "context"
    "log"

    "github.com/kagent-dev/kagent/go/pkg/client"
)

func main() {
    c := client.New("http://localhost:8080", client.WithUserID("user123"))
    ctx := context.Background()

    // Create a session
    sessionReq := &client.SessionRequest{
        Name:   "Chat Session",
        UserID: "user123",
    }
    session, err := c.Session.CreateSession(ctx, sessionReq)
    if err != nil {
        log.Fatal("Failed to create session:", err)
    }

    // List all sessions
    sessions, err := c.Session.ListSessions(ctx, "user123")
    if err != nil {
        log.Fatal("Failed to list sessions:", err)
    }
    
    log.Printf("Created session: %+v\n", session)
    log.Printf("Total sessions: %d\n", len(sessions))

    // Get session runs
    runs, err := c.Session.ListSessionRuns(ctx, session.Name, "user123")
    if err != nil {
        log.Fatal("Failed to get session runs:", err)
    }
    
    log.Printf("Session runs: %d\n", len(runs))

    // Clean up
    err = c.Session.DeleteSession(ctx, session.Name, "user123")
    if err != nil {
        log.Fatal("Failed to delete session:", err)
    }
}

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DecodeResponse 

func DecodeResponse(resp *http.Response, target any) error

Types

type Agent 

type Agent interface {
	ListAgents(ctx context.Context) (*api.StandardResponse[[]api.AgentResponse], error)
	CreateAgent(ctx context.Context, request *v1alpha2.Agent) (*api.StandardResponse[*v1alpha2.Agent], error)
	GetAgent(ctx context.Context, agentRef string) (*api.StandardResponse[*api.AgentResponse], error)
	UpdateAgent(ctx context.Context, request *v1alpha2.Agent) (*api.StandardResponse[*v1alpha2.Agent], error)
	DeleteAgent(ctx context.Context, agentRef string) error
}

Agent defines the agent operations

func NewAgentClient 

func NewAgentClient(client *BaseClient) Agent

NewAgentClient creates a new agent client

type BaseClient 

type BaseClient struct {
	BaseURL    string
	HTTPClient *http.Client
	UserID     string // Default user ID for requests that require it
}

BaseClient contains the shared HTTP functionality used by all sub-clients

func NewBaseClient 

func NewBaseClient(baseURL string, options ...ClientOption) *BaseClient

NewBaseClient creates a new base client with the given configuration

func (*BaseClient) Delete 

func (c *BaseClient) Delete(ctx context.Context, path string, userID string) (*http.Response, error)

func (*BaseClient) Get 

func (c *BaseClient) Get(ctx context.Context, path string, userID string) (*http.Response, error)

func (*BaseClient) GetUserIDOrDefault 

func (c *BaseClient) GetUserIDOrDefault(userID string) string

GetUserIDOrDefault returns the provided userID or falls back to the client's default

func (*BaseClient) Post 

func (c *BaseClient) Post(ctx context.Context, path string, body any, userID string) (*http.Response, error)

func (*BaseClient) Put 

func (c *BaseClient) Put(ctx context.Context, path string, body any, userID string) (*http.Response, error)

type ClientError 

type ClientError struct {
	StatusCode int
	Message    string
	Body       string
}

ClientError represents a client-side error

func (*ClientError) Error 

func (e *ClientError) Error() string

type ClientOption 

type ClientOption func(*BaseClient)

ClientOption represents a configuration option for the client

func WithHTTPClient 

func WithHTTPClient(httpClient *http.Client) ClientOption

WithHTTPClient sets a custom HTTP client

func WithUserID 

func WithUserID(userID string) ClientOption

WithUserID sets a default user ID for requests

type ClientSet 

type ClientSet struct {
	Health      Health
	Version     Version
	ModelConfig ModelConfigInterface
	Session     Session
	Agent       Agent
	Tool        Tool
	ToolServer  ToolServer
	Memory      Memory
	Provider    Provider
	Model       Model
	Namespace   Namespace
	Feedback    Feedback
	// contains filtered or unexported fields
}

ClientSet contains all the sub-clients for different resource types

func New 

func New(baseURL string, options ...ClientOption) *ClientSet

New creates a new KAgent client set

type Feedback 

type Feedback interface {
	CreateFeedback(ctx context.Context, feedback *api.Feedback, userID string) error
	ListFeedback(ctx context.Context, userID string) (*api.StandardResponse[[]api.Feedback], error)
}

Feedback defines the feedback operations

func NewFeedbackClient 

func NewFeedbackClient(client *BaseClient) Feedback

NewFeedbackClient creates a new feedback client

type Health 

type Health interface {
	Get(ctx context.Context) error
}

Health defines the health-related operations

func NewHealthClient 

func NewHealthClient(client *BaseClient) Health

NewHealthClient creates a new health client

type Memory 

type Memory interface {
	ListMemories(ctx context.Context) (*api.StandardResponse[[]api.MemoryResponse], error)
	CreateMemory(ctx context.Context, request *api.CreateMemoryRequest) (*api.StandardResponse[*v1alpha1.Memory], error)
	GetMemory(ctx context.Context, namespace, memoryName string) (*api.StandardResponse[*api.MemoryResponse], error)
	UpdateMemory(ctx context.Context, namespace, memoryName string, request *api.UpdateMemoryRequest) (*api.StandardResponse[*v1alpha1.Memory], error)
	DeleteMemory(ctx context.Context, namespace, memoryName string) error
}

Memory defines the memory operations

func NewMemoryClient 

func NewMemoryClient(client *BaseClient) Memory

NewMemoryClient creates a new memory client

type Model 

type Model interface {
	ListSupportedModels(ctx context.Context) (*api.StandardResponse[ProviderModels], error)
}

Model defines the model operations

func NewModelClient 

func NewModelClient(client *BaseClient) Model

NewModelClient creates a new model client

type ModelConfigClient 

type ModelConfigClient struct {
	// contains filtered or unexported fields
}

ModelConfigClient handles model configuration requests

func (*ModelConfigClient) CreateModelConfig 

func (c *ModelConfigClient) CreateModelConfig(ctx context.Context, request *api.CreateModelConfigRequest) (*api.StandardResponse[*v1alpha2.ModelConfig], error)

CreateModelConfig creates a new model configuration

func (*ModelConfigClient) DeleteModelConfig 

func (c *ModelConfigClient) DeleteModelConfig(ctx context.Context, namespace, configName string) error

DeleteModelConfig deletes a model configuration

func (*ModelConfigClient) GetModelConfig 

func (c *ModelConfigClient) GetModelConfig(ctx context.Context, namespace, name string) (*api.StandardResponse[*api.ModelConfigResponse], error)

GetModelConfig retrieves a specific model configuration

func (*ModelConfigClient) ListModelConfigs 

func (c *ModelConfigClient) ListModelConfigs(ctx context.Context) (*api.StandardResponse[[]api.ModelConfigResponse], error)

ListModelConfigs lists all model configurations

func (*ModelConfigClient) UpdateModelConfig 

func (c *ModelConfigClient) UpdateModelConfig(ctx context.Context, namespace, configName string, request *api.UpdateModelConfigRequest) (*api.StandardResponse[*api.ModelConfigResponse], error)

UpdateModelConfig updates an existing model configuration

type ModelConfigInterface 

type ModelConfigInterface interface {
	ListModelConfigs(ctx context.Context) (*api.StandardResponse[[]api.ModelConfigResponse], error)
	GetModelConfig(ctx context.Context, namespace, name string) (*api.StandardResponse[*api.ModelConfigResponse], error)
	CreateModelConfig(ctx context.Context, request *api.CreateModelConfigRequest) (*api.StandardResponse[*v1alpha2.ModelConfig], error)
	UpdateModelConfig(ctx context.Context, namespace, name string, request *api.UpdateModelConfigRequest) (*api.StandardResponse[*api.ModelConfigResponse], error)
	DeleteModelConfig(ctx context.Context, namespace, name string) error
}

ModelConfigInterface defines the model configuration operations

func NewModelConfigClient 

func NewModelConfigClient(client *BaseClient) ModelConfigInterface

NewModelConfigClient creates a new model config client

type ModelInfo 

type ModelInfo struct {
	Name            string `json:"name"`
	FunctionCalling bool   `json:"function_calling"`
}

ModelInfo represents information about a model

type Namespace 

type Namespace interface {
	ListNamespaces(ctx context.Context) (*api.StandardResponse[[]api.NamespaceResponse], error)
}

Namespace defines the namespace operations

func NewNamespaceClient 

func NewNamespaceClient(client *BaseClient) Namespace

NewNamespaceClient creates a new namespace client

type Provider 

type Provider interface {
	ListSupportedModelProviders(ctx context.Context) (*api.StandardResponse[[]api.ProviderInfo], error)
	ListSupportedMemoryProviders(ctx context.Context) (*api.StandardResponse[[]api.ProviderInfo], error)
}

Provider defines the provider operations

func NewProviderClient 

func NewProviderClient(client *BaseClient) Provider

NewProviderClient creates a new provider client

type ProviderModels 

type ProviderModels map[v1alpha2.ModelProvider][]ModelInfo

ProviderModels represents a map of provider names to their supported models

type Session 

type Session interface {
	ListSessions(ctx context.Context) (*api.StandardResponse[[]*api.Session], error)
	CreateSession(ctx context.Context, request *api.SessionRequest) (*api.StandardResponse[*api.Session], error)
	GetSession(ctx context.Context, sessionName string) (*api.StandardResponse[*api.Session], error)
	UpdateSession(ctx context.Context, request *api.SessionRequest) (*api.StandardResponse[*api.Session], error)
	DeleteSession(ctx context.Context, sessionName string) error
	ListSessionRuns(ctx context.Context, sessionName string) (*api.StandardResponse[any], error)
}

Session defines the session operations

func NewSessionClient 

func NewSessionClient(client *BaseClient) Session

NewSessionClient creates a new session client

type Tool 

type Tool interface {
	ListTools(ctx context.Context) ([]api.Tool, error)
}

Tool defines the tool operations

func NewToolClient 

func NewToolClient(client *BaseClient) Tool

NewToolClient creates a new tool client

type ToolServer 

type ToolServer interface {
	ListToolServers(ctx context.Context) ([]api.ToolServerResponse, error)
	CreateToolServer(ctx context.Context, toolServer *v1alpha1.ToolServer) (*v1alpha1.ToolServer, error)
	DeleteToolServer(ctx context.Context, namespace, toolServerName string) error
}

ToolServer defines the tool server operations

func NewToolServerClient 

func NewToolServerClient(client *BaseClient) ToolServer

NewToolServerClient creates a new tool server client

type ToolServerClient 

type ToolServerClient struct {
	// contains filtered or unexported fields
}

ToolServerClient handles tool server-related requests

func (*ToolServerClient) CreateToolServer 

func (c *ToolServerClient) CreateToolServer(ctx context.Context, toolServer *v1alpha1.ToolServer) (*v1alpha1.ToolServer, error)

CreateToolServer creates a new tool server

func (*ToolServerClient) DeleteToolServer 

func (c *ToolServerClient) DeleteToolServer(ctx context.Context, namespace, toolServerName string) error

DeleteToolServer deletes a tool server

func (*ToolServerClient) ListToolServers 

func (c *ToolServerClient) ListToolServers(ctx context.Context) ([]api.ToolServerResponse, error)

ListToolServers lists all tool servers

type Version 

type Version interface {
	GetVersion(ctx context.Context) (*api.VersionResponse, error)
}

Version defines the version-related operations

func NewVersionClient 

func NewVersionClient(client *BaseClient) Version

NewVersionClient creates a new version client

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.