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

# `createInngestAgent()`

`createInngestAgent()`기존을 래핑[`Agent`](https://mastra.zisheng.pro/ko/reference/agents/agent)\~와 함께[섭취](https://www.inngest.com/docs)-강력한 내구성 실행. 좋다[`createDurableAgent()`](https://mastra.zisheng.pro/ko/reference/agents/durable-agent), 이벤트를 스트리밍합니다.[PubSub](https://mastra.zisheng.pro/ko/docs/server/pubsub)재개 가능한 스트림을 지원하지만 프로세스 내 대신 Ingest의 실행 엔진에서 Agent 루프를 실행합니다. 실행이 프로세스를 다시 시작한 후에도 유지되어야 하거나 분산 환경에서 실행되어야 하는 경우 이를 사용합니다.

프로세스 내 내구성 실행에는 [`createDurableAgent()`](https://mastra.zisheng.pro/ko/reference/agents/durable-agent)를 사용하세요. 기본 제공 Workflow 엔진에서 실행 후 결과를 기다리지 않는 방식으로 처리하려면 [`createEventedAgent()`](https://mastra.zisheng.pro/ko/reference/agents/durable-agent)를 사용하세요.

## 사용예

Ingest 클라이언트를 설정하고, Agent를 래핑하고, 이를 Mastra에 등록하고, Ingest 서비스 엔드포인트를 노출합니다.

```typescript
import { Mastra } from '@mastra/core'
import { Agent } from '@mastra/core/agent'
import { createInngestAgent, serve as inngestServe } from '@mastra/inngest'
import { Inngest } from 'inngest'

const inngest = new Inngest({ id: 'my-app' })

const agent = new Agent({
  id: 'my-agent',
  name: 'My Agent',
  instructions: 'You are a helpful assistant',
  model: 'openai/gpt-5.6-sol',
})

const durableAgent = createInngestAgent({ agent, inngest })

export const mastra = new Mastra({
  agents: { myAgent: durableAgent },
  server: {
    apiRoutes: [
      {
        path: '/inngest/api',
        method: 'ALL',
        createHandler: async ({ mastra }) => inngestServe({ mastra, inngest }),
      },
    ],
  },
})
```

응답을 스트리밍하고 결과를 읽습니다.

```typescript
const { output, runId, cleanup } = await durableAgent.stream('Hello!')

const text = await output.text

cleanup()
```

## `createInngestAgent(options)`

`Agent`를 Inngest 기반 내구성 실행 및 재개 가능한 스트림으로 래핑합니다.

```typescript
import { createInngestAgent } from '@mastra/inngest'

const durableAgent = createInngestAgent({ agent, inngest })
```

보고:[`InngestAgent`](#inngestagent-interface)

### 매개변수

**agent** (`Agent`): Inngest 내구성 실행으로 래핑할 Agent입니다. InngestAgent에서 구현하지 않은 메서드(예: listTools() 및 getMemory())는 Proxy를 통해 이 Agent에 위임됩니다.

**inngest** (`Inngest`): Inngest 클라이언트 인스턴스입니다. Workflow 이벤트를 전송하고 SDK v4에서는 실시간 스트림 이벤트를 게시하는 데 사용됩니다.

**id** (`string`): ID 재정의입니다. (Default: `agent.id`)

**name** (`string`): 이름 재정의입니다. (Default: `agent.name`)

**pubsub** (`PubSub`): 스트리밍 이벤트를 위한 PubSub 인스턴스입니다. 기본 InngestPubSub은 프로세스 간에 작동하는 Inngest Realtime을 사용합니다. (Default: `InngestPubSub`)

**cache** (`MastraServerCache`): 저장된 스트림 이벤트를 위한 캐시로, 재개 가능한 스트림을 지원합니다. 제공하면 PubSub이 자동으로 CachingPubSub으로 래핑됩니다. 생략하면 Agent가 Mastra 인스턴스에서 캐시를 상속합니다.

**mastra** (`Mastra`): Observability를 위한 Mastra 인스턴스입니다. Agent가 Mastra에 등록되면 자동으로 설정됩니다.

## `InngestAgent`인터페이스

`createInngestAgent()`가 반환한 객체입니다. 아래의 내구성 실행 메서드를 제공합니다. 명시적으로 정의되지 않은 모든 속성이나 메서드(예: `listTools()` 및 `getMemory()`)는 Proxy를 통해 기본 Agent로 전달됩니다.

### 속성

**id** (`string`): Agent ID입니다.

**name** (`string`): Agent 이름입니다.

**agent** (`Agent`): 기본 Mastra Agent입니다.

**inngest** (`Inngest`): Inngest 클라이언트입니다.

**cache** (`MastraServerCache | undefined`): 재개 가능한 스트림이 활성화된 경우 해석된 캐시 인스턴스입니다.

**pubsub** (`PubSub`): 스트리밍 이벤트에 사용되는 PubSub 인스턴스입니다.

## 행동 양식

### 실행

#### `stream(messages, options?)`

Ingest의 내구성 있는 실행 엔진을 사용하여 응답을 스트리밍합니다. Workflow는 PubSub 구독이 설정된 후 Ingest 이벤트를 통해 트리거됩니다.

```typescript
const { output, runId, cleanup } = await durableAgent.stream('Hello!', {
  onChunk: chunk => console.log(chunk),
  onFinish: result => console.log('done', result),
})

const text = await output.text
cleanup()
```

보고:[`Promise<InngestAgentStreamResult>`](#inngestagentstreamresult)

#### `resume(runId, resumeData, options?)`

예를 들어 Tool 승인 후 일시 중지된 Ingest 실행을 재개합니다. 스토리지에서 Workflow 스냅샷을 로드하고 일시 중단된 단계를 찾은 다음 재개 이벤트를 Ingest로 보냅니다.

```typescript
const { output, cleanup } = await durableAgent.resume(
  runId,
  {
    approved: true,
  },
  { threadId: 'thread-1', resourceId: 'user-1' },
)

await output.text
cleanup()
```

세 번째 인수에는 수명 주기 콜백 외에도 `threadId`와 `resourceId`가 포함됩니다.

**threadId** (`string`): 재개된 실행과 연결할 스레드 ID입니다.

**resourceId** (`string`): 재개된 실행과 연결할 리소스 ID입니다.

**onChunk** (`(chunk: ChunkType) => void | Promise<void>`): 스트리밍되는 각 청크마다 호출됩니다.

**onStepFinish** (`(result: AgentStepFinishEventData) => void | Promise<void>`): Agent 루프의 단계가 완료될 때 호출됩니다.

**onFinish** (`(result: AgentFinishEventData) => void | Promise<void>`): 실행이 완료될 때 호출됩니다.

**onError** (`(error: Error) => void | Promise<void>`): 실행 중 오류가 발생할 때 호출됩니다.

**onSuspended** (`(data: AgentSuspendedEventData) => void | Promise<void>`): 실행이 일시 중지될 때 호출됩니다.

보고:[`Promise<InngestAgentStreamResult>`](#inngestagentstreamresult)

#### `generate(messages, options?)`

Inngest의 내구성 실행 엔진에서 응답을 실행하고 단일 `FullOutput`으로 해석합니다. 실행이 일시 중지되면 `generate()`는 `finishReason: 'suspended'`와 함께 해석됩니다. `runId` 옵션은 선택 사항입니다. 생략하면 `generate()`가 실행 ID를 생성하고 `result.runId`에 반환합니다. [`resumeGenerate()`](#resumegeneraterunid-resumedata-options)을 사용하여 실행을 계속하세요. 호출자에게 일시 중지 콜백이 필요한 경우 `onSuspended`와 함께 [`stream()`](#streammessages-options)을 사용하세요.

```typescript
const result = await durableAgent.generate('Delete the old records', {
  requireToolApproval: true,
})

result.runId // Generated automatically
result.finishReason // 'suspended' when approval is required
```

보고:`Promise<FullOutput<TOutput>>`

#### `resumeGenerate(runId, resumeData, options?)`

일시 중지된 `generate()` 실행을 재개하고 단일 `FullOutput`으로 해석합니다.

```typescript
if (!result.runId) {
  throw new Error('Run ID is missing')
}

const resumedResult = await durableAgent.resumeGenerate(result.runId, { approved: true })
```

보고:`Promise<FullOutput<TOutput>>`

#### `observe(runId, options?)`

기존 실행에 다시 연결하고 라이브 이벤트를 전달하기 전에 캐시된 이벤트를 재생합니다. 네트워크 연결이 끊어진 후 사용하세요. 알려진 위치부터 재생하려면 `offset`을 전달하세요.

```typescript
const { output, cleanup } = await durableAgent.observe(runId, {
  offset: 0,
  onChunk: chunk => console.log(chunk),
})

await output.text
```

`observe()`의 결과에는 `threadId` 또는 `resourceId`가 포함되지 않습니다. 보고:`Promise<Omit<InngestAgentStreamResult, 'threadId' | 'resourceId'>>`

> **경고:** `observe()`가 반환한 `cleanup()`은 실행의 레지스트리 항목과 캐시된 이벤트를 제거합니다. 실행 사용을 마쳤을 때만 호출하세요. 실행이 일시 중지되었고 나중에 재개하려는 경우 `cleanup()`을 호출하지 마세요.

#### `prepare(messages, options?)`

트리거하지 않고 지속 가능한 실행을 위한 실행을 준비합니다. Ingest Workflow 이벤트를 수동으로 트리거하는 데 사용할 수 있는 직렬화된 Workflow 입력을 반환합니다.

```typescript
const { runId, messageId, workflowInput, threadId, resourceId } = await durableAgent.prepare(
  'Summarize the document',
  {
    memory: { threadId: 'thread-1', resourceId: 'user-1' },
  },
)
```

보고:

```typescript
interface PrepareResult {
  runId: string
  messageId: string
  workflowInput: any
  threadId?: string
  resourceId?: string
}
```

### 내성

#### `isInngestAgent(obj)`

객체가 객체인지 확인하는 유형 가드`InngestAgent`.

```typescript
import { isInngestAgent } from '@mastra/inngest'

if (isInngestAgent(agent)) {
  // agent is InngestAgent
}
```

보고:`boolean`

## 스트림 옵션

`stream()`은 `InngestAgentStreamOptions` 객체를 받습니다. [`DurableAgent.stream()`](https://mastra.zisheng.pro/ko/reference/agents/durable-agent)과 동일한 Agent 실행 옵션과 수명 주기 콜백을 지원합니다.

**runId** (`string`): 이 실행의 고유 식별자입니다. 나중에 resume() 또는 observe()와 함께 사용하세요.

**instructions** (`AgentExecutionOptions['instructions']`): 이 실행에서 Agent의 기본 지침을 재정의합니다.

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

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

**requestContext** (`RequestContext`): 이 실행의 동적 구성과 상태를 전달하는 요청 컨텍스트입니다.

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

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

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

**toolChoice** (`'auto' | 'none' | 'required' | { type: 'tool'; toolName: string }`): Tool 선택 전략입니다.

**modelSettings** (`object`): temperature와 같은 Model별 설정입니다.

**requireToolApproval** (`boolean`): 모든 Tool 호출에 승인을 요구하며, 재개될 때까지 실행을 일시 중단합니다.

**autoResumeSuspendedTools** (`boolean`): 외부 resume() 호출을 기다리지 않고 일시 중단된 Tool을 자동으로 재개합니다.

**toolCallConcurrency** (`number`): 동시에 실행할 최대 Tool 호출 수입니다.

**includeRawChunks** (`boolean`): 스트림 출력에 원시 Provider 청크를 포함합니다.

**maxProcessorRetries** (`number`): 생성당 최대 프로세서 재시도 횟수입니다.

**untilIdle** (`boolean | { maxIdleMs?: number }`): 설정하면 Agent가 유휴 상태가 될 때까지 백그라운드 작업이 이어지는 동안 스트림을 열린 상태로 유지합니다. 기본 5분 유휴 시간 제한을 사용하려면 true를 전달하고, 사용자 지정하려면 { maxIdleMs }를 전달하세요.

**onChunk** (`(chunk: ChunkType) => void | Promise<void>`): 스트리밍되는 각 청크에 대해 호출됩니다.

**onStepFinish** (`(result: AgentStepFinishEventData) => void | Promise<void>`): Agent 루프의 단계가 완료될 때 호출됩니다.

**onFinish** (`(result: AgentFinishEventData) => void | Promise<void>`): 실행이 완료될 때 호출됩니다.

**onError** (`(error: Error) => void | Promise<void>`): 실행 중 오류가 발생할 때 호출됩니다.

**onSuspended** (`(data: AgentSuspendedEventData) => void | Promise<void>`): Tool 승인 등의 이유로 실행이 일시 중단될 때 호출됩니다.

`observe()`는 수명 주기 콜백(`onChunk`, `onStepFinish`, `onFinish`, `onError`, `onSuspended`)과 재생 시작 위치를 제어하는 `offset`을 허용합니다.

## `InngestAgentStreamResult`

반환된 객체에는 `stream()`과 `resume()`이 포함됩니다. `observe()` 메서드는 동일한 형태를 반환하지만 `threadId`와 `resourceId`는 생략합니다.

```typescript
interface InngestAgentStreamResult<OUTPUT = undefined> {
  output: MastraModelOutput<OUTPUT>
  readonly fullStream: ReadableStream<any>
  runId: string
  threadId?: string
  resourceId?: string
  cleanup: () => void
}
```

**output** (`MastraModelOutput`): 스트리밍 출력입니다. 전체 텍스트를 가져오려면 output.text를 기다리고, 스트림을 소비하려면 output.fullStream을 사용하세요.

**fullStream** (`ReadableStream`): output.fullStream에 위임하는 전체 이벤트 스트림입니다.

**runId** (`string`): 고유한 실행 ID입니다. 다시 연결하려면 이를 resume() 또는 observe()에 전달하세요.

**threadId** (`string`): Memory를 사용할 때의 스레드 ID입니다.

**resourceId** (`string`): Memory를 사용할 때의 리소스 ID입니다.

**cleanup** (`() => void`): PubSub 구독을 해제하고 실행의 레지스트리 항목을 정리합니다. 실행 사용을 마치면 호출하세요.

## Ingest 기능 제공

`@mastra/inngest` 패키지는 HTTP 프레임워크에 Inngest Workflow 함수를 등록하기 위한 `serve()`와 `createServe()`를 제공합니다.

### `serve(options)`

Hono(기본 프레임워크)를 사용하여 Mastra Workflow를 제공합니다. Mastra에서 모든 Ingest 지원 Workflow를 수집하고 이를 Ingest 기능으로 등록합니다.

```typescript
import { serve } from '@mastra/inngest'

app.use('/inngest/api', async c => {
  return serve({ mastra, inngest })(c)
})
```

### `createServe(adapter)`

모든 Inngest 서버 어댑터(`inngest/express`, `inngest/fastify`, `inngest/next` 등)를 받아 해당 프레임워크용 serve 함수를 반환하는 팩토리입니다.

```typescript
import { createServe } from '@mastra/inngest'
import { serve } from 'inngest/express'

const serveExpress = createServe(serve)
app.use('/inngest/api', serveExpress({ mastra, inngest }))
```

```typescript
import { createServe } from '@mastra/inngest'
import { serve } from 'inngest/next'

const serveNext = createServe(serve)
export const { GET, POST, PUT } = serveNext({ mastra, inngest })
```

### 서브 옵션

**mastra** (`Mastra`): 등록된 Agent와 Workflow를 포함하는 Mastra 인스턴스입니다.

**inngest** (`Inngest`): Inngest 클라이언트 인스턴스입니다.

**functions** (`InngestFunction.Like[]`): Mastra Workflow와 함께 제공할 추가 Inngest 함수입니다.

**registerOptions** (`RegisterOptions`): Inngest 등록 핸들러에 전달되는 옵션입니다.

## 관련된

- [내구성 Agent 참조](https://mastra.zisheng.pro/ko/reference/agents/durable-agent)
- [Agent 클래스](https://mastra.zisheng.pro/ko/reference/agents/agent)
- [Ingest 배포 가이드](https://mastra.zisheng.pro/ko/guides/deployment/inngest)
- [PubSub](https://mastra.zisheng.pro/ko/docs/server/pubsub)