Documentation
¶
Overview ¶
Package instruction provides instruction templating for Hector v2 agents.
This package implements adk-go compatible instruction templating, allowing agent instructions to contain dynamic placeholders that are resolved at runtime.
Placeholder Syntax ¶
Placeholders use curly braces and support several forms:
{variable} - Session state variable
{app:variable} - App-scoped state (shared across all users/sessions)
{user:variable} - User-scoped state (shared across sessions for a user)
{temp:variable} - Temporary state (discarded after invocation)
{artifact.filename} - Artifact text content
{variable?} - Optional (empty string if not found, no error)
Usage ¶
Basic usage with InjectState:
template := "Hello {user_name}, you are working on {app:project_name}."
resolved, err := instruction.InjectState(ctx, template)
if err != nil {
return err
}
// resolved: "Hello Alice, you are working on MyProject."
Using the Template type:
tmpl := instruction.New("Task: {task}\nContext: {artifact.context?}")
resolved, err := tmpl.Render(ctx)
Integration with LLM Agents ¶
The instruction package is used by llmagent to resolve instruction templates before sending to the LLM:
agent, _ := llmagent.New(llmagent.Config{
Name: "assistant",
Instruction: `
You are helping {user_name?} with {task}.
Project context:
{artifact.project_context?}
`,
})
Error Handling ¶
Required placeholders (without ?) return an error if not found. Optional placeholders (with ?) return an empty string if not found. Invalid placeholder names (not valid identifiers) are left as-is.
Package instruction provides instruction templating utilities for Hector v2.
Instructions can contain placeholders that are resolved at runtime:
{variable} - resolves from session state
{app:variable} - resolves from app-scoped state
{user:variable} - resolves from user-scoped state
{temp:variable} - resolves from temp-scoped state
{artifact.filename} - resolves artifact text content
{variable?} - optional (empty string if not found)
Example:
instruction := "Hello {user_name}, you are working on {app:project_name}."
resolved, err := instruction.InjectState(ctx, instruction)
Index ¶
Constants ¶
const ( PrefixApp = "app:" PrefixUser = "user:" PrefixTemp = "temp:" )
State key prefixes matching adk-go and session package.
Variables ¶
This section is empty.
Functions ¶
func HasPlaceholders ¶
HasPlaceholders returns true if the template contains any placeholders.
func InjectState ¶
func InjectState(ctx agent.ReadonlyContext, template string) (string, error)
InjectState populates values in an instruction template from context. This is the main entry point for template resolution, matching adk-go's pattern.
Placeholder syntax:
- {variable_name} - resolves from session state
- {app:variable} - resolves from app-scoped state
- {user:variable} - resolves from user-scoped state
- {temp:variable} - resolves from temp-scoped state
- {artifact.filename} - resolves artifact text content
- {variable?} - optional (empty string if not found, no error)
If a required placeholder cannot be resolved, an error is returned. Invalid placeholder names (not matching identifier rules) are left as-is.
func ListPlaceholders ¶
ListPlaceholders returns all placeholder names found in the template.
func MustInjectState ¶
func MustInjectState(ctx agent.ReadonlyContext, template string) string
MustInjectState is like InjectState but panics on error. Use only when you're certain the template is valid.
Source Files