> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ko/llms.txt

# Agent.생성()

그만큼`.generate()`방법을 사용하면 향상된 기능을 갖춘 Agent에서 비스트리밍 응답 생성이 가능합니다. 메시지와 선택적 생성 옵션을 허용합니다.

## 사용예

응답을 생성하려면 메시지로 Agent를 호출하세요.

```ts
const result = await agent.generate('message for agent')
```

## 매개변수

**messages** (`string | string[] | CoreMessage[] | AiMessageType[] | UIMessageWithMetadata[]`): Agent에 보낼 메시지입니다. 단일 문자열, 문자열 배열 또는 구조화된 메시지 객체를 사용할 수 있습니다.

**options** (`AgentExecutionOptions<Output, Format>`): 생성 프로세스의 선택적 구성입니다.

**options.maxSteps** (`number`): 실행 중 수행할 최대 단계 수입니다.

**options.stopWhen** (`LoopOptions['stopWhen']`): 실행을 중지하는 조건입니다(예: 단계 수, 토큰 한도).

**options.onIterationComplete** (`(context: IterationCompleteContext) => { continue?: boolean; feedback?: string } | void | Promise<{ continue?: boolean; feedback?: string } | void>`): 각 반복이 완료된 후 호출되는 콜백 함수입니다. 진행 상황을 모니터링하거나, Agent를 안내하는 피드백을 제공하거나, 실행을 조기에 중지할 때 사용하세요. 콜백은 현재 텍스트, Tool 호출, 완료 사유 등 반복에 관한 컨텍스트를 받습니다.

**options.onIterationComplete.context.iteration** (`number`): 현재 반복 번호입니다(1부터 시작).

**options.onIterationComplete.context.maxIterations** (`number | undefined`): 허용되는 최대 반복 횟수입니다(설정된 경우).

**options.onIterationComplete.context.text** (`string`): 이 반복에서 생성된 텍스트 응답입니다.

**options.onIterationComplete.context.isFinal** (`boolean`): 이 반복이 마지막 반복인지 여부입니다.

**options.onIterationComplete.context.finishReason** (`string`): 이 반복이 완료된 이유입니다(예: 'stop', 'length', 'tool-calls').

**options.onIterationComplete.context.toolCalls** (`ToolCall[]`): 이 반복에서 수행된 Tool 호출입니다.

**options.onIterationComplete.context.messages** (`MastraDBMessage[]`): 지금까지 누적된 모든 메시지입니다.

**options.onIterationComplete.return.continue** (`boolean`): 실행을 조기에 중지하려면 false로 설정합니다.

**options.onIterationComplete.return.feedback** (`string`): Agent의 다음 반복을 안내하는 피드백 메시지입니다.

**options.isTaskComplete** (`IsTaskCompleteConfig`): 작업 완료 여부를 검증하는 완료 점수 산정 구성입니다. Mastra의 평가 스코어러를 사용하여 Agent의 응답이 완료 기준을 충족하는지 자동으로 확인합니다.

**options.isTaskComplete.scorers** (`MastraScorer[]`): 작업 완료 여부를 평가하는 스코어러 배열입니다. 각 스코어러는 0(실패) 또는 1(통과)을 반환합니다.

**options.isTaskComplete.strategy** (`'all' | 'any'`): 스코어러 결과를 결합하는 전략입니다. 'all'은 모든 스코어러가 통과해야 하고, 'any'는 하나 이상이 통과해야 합니다.

**options.isTaskComplete.onComplete** (`(result: IsTaskCompleteRunResult) => void | Promise<void>`): 작업 완료 검사가 끝나면 호출되는 콜백입니다. 개별 스코어러 점수가 포함된 결과를 받습니다.

**options.isTaskComplete.parallel** (`boolean`): 스코어러를 병렬로 실행할지 여부입니다.

**options.isTaskComplete.timeout** (`number`): 모든 스코어러가 완료될 때까지 기다리는 최대 시간(밀리초)입니다.

