agent

type Agent ¶

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

Agent encapsulates Genkit AI functionality.

Responsibilities: AI interactions, tool registration, conversation history (in-memory and optional persistence). NOT responsible for: User interaction (cmd package handles CLI).

Thread Safety: Thread-safe for concurrent access (messages protected by RWMutex). Tools (registered via tools.RegisterTools) are thread-safe and hold their own validators.

func New(
	ctx context.Context,
	cfg *config.Config,
	g *genkit.Genkit,
	retriever ai.Retriever,
	opts ...Option,
) (*Agent, error)

func (a *Agent) ClearHistory()

func (a *Agent) Execute(ctx context.Context, input string) (*Response, error)

func (a *Agent) GetCurrentSession(ctx context.Context) (*session.Session, error)

func (a *Agent) HistoryLength() int

func (a *Agent) NewSession(ctx context.Context, title string) (*session.Session, error)

func (a *Agent) SwitchSession(ctx context.Context, sessionID uuid.UUID) error

type Generator ¶

type Generator interface {
	Generate(ctx context.Context, opts ...ai.GenerateOption) (*ai.ModelResponse, error)
}

Generator defines an interface for generating model responses, allowing for mocking in tests.

type KnowledgeStore ¶

type KnowledgeStore interface {
	// Count returns the number of documents matching the filter
	Count(ctx context.Context, filter map[string]string) (int, error)

	// Add adds a document to the knowledge store with automatic embedding generation
	Add(ctx context.Context, doc knowledge.Document) error

	// Search performs semantic search on knowledge documents
	Search(ctx context.Context, query string, opts ...knowledge.SearchOption) ([]knowledge.Result, error)
}

KnowledgeStore defines the minimal interface for knowledge operations needed by Agent. Following Go best practices: interfaces are defined by the consumer (agent), not the provider (knowledge package). This allows Agent to depend on abstraction rather than concrete implementation, improving testability.

Design: Only includes methods actually used by Agent (Count, Add, Search), not the full knowledge.Store API. This follows the Interface Segregation Principle - clients should not depend on methods they don't use.

Note: Search is needed by tools.KnowledgeSearcher interface (used in tools.RegisterTools).

type Option ¶

type Option func(*Agent)

Option is a functional option for configuring the Agent.

func WithKnowledgeStore(store KnowledgeStore) Option

func WithLogger(logger *slog.Logger) Option

func WithSessionStore(store SessionStore) Option

type Response ¶

type Response struct {
	FinalText string        // Model's final text output
	History   []*ai.Message // Complete conversation history including all tool calls
}

Response represents the complete result of an agent execution. Designed for synchronous, blocking execution following 建議.md architecture.

type SessionStore ¶

type SessionStore interface {
	// CreateSession creates a new conversation session
	CreateSession(ctx context.Context, title, modelName, systemPrompt string) (*session.Session, error)

	// GetSession retrieves a session by ID
	GetSession(ctx context.Context, sessionID uuid.UUID) (*session.Session, error)

	// GetMessages retrieves messages for a session with pagination
	GetMessages(ctx context.Context, sessionID uuid.UUID, limit, offset int32) ([]*session.Message, error)

	// AddMessages adds multiple messages to a session in batch
	AddMessages(ctx context.Context, sessionID uuid.UUID, messages []*session.Message) error
}

SessionStore defines the interface for session persistence operations. Following Go best practices: interfaces are defined by the consumer (agent), not the provider (session package). This allows Agent to depend on abstraction rather than concrete implementation, improving testability.

type TestAgentFramework ¶

type TestAgentFramework struct {
	// Database
	DBContainer *testutil.TestDBContainer

	// Core components
	Agent          *Agent
	KnowledgeStore *knowledge.Store
	SystemIndexer  *knowledge.SystemKnowledgeIndexer
	SessionStore   *session.Store
	Genkit         *genkit.Genkit
	Embedder       ai.Embedder
	Retriever      ai.Retriever
	Config         *config.Config

	// Test session
	SessionID uuid.UUID
	// contains filtered or unexported fields
}

TestAgentFramework provides a complete test environment for Agent integration tests.

Includes all components needed for full-stack agent testing:

• PostgreSQL database with test data
• Genkit AI framework
• Knowledge store with embeddings
• Session management
• Configured Agent instance

Usage:

framework, cleanup := SetupTestAgent(t)
defer cleanup()
resp, err := framework.Agent.Execute(ctx, "test query")

func SetupTestAgent(t *testing.T) (*TestAgentFramework, func())

func TestAgentFeature(t *testing.T) {
    framework, cleanup := SetupTestAgent(t)
    defer cleanup()

    resp, err := framework.Agent.Execute(ctx, "What is Go?")
    require.NoError(t, err)
    assert.NotEmpty(t, resp.FinalText)
}

func (f *TestAgentFramework) IndexSystemKnowledge(t *testing.T)

framework, cleanup := SetupTestAgent(t)
defer cleanup()
framework.IndexSystemKnowledge(t)
// Now system knowledge is available for RAG queries