Documentation
¶
Overview ¶
Package glue provides the public API for defining and running agents.
It is intentionally thin over the lower-level loop package. Users construct an Agent with NewAgent, open a named Session with Agent.Session, and drive turns with Session.Prompt. Provider implementations live in subpackages (initially providers/gemini), and session persistence is provided by stores subpackages (initially stores/file).
Normalized message and event types are re-exported here so that callers only need to import "github.com/erain/glue".
Index ¶
- Constants
- type Agent
- type AgentOptions
- type Compactor
- type CompactorFunc
- type ContentPart
- type ContentType
- type Event
- type EventType
- type ImageContent
- type Message
- type MessageRole
- type ProjectContext
- type PromptOption
- func WithEvents(handler func(Event)) PromptOption
- func WithJSONSchema(schema any) PromptOption
- func WithMaxTurns(maxTurns int) PromptOption
- func WithModel(model string) PromptOption
- func WithProviderOptions(options map[string]any) PromptOption
- func WithRole(role string) PromptOption
- func WithSystemPrompt(systemPrompt string) PromptOption
- func WithTools(tools []Tool) PromptOption
- type PromptResult
- type Provider
- type ProviderEvent
- type ProviderEventType
- type ProviderRequest
- type Role
- type Session
- func (s *Session) ID() string
- func (s *Session) Messages() []Message
- func (s *Session) Prompt(ctx context.Context, text string, options ...PromptOption) (PromptResult, error)
- func (s *Session) PromptJSON(ctx context.Context, text string, outPtr any, options ...PromptOption) (PromptResult, error)
- func (s *Session) Skill(ctx context.Context, name string, args any, options ...PromptOption) (PromptResult, error)
- func (s *Session) State() SessionState
- func (s *Session) Subscribe(handler func(Event)) func()
- type SessionOption
- type SessionState
- type Skill
- type StopReason
- type Store
- type Tool
- type ToolCall
- type ToolExecutor
- type ToolResult
- type ToolSpec
- type Usage
Constants ¶
const ( MessageRoleUser = loop.MessageRoleUser MessageRoleAssistant = loop.MessageRoleAssistant MessageRoleTool = loop.MessageRoleTool )
MessageRole constants re-exported from package loop.
const ( ContentTypeText = loop.ContentTypeText ContentTypeThinking = loop.ContentTypeThinking ContentTypeImage = loop.ContentTypeImage ContentTypeToolCall = loop.ContentTypeToolCall )
ContentType constants re-exported from package loop.
const ( StopReasonStop = loop.StopReasonStop StopReasonLength = loop.StopReasonLength StopReasonToolUse = loop.StopReasonToolUse StopReasonError = loop.StopReasonError StopReasonCanceled = loop.StopReasonCanceled )
StopReason constants re-exported from package loop.
const ( EventLoopStart = loop.EventLoopStart EventLoopEnd = loop.EventLoopEnd EventTurnStart = loop.EventTurnStart EventTurnEnd = loop.EventTurnEnd EventMessageStart = loop.EventMessageStart EventMessageEnd = loop.EventMessageEnd EventTextDelta = loop.EventTextDelta EventToolStart = loop.EventToolStart EventToolEnd = loop.EventToolEnd EventError = loop.EventError )
EventType constants re-exported from package loop.
const ( ProviderEventStart = loop.ProviderEventStart ProviderEventTextDelta = loop.ProviderEventTextDelta ProviderEventThinkingDelta = loop.ProviderEventThinkingDelta ProviderEventToolCall = loop.ProviderEventToolCall ProviderEventDone = loop.ProviderEventDone ProviderEventError = loop.ProviderEventError )
ProviderEventType constants re-exported from package loop.
const SessionStateVersion = 1
SessionStateVersion is the on-disk version tag for SessionState.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Agent ¶
type Agent struct {
// contains filtered or unexported fields
}
Agent owns shared configuration and an in-memory session map.
func NewAgent ¶
func NewAgent(options AgentOptions) *Agent
NewAgent creates an agent. When AgentOptions.Store is set, sessions are loaded from and saved to that store; otherwise sessions are in-memory. The Provider must be supplied for Session.Prompt to succeed.
type AgentOptions ¶
type AgentOptions struct {
Provider Provider
Model string
SystemPrompt string
Tools []Tool
Options map[string]any
MaxTurns int
Store Store
WorkDir string
Skills map[string]Skill
Roles []Role
Role string
// Compactor, if non-nil and CompactionThreshold > 0, is invoked
// before every prompt whenever the in-memory transcript has more
// than CompactionThreshold messages. The compactor's output replaces
// the in-memory transcript before [loop.Run] is called and is
// persisted by the next save.
Compactor Compactor
CompactionThreshold int
}
AgentOptions configures a Glue agent.
All fields are wired. When WorkDir is set, the agent loads `<WorkDir>/AGENTS.md` (non-fatal if missing), discovers Markdown skills under `<WorkDir>/.agents/skills/<name>/SKILL.md`, and discovers Markdown roles under `<WorkDir>/roles/*.md`. Programmatic entries supplied via Skills and Roles are merged with the on-disk catalog; programmatic entries win on name collision.
Role is the agent-default role applied to every prompt unless overridden at session or call level. Effective role precedence is call (WithRole) > session (WithSessionRole) > agent (Role). Effective model precedence is call (WithModel) > effective role's Model > Model.
type Compactor ¶
Compactor rewrites a session transcript before it is sent to the provider. Implementations should preserve the user's most recent intent and the assistant context that depends on it; older turns can be dropped, summarized, or replaced. Compactors must not mutate the input slice; they return a new slice.
func KeepRecentMessages ¶
KeepRecentMessages returns a Compactor that keeps the last n messages of a transcript and replaces everything older with a single system-style summary message that records how many turns were dropped.
This is the simplest useful compaction policy: it has no token model and never calls a provider. It is appropriate when a session is allowed to accumulate but the caller can tolerate losing older context past a fixed window.
n must be positive. If the input transcript has n or fewer messages, the compactor returns it unchanged.
type CompactorFunc ¶
CompactorFunc adapts a function to the Compactor interface.
type ContentPart ¶
type ContentPart = loop.ContentPart
Re-export the loop package's normalized types as part of the public API so callers only need to import `glue`.
type ContentType ¶
type ContentType = loop.ContentType
Re-export the loop package's normalized types as part of the public API so callers only need to import `glue`.
type Event ¶
Re-export the loop package's normalized types as part of the public API so callers only need to import `glue`.
type EventType ¶
Re-export the loop package's normalized types as part of the public API so callers only need to import `glue`.
type ImageContent ¶
type ImageContent = loop.ImageContent
Re-export the loop package's normalized types as part of the public API so callers only need to import `glue`.
type Message ¶
Re-export the loop package's normalized types as part of the public API so callers only need to import `glue`.
type MessageRole ¶
type MessageRole = loop.MessageRole
Re-export the loop package's normalized types as part of the public API so callers only need to import `glue`.
type ProjectContext ¶
ProjectContext is the WorkDir-loaded state injected by LoadContext. AgentsMD is appended to the system prompt; Skills are exposed via Session.Skill; Roles are looked up by name during prompt configuration.
func LoadContext ¶
func LoadContext(workDir string) (ProjectContext, error)
LoadContext loads AGENTS.md (non-fatal if missing) and skills under `<workDir>/.agents/skills/<name>/SKILL.md`. An empty workDir returns an empty context.
type PromptOption ¶
type PromptOption func(*promptConfig)
PromptOption configures one Session.Prompt invocation.
func WithEvents ¶
func WithEvents(handler func(Event)) PromptOption
WithEvents registers a per-prompt event handler. It receives every loop event for that prompt in addition to any session-scoped subscribers installed via Session.Subscribe.
func WithJSONSchema ¶
func WithJSONSchema(schema any) PromptOption
WithJSONSchema attaches a JSON Schema for Session.PromptJSON. The schema may be passed as a Go value (map / struct), a json.RawMessage, a []byte, or a string; bytes/string forms are JSON-decoded once. When the active provider supports structured output, the schema is forwarded as the provider's structured-response config (Gemini: `response_json_schema`).
func WithMaxTurns ¶
func WithMaxTurns(maxTurns int) PromptOption
WithMaxTurns overrides the loop max-turn guard for one prompt.
func WithModel ¶
func WithModel(model string) PromptOption
WithModel overrides the model for one prompt. When set, this beats any role's Model and the agent's Model.
func WithProviderOptions ¶
func WithProviderOptions(options map[string]any) PromptOption
WithProviderOptions replaces provider options for one prompt.
func WithRole ¶
func WithRole(role string) PromptOption
WithRole overrides the effective role for one prompt. The named role must exist in AgentOptions.Roles or the loaded WorkDir context, or the prompt fails with a typed error.
func WithSystemPrompt ¶
func WithSystemPrompt(systemPrompt string) PromptOption
WithSystemPrompt overrides the agent system prompt for one prompt.
func WithTools ¶
func WithTools(tools []Tool) PromptOption
WithTools replaces the agent tools for one prompt.
type PromptResult ¶
type PromptResult struct {
// Text concatenates all text parts of the final assistant message.
Text string
// Message is the final assistant message of this run, cloned. Nil if no
// assistant message was produced.
Message *Message
// NewMessages contains every message produced during this run, in append
// order (assistant + tool messages, possibly across multiple turns).
NewMessages []Message
// Messages is a snapshot of the full session transcript after this run.
Messages []Message
}
PromptResult is returned by Session.Prompt.
type Provider ¶
Re-export the loop package's normalized types as part of the public API so callers only need to import `glue`.
type ProviderEvent ¶
type ProviderEvent = loop.ProviderEvent
Re-export the loop package's normalized types as part of the public API so callers only need to import `glue`.
type ProviderEventType ¶
type ProviderEventType = loop.ProviderEventType
Re-export the loop package's normalized types as part of the public API so callers only need to import `glue`.
type ProviderRequest ¶
type ProviderRequest = loop.ProviderRequest
Re-export the loop package's normalized types as part of the public API so callers only need to import `glue`.
type Role ¶
Role is a named instruction profile with an optional model override. Roles are loaded from `<WorkDir>/roles/*.md` (with `name:`, `description:`, `model:` frontmatter) or supplied via AgentOptions.Roles.
type Session ¶
type Session struct {
// contains filtered or unexported fields
}
Session is an in-memory conversation with an Agent. Sessions are goroutine-safe but a single session executes one Session.Prompt at a time.
func (*Session) Prompt ¶
func (s *Session) Prompt(ctx context.Context, text string, options ...PromptOption) (PromptResult, error)
Prompt sends a user message through the agent loop and stores the resulting transcript in memory.
func (*Session) PromptJSON ¶
func (s *Session) PromptJSON(ctx context.Context, text string, outPtr any, options ...PromptOption) (PromptResult, error)
PromptJSON sends a prompt and decodes the assistant's final text into outPtr, which must be a non-nil pointer. It augments the user prompt with JSON-only instructions so non-Gemini providers can still produce parseable output, and sets `response_mime_type: application/json` on the provider request. When WithJSONSchema is provided, the schema is also forwarded as `response_json_schema`.
V1 validation is intentionally limited to JSON decoding into the caller's Go type; full JSON Schema validation is out of scope.
func (*Session) Skill ¶
func (s *Session) Skill(ctx context.Context, name string, args any, options ...PromptOption) (PromptResult, error)
Skill renders the named skill (looked up from AgentOptions.Skills or the agent's WorkDir context), appends args as JSON, and runs the result through Session.Prompt. Unknown skill names return a typed error.
func (*Session) State ¶
func (s *Session) State() SessionState
State returns a snapshot of the durable session state.
type SessionOption ¶
type SessionOption func(*sessionConfig)
SessionOption configures a session at creation time.
func WithSessionRole ¶
func WithSessionRole(role string) SessionOption
WithSessionRole sets the session-default role used when no per-call WithRole is provided.
type SessionState ¶
type SessionState struct {
Version int `json:"version"`
ID string `json:"id"`
Messages []Message `json:"messages,omitempty"`
Metadata map[string]any `json:"metadata,omitempty"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
}
SessionState is the durable representation of a session.
type Skill ¶
Skill is a Markdown-defined reusable prompt loaded from `<WorkDir>/.agents/skills/<name>/SKILL.md` or supplied directly via AgentOptions.Skills.
type StopReason ¶
type StopReason = loop.StopReason
Re-export the loop package's normalized types as part of the public API so callers only need to import `glue`.
type Store ¶
type Store interface {
Load(ctx context.Context, id string) (SessionState, bool, error)
Save(ctx context.Context, id string, state SessionState) error
Delete(ctx context.Context, id string) error
}
Store persists Glue session state. Implementations are expected to be goroutine-safe across distinct session ids; concurrent calls for the same id within a single session are serialized by the session itself.
Load returns found=false when the id is not present, with a zero-valued SessionState and a nil error. Save must be atomic against partial writes. Delete must be idempotent — removing a missing id is a no-op success.
type Tool ¶
Re-export the loop package's normalized types as part of the public API so callers only need to import `glue`.
type ToolCall ¶
Re-export the loop package's normalized types as part of the public API so callers only need to import `glue`.
type ToolExecutor ¶
type ToolExecutor = loop.ToolExecutor
Re-export the loop package's normalized types as part of the public API so callers only need to import `glue`.
type ToolResult ¶
type ToolResult = loop.ToolResult
Re-export the loop package's normalized types as part of the public API so callers only need to import `glue`.
Directories
¶
| Path | Synopsis |
|---|---|
|
agents
|
|
|
glue-review
command
Command glue-review is a free, local pre-push branch reviewer built on the Glue agent harness.
|
Command glue-review is a free, local pre-push branch reviewer built on the Glue agent harness. |
|
cmd
|
|
|
glue
command
Command glue is the local CLI runner for Glue agents.
|
Command glue is the local CLI runner for Glue agents. |
|
examples
|
|
|
echo-provider
Package echo is a minimal example of a custom Glue provider.
|
Package echo is a minimal example of a custom Glue provider. |
|
local-agent
command
Command local-agent is a small Gemini-backed CLI built directly on the glue library.
|
Command local-agent is a small Gemini-backed CLI built directly on the glue library. |
|
Package loop contains Glue's provider-agnostic agent loop.
|
Package loop contains Glue's provider-agnostic agent loop. |
|
providers
|
|
|
gemini
Package gemini adapts Google's Gemini API to Glue's provider interface.
|
Package gemini adapts Google's Gemini API to Glue's provider interface. |
|
nvidia
Package nvidia implements a Glue provider for the NVIDIA build inference API (https://build.nvidia.com), which exposes an OpenAI-compatible chat-completions endpoint at https://integrate.api.nvidia.com/v1.
|
Package nvidia implements a Glue provider for the NVIDIA build inference API (https://build.nvidia.com), which exposes an OpenAI-compatible chat-completions endpoint at https://integrate.api.nvidia.com/v1. |
|
openaicompat
Package openaicompat implements the shared streaming, tool-call, and convert logic for OpenAI-style chat-completions endpoints used by the concrete providers under providers/.
|
Package openaicompat implements the shared streaming, tool-call, and convert logic for OpenAI-style chat-completions endpoints used by the concrete providers under providers/. |
|
openrouter
Package openrouter implements a Glue provider for OpenRouter (https://openrouter.ai), an OpenAI-compatible aggregator that routes requests across many underlying model providers.
|
Package openrouter implements a Glue provider for OpenRouter (https://openrouter.ai), an OpenAI-compatible aggregator that routes requests across many underlying model providers. |
|
stores
|
|
|
file
Package file provides a local JSON-backed session store for Glue.
|
Package file provides a local JSON-backed session store for Glue. |