**options.delegation** (`DelegationConfig`): 하위 Agent 위임을 위한 구성입니다. Agent가 다른 Agent에 작업을 위임하는 시점을 제어하고 모니터링하는 데 사용합니다. 위임을 수정하거나 거부하고, 감독 Agent를 안내하는 피드백을 제공하는 기능도 포함됩니다.

**options.delegation.onDelegationStart** (`(context: DelegationStartContext) => DelegationStartResult | void | Promise<DelegationStartResult | void>`): 하위 Agent에 위임하기 전에 호출됩니다. 위임 매개변수를 수정하거나, 위임을 완전히 거부하거나, context.requestContext를 변경하여 하위 Agent 실행의 요청 컨텍스트에 항목을 추가할 때 사용하세요.

**options.delegation.onDelegationComplete** (`(context: DelegationCompleteContext) => { feedback?: string } | void | Promise<{ feedback?: string } | void>`): 하위 Agent 위임이 완료된 후 호출됩니다. 컨텍스트에는 추가 실행을 중지하는 bail() 메서드가 포함되며, { feedback }을 반환하여 감독자의 다음 작업을 안내할 수 있습니다. 피드백은 감독자의 Memory에 assistant 메시지로 저장됩니다.

**options.delegation.messageFilter** (`(context: MessageFilterContext) => MastraDBMessage[] | Promise<MastraDBMessage[]>`): 하위 Agent에 위임하기 전에 호출되는 콜백 함수입니다. 하위 Agent에 전달되는 메시지를 필터링하는 데 사용합니다.

**options.scorers** (`MastraScorers | Record<string, { scorer: MastraScorer['name']; sampling?: ScoringSamplingConfig }>`): 실행 결과에 적용할 평가 채점기입니다.

**options.scorers.scorer** (`string`): 사용할 채점기의 이름입니다.

**options.scorers.sampling** (`ScoringSamplingConfig`): 채점기의 샘플링 구성입니다.

**options.scorers.sampling.type** (`'none' | 'ratio'`): 샘플링 전략의 유형입니다. 샘플링을 비활성화하려면 'none'을, 백분율 기반 샘플링에는 'ratio'를 사용합니다.

**options.scorers.sampling.rate** (`number`): 샘플링 비율(0\~1)입니다. type이 'ratio'일 때 필수입니다.

**options.returnScorerData** (`boolean`): 응답에 상세 채점 데이터를 반환할지 여부입니다.

**options.onChunk** (`(chunk: ChunkType) => Promise<void> | void`): 생성 중 각 청크에 대해 호출되는 콜백 함수입니다.

**options.onError** (`({ error }: { error: Error | string }) => Promise<void> | void`): 생성 중 오류가 발생할 때 호출되는 콜백 함수입니다.

**options.onAbort** (`(event: any) => Promise<void> | void`): 생성이 중단될 때 호출되는 콜백 함수입니다.

**options.activeTools** (`Array<keyof ToolSet> | undefined`): 실행 중 활성화할 Tool 이름의 배열입니다. undefined이면 사용 가능한 모든 Tool이 활성화됩니다.

**options.abortSignal** (`AbortSignal`): Agent 실행을 중단할 수 있는 신호 객체입니다. 신호가 중단되면 Agent가 위임하여 진행 중인 모든 하위 Agent 실행을 포함해 진행 중인 모든 작업이 종료됩니다.

**options.prepareStep** (`PrepareStepFunction`): 다단계 실행의 각 단계 전에 호출되는 콜백 함수입니다.

**options.requireToolApproval** (`boolean`): true이면 모든 Tool 호출을 실행하기 전에 명시적인 승인이 필요합니다. generate() 메서드는 finishReason: 'suspended'와 함께 반환되며 Tool 호출 세부 정보(toolCallId, toolName, args)가 담긴 suspendPayload를 포함합니다. 계속하려면 approveToolCallGenerate() 또는 declineToolCallGenerate()를 사용합니다. 자세한 내용은 Agent 승인을 참조하세요.

