git:20260603.ad35c02 to git:20260625.c20d24c

---

name: inngest-agents

description: Use when building durable AI agents or agentic workflows with Inngest and AgentKit, including model calls, tool calls, multi-agent networks, human approval, realtime progress, provider rate limits, and crash-safe execution. Covers AgentKit, `step.ai`, `step.run`, `step.waitForEvent`, native realtime, and when to use lower-level Inngest primitives instead of an in-memory agent loop.

---

# Inngest Agents

Use this skill when the user wants to build, migrate, or debug an AI agent,

multi-step AI workflow, tool-calling loop, support agent, research agent,

human-in-the-loop review flow, or realtime agent UI.

Inngest's AgentKit defines agents with `createAgent`; when an AgentKit run is

owned by an Inngest function, model calls use Inngest `step.ai` so they retry

and cache model results durably. Use the lower-level Inngest step primitives

around the agent for database reads/writes, tool side effects, waits,

approvals, realtime progress, and flow control.

Official references:

- AgentKit agents: https://agentkit.inngest.com/concepts/agents

- `createAgent`: https://agentkit.inngest.com/reference/create-agent

- AI inference and `step.ai`: https://www.inngest.com/docs/features/inngest-functions/steps-workflows/step-ai-orchestration

- AgentKit realtime hooks: https://www.inngest.com/changelog/2025-09-24-agentkit-use-agent

## Copyable Example

When starting a durable support or tool-calling agent from scratch, use the

official `inngest/inngest-codex-plugin` companion example at

`plugins/inngest/examples/durable-agent` as the upstream reference. This repo

does not vendor Codex plugin examples; copy only the patterns needed for a

separate product integration change.

## When to Use Inngest for Agents

Good fit:

- Agent can take longer than one HTTP request.

- Agent calls tools, APIs, databases, browsers, sandboxes, or MCP servers.

- Agent needs to survive deploys, crashes, serverless timeouts, or model/API

failures.

- Agent may wait for human approval, external callbacks, scheduled follow-up,

or user input.

- Agent progress should stream to a UI from the durable workflow.

- Model/provider calls need concurrency or throttle limits.

- Duplicate sends, charges, writes, or model calls would be costly.

Not usually worth it:

- One short, read-only model call with no side effects and no need for durable

progress.

- UI-only autocomplete where losing the request is acceptable.

## Architecture

Use this shape unless the repo already has a stronger established pattern:

1. The HTTP/server action layer validates auth, stores the user's intent if

needed, emits an event with a stable `id`, and returns quickly.

2. An Inngest function owns the agent run.

3. Load state and external context inside `step.run`.

4. Create AgentKit agents inside the function or import agent/network

factories.

5. Run model inference through AgentKit / `step.ai`; wrap non-model tool side

effects in `step.run`.

6. Use `step.waitForEvent` or `step.waitForSignal` for human approval and

external callbacks.

7. Publish durable progress with native realtime.

8. Apply flow control at the function level for provider and tenant limits.

## Basic AgentKit Function

Prefer a small, typed function first; add networks and extra tools after the

single-agent path is proven.

```typescript

import { createAgent, openai } from "@inngest/agent-kit";

import { inngest } from "@/inngest/client";

export const summarizeTicket = inngest.createFunction(

{

id: "summarize-ticket",

triggers: [{ event: "support/ticket.created" }],

},

async ({ event, step }) => {

const ticket = await step.run("load-ticket", () => {

return getTicket(event.data.ticketId);

});

const writer = createAgent({

name: "support-summary-writer",

system: "Write a concise support-ticket summary with next actions.",

});

const { output } = await writer.run(JSON.stringify(ticket));

await step.run("save-summary", () => {

return saveTicketSummary(event.data.ticketId, output);

});

return { ticketId: event.data.ticketId };

);

```

## Tool Calls

Tools can be defined with AgentKit, but agent-safe tools should still follow

durability rules:

- Read-only tool calls can run as part of the agent when replaying is harmless.

- External side effects should be isolated with stable IDs and `step.run`

boundaries, or implemented as tool handlers that use the provided `step`.

- Tool outputs should be small enough for step state limits.

- Validate tool parameters with schemas; never trust model-provided arguments.

- Use tenant/user IDs from authenticated event data, not only from model text.

Tool side-effect checklist:

