Agent
agent.Agent is the interface implemented by autonomous agents in the Go AI
SDK. It lives in github.com/digitallysavvy/go-ai/pkg/agent, not pkg/ai.
The SDK's concrete implementation is ToolLoopAgent,
created with agent.NewToolLoopAgent.
Signature
type Agent interface {
// Version returns the agent interface specification version.
Version() string
// ID returns the optional agent identifier.
ID() string
// Tools returns the tools that the agent can use.
Tools() []types.Tool
// Generate runs the agent with per-call options and returns the core
// GenerateText result.
Generate(ctx context.Context, opts AgentGenerateOptions) (*ai.GenerateTextResult, error)
// Stream streams the agent with per-call options.
Stream(ctx context.Context, opts AgentStreamOptions) (*ai.StreamTextResult, error)
// Execute runs the agent with the given prompt and returns the final result
Execute(ctx context.Context, prompt string) (*AgentResult, error)
// ExecuteWithMessages runs the agent with a message history
ExecuteWithMessages(ctx context.Context, messages []types.Message) (*AgentResult, error)
}
Return Value
AgentResult
| Field | Type | Description |
|---|---|---|
| Text | string | Final text output |
| Output | interface | Parsed/structured final output when an output strategy is configured |
| Steps | []types.StepResult | All steps taken by the agent |
| ToolResults | []types.ToolResult | All tool results from agent execution |
| Delegations | []agent.SubagentDelegation | Subagent delegations during execution |
| FinishReason | types.FinishReason | Final finish reason |
| StopReason | string | Reason string from the StopCondition that stopped the loop; empty if the agent ended naturally |
| Usage | types.Usage | Total usage across all steps |
| Warnings | []types.Warning | Warnings from any step |
Examples
Basic Agent
package main
import (
"context"
"fmt"
"log"
"github.com/digitallysavvy/go-ai/pkg/agent"
"github.com/digitallysavvy/go-ai/pkg/provider/types"
"github.com/digitallysavvy/go-ai/pkg/providers/openai"
)
func main() {
p := openai.New(openai.Config{
APIKey: "your-api-key",
})
model, _ := p.LanguageModel("gpt-6-astra")
searchTool := types.Tool{
Name: "search",
Description: "Search the web for information",
Parameters: map[string]interface{}{
"type": "object",
"properties": map[string]interface{}{
"query": map[string]interface{}{
"type": "string",
"description": "Search query",
},
},
"required": []string{"query"},
},
Execute: func(ctx context.Context, input map[string]interface{}, opts types.ToolExecutionOptions) (interface{}, error) {
query := input["query"].(string)
return fmt.Sprintf("Search results for: %s", query), nil
},
}
var a agent.Agent = agent.NewToolLoopAgent(agent.AgentConfig{
Model: model,
Tools: []types.Tool{searchTool},
})
result, err := a.Execute(context.Background(), "Find the current weather in Tokyo")
if err != nil {
log.Fatal(err)
}
fmt.Printf("Result: %s\n", result.Text)
fmt.Printf("Steps taken: %d\n", len(result.Steps))
}
Call options (generated)
These tables are generated from the agent.AgentGenerateOptions and agent.AgentStreamOptions source.
AgentGenerateOptions
| Field | Type | Description |
|---|---|---|
Prompt | string | |
Messages | []types.Message | |
System | string | |
Instructions | *string | |
AllowSystemInMessages | bool | AllowSystemInMessages controls whether system-role messages in Messages are accepted instead of requiring Instructions/System. |
RuntimeContext | interface{} | |
ToolsContext | map[string]interface{} | |
CallOptions | interface{} | |
Model | provider.LanguageModel | |
Tools | []types.Tool | |
ToolChoice | types.ToolChoice | |
ToolOrder | []string | |
ActiveTools | []string | |
StopWhen | []ai.StopCondition | |
MaxSteps | int | |
ExperimentalToolCallers | ai.ExperimentalToolCallers | ExperimentalToolCallers configures which tools may call which other tools, and which tools stay hidden until discovered via ai.ToolSearch. Forwarded to the underlying GenerateText/StreamText call. |
Temperature | *float64 | |
MaxTokens | *int | |
TopP | *float64 | |
TopK | *int | |
FrequencyPenalty | *float64 | |
PresencePenalty | *float64 | |
StopSequences | []string | |
Seed | *int | |
Headers | map[string]string | |
Reasoning | *types.ReasoningLevel | |
SendReasoning | *bool | |
ProviderOptions | map[string]interface{} | |
Output | interface{} | |
Telemetry | *ai.TelemetrySettings | |
ExperimentalTelemetry | *ai.TelemetrySettings | |
SensitiveRuntimeContext | bool | SensitiveRuntimeContext omits runtime context from telemetry payloads. |
Include | *ai.IncludeOptions | |
ToolApproval | types.ToolApprovalConfig | |
Internal | *ai.InternalOptions | |
ExperimentalSandbox | interface{} | |
ExperimentalRefineToolInput | map[string]ai.ToolInputRefiner | |
ExperimentalDownload | ai.DownloadFunction | |
HarnessSession | interface{} | HarnessSession is the extension point a harness.HarnessAgent (see pkg/harness) uses to receive the *harness.AgentSession its caller created via HarnessAgent.CreateSession. Typed as interface{} (rather than a pkg/harness type) to avoid an import cycle: pkg/harness imports this package so HarnessAgent can satisfy the Agent interface. Other Agent implementations ignore this field. Mirrors the way TS AgentCallParameters carries a session for HarnessAgent's generate/stream (state/parity/sep_23_2026/harness.md §1.3, "the session is passed via options"). See harness.SessionFromCallOptions. |
InstructionMessages | []types.Message | InstructionMessages supplies this call's instructions as system messages. Takes precedence over Instructions/System/Prompt when non-empty. See AgentConfig.InstructionMessages. |
PrepareStep | func(ctx context.Context, step ai.PrepareStepOptions) ai.PrepareStepOptions | PrepareStep overrides AgentConfig.PrepareStep for this call. |
RepairToolCall | ai.ToolCallRepairFunction | RepairToolCall overrides AgentConfig.RepairToolCall for this call. |
ExperimentalRepairToolCall | ai.ToolCallRepairFunction | Deprecated: use RepairToolCall. |
OnLanguageModelCallStart | ai.OnLanguageModelCallStartCallback | OnLanguageModelCallStart overrides AgentConfig.OnLanguageModelCallStart for this call. |
ExperimentalOnLanguageModelCallStart | ai.OnLanguageModelCallStartCallback | Deprecated: use OnLanguageModelCallStart. |
OnLanguageModelCallEnd | ai.OnLanguageModelCallEndCallback | OnLanguageModelCallEnd overrides AgentConfig.OnLanguageModelCallEnd for this call. |
ExperimentalOnLanguageModelCallEnd | ai.OnLanguageModelCallEndCallback | Deprecated: use OnLanguageModelCallEnd. |
OnStart | func(ctx context.Context, e ai.OnStartEvent) | |
OnStepStart | func(ctx context.Context, e ai.OnStepStartEvent) | |
OnToolExecutionStart | func(ctx context.Context, e ai.OnToolCallStartEvent) | |
OnToolExecutionEnd | func(ctx context.Context, e ai.OnToolCallFinishEvent) | |
OnToolCallStart | func(ctx context.Context, e ai.OnToolCallStartEvent) | Deprecated: use OnToolExecutionStart. |
OnToolCallFinish | func(ctx context.Context, e ai.OnToolCallFinishEvent) | Deprecated: use OnToolExecutionEnd. |
OnStepEnd | func(ctx context.Context, e ai.OnStepFinishEvent) | |
OnStepFinish | func(ctx context.Context, e ai.OnStepFinishEvent) | Deprecated: use OnStepEnd. |
OnEnd | func(ctx context.Context, e ai.OnFinishEvent) | |
OnFinish | func(ctx context.Context, e ai.OnFinishEvent) | Deprecated: use OnEnd. |
AgentStreamOptions
| Field | Type | Description |
|---|---|---|
| (embedded) | AgentGenerateOptions | Embedded. |
OnChunk | func(chunk provider.StreamChunk) | |
InitialStreamChunks | []provider.StreamChunk | |
ExperimentalTransform | []ai.StreamTransformFunc | ExperimentalTransform is an ordered list of transforms applied to stream chunks before they reach OnChunk and the returned StreamTextResult, forwarded to ai.StreamTextOptions.ExperimentalTransform. |
Set ExperimentalToolApprovalSecret on agent.AgentConfig (or per call on agent.PrepareCallConfig) to sign approval requests and verify approval responses. See ToolLoopAgent.
See Also
- ToolLoopAgent - The SDK's concrete
Agentimplementation - Tool - Tool definition
- Agents Guide