**options.autoResumeSuspendedTools** (`boolean`): true이면 사용자가 같은 스레드에 새 메시지를 보낼 때 일시 중단된 Tool을 자동으로 재개합니다. Agent는 Tool의 resumeSchema를 기반으로 사용자 메시지에서 resumeData를 추출합니다. Memory를 구성해야 합니다.

**options.toolCallConcurrency** (`number`): 동시에 실행할 수 있는 Tool 호출의 최대 개수입니다. 승인이 필요할 수 있으면 기본값은 1이고, 그렇지 않으면 10입니다.

**options.context** (`ModelMessage[]`): Agent에 제공할 추가 컨텍스트 메시지입니다.

**options.structuredOutput** (`StructuredOutputOptions<S extends ZodTypeAny = ZodTypeAny>`): 구조화된 출력 생성을 세부 조정하는 옵션입니다.

**options.structuredOutput.schema** (`StandardJSONSchemaV1`): 예상 출력 구조를 정의하는 표준 JSON Schema입니다.

**options.structuredOutput.model** (`MastraLanguageModel`): 구조화된 출력 생성에 사용할 언어 Model입니다. 제공하면 Agent가 Tool 호출, 텍스트, 구조화된 출력을 포함한 다단계 응답을 생성할 수 있습니다.

**options.structuredOutput.errorStrategy** (`'strict' | 'warn' | 'fallback'`): 스키마 검증 오류를 처리하는 전략입니다. 'strict'는 오류를 발생시키고, 'warn'은 경고를 기록하며, 'fallback'은 대체 값을 사용합니다.

**options.structuredOutput.fallbackValue** (`<S extends ZodTypeAny>`): 스키마 검증에 실패하고 errorStrategy가 'fallback'일 때 사용할 대체 값입니다.

**options.structuredOutput.instructions** (`string`): 구조화된 출력 Model에 제공할 추가 지침입니다.

**options.structuredOutput.jsonPromptInjection** (`boolean | 'system' | 'inline' | 'auto'`): JSON 스키마가 Model에 전달되는 방식을 제어합니다. 지원되는 경우 네이티브 구조화 출력을 사용하고, 그렇지 않으면 인라인 Prompt 삽입을 사용하려면 'auto'로 설정합니다.

**options.structuredOutput.logger** (`IMastraLogger`): 출력 생성 중 구조화된 로깅에 사용할 선택적 로거 인스턴스입니다.

**options.structuredOutput.providerOptions** (`ProviderOptions`): 내부 구조화 Agent에 전달되는 Provider별 옵션입니다. 사고 Model의 추론 노력 수준과 같은 Model 동작을 제어하는 데 사용합니다(예: { openai: { reasoningEffort: 'low' } }).

**options.outputProcessors** (`OutputProcessorOrWorkflow[]`): 이 실행에 사용할 출력 프로세서입니다(Agent의 기본값을 재정의함).

**options.maxProcessorRetries** (`number`): 이 생성에서 프로세서가 재시도를 트리거할 수 있는 최대 횟수입니다. Agent의 기본 maxProcessorRetries를 재정의합니다.

**options.inputProcessors** (`InputProcessorOrWorkflow[]`): 이 실행에 사용할 입력 프로세서입니다(Agent의 기본값을 재정의함).

**options.instructions** (`string | string[] | CoreSystemMessage | SystemModelMessage | CoreSystemMessage[] | SystemModelMessage[]`): 이 실행에서 Agent의 기본 지침을 재정의하는 사용자 지정 지침입니다. 단일 문자열, 메시지 객체 또는 둘 중 하나의 배열일 수 있습니다.

**options.system** (`string | string[] | CoreSystemMessage | SystemModelMessage | CoreSystemMessage[] | SystemModelMessage[]`): Prompt에 포함할 사용자 지정 시스템 메시지입니다. 단일 문자열, 메시지 객체 또는 둘 중 하나의 배열일 수 있습니다. 시스템 메시지는 Agent의 주요 지침을 보완하는 추가 컨텍스트 또는 동작 지침을 제공합니다.

**options.output** (`Zod schema | JsonSchema7`): \*\*사용 중단됨.\*\* 동일한 결과를 얻으려면 Model 없이 structuredOutput을 사용하세요. 예상 출력 구조를 정의합니다. JSON Schema 객체 또는 Zod 스키마일 수 있습니다.