```text

- What external state can this tool change?

- What idempotency key prevents duplicate writes?

- What should happen if the model calls the same tool twice?

- Is the output safe to store in function run state?

- Does the tool need provider-specific concurrency or throttle limits?

```

## Human in the Loop

Use a durable wait instead of polling a database or keeping state in memory.

```typescript

const approval = await step.waitForEvent("wait-for-approval", {

event: "support/reply.approved",

timeout: "3d",

});

if (!approval) {

await step.run("mark-review-timeout", () => {

return markTicketNeedsManualReview(event.data.ticketId);

});

return { status: "timed_out" };

}

await step.run("send-reply", () => {

return sendSupportReply({

ticketId: event.data.ticketId,

});

});

```

## Realtime Progress

For v4 native realtime:

- Use `step.realtime.publish` between steps.

- Use `inngest.realtime.publish` inside an existing `step.run`.

- Do not install the v3 `@inngest/realtime` package for v4 projects.

- Do not build a process-local WebSocket as the only source of progress for a

durable function.

For AgentKit-specific UI hooks, check the installed `@inngest/agent-kit`

version and current docs before wiring `useAgent` or `useChat`.

## Flow Control and Cost

Agent workloads often need provider and tenant limits:

- Use account-scoped concurrency or throttle keys for model providers.

- Key per tenant or account where fairness matters.

- Use deterministic event IDs so duplicate user actions do not spawn duplicate

expensive runs.

- Keep successful model/tool results in steps so retrying a later failure does

not re-charge earlier model calls.

Example:

```typescript

{

id: "support-agent-run",

triggers: [{ event: "support/agent.requested" }],

throttle: {

limit: 120,

period: "1m",

key: `"openai"`

},

concurrency: [

{ key: "event.data.accountId", limit: 3 }

]

}

```

## Brownfield Migration

When migrating an existing agent:

1. Search for model calls, tool loops, in-memory state, streaming handlers,

approval polling, and external side effects.

2. Keep prompt/tool behavior stable at first.

3. Move the trigger into an event and an Inngest function.

4. Move model calls to AgentKit / `step.ai`.

5. Move side-effecting tools into `step.run` or durable tool handlers.

6. Replace process-local waits with `step.waitForEvent` or

`step.waitForSignal`.

7. Add realtime after the durable run is working.

Use `inngest-brownfield-audit` first when the repo has multiple possible

workflows and the user has not picked one.

## Anti-Patterns

- Agent loop state only in memory.

- One giant `try/catch` around all model and tool calls.

- Retrying the entire agent after one tool failure.

- Charging repeatedly for successful model calls after a later step fails.

- `setTimeout`, cron polling, or Redis TTL as the human-review mechanism.

- Side-effecting tools with no idempotency key.

- Streaming progress from a server process that can die while the durable work

continues elsewhere.

- Adding AgentKit without registering the surrounding Inngest function.

## Verification

- Typecheck the agent, tool schemas, and event payloads.

- Unit-test tool handlers separately from model behavior.

- Test that the HTTP entrypoint emits one deterministic event and returns fast.

- Test that duplicate event IDs do not duplicate final side effects.

- If possible, run the Inngest dev server and inspect the agent steps/traces.

## This Repository

These upstream Inngest instructions are vendored for agent tooling and

integration work in this monorepo.

## Repository Triggers

Use this skill when `inngest-agents` matches the current Inngest task. If the

right skill is unclear, start with `docs/ai/skills/inngest/SKILL.md`.

## Repository Workflow

1. Confirm whether the request is agent-tooling guidance or product runtime

integration.

2. Use `inngest-brownfield-audit` before changing existing app workflows or

fragile background work.

3. Follow this upstream guidance under OpenSpec, root `AGENTS.md`, repo

rulebooks, framework docs, and runtime evidence.

4. Keep runtime packages, app code, migrations, and `INNGEST_*` env

requirements out of agent-tooling-only changes.

## Repository Checklist

- [ ] The task has explicit product-runtime scope before adding Inngest app code

or dependencies.

- [ ] Existing workflows were audited before introducing or changing durable

workflow behavior.

- [ ] Any MCP usage is backed by a running Inngest dev server on the configured

port.

- [ ] Upstream source and license attribution remain documented in

`docs/ai/skills/inngest/references/upstream.md`.