AI SDK
DocsProvidersGuides
DocumentationReferenceTroubleshootingProvidersGuidesChangelog

Agent

A model, its instructions, and its tools bundled into one reusable object.

Everything you would otherwise pass to generateText on every call, held in one value you configure once and call many times. The properties mirror that function's parameters exactly, so anything you can do there you can do here.

Reach for it when the same setup runs more than once: a support agent, a code reviewer, a research step in a larger pipeline. For a single one-off call, the free functions are less ceremony.

An agent can also become a tool for another agent via asTool, which is how you build a supervisor that delegates to specialists.

let researcher = Agent(
  model: AnthropicModel("claude-sonnet-5"),
  instructions: "You research questions and cite your sources.",
  tools: [webSearch]
)

let result = try await researcher.generate(prompt: "Who first isolated neon?")

Declaration

public struct Agent

Defined in Sources/AI/Core/Agent.swift.

Initializer

init(
    model: any LanguageModel,
    instructions: String? = nil,
    tools: [any AIToolProtocol] = [],
    toolChoice: ToolChoice = .auto,
    activeTools: [String]? = nil,
    toolOrder: [String]? = nil,
    toolsContext: [String: JSONValue] = [:],
    maxOutputTokens: Int = 1024,
    temperature: Double? = nil,
    topP: Double? = nil,
    topK: Int? = nil,
    presencePenalty: Double? = nil,
    frequencyPenalty: Double? = nil,
    seed: Int? = nil,
    reasoning: ReasoningEffort = .providerDefault,
    stopWhen: [StopCondition]? = nil,
    maxSteps: Int = 8,
    prepareCall: PrepareCall? = nil,
    prepareStep: PrepareStep? = nil,
    onStepFinish: OnStepFinish? = nil,
    maxRetries: Int = 2,
    providerOptions: JSONValue? = nil,
    toolApproval: ToolApprovalPolicy? = nil,
    toolApprovalSecret: String? = nil,
    timeout: GenerationTimeout? = nil,
    runtimeContext: JSONValue? = nil,
    telemetry: TelemetrySettings? = nil,
    compaction: Compaction? = nil
)

Properties

PropertyTypeDefault
var modelany LanguageModel—
var instructionsString?—
var tools[any AIToolProtocol]—
var toolChoiceToolChoice—
var activeTools[String]?—
var toolOrder[String]?—
var toolsContext[String: JSONValue]—
var maxOutputTokensInt—
var temperatureDouble?—
var topPDouble?—
var topKInt?—
var presencePenaltyDouble?—
var frequencyPenaltyDouble?—
var seedInt?—
var reasoningReasoningEffort—
var stopWhen[StopCondition]?—
var maxStepsInt—
var prepareCallPrepareCall?—
var prepareStepPrepareStep?—
var onStepFinishOnStepFinish?—
var maxRetriesInt—
var providerOptionsJSONValue?—
var toolApprovalToolApprovalPolicy?—
var toolApprovalSecretString?—
var timeoutGenerationTimeout?—
var runtimeContextJSONValue?—
var telemetryTelemetrySettings?—
var compactionCompaction?—

Methods

func generate(
    prompt: String
) async throws -> GenerateTextResult
func generate(
    messages: [Message]
) async throws -> GenerateTextResult
func stream(
    prompt: String
) -> StreamTextResult
func stream(
    messages: [Message]
) -> StreamTextResult
func asTool(
    name: String,
    description: String,
    promptDescription: String = "The task for the agent to perform."
) -> Tool

See also

uploadFile

Upload a file to a provider and get a reference back.

ContentPart

One piece of a message: text, an image, a file, a tool call, a result, or reasoning.

On this page

DeclarationInitializerPropertiesMethodsSee also