**options.memory** (`object`): 대화 유지 및 검색을 위한 Memory 구성입니다.

**options.memory.thread** (`string | { id: string; metadata?: Record<string, any>, title?: string }`): 대화 연속성을 위한 스레드 식별자입니다. 문자열 ID 또는 ID와 선택적 메타데이터/제목이 포함된 객체일 수 있습니다.

**options.memory.resource** (`string`): 사용자, 세션 또는 컨텍스트별로 대화를 구성하기 위한 리소스 식별자입니다.

**options.memory.options** (`MemoryConfig`): lastMessages, readOnly, semanticRecall, workingMemory, filterIncompleteToolCalls를 포함한 추가 Memory 구성 옵션입니다.

**options.memory.onTitleGenerated** (`(title: string) => void | Promise<void>`): 스레드 제목이 생성되어 스토리지에 유지될 때 비동기적으로 실행되는 콜백입니다. 제목 생성은 백그라운드에서 실행되며 generate()가 반환된 후 완료될 수 있습니다. Memory 옵션에서 generateTitle이 활성화되어 있고 스레드에 기존 제목이 없을 때만 실행됩니다.

**options.onFinish** (`LoopConfig['onFinish']`): 생성이 완료될 때 실행되는 콜백입니다.

**options.onStepFinish** (`LoopConfig['onStepFinish']`): 각 생성 단계 후에 실행되는 콜백입니다.

**options.telemetry** (`TelemetrySettings`): 생성 중 OTLP 텔레메트리 수집을 위한 설정입니다(Tracing 아님).

**options.telemetry.isEnabled** (`boolean`): 텔레메트리 수집 활성화 여부입니다.

**options.telemetry.recordInputs** (`boolean`): 텔레메트리에 입력 데이터를 기록할지 여부입니다.

**options.telemetry.recordOutputs** (`boolean`): 텔레메트리에 출력 데이터를 기록할지 여부입니다.

**options.telemetry.functionId** (`string`): 실행 중인 함수의 식별자입니다.

**options.modelSettings** (`CallSettings`): Model-specific settings like temperature, maxOutputTokens, topP, etc. These settings control how the language model generates responses.

**options.modelSettings.temperature** (`number`): Controls randomness in generation (0-2). Higher values make output more random.

**options.modelSettings.maxOutputTokens** (`number`): Maximum number of tokens to generate in the response. Note: Use maxOutputTokens (not maxTokens) as per AI SDK v5 convention.

**options.modelSettings.maxRetries** (`number`): Maximum number of retry attempts for failed requests.

**options.modelSettings.topP** (`number`): Nucleus sampling parameter (0-1). Controls diversity of generated text.

**options.modelSettings.topK** (`number`): Top-k sampling parameter. Limits vocabulary to k most likely tokens.

**options.modelSettings.presencePenalty** (`number`): Penalty for token presence (-2 to 2). Reduces repetition.

**options.modelSettings.frequencyPenalty** (`number`): Penalty for token frequency (-2 to 2). Reduces repetition of frequent tokens.

**options.modelSettings.stopSequences** (`string[]`): Stop sequences. If set, the model will stop generating text when one of the stop sequences is generated.

**options.toolChoice** (`'auto' | 'none' | 'required' | { type: 'tool'; toolName: string }`): 생성 중 Tool을 선택하는 방식을 제어합니다.

**options.toolChoice.'auto'** (`string`): Tool을 사용할 시점을 Model이 결정하도록 합니다(기본값).

**options.toolChoice.'none'** (`string`): Tool 사용을 완전히 비활성화합니다.

**options.toolChoice.'required'** (`string`): Model이 하나 이상의 Tool을 반드시 사용하도록 합니다.

**options.toolChoice.{ type: 'tool'; toolName: string }** (`object`): Model이 특정 Tool을 반드시 사용하도록 합니다.

**options.toolsets** (`ToolsetsInput`): 이 실행에 사용할 수 있는 추가 Tool 세트입니다.

