Skip to main content

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​

FieldTypeDescription
TextstringFinal text output
OutputinterfaceParsed/structured final output when an output strategy is configured
Steps[]types.StepResultAll steps taken by the agent
ToolResults[]types.ToolResultAll tool results from agent execution
Delegations[]agent.SubagentDelegationSubagent delegations during execution
FinishReasontypes.FinishReasonFinal finish reason
StopReasonstringReason string from the StopCondition that stopped the loop; empty if the agent ended naturally
Usagetypes.UsageTotal usage across all steps
Warnings[]types.WarningWarnings 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​

FieldTypeDescription
Promptstring
Messages[]types.Message
Systemstring
Instructions*string
AllowSystemInMessagesboolAllowSystemInMessages controls whether system-role messages in Messages are accepted instead of requiring Instructions/System.
RuntimeContextinterface{}
ToolsContextmap[string]interface{}
CallOptionsinterface{}
Modelprovider.LanguageModel
Tools[]types.Tool
ToolChoicetypes.ToolChoice
ToolOrder[]string
ActiveTools[]string
StopWhen[]ai.StopCondition
MaxStepsint
ExperimentalToolCallersai.ExperimentalToolCallersExperimentalToolCallers 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
Headersmap[string]string
Reasoning*types.ReasoningLevel
SendReasoning*bool
ProviderOptionsmap[string]interface{}
Outputinterface{}
Telemetry*ai.TelemetrySettings
ExperimentalTelemetry*ai.TelemetrySettings
SensitiveRuntimeContextboolSensitiveRuntimeContext omits runtime context from telemetry payloads.
Include*ai.IncludeOptions
ToolApprovaltypes.ToolApprovalConfig
Internal*ai.InternalOptions
ExperimentalSandboxinterface{}
ExperimentalRefineToolInputmap[string]ai.ToolInputRefiner
ExperimentalDownloadai.DownloadFunction
HarnessSessioninterface{}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.MessageInstructionMessages supplies this call's instructions as system messages. Takes precedence over Instructions/System/Prompt when non-empty. See AgentConfig.InstructionMessages.
PrepareStepfunc(ctx context.Context, step ai.PrepareStepOptions) ai.PrepareStepOptionsPrepareStep overrides AgentConfig.PrepareStep for this call.
RepairToolCallai.ToolCallRepairFunctionRepairToolCall overrides AgentConfig.RepairToolCall for this call.
ExperimentalRepairToolCallai.ToolCallRepairFunctionDeprecated: use RepairToolCall.
OnLanguageModelCallStartai.OnLanguageModelCallStartCallbackOnLanguageModelCallStart overrides AgentConfig.OnLanguageModelCallStart for this call.
ExperimentalOnLanguageModelCallStartai.OnLanguageModelCallStartCallbackDeprecated: use OnLanguageModelCallStart.
OnLanguageModelCallEndai.OnLanguageModelCallEndCallbackOnLanguageModelCallEnd overrides AgentConfig.OnLanguageModelCallEnd for this call.
ExperimentalOnLanguageModelCallEndai.OnLanguageModelCallEndCallbackDeprecated: use OnLanguageModelCallEnd.
OnStartfunc(ctx context.Context, e ai.OnStartEvent)
OnStepStartfunc(ctx context.Context, e ai.OnStepStartEvent)
OnToolExecutionStartfunc(ctx context.Context, e ai.OnToolCallStartEvent)
OnToolExecutionEndfunc(ctx context.Context, e ai.OnToolCallFinishEvent)
OnToolCallStartfunc(ctx context.Context, e ai.OnToolCallStartEvent)Deprecated: use OnToolExecutionStart.
OnToolCallFinishfunc(ctx context.Context, e ai.OnToolCallFinishEvent)Deprecated: use OnToolExecutionEnd.
OnStepEndfunc(ctx context.Context, e ai.OnStepFinishEvent)
OnStepFinishfunc(ctx context.Context, e ai.OnStepFinishEvent)Deprecated: use OnStepEnd.
OnEndfunc(ctx context.Context, e ai.OnFinishEvent)
OnFinishfunc(ctx context.Context, e ai.OnFinishEvent)Deprecated: use OnEnd.

AgentStreamOptions​

FieldTypeDescription
(embedded)AgentGenerateOptionsEmbedded.
OnChunkfunc(chunk provider.StreamChunk)
InitialStreamChunks[]provider.StreamChunk
ExperimentalTransform[]ai.StreamTransformFuncExperimentalTransform 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​