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-4")

    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))
}

See Also

• ToolLoopAgent - The SDK's concrete Agent implementation
• Tool - Tool definition
• Agents Guide