**options.clientTools** (`ToolsInput`): 실행 중 사용할 수 있는 클라이언트 측 Tool입니다.

**options.hooks** (`ToolHooks`): Tool 호출 전후에 실행되는 실행별 훅입니다. 이 실행에서 일치하는 Agent 수준 훅을 재정의합니다. beforeToolCall은 { proceed: false, output }을 반환하여 Tool 호출을 건너뛸 수 있습니다.

**options.savePerStep** (`boolean`): 각 생성 단계가 완료된 후 메시지를 점진적으로 저장합니다(기본값: false). 관찰 Memory가 활성화되면 내부적으로 비활성화됩니다.

**options.providerOptions** (`Record<string, Record<string, JSONValue>>`): 언어 Model에 전달되는 Provider별 옵션입니다.

**options.providerOptions.openai** (`Record<string, JSONValue>`): reasoningEffort, responseFormat 등 OpenAI별 옵션입니다.

**options.providerOptions.anthropic** (`Record<string, JSONValue>`): maxTokens 등 Anthropic별 옵션입니다.

**options.providerOptions.google** (`Record<string, JSONValue>`): Google별 옵션입니다.

**options.providerOptions.\[providerName]** (`Record<string, JSONValue>`): 임의의 Provider별 옵션입니다.

**options.runId** (`string`): 이 실행의 고유 식별자입니다.

**options.requestContext** (`RequestContext`): 동적 구성과 상태를 포함하는 Request Context입니다.

**options.tracingContext** (`TracingContext`): 하위 span을 생성하고 메타데이터를 추가하기 위한 Tracing 컨텍스트입니다. Mastra의 Tracing 시스템을 사용할 때 자동으로 주입됩니다.

**options.tracingContext.currentSpan** (`Span`): 하위 span을 생성하고 메타데이터를 추가하기 위한 현재 span입니다. 실행 중 사용자 지정 하위 span을 생성하거나 span 속성을 업데이트하는 데 사용합니다.

**options.tracingOptions** (`TracingOptions`): Tracing 구성을 위한 옵션입니다.

**options.tracingOptions.metadata** (`Record<string, any>`): 루트 Trace span에 추가할 메타데이터입니다. 사용자 ID, 세션 ID 또는 기능 플래그와 같은 사용자 지정 속성을 추가하는 데 유용합니다.

**options.tracingOptions.requestContextKeys** (`string[]`): 이 Trace의 메타데이터로 추출할 추가 RequestContext 키입니다. 중첩된 값에는 점 표기법을 지원합니다(예: 'user.id').

**options.tracingOptions.traceId** (`string`): 이 실행에 사용할 Trace ID입니다(1\~32자의 16진수 문자). 제공하면 이 Trace가 지정된 Trace의 일부가 됩니다.

**options.tracingOptions.parentSpanId** (`string`): 이 실행에 사용할 상위 span ID입니다(1\~16자의 16진수 문자). 제공하면 루트 span이 이 span의 하위로 생성됩니다.

**options.tracingOptions.tags** (`string[]`): 이 Trace에 적용할 태그입니다. Trace를 분류하고 필터링하기 위한 문자열 레이블입니다.

**options.versions** (`VersionOverrides`): 하위 Agent 위임을 위한 호출별 버전 재정의입니다. Mastra 인스턴스 수준 버전 위에 병합되며 requestContext를 통해 하위 Agent 호출에 자동으로 전파됩니다. editor 패키지가 필요합니다. Editor 버전 관리를 참조하세요.

**options.versions.agents** (`Record<string, VersionSelector>`): Agent ID를 해당 버전 선택기에 매핑한 맵입니다.

**options.versions.agents.versionId** (`string`): ID로 특정 버전을 지정합니다.

**options.versions.agents.status** (`'draft' | 'published'`): 이 게시 상태에 해당하는 최신 버전을 지정합니다.

**options.includeRawChunks** (`boolean`): 스트림 출력에 원시 청크를 포함할지 여부입니다. 일부 Model Provider에서는 사용할 수 없습니다.

