agents

package
v1.5.3 Latest Latest
Warning

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

 Go to latest Published: Aug 8, 2026 License: MIT Imports: 6 Imported by: 0

Documentation

Overview

Package agents implements a LangChain-v1 style unified agent framework for Go, built on the state-graph engine and the middleware system.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func SetModelInitializer 

func SetModelInitializer(fn func(ctx context.Context, identifier string, opts ...ModelOption) (ChatModel, error))

SetModelInitializer registers the resolver used by create_agent to turn a model string into a ChatModel. It is called by the v1/modelprofile package.

Types

type Agent 

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

Agent is a compiled agent graph.

func NewAgent 

func NewAgent(model any, opts ...AgentOption) (*Agent, error)

NewAgent builds and compiles an agent graph from the given model and options.

func (*Agent) AInvoke 

func (a *Agent) AInvoke(ctx context.Context, input []*graph.Message, opts ...graph.RunOption) ([]*graph.Message, error)

AInvoke is the async variant of Invoke. The graph engine is Go-native, so this simply delegates to Invoke; callers may run it in a goroutine.

func (*Agent) Batch 

func (a *Agent) Batch(ctx context.Context, inputs [][]*graph.Message, workers int, opts ...graph.RunOption) ([][]*graph.Message, error)

Batch runs the agent over multiple conversations concurrently and preserves input order.

func (*Agent) Invoke 

func (a *Agent) Invoke(ctx context.Context, input []*graph.Message, opts ...graph.RunOption) ([]*graph.Message, error)

Invoke runs the agent to completion with the given input messages.

func (*Agent) Stream 

func (a *Agent) Stream(ctx context.Context, input []*graph.Message, opts ...graph.RunOption) (<-chan graph.StreamUpdate, error)

Stream runs the agent and yields state updates after each node.

type AgentConfig 

type AgentConfig struct {
	// Model is a string identifier or a ChatModel instance.
	Model any
	// Tools available to the agent.
	Tools []graph.Tool
	// SystemPrompt is prepended to the message list.
	SystemPrompt string
	// Middleware applied to the agent.
	Middleware []Middleware
	// Checkpointer enables persistence/interrupts.
	Checkpointer graph.Checkpointer
	// Name of the agent graph.
	Name string
	// ResponseFormat configures structured output.
	ResponseFormat *structured.ResponseFormat
}

AgentConfig configures create_agent.

type AgentOption 

type AgentOption func(*AgentConfig)

AgentOption sets an AgentConfig field.

func WithCheckpointer 

func WithCheckpointer(cp graph.Checkpointer) AgentOption

WithCheckpointer sets the agent's checkpointer.

func WithMiddleware 

func WithMiddleware(m ...Middleware) AgentOption

WithMiddleware appends middleware to the agent.

func WithName 

func WithName(name string) AgentOption

WithName sets the agent graph name.

func WithResponseFormat 

func WithResponseFormat(rf *structured.ResponseFormat) AgentOption

WithResponseFormat sets the agent's structured output response format.

func WithSystemPrompt 

func WithSystemPrompt(p string) AgentOption

WithSystemPrompt sets the system prompt.

func WithTools 

func WithTools(tools ...graph.Tool) AgentOption

WithTools sets the agent's tools.

type AgentState 

type AgentState = graph.State

AgentState is the base state schema for an agent. It carries the message list and an optional structured response.

type Base 

type Base struct{}

Base is a no-op middleware that implements every hook. Embed it in a concrete middleware and override only the hooks you need.

func (Base) AfterModel 

func (Base) AfterModel(_ context.Context, _ *ModelRequest, _ *ModelResponse) error

AfterModel implements Middleware.

func (Base) AfterTool 

func (Base) AfterTool(_ context.Context, _ *ToolCallRequest, _ *ToolCallResponse) error

AfterTool implements Middleware.

func (Base) BeforeModel 

func (Base) BeforeModel(_ context.Context, _ *ModelRequest) (*ModelResponse, error)

BeforeModel implements Middleware.

func (Base) BeforeTool 

func (Base) BeforeTool(_ context.Context, _ *ToolCallRequest) (*ToolCallResponse, error)

BeforeTool implements Middleware.

