Update to Inngest

{
  "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, crash-safe execution, and Agent Evals handoff. 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. Use `inngest-agent-evals` with this skill when the user wants scoring, sessions, experiments, deferred scorers, or outcome-based evaluation for the agent.",
  "included_files": [],
  "name": "inngest-agents",
  "skill_md_contents": "---\nname: inngest-agents\ndescription: 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, crash-safe execution, and Agent Evals handoff. 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. Use `inngest-agent-evals` with this skill when the user wants scoring, sessions, experiments, deferred scorers, or outcome-based evaluation for the agent.\n---\n\n# Inngest Agents\n\nUse this skill when the user wants to build, migrate, or debug an AI agent,\nmulti-step AI workflow, tool-calling loop, support agent, research agent,\nhuman-in-the-loop review flow, or realtime agent UI.\n\nInngest's AgentKit defines agents with `createAgent`; when an AgentKit run is\nowned by an Inngest function, model calls use Inngest `step.ai` so they retry\nand cache model results durably. Use the lower-level Inngest step primitives\naround the agent for database reads/writes, tool side effects, waits,\napprovals, realtime progress, and flow control.\n\nOfficial references:\n\n- AgentKit agents: https://agentkit.inngest.com/concepts/agents\n- `createAgent`: https://agentkit.inngest.com/reference/create-agent\n- AI inference and `step.ai`: https://www.inngest.com/docs/features/inngest-functions/steps-workflows/step-ai-orchestration\n- Agent Evals: https://www.inngest.com/docs/learn/agent-evals\n- AgentKit realtime hooks: https://www.inngest.com/changelog/2025-09-24-agentkit-use-agent\n\n## Copyable Example\n\nWhen starting a durable support or tool-calling agent from scratch, inspect the\ncompanion example at `../../examples/durable-agent`. It shows the expected\nagent-first shape: quick HTTP trigger, typed events, AgentKit inside an\nInngest function, step-scoped context loading, human approval with\n`step.waitForEvent`, and durable side effects after approval.\n\n## When to Use Inngest for Agents\n\nGood fit:\n\n- Agent can take longer than one HTTP request.\n- Agent calls tools, APIs, databases, browsers, sandboxes, or MCP servers.\n- Agent needs to survive deploys, crashes, serverless timeouts, or model/API\n  failures.\n- Agent may wait for human approval, external callbacks, scheduled follow-up,\n  or user input.\n- Agent progress should stream to a UI from the durable workflow.\n- Model/provider calls need concurrency or throttle limits.\n- Duplicate sends, charges, writes, or model calls would be costly.\n\nNot usually worth it:\n\n- One short, read-only model call with no side effects and no need for durable\n  progress.\n- UI-only autocomplete where losing the request is acceptable.\n\n## Architecture\n\nUse this shape unless the repo already has a stronger established pattern:\n\n1. The HTTP/server action layer validates auth, stores the user's intent if\n   needed, emits an event with a stable `id`, and returns quickly.\n2. An Inngest function owns the agent run.\n3. Load state and external context inside `step.run`.\n4. Create AgentKit agents inside the function or import agent/network\n   factories.\n5. Run model inference through AgentKit / `step.ai`; wrap non-model tool side\n   effects in `step.run`.\n6. Use `step.waitForEvent` or `step.waitForSignal` for human approval and\n   external callbacks.\n7. Publish durable progress with native realtime.\n8. Add sessions and scores when the agent outcome needs to be evaluated later.\n9. Apply flow control at the function level for provider and tenant limits.\n\n## Basic AgentKit Function\n\nPrefer a small, typed function first; add networks and extra tools after the\nsingle-agent path is proven.\n\n```typescript\nimport { createAgent, openai } from \"@inngest/agent-kit\";\nimport { inngest } from \"@/inngest/client\";\n\nexport const summarizeTicket = inngest.createFunction(\n  {\n    id: \"summarize-ticket\",\n    triggers: [{ event: \"support/ticket.created\" }],\n    concurrency: [{ key: \"event.data.accountId\", limit: 2 }]\n  },\n  async ({ event, step }) => {\n    const ticket = await step.run(\"load-ticket\", () => {\n      return getTicket(event.data.ticketId);\n    });\n\n    const writer = createAgent({\n      name: \"support-summary-writer\",\n      system: \"Write a concise support-ticket summary with next actions.\",\n      model: openai({ model: \"gpt-4o\" })\n    });\n\n    const { output } = await writer.run(JSON.stringify(ticket));\n\n    await step.run(\"save-summary\", () => {\n      return saveTicketSummary(event.data.ticketId, output);\n    });\n\n    return { ticketId: event.data.ticketId };\n  }\n);\n```\n\n## Tool Calls\n\nTools can be defined with AgentKit, but agent-safe tools should still follow\ndurability rules:\n\n- Read-only tool calls can run as part of the agent when replaying is harmless.\n- External side effects should be isolated with stable IDs and `step.run`\n  boundaries, or implemented as tool handlers that use the provided `step`.\n- Tool outputs should be small enough for step state limits.\n- Validate tool parameters with schemas; never trust model-provided arguments.\n- Use tenant/user IDs from authenticated event data, not only from model text.\n\nTool side-effect checklist:\n\n```text\n- What external state can this tool change?\n- What idempotency key prevents duplicate writes?\n- What should happen if the model calls the same tool twice?\n- Is the output safe to store in function run state?\n- Does the tool need provider-specific concurrency or throttle limits?\n```\n\n## Human in the Loop\n\nUse a durable wait instead of polling a database or keeping state in memory.\n\n```typescript\nconst approval = await step.waitForEvent(\"wait-for-approval\", {\n  event: \"support/reply.approved\",\n  timeout: \"3d\",\n  match: \"data.ticketId\"\n});\n\nif (!approval) {\n  await step.run(\"mark-review-timeout\", () => {\n    return markTicketNeedsManualReview(event.data.ticketId);\n  });\n  return { status: \"timed_out\" };\n}\n\nawait step.run(\"send-reply\", () => {\n  return sendSupportReply({\n    ticketId: event.data.ticketId,\n    approvalId: approval.data.approvalId\n  });\n});\n```\n\n## Realtime Progress\n\nFor v4 native realtime:\n\n- Use `step.realtime.publish` between steps.\n- Use `inngest.realtime.publish` inside an existing `step.run`.\n- Do not install the v3 `@inngest/realtime` package for v4 projects.\n- Do not build a process-local WebSocket as the only source of progress for a\n  durable function.\n\nFor AgentKit-specific UI hooks, check the installed `@inngest/agent-kit`\nversion and current docs before wiring `useAgent` or `useChat`.\n\n## Agent Evals\n\nUse `inngest-agent-evals` when the user asks to score an agent, compare prompts\nor models, track user feedback, group runs by conversation/ticket, or debug\nagent quality over time. In durable agent workflows, add `meta.sessions` at the\nevent that starts or connects the user flow, use direct scoring for signals\nknown during the run, and use deferred scorers for product outcomes that arrive\nlater.\n\n## Flow Control and Cost\n\nAgent workloads often need provider and tenant limits:\n\n- Use account-scoped concurrency or throttle keys for model providers.\n- Key per tenant or account where fairness matters.\n- Use deterministic event IDs so duplicate user actions do not spawn duplicate\n  expensive runs.\n- Keep successful model/tool results in steps so retrying a later failure does\n  not re-charge earlier model calls.\n\nExample:\n\n```typescript\n{\n  id: \"support-agent-run\",\n  triggers: [{ event: \"support/agent.requested\" }],\n  throttle: {\n    limit: 120,\n    period: \"1m\",\n    key: `\"openai\"`\n  },\n  concurrency: [\n    { key: \"event.data.accountId\", limit: 3 }\n  ]\n}\n```\n\n## Brownfield Migration\n\nWhen migrating an existing agent:\n\n1. Search for model calls, tool loops, in-memory state, streaming handlers,\n   approval polling, and external side effects.\n2. Keep prompt/tool behavior stable at first.\n3. Move the trigger into an event and an Inngest function.\n4. Move model calls to AgentKit / `step.ai`.\n5. Move side-effecting tools into `step.run` or durable tool handlers.\n6. Replace process-local waits with `step.waitForEvent` or\n   `step.waitForSignal`.\n7. Add realtime after the durable run is working.\n\nUse `inngest-brownfield-audit` first when the repo has multiple possible\nworkflows and the user has not picked one.\n\n## Anti-Patterns\n\n- Agent loop state only in memory.\n- One giant `try/catch` around all model and tool calls.\n- Retrying the entire agent after one tool failure.\n- Charging repeatedly for successful model calls after a later step fails.\n- `setTimeout`, cron polling, or Redis TTL as the human-review mechanism.\n- Side-effecting tools with no idempotency key.\n- Streaming progress from a server process that can die while the durable work\n  continues elsewhere.\n- Adding AgentKit without registering the surrounding Inngest function.\n\n## Verification\n\n- Typecheck the agent, tool schemas, and event payloads.\n- Unit-test tool handlers separately from model behavior.\n- Test that the HTTP entrypoint emits one deterministic event and returns fast.\n- Test that duplicate event IDs do not duplicate final side effects.\n- If possible, run the Inngest dev server and inspect the agent steps/traces.\n"
}