## 응답 구조

`Agent.generate()` 실행 중 수집된 최종 데이터를 반환합니다. `steps`는 단계 객체의 배열입니다. 최상위 `toolCalls`와 `toolResults`, 중첩된 `step.toolCalls`와 `step.toolResults` 배열을 포함하여 결과의 Tool 배열에는 Mastra의 청크 형식을 사용합니다. 이는 Tool 데이터가 래핑되어 있음을 의미합니다.`payload`:

```ts
const response = await agent.generate('Check the weather in Lagos')

for (const toolCall of response.toolCalls) {
  console.log(toolCall.type) // 'tool-call'
  console.log(toolCall.runId)
  console.log(toolCall.from)
  console.log(toolCall.payload.toolName)
  console.log(toolCall.payload.args)
}

for (const step of response.steps) {
  for (const toolResult of step.toolResults) {
    console.log(toolResult.type) // 'tool-result'
    console.log(toolResult.payload.toolName)
    console.log(toolResult.payload.result)
  }
}
```

동일한 청크 모양의 스트리밍 버전에 대해서는 다음을 참조하세요.[ChunkType reference](https://mastra.zisheng.pro/ko/reference/streaming/ChunkType).

## 보고

**result** (`Awaited<ReturnType<MastraModelOutput<Output>['getFullOutput']>>`): 텍스트, 객체(구조화된 출력인 경우), Tool 호출, Tool 결과, 사용량 통계 및 단계 정보를 포함한 생성 프로세스의 전체 출력을 반환합니다.

**text** (`string`): Agent가 생성한 텍스트 응답입니다.

**object** (`Output | undefined`): structuredOutput이 제공된 경우 스키마에 따라 검증된 구조화된 출력 객체입니다.

**toolCalls** (`ToolCallChunk[]`): 생성 중 이루어진 Tool 호출 청크의 배열입니다.

**toolCalls.type** (`'tool-call'`): 청크 유형 식별자입니다.

**toolCalls.runId** (`string`): 실행 식별자입니다.

**toolCalls.from** (`ChunkFrom`): AGENT 또는 WORKFLOW과 같은 청크의 소스입니다.

**toolCalls.payload** (`ToolCallPayload`): Tool 호출 데이터입니다.

**toolCalls.payload.toolCallId** (`string`): Tool 호출의 고유 식별자입니다.

**toolCalls.payload.toolName** (`string`): 호출된 Tool의 이름입니다.

**toolCalls.payload.args** (`Record<string, unknown>`): Tool에 전달된 인수입니다.

**toolCalls.payload.providerExecuted** (`boolean`): Model Provider가 Tool을 직접 실행했는지 여부입니다.

**toolResults** (`ToolResultChunk[]`): Tool 실행에서 나온 Tool 결과 청크의 배열입니다.

**toolResults.type** (`'tool-result'`): 청크 유형 식별자입니다.

**toolResults.runId** (`string`): 실행 식별자입니다.

**toolResults.from** (`ChunkFrom`): AGENT 또는 WORKFLOW과 같은 청크의 소스입니다.

**toolResults.payload** (`ToolResultPayload`): Tool 결과 데이터입니다.

**toolResults.payload.toolCallId** (`string`): Tool 호출의 고유 식별자입니다.

**toolResults.payload.toolName** (`string`): 결과를 생성한 Tool의 이름입니다.

**toolResults.payload.result** (`unknown`): Tool이 반환한 값입니다.

**toolResults.payload.isError** (`boolean`): Tool 실행 실패 여부입니다.

**usage** (`TokenUsage`): 생성의 토큰 사용량 통계입니다.

**steps** (`object[]`): 실행 단계의 배열로, 다단계 생성을 디버깅하는 데 유용합니다.

**steps.text** (`string`): 이 단계에서 생성된 텍스트입니다.

**steps.toolCalls** (`ToolCallChunk[]`): 이 단계에서 내보낸 Tool 호출입니다.

**steps.toolResults** (`ToolResultChunk[]`): 이 단계에서 내보낸 Tool 결과입니다.

**steps.finishReason** (`string`): 이 단계가 완료된 이유입니다.

**steps.usage** (`LanguageModelUsage`): 이 단계의 토큰 사용량입니다.

**steps.request** (`{ body?: unknown }`): 이 단계의 요청 메타데이터입니다.

**steps.response** (`object`): 이 단계의 응답 메타데이터입니다.

**finishReason** (`string`): 생성이 완료된 이유입니다. 값에는 'stop'(정상 완료), 'tool-calls'(Tool 호출로 종료), 'suspended'(Tool 승인 대기) 또는 'error'(오류 발생)가 포함됩니다.

**response** (`object`): Model Provider의 응답 메타데이터입니다. 요청 한도 헤더와 요청 ID에 접근하는 데 유용합니다.

**response.id** (`string`): Model Provider의 응답 ID입니다.

**response.timestamp** (`Date`): 응답이 생성된 타임스탬프입니다.

**response.modelId** (`string`): 이 응답에 사용된 Model 식별자입니다.

**response.headers** (`Record<string, string>`): Model Provider의 HTTP 응답 헤더입니다. 요청 한도 정보(예: anthropic-ratelimit-requests-remaining, x-ratelimit-remaining-tokens)와 기타 Provider별 메타데이터를 포함합니다.

**response.messages** (`ResponseMessage[]`): Model 형식의 응답 메시지입니다.

**response.uiMessages** (`UIMessage[]`): UI 형식의 응답 메시지이며, 출력 프로세서가 추가한 모든 메타데이터를 포함합니다.

**request** (`object`): Model에 전송된 요청입니다.

**request.body** (`unknown`): Model Provider에 전송된 요청 본문입니다.

**warnings** (`LanguageModelWarning[]`): 생성 중 Model Provider에서 발생한 모든 경고입니다.

**providerMetadata** (`Record<string, unknown>`): 응답과 함께 반환된 Provider별 메타데이터입니다.

**reasoning** (`ReasoningChunk[]`): 추론을 지원하는 Model의 추론 세부 정보입니다(예: OpenAI o1 시리즈).

**reasoningText** (`string`): 추론 Model에서 나온 결합된 추론 텍스트입니다.

**sources** (`SourceChunk[]`): 생성 중 Model이 참조한 소스입니다.

**files** (`FileChunk[]`): Model이 생성한 파일입니다.

**suspendPayload** (`object`): finishReason이 'suspended'일 때 존재합니다. 대기 중인 Tool 호출을 승인하거나 거부하는 데 필요한 Tool 호출 세부 정보를 포함합니다.

**suspendPayload.toolCallId** (`string`): 대기 중인 Tool 호출의 고유 식별자입니다.

**suspendPayload.toolName** (`string`): 승인이 필요한 Tool의 이름입니다.

**suspendPayload.args** (`Record<string, any>`): Tool에 전달될 인수입니다.

**runId** (`string`): 이 실행의 고유 식별자입니다. 일시 중단된 실행을 재개하기 위해 approveToolCallGenerate() 또는 declineToolCallGenerate()를 호출할 때 필요합니다.

**traceId** (`string`): Tracing이 활성화되었을 때 이 실행과 연결된 Trace ID입니다. 로그를 연관 짓고 실행 흐름을 디버깅하는 데 사용합니다.

**spanId** (`string`): Tracing이 활성화되었을 때 이 실행과 연결된 루트 span ID입니다. span 수준 조회 및 연관 분석에 사용합니다.

**messages** (`MastraDBMessage[]`): 입력, Memory 기록 및 응답을 포함한 이 실행의 모든 메시지입니다.

**rememberedMessages** (`MastraDBMessage[]`): Memory에서 불러온 메시지(대화 기록)만 포함합니다.

**error** (`Error`): 생성에 실패한 경우의 오류 객체입니다.

**tripwire** (`StepTripwireData`): 프로세서가 콘텐츠를 차단한 경우의 트립와이어 데이터입니다.

**scoringData** (`object`): returnScorerData가 활성화된 경우 Evals의 채점 데이터입니다.

## 더 많은 예시

### Model 설정으로

출력 토큰 제한 및 온도 설정의 예:

```ts
const limitedResult = await agent.generate('Write a short poem about coding', {
  modelSettings: {
    maxOutputTokens: 50,
    temperature: 0.7,
  },
})
```

### Memory 포함

Memory 옵션을 구성하여 Agent에 대화 기록 및 지속성에 대한 액세스 권한을 부여하세요. 이를 통해 Agent는 이전 상호 작용을 기억하고 메시지 전반에 걸쳐 컨텍스트를 유지할 수 있습니다.

```ts
const memoryResult = await agent.generate('Remember my favorite color is blue', {
  memory: {
    thread: 'user-123-thread',
    resource: 'user-123',
  },
})
```

### 응답 헤더에 액세스

일부 Model 공급자는 남은 토큰 수 또는 속도 제한 상태와 같은 유용한 정보를 응답 헤더에 반환합니다. 생성이 완료된 후 결과 개체에서 이러한 헤더에 액세스할 수 있습니다.

```ts
const result = await agent.generate('Hello!')
const remainingRequests = result.response?.headers?.['anthropic-ratelimit-requests-remaining']
const remainingTokens = result.response?.headers?.['x-ratelimit-remaining-tokens']
console.log(`Remaining requests: ${remainingRequests}, Remaining tokens: ${remainingTokens}`)
```

### 이미지 분석

Agent는 시각적 콘텐츠와 그 안의 텍스트를 모두 처리하여 이미지를 분석하고 설명할 수 있습니다. 이미지 분석을 활성화하려면 `type: 'image'`가 지정된 객체와 이미지 URL을 `content` 배열에 전달하세요. 이미지 콘텐츠와 텍스트 Prompt를 결합하여 Agent의 분석을 안내할 수 있습니다.

```typescript
const response = await agent.generate([
  {
    role: 'user',
    content: [
      {
        type: 'image',
        image: 'https://placebear.com/cache/395-205.jpg',
        mimeType: 'image/jpeg',
      },
      {
        type: 'text',
        text: 'Describe the image in detail, and extract all the text in the image.',
      },
    ],
  },
])

console.log(response.text)
```

### 사용`maxSteps`

`maxSteps` 매개변수는 Agent가 순차적으로 수행할 수 있는 최대 LLM 호출 횟수를 제어합니다. 각 단계에서는 응답을 생성하고 모든 Tool 호출을 실행한 후 그 결과를 처리합니다. 단계 수를 제한하면 무한 루프를 방지하고 지연 시간을 줄일 수 있습니다. 또한 Tool을 사용하는 Agent의 토큰 사용량도 제어할 수 있습니다. 기본값은 5이지만 늘릴 수 있습니다.

```typescript
const response = await agent.generate('Help me organize my day', {
  maxSteps: 10,
})

console.log(response.text)
```

### 사용`onStepFinish`

`onStepFinish` 콜백을 사용하여 다단계 작업의 진행 상황을 모니터링할 수 있습니다. 디버깅하거나 사용자에게 진행 상황을 알릴 때 유용합니다. `onStepFinish`구조화된 출력 없이 텍스트를 스트리밍하거나 생성하는 경우에만 사용할 수 있습니다.

```typescript
const response = await agent.generate('Help me organize my day', {
  onStepFinish: ({ text, toolCalls, toolResults, finishReason, usage }) => {
    console.log({ text, toolCalls, toolResults, finishReason, usage })
  },
})
```

### 사용`onTitleGenerated`

Memory 옵션에서 `generateTitle`을 활성화하면 응답이 완료된 후 제목 생성이 비동기적으로 실행됩니다. 제목이 준비되었을 때 처리하려면 `onTitleGenerated`를 사용하세요. 예를 들어 SSE를 통해 클라이언트에 제목을 푸시할 수 있습니다.

```typescript
const response = await agent.generate('What is quantum computing?', {
  memory: {
    thread: threadId,
    resource: userId,
    onTitleGenerated: title => {
      console.log('Thread title:', title)
    },
  },
})
```