func (Base) Name 

func (Base) Name() string

Name implements Middleware.

func (Base) WrapModelCall 

func (Base) WrapModelCall(ctx context.Context, req *ModelRequest, handler ModelHandler) (*ModelResponse, error)

WrapModelCall implements Middleware.

type Chain 

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

Chain composes middleware into a model and tool pipeline, applying "before" hooks in order and "after" hooks in reverse order (nested onion).

func NewChain 

func NewChain(middleware ...Middleware) *Chain

NewChain builds a Chain from the given middleware.

func (*Chain) RunModel 

func (c *Chain) RunModel(ctx context.Context, req *ModelRequest, model ModelHandler) (*ModelResponse, error)

RunModel runs the model pipeline. The innermost handler invokes the actual model. Middleware wrap this handler via WrapModelCall; before/after hooks are applied around it.

func (*Chain) RunTool 

func (c *Chain) RunTool(ctx context.Context, req *ToolCallRequest, call func(ctx context.Context, req *ToolCallRequest) (*graph.Message, error)) (*ToolCallResponse, error)

RunTool runs the tool pipeline with before/after tool hooks.

type ChatModel 

type ChatModel interface {
	// BindTools returns a copy of the model bound to the given tools.
	BindTools(tools []graph.Tool) (ChatModel, error)
	// GenerateMessages produces an assistant message from the input messages.
	GenerateMessages(ctx context.Context, messages []*graph.Message) (*graph.Message, error)
	// StreamMessages streams an assistant message incrementally.
	StreamMessages(ctx context.Context, messages []*graph.Message) (<-chan *graph.Message, error)
	// SupportsStructuredOutput reports provider-native structured output support.
	SupportsStructuredOutput(schema map[string]any) bool
	// GenerateStructured generates structured output constrained by schema.
	GenerateStructured(ctx context.Context, messages []*graph.Message, schema map[string]any) (any, error)
}

ChatModel is the abstraction the agent uses to talk to a language model. It mirrors langchain-core's BaseChatModel subset needed by create_agent.

func ToChatModel 

func ToChatModel(m ChatModel) ChatModel

ToChatModel converts an existing ChatModel to itself (identity).

type JumpTo 

type JumpTo string

JumpTo is a routing directive used by middleware hooks to redirect control.

type Middleware 

type Middleware interface {
	// Name returns a unique identifier for the middleware.
	Name() string
	// BeforeModel runs before the model is invoked. It may return a command to
	// short-circuit or redirect.
	BeforeModel(ctx context.Context, req *ModelRequest) (*ModelResponse, error)
	// AfterModel runs after the model returns.
	AfterModel(ctx context.Context, req *ModelRequest, resp *ModelResponse) error
	// WrapModelCall wraps the model invocation, allowing full control.
	WrapModelCall(ctx context.Context, req *ModelRequest, handler ModelHandler) (*ModelResponse, error)
	// BeforeTool runs before a tool is called.
	BeforeTool(ctx context.Context, req *ToolCallRequest) (*ToolCallResponse, error)
	// AfterTool runs after a tool returns.
	AfterTool(ctx context.Context, req *ToolCallRequest, resp *ToolCallResponse) error
}

Middleware is a composable hook that can intercept model calls and tool calls during an agent run. All hooks are optional; a middleware only implements the methods it cares about.

type MiddlewareFunc 

type MiddlewareFunc struct {
	Base
	// contains filtered or unexported fields
}

MiddlewareFunc adapts a set of hook funcs into a Middleware. Embed Base and set the funcs you want; nil funcs fall through to the base behavior.

func NewMiddleware 

func NewMiddleware(h MiddlewareHooks) *MiddlewareFunc

NewMiddleware builds a MiddlewareFunc from the given hooks.

func (*MiddlewareFunc) AfterModel 

func (m *MiddlewareFunc) AfterModel(ctx context.Context, req *ModelRequest, resp *ModelResponse) error

AfterModel implements Middleware.

func (*MiddlewareFunc) AfterTool 

func (m *MiddlewareFunc) AfterTool(ctx context.Context, req *ToolCallRequest, resp *ToolCallResponse) error

AfterTool implements Middleware.

func (*MiddlewareFunc) BeforeModel 

func (m *MiddlewareFunc) BeforeModel(ctx context.Context, req *ModelRequest) (*ModelResponse, error)

BeforeModel implements Middleware.

func (*MiddlewareFunc) BeforeTool 

func (m *MiddlewareFunc) BeforeTool(ctx context.Context, req *ToolCallRequest) (*ToolCallResponse, error)

BeforeTool implements Middleware.

func (*MiddlewareFunc) Name 

func (m *MiddlewareFunc) Name() string

Name implements Middleware.

func (*MiddlewareFunc) WrapModelCall 

func (m *MiddlewareFunc) WrapModelCall(ctx context.Context, req *ModelRequest, handler ModelHandler) (*ModelResponse, error)

WrapModelCall implements Middleware.

type MiddlewareHooks 

type MiddlewareHooks struct {
	Name          string
	BeforeModel   func(ctx context.Context, req *ModelRequest) (*ModelResponse, error)
	AfterModel    func(ctx context.Context, req *ModelRequest, resp *ModelResponse) error
	WrapModelCall func(ctx context.Context, req *ModelRequest, handler ModelHandler) (*ModelResponse, error)
	BeforeTool    func(ctx context.Context, req *ToolCallRequest) (*ToolCallResponse, error)
	AfterTool     func(ctx context.Context, req *ToolCallRequest, resp *ToolCallResponse) error
}

MiddlewareHooks collects the optional hook funcs for a MiddlewareFunc.

type ModelHandler 

type ModelHandler func(ctx context.Context, req *ModelRequest) (*ModelResponse, error)

ModelHandler is the inner model invocation passed to WrapModelCall.

type ModelOption 

type ModelOption func(*modelConfig)

ModelOption configures how a model string is resolved.

func WithProvider 

func WithProvider(p string) ModelOption

WithProvider forces a specific provider when resolving a model name.

type ModelProfile 

type ModelProfile struct {
	Provider string
	Name     string
}

ModelProfile describes a concrete model provider/name for the agent.

type ModelRequest 

type ModelRequest struct {
	// Messages are the input messages.
	Messages []*graph.Message
	// Tools are the tools offered to the model.
	Tools []graph.Tool
	// Context holds runtime context.
	Context any
	// Step is the current iteration index.
	Step int
}

ModelRequest wraps a single model invocation for middleware.

type ModelResponse 

type ModelResponse struct {
	// Messages are the messages produced by the model.
	Messages []*graph.Message
	// StructuredResponse is set when the model produced structured output.
	StructuredResponse any
	// Commands are control-flow commands emitted by middleware.
	Commands []graph.Command
}

ModelResponse is the result of a model invocation.

type SubAgent 

type SubAgent struct {
	Tools        []graph.Tool
	Checkpoint   graph.Checkpointer
	SystemPrompt string
	// contains filtered or unexported fields
}

SubAgent is a graph node that can be embedded into a parent agent as a handoff. It runs a child agent to completion and returns its final messages.

func NewSubAgent 

func NewSubAgent(model any, opts ...AgentOption) (*SubAgent, error)

NewSubAgent builds a SubAgent from a child model and options. The child runs as its own graph; the parent agent exposes it as a tool-like handoff.

func (*SubAgent) AsTool 

func (s *SubAgent) AsTool(name, description string) graph.Tool

AsTool wraps the sub-agent as a handoff tool ready to be bound to a parent agent. The tool input is JSON-decoded into messages and the sub-agent's result is returned as a tool message.

func (*SubAgent) RunNode 

func (s *SubAgent) RunNode(ctx context.Context, state graph.State) (graph.State, error)

RunNode implements graph.NodeFunc, allowing a SubAgent to be added directly to a parent StateGraph as a node.

type ToolCallRequest 

type ToolCallRequest struct {
	// ToolCall is the tool invocation.
	ToolCall graph.ToolCall
	// Step is the current iteration index.
	Step int
}

ToolCallRequest wraps a single tool call for middleware.

type ToolCallResponse 

type ToolCallResponse struct {
	// Message is the tool message produced.
	Message *graph.Message
}

ToolCallResponse is the result of a tool call.

Source Files

View all Source files

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.