# Human in the Loop
Source: https://agentkit.inngest.com/advanced-patterns/human-in-the-loop

Enable your Agents to wait for human input.

Agents such as Support Agents, Coding or Research Agents might require human oversight.

By combining AgentKit with Inngest, you can create [Tools](/concepts/tools) that can wait for human input.

## Creating a "Human in the Loop" tool

"Human in the Loop" tools are implemented using Inngest's [`waitForEvent()`](https://www.inngest.com/docs/features/inngest-functions/steps-workflows/wait-for-event) step method:

```ts theme={"system"}
import { createTool } from "@inngest/agent-kit";

createTool({
  name: "ask_developer",
  description: "Ask a developer for input on a technical issue",
  parameters: z.object({
    question: z.string().describe("The technical question for the developer"),
    context: z.string().describe("Additional context about the issue"),
  }),
  handler: async ({ question, context }, { step }) => {
    if (!step) {
      return { error: "This tool requires step context" };
    }

    // Example: Send a Slack message to the developer

    // Wait for developer response event
    const developerResponse = await step.waitForEvent("developer.response", {
      event: "app/support.ticket.developer-response",
      timeout: "4h",
      match: "data.ticketId",
    });

    if (!developerResponse) {
      return { error: "No developer response provided" };
    }

    return {
      developerResponse: developerResponse.data.answer,
      responseTime: developerResponse.data.timestamp,
    };
  },
});
```

The `ask_developer` tool will wait up to 4 hours for a `"developer.response"` event to be received, pausing the execution of the AgentKit network.
The incoming `"developer.response"` event will be matched against the `data.ticketId` field of the event that trigger the AgentKit network.
For this reason, the AgentKit network will need to be wrapped in an Inngest function as demonstrated in the next section.

## Example: Support Agent with Human in the Loop

Let's consider a Support Agent Network automously triaging and solving tickets:

```tsx theme={"system"}
const customerSupportAgent = createAgent({
  name: "Customer Support",
  description:
    "I am a customer support agent that helps customers with their inquiries.",
  system: `You are a helpful customer support agent.
Your goal is to assist customers with their questions and concerns.
Be professional, courteous, and thorough in your responses.`,
  model: anthropic({
    model: "claude-3-5-haiku-latest",
    max_tokens: 1000,
  }),
  tools: [
    searchKnowledgeBase,
    // ...
  ],
});

const technicalSupportAgent = createAgent({
  name: "Technical Support",
  description: "I am a technical support agent that helps critical tickets.",
  system: `You are a technical support specialist.
Your goal is to help resolve critical tickets.
Use your expertise to diagnose problems and suggest solutions.
If you need developer input, use the ask_developer tool.`,
  model: anthropic({
    model: "claude-3-5-haiku-latest",
    max_tokens: 1000,
  }),
  tools: [
    searchLatestReleaseNotes,
    // ...
  ],
});

const supervisorRoutingAgent = createRoutingAgent({
  // ...
});

// Create a network with the agents and default router
const supportNetwork = createNetwork({
  name: "Support Network",
  agents: [customerSupportAgent, technicalSupportAgent],
  defaultModel: anthropic({
    model: "claude-3-5-haiku-latest",
    max_tokens: 1000,
  }),
  router: supervisorRoutingAgent,
});
```

<Info>
  You can find the complete example code in the
  [examples/support-agent-human-in-the-loop](https://github.com/inngest/agent-kit/tree/main/examples/support-agent-human-in-the-loop)
  directory.
</Info>

To avoid the Support Agent to be stuck or classifying tickets incorrectly, we'll implement a "Human in the Loop" tool to enable a human to add some context.

To implement a "Human in the Loop" tool, we'll need to embed our AgentKit network into an Inngest function.

### Transforming your AgentKit network into an Inngest function

First, you'll need to create an Inngest Client:

```ts src/inngest/client.ts theme={"system"}
import { Inngest } from "inngest";

const inngest = new Inngest({
  id: "my-agentkit-network",
});
```

Then, transform your AgentKit network into an Inngest function as follows:

```ts src/inngest/agent-network.ts {21-54} theme={"system"}
import { createAgent, createNetwork, openai } from "@inngest/agent-kit";
import { createServer } from "@inngest/agent-kit/server";

const customerSupportAgent = createAgent({
  name: "Customer Support",
  // ..
});

const technicalSupportAgent = createAgent({
  name: "Technical Support",
  // ..
});

// Create a network with the agents and default router
const supportNetwork = createNetwork({
  name: "Support Network",
  agents: [customerSupportAgent, technicalSupportAgent],
  // ..
});

const supportAgentWorkflow = inngest.createFunction(
  {
    id: "support-agent-workflow",
  },
  {
    event: "app/support.ticket.created",
  },
  async ({ step, event }) => {
    const ticket = await step.run("get_ticket_details", async () => {
      const ticket = await getTicketDetails(event.data.ticketId);
      return ticket;
    });

    if (!ticket || "error" in ticket) {
      throw new NonRetriableError(`Ticket not found: ${ticket.error}`);
    }

    const response = await supportNetwork.run(ticket.title);

    return {
      response,
      ticket,
    };
  }
);

// Create and start the server
const server = createServer({
  functions: [supportAgentWorkflow as any],
});

server.listen(3010, () =>
  console.log("Support Agent demo server is running on port 3010")
);
```

The `network.run()` is now performed by the Inngest function.

Don't forget to register the function with `createServer`'s `functions` property.

### Add a `ask_developer` tool to the network

Our AgentKit network is now ran inside an Inngest function triggered by the `"app/support.ticket.created"` event which carries
the `data.ticketId` field.

The `Technical Support` Agent will now use the `ask_developer` tool to ask a developer for input on a technical issue:

```ts theme={"system"}
import { createTool } from "@inngest/agent-kit";

createTool({
  name: "ask_developer",
  description: "Ask a developer for input on a technical issue",
  parameters: z.object({
    question: z.string().describe("The technical question for the developer"),
    context: z.string().describe("Additional context about the issue"),
  }),
  handler: async ({ question, context }, { step }) => {
    if (!step) {
      return { error: "This tool requires step context" };
    }

    // Example: Send a Slack message to the developer

    // Wait for developer response event
    const developerResponse = await step.waitForEvent("developer.response", {
      event: "app/support.ticket.developer-response",
      timeout: "4h",
      match: "data.ticketId",
    });

    if (!developerResponse) {
      return { error: "No developer response provided" };
    }

    return {
      developerResponse: developerResponse.data.answer,
      responseTime: developerResponse.data.timestamp,
    };
  },
});
```

Our `ask_developer` tool will now wait for a `"developer.response"` event to be received (ex: from a Slack message), and match it against the `data.ticketId` field.

The result of the `ask_developer` tool will be returned to the `Technical Support` Agent.

Look at the Inngest [`step.waitForEvent()`](https://www.inngest.com/docs/features/inngest-functions/steps-workflows/wait-for-event) documentation for more details and examples.

### Try it out

<Card title={`Support Agent with "Human in the loop"`} href="https://github.com/inngest/agent-kit/tree/main/examples/support-agent-human-in-the-loop#readme" icon="github">
  This Support AgentKit Network is composed of two Agents (Customer Support and
  Technical Support) and a Supervisor Agent that routes the ticket to the
  correct Agent. The Technical Support Agent can wait for a developer response
  when facing complex technical issues.
</Card>


# UI Streaming with useAgent
Source: https://agentkit.inngest.com/advanced-patterns/legacy-ui-streaming

Stream AgentKit events to your UI with the useAgent hook.

The `useAgent` hook is a powerful client-side hook for React that manages real-time, multi-threaded conversations with an AgentKit network. It encapsulates the entire lifecycle of agent interactions, including sending messages, receiving streaming events, handling out-of-order event sequences, and managing connection state.

While `useChat` is the recommended high-level hook for building chat interfaces, `useAgent` provides the low-level building blocks for more customized implementations where you need direct control over the event stream and state management.

<CardGroup>
  <Card title="use-agent Example" href="https://github.com/inngest/agent-kit/tree/main/examples/use-agent">
    Find the complete source code for a Next.js chat application using
    `useAgent` on GitHub.
  </Card>
</CardGroup>

## How it Works

`useAgent` builds upon Inngest's Realtime capabilities to create a persistent, unified stream of events for a user. Here’s a step-by-step breakdown of the data flow:

1. **Client Initialization**: The `useAgent` hook is initialized in your React component. It uses the `useInngestSubscription` hook from `@inngest/realtime/hooks` to establish a WebSocket connection.
2. **Authentication**: To connect, it calls a backend API route (e.g., `/api/realtime/token`) to get a short-lived subscription token. This token authorizes the client to listen to events on a specific user channel.
3. **Sending a Message**: The user types a message and the UI calls the `sendMessage` function returned by the hook.
4. **API Request**: `sendMessage` makes a `POST` request to a backend API route (e.g., `/api/chat`). This request contains the message content, the current `threadId`, and the conversation history.
5. **Triggering Inngest**: The chat API route receives the request and sends an `agent/chat.requested` event to Inngest using `inngest.send()`.
6. **Agent Execution**: An Inngest function (`run-agent-chat.ts` in our example) is triggered by the event. It sets up the AgentKit network, state, and history adapter.
7. **Running the Network**: The Inngest function calls `network.run(message, { streaming: ... })`.
8. **Streaming Events**: As the network and its agents execute, they generate streaming events (e.g., `run.started`, `part.created`, `text.delta`). The `streaming.publish` function inside the Inngest function forwards these events back to the user's realtime channel.
9. **Realtime Push**: The events are pushed over the WebSocket connection to the client.
10. **State Update**: `useAgent` receives the raw events, processes them in the correct sequence, handles out-of-order events, and updates its internal state.
11. **UI Re-render**: The component using the hook re-renders with the new messages, agent status, and other UI parts.

### Sequence Diagram

```mermaid theme={"system"}
sequenceDiagram
    participant Client (React UI)
    participant useAgent Hook
    participant Backend API
    participant Inngest
    participant AgentKit Network

    Client->>useAgent Hook: Initialize with threadId, userId
    useAgent Hook->>Backend API: POST /api/realtime/token
    Backend API-->>useAgent Hook: Subscription Token
    useAgent Hook->>Inngest: Establishes WebSocket Connection

    Client->>useAgent Hook: sendMessage("Hello!")
    useAgent Hook->>Backend API: POST /api/chat (message, history)
    Backend API->>Inngest: inngest.send("agent/chat.requested")

    Inngest->>AgentKit Network: Triggers Inngest Function (run-agent-chat.ts)
    AgentKit Network->>AgentKit Network: network.run(message, { streaming })

    loop Event Streaming
        AgentKit Network-->>Inngest: publish(event)
        Inngest-->>useAgent Hook: Pushes event via WebSocket
        useAgent Hook->>useAgent Hook: Processes event, updates state
        useAgent Hook-->>Client: Re-renders UI with new data
    end
```

## Usage Guide

### 1. Backend Setup

First, you need to set up the backend infrastructure to handle chat requests and realtime communication.

#### Inngest Function

This function is the core of your agent's execution. It listens for chat requests and runs your AgentKit network, streaming events back to the client.

```ts title="inngest/functions/run-agent-chat.ts" theme={"system"}
import { inngest } from "../client";
import { createCustomerSupportNetwork } from "../networks/customer-support-network";
import { userChannel } from "../../lib/realtime";
import { createState } from "@inngest/agent-kit";
import type { CustomerSupportState } from "../types/state";
import { PostgresHistoryAdapter } from "../db";

const historyAdapter = new PostgresHistoryAdapter<CustomerSupportState>({});

export const runAgentChat = inngest.createFunction(
  { id: "run-agent-chat" },
  { event: "agent/chat.requested" },
  async ({ event, step, publish }) => {
    await step.run("initialize-db-tables", () =>
      historyAdapter.initializeTables()
    );

    const { threadId, message, userId, history, messageId } = event.data;

    const network = createCustomerSupportNetwork(
      threadId,
      createState<CustomerSupportState>(
        { customerId: userId },
        { messages: history, threadId }
      ),
      historyAdapter
    );

    // Run the network and stream events back to the client
    const result = await network.run(message, {
      streaming: {
        publish: async (chunk) => {
          const enrichedChunk = {
            ...chunk,
            data: { ...chunk.data, threadId, userId },
          };
          await publish(userChannel(userId).agent_stream(enrichedChunk));
        },
      },
      messageId,
    });

    return { success: true, threadId, result };
  }
);
```

#### API Routes

You'll need a few API routes in your Next.js application.

```ts title="app/api/chat/route.ts" theme={"system"}
import { NextRequest, NextResponse } from "next/server";
import { inngest } from "@/inngest/client";
import { randomUUID } from "crypto";

export async function POST(req: NextRequest) {
  const {
    message,
    threadId: providedThreadId,
    userId,
    history,
    messageId,
  } = await req.json();
  const threadId = providedThreadId || randomUUID();

  await inngest.send({
    name: "agent/chat.requested",
    data: { threadId, message, messageId, history, userId },
  });

  return NextResponse.json({ success: true, threadId });
}
```

```ts title="app/api/realtime/token/route.ts" theme={"system"}
import { NextRequest, NextResponse } from "next/server";
import { getSubscriptionToken } from "@inngest/realtime";
import { inngest } from "@/inngest/client";
import { userChannel } from "@/lib/realtime";

export async function POST(req: NextRequest) {
  const { userId } = await req.json();
  // TODO: Add authentication/authorization here
  const token = await getSubscriptionToken(inngest, {
    channel: userChannel(userId),
    topics: ["agent_stream"],
  });
  return NextResponse.json(token);
}
```

### 2. Frontend Setup

Now, let's wire up the `useAgent` hook in a React component.

```tsx title="components/ChatComponent.tsx" theme={"system"}
"use client";

import { useAgent, type ConversationMessage } from "@/hooks/use-agent";

const USER_ID = "test-user-123";

export function ChatComponent({ threadId }: { threadId: string }) {
  const { messages, status, sendMessage, isConnected, error, clearError } =
    useAgent({
      threadId: threadId,
      userId: USER_ID,
      debug: true,
      onError: (err) => console.error("Agent error:", err),
    });

  const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    const formData = new FormData(e.currentTarget);
    const message = formData.get("message") as string;
    if (message.trim()) {
      sendMessage(message);
      e.currentTarget.reset();
    }
  };

  return (
    <div>
      <div>Status: {status}</div>
      <div>Connected: {isConnected ? "Yes" : "No"}</div>
      {error && (
        <div>
          Error: {error.message}
          <button onClick={clearError}>Clear</button>
        </div>
      )}

      <div className="message-list">
        {messages.map((msg) => (
          <Message key={msg.id} message={msg} />
        ))}
      </div>

      <form onSubmit={handleSubmit}>
        <input
          name="message"
          placeholder="Ask anything..."
          disabled={status !== "idle"}
        />
        <button type="submit" disabled={status !== "idle"}>
          Send
        </button>
      </form>
    </div>
  );
}

// A simple component to render a message with all its parts
function Message({ message }: { message: ConversationMessage }) {
  return (
    <div className={`message ${message.role}`}>
      <strong>{message.role}</strong>
      {message.parts.map((part, index) => {
        switch (part.type) {
          case "text":
            return <p key={index}>{part.content}</p>;
          case "tool-call":
            return (
              <div
                key={index}
                className="tool-call"
                style={{
                  border: "1px solid #ccc",
                  padding: "10px",
                  marginTop: "10px",
                  borderRadius: "5px",
                }}
              >
                <div>
                  <strong>Tool Call:</strong> {part.toolName}
                </div>
                <pre style={{ whiteSpace: "pre-wrap", wordBreak: "break-all" }}>
                  Status: {part.state}
                  <br />
                  Input: {JSON.stringify(part.input, null, 2)}
                  {part.output && (
                    <>
                      <br />
                      Output: {JSON.stringify(part.output, null, 2)}
                    </>
                  )}
                </pre>
              </div>
            );
          // TODO: Add cases for other part types like 'data', 'reasoning', etc.
          default:
            return null;
        }
      })}
    </div>
  );
}
```

## API Reference

The `useAgent` hook returns an object with the following properties and methods.

### State Properties

<ParamField type="ConversationMessage[]">
  The array of messages for the **current thread**. Each message contains an
  array of `parts` that are streamed in real-time.
</ParamField>

<ParamField type="AgentStatus">
  The current status of the agent for the active thread. It can be one of:
  `"idle"`, `"thinking"`, `"calling-tool"`, `"responding"`, or `"error"`.
</ParamField>

<ParamField type="{ message: string; ... } | undefined">
  An object containing details about the last error that occurred in the active
  thread. `undefined` if there is no error.
</ParamField>

<ParamField type="Record<string, ThreadState>">
  An object containing the full state for all active threads, indexed by
  `threadId`. This allows you to manage multiple conversations in the
  background.
</ParamField>

<ParamField type="string">
  The ID of the currently active/displayed thread.
</ParamField>

<ParamField type="boolean">
  `true` if the client is currently connected to the Inngest Realtime server.
</ParamField>

<ParamField type="{ message: string; ... } | undefined">
  An object containing details about a connection-level error (e.g., failure to
  get a subscription token).
</ParamField>

### Action Methods

<ParamField type="(message: string) => Promise<void>">
  Sends a message to the **current thread**. It handles optimistic UI updates
  and formats the history for the backend.
</ParamField>

<ParamField type="(threadId: string, message: string) => Promise<void>">
  Sends a message to a **specific thread**, which can be different from the
  currently active one.
</ParamField>

<ParamField type="(threadId: string) => void">
  Switches the active thread. This updates which thread's state is exposed via
  the top-level `messages`, `status`, and `error` properties.
</ParamField>

<ParamField type="(threadId: string) => void">
  Creates a new, empty thread in the local state.
</ParamField>

<ParamField type="() => void">
  Clears all messages from the **current thread's** local state.
</ParamField>

<ParamField type="(messages: ConversationMessage[]) => void">
  Replaces all messages in the **current thread's** local state. Useful for
  loading historical messages.
</ParamField>

<ParamField type="() => void">
  Clears the error state for the **current thread**.
</ParamField>

<ParamField type="() => void">
  Clears any connection-level error.
</ParamField>

## UI Data Models

The `useAgent` hook exposes a set of rich UI data models to make building chat interfaces easier. These types define the structure of messages and their constituent parts.

### ConversationMessage

Represents a complete message in the conversation, containing one or more parts.

```typescript theme={"system"}
export interface ConversationMessage {
  /** Unique identifier for this message */
  id: string;
  /** Whether this message is from the user or the assistant */
  role: "user" | "assistant";
  /** Array of message parts that make up the complete message */
  parts: MessagePart[];
  /** ID of the agent that created this message (for assistant messages) */
  agentId?: string;
  /** When this message was created */
  timestamp: Date;
  /** The status of the message, particularly for optimistic user messages */
  status?: "sending" | "sent" | "failed";
}
```

### MessagePart

A union type representing all possible parts of a message.

```typescript theme={"system"}
export type MessagePart =
  | TextUIPart
  | ToolCallUIPart
  | DataUIPart
  | FileUIPart
  | SourceUIPart
  | ReasoningUIPart
  | StatusUIPart
  | ErrorUIPart
  | HitlUIPart;
```

### TextUIPart

Represents a text message part that can be streamed character by character.

```typescript theme={"system"}
export interface TextUIPart {
  type: "text";
  /** Unique identifier for this text part */
  id: string;
  /** The text content, updated incrementally during streaming */
  content: string;
  /** Whether the text is still being streamed or is complete */
  status: "streaming" | "complete";
}
```

### ToolCallUIPart

Represents a tool call that the agent is making, with streaming input and output.

```typescript theme={"system"}
export interface ToolCallUIPart {
  type: "tool-call";
  /** Unique identifier for this tool call */
  toolCallId: string;
  /** Name of the tool being called */
  toolName: string;
  /** Current state of the tool call execution */
  state:
    | "input-streaming"
    | "input-available"
    | "awaiting-approval"
    | "executing"
    | "output-available";
  /** Tool input parameters, streamed incrementally */
  input: any;
  /** Tool output result, if available */
  output?: any;
  /** Error information if the tool call failed */
  error?: any;
}
```

*(For brevity, other part types like `DataUIPart`, `ReasoningUIPart`, etc., are omitted here but follow a similar structure. You can find their full definitions in the `use-agent.ts` file in the example.)*

### AgentStatus

Represents the current activity status of the agent.

```typescript theme={"system"}
export type AgentStatus =
  | "idle"
  | "thinking"
  | "calling-tool"
  | "responding"
  | "error";
```


# MCP as tools
Source: https://agentkit.inngest.com/advanced-patterns/mcp

Provide your Agents with MCP Servers as tools

AgentKit supports using [Claude's Model Context Protocol](https://modelcontextprotocol.io/) as tools.

Using MCP as tools allows you to use any MCP server as a tool in your AgentKit network, enabling your Agent
to access thousands of pre-built tools to interact with. Our integration with [Smithery](https://smithery.ai/)
provides a registry of MCP servers for common use cases, with more than 2,000 servers across multiple use cases.

## Using MCP as tools

AgentKit supports configuring MCP servers via `Streamable HTTP`, `SSE` or `WS` transports:

<CodeGroup>
  ```ts Self-hosted MCP server theme={"system"}
  import { createAgent } from "@inngest/agent-kit";

  const neonAgent = createAgent({
    name: "neon-agent",
    system: `You are a helpful assistant that help manage a Neon account.
    `,
    mcpServers: [
      {
        name: "neon",
        transport: {
          type: "ws",
          url: "ws://localhost:8080",
        },
      },
    ],
  });
  ```

  ```ts Smithery MCP server theme={"system"}
  import { createAgent } from "@inngest/agent-kit";
  import { createSmitheryUrl } from "@smithery/sdk/config.js";

  const smitheryUrl = createSmitheryUrl("https://server.smithery.ai/neon/ws", {
    neonApiKey: process.env.NEON_API_KEY,
  });

  const neonAgent = createAgent({
    name: "neon-agent",
    system: `You are a helpful assistant that help manage a Neon account.
    `,
    mcpServers: [
      {
        name: "neon",
        transport: {
          type: "streamable-http",
          url: neonServerUrl.toString(),
        },
      },
    ],
  });
  ```
</CodeGroup>

## `mcpServers` reference

The `mcpServers` parameter allows you to configure Model Context Protocol servers that provide tools for your agent. AgentKit automatically fetches the list of available tools from these servers and makes them available to your agent.

<ParamField type="MCP.Server[]">
  An array of MCP server configurations.
</ParamField>

### MCP.Server

<ParamField type="string">
  A short name for the MCP server (e.g., "github", "neon"). This name is used to
  namespace tools for each MCP server. Tools from this server will be prefixed
  with this name (e.g., "neon-createBranch").
</ParamField>

<ParamField type="TransportSSE | TransportWebsocket">
  The transport configuration for connecting to the MCP server.
</ParamField>

### TransportSSE

<ParamField type="'sse'">
  Specifies that the transport is Server-Sent Events.
</ParamField>

<ParamField type="string">
  The URL of the SSE endpoint.
</ParamField>

<ParamField type="EventSourceInit">
  Optional configuration for the EventSource.
</ParamField>

<ParamField type="RequestInit">
  Optional request configuration.
</ParamField>

### TransportWebsocket

<ParamField type="'ws'">
  Specifies that the transport is WebSocket.
</ParamField>

<ParamField type="string">
  The WebSocket URL of the MCP server.
</ParamField>

## Examples

<Card title="Neon Assistant Agent (using MCP)" href="https://github.com/inngest/agent-kit/tree/main/examples/mcp-neon-agent/#readme" icon="github">
  This examples shows how to use the [Neon MCP Smithery Server](https://smithery.ai/server/neon/) to build a Neon Assistant Agent that can help you manage your Neon databases.

  <br />

  <span>
    Agents
  </span>

  <span>
    Tools
  </span>

  <span>
    Network
  </span>

  <span>
    Integrations
  </span>

  <br />

  <span>
    Code-based Router
  </span>
</Card>


# Multi-steps tools
Source: https://agentkit.inngest.com/advanced-patterns/multi-steps-tools

Use multi-steps tools to create more complex Agents.

In this guide, we'll learn how to create a multi-steps tool that can be used in your AgentKit [Tools](/concepts/tools) to reliably perform complex operations.

By combining your AgentKit network with Inngest, each step of your tool will be **retried automatically** and you'll be able to **configure concurrency and throttling**.

<Info>
  **Prerequisites**

  Your AgentKit network [must be configured with Inngest](/getting-started/local-development#1-install-the-inngest-package).
</Info>

## Creating a multi-steps tool

Creating a multi-steps tool is done by creating an Inngest Function that will be used as a tool in your AgentKit network.

To create an Inngest Function, you'll need to create an Inngest Client:

```ts src/inngest/client.ts theme={"system"}
import { Inngest } from 'inngest';

const inngest = new Inngest({
  id: 'my-agentkit-network',
});
```

Then, we will implement our AgentKit Tool as an Inngest Function with multiple steps.
For example, we'll create a tool that searches for perform a research by crawling the web:

```ts src/inngest/tools/research-web.ts {10, 22, 27} theme={"system"}
import { inngest } from '../client';

export const researchWebTool = inngest.createFunction({ 
  id: 'research-web-tool',
}, {
  event: "research-web-tool/run"
}, async ({ event, step }) => {
    const { input } = event.data;

    const searchQueries = await step.ai.infer('generate-search-queries', {
      model: step.ai.models.openai({ model: "gpt-4o" }),
      // body is the model request, which is strongly typed depending on the model
      body: {
        messages: [{
          role: "user",
          content: `From the given input, generate a list of search queries to perform. \n ${input}`,
        }],
      },
    });

    const searchResults = await Promise.all(
        searchQueries.map(query => step.run('crawl-web', async (query) => {
        // perform crawling...
        })
    ));

    const summary = await step.ai.infer('summarize-search-results', {
      model: step.ai.models.openai({ model: "gpt-4o" }),
      body: {
        messages: [{
          role: "user",
          content: `Summarize the following search results: \n ${searchResults.join('\n')}`,
        }],
      },
    });

    return summary.choices[0].message.content;
});
```

Our `researchWebTool` Inngest defines 3 main steps.

* The `step.ai.infer()` call will offload the LLM requests to the Inngest infrastructe which will also handle retries.
* The `step.run()` call will run the `crawl-web` step in parallel.

All the above steps will be retried automatically in case of failure, resuming the AgentKit network upon completion of the tool.

## Using the multi-steps tool in your AgentKit network

We can now add our `researchWebTool` to our AgentKit network:

```ts src/inngest/agent-network.ts {2, 7, 18} theme={"system"}
import { createAgent, createNetwork, openai } from '@inngest/agent-kit';
import { createServer } from '@inngest/agent-kit/server';

import { researchWebTool } from './inngest/tools/research-web';


const deepResearchAgent = createAgent({ 
  name: 'Deep Research Agent',
  tools: [researchWebTool],
});

const network = createNetwork({
  name: 'My Network',
  defaultModel: openai({ model: "gpt-4o" }),
  agents: [deepResearchAgent],
});

const server = createServer({
  networks: [network],
  functions: [researchWebTool],
});

server.listen(3010, () => console.log("Agent kit running!"));
```

We first import our `researchWebTool` function and pass it to the `deepResearchAgent` [`tools` array](/reference/create-agent#param-tools).

Finally, we also need to pass the `researchWebTool` function to the `createServer()`'s `functions` array.

## Going further

<CardGroup>
  <Card title="Configuring Multitenancy" icon="arrows-rotate" href="/advanced-patterns/multitenancy">
    Learn how to configure user-based capacity for your AgentKit network.
  </Card>

  <Card title="Customizing the retries" icon="arrows-rotate" href="/advanced-patterns/retries">
    Learn how to customize the retries of your multi-steps tools.
  </Card>
</CardGroup>


# Configuring Multi-tenancy
Source: https://agentkit.inngest.com/advanced-patterns/multitenancy

Configure capacity based on users or organizations.

As discussed in the [deployment guide](/concepts/deployment), moving an AgentKit network into users' hands requires configuring usage limits.

To avoid having one user's usage affect another, you can configure multi-tenancy.

Multi-tenancy consists of configuring limits based on users or organizations (*called "tenants"*).
It can be easily configured on your AgentKit network using Inngest.

<Info>
  **Prerequisites**

  Your AgentKit network [must be configured with Inngest](/getting-started/local-development#1-install-the-inngest-package).
</Info>

## Configuring Multi-tenancy

Adding multi-tenancy to your AgentKit network is done by transforming your AgentKit network into an Inngest function.

### Transforming your AgentKit network into an Inngest function

First, you'll need to create an Inngest Client:

```ts src/inngest/client.ts theme={"system"}
import { Inngest } from "inngest";

const inngest = new Inngest({
  id: "my-agentkit-network",
});
```

Then, transform your AgentKit network into an Inngest function as follows:

```ts src/inngest/agent-network.ts {19-30, 33} theme={"system"}
import { createAgent, createNetwork, openai } from "@inngest/agent-kit";
import { createServer } from "@inngest/agent-kit/server";

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

const deepResearchAgent = createAgent({
  name: "Deep Research Agent",
  tools: [
    /* ... */
  ],
});

const network = createNetwork({
  name: "My Network",
  defaultModel: openai({ model: "gpt-4o" }),
  agents: [deepResearchAgent],
});

const deepResearchNetworkFunction = inngest.createFunction(
  {
    id: "deep-research-network",
  },
  {
    event: "deep-research-network/run",
  },
  async ({ event, step }) => {
    const { input } = event.data;
    return network.run(input);
  }
);

const server = createServer({
  functions: [deepResearchNetworkFunction],
});

server.listen(3010, () => console.log("Agent kit running!"));
```

The `network.run()` is now performed by the Inngest function.

Don't forget to register the function with `createServer`'s `functions` property.

### Configuring a concurrency per user

We can now configure the capacity by user by adding concurrency and throttling configuration to our Inngest function:

```ts src/inngest/agent-network.ts {8-13} theme={"system"}
import { createAgent, createNetwork, openai } from '@inngest/agent-kit';
import { createServer } from '@inngest/agent-kit/server';

import { inngest } from './inngest/client';

// network and agent definitions..

const deepResearchNetworkFunction = inngest.createFunction({ 
  id: 'deep-research-network',
  concurrency: [
      {
        key: "event.data.user_id",
        limit: 10,
      },
    ],
}, {
  event: "deep-research-network/run"
}, async ({ event, step }) => {
    const { input } = event.data;

    return network.run(input);
})

const server = createServer({
  functions: [deepResearchNetworkFunction],
});

server.listen(3010, () => console.log("Agent kit running!"));
```

Your AgentKit network will now be limited to 10 concurrent requests per user.

The same can be done to add [throttling](https://www.inngest.com/docs/guides/throttling?ref=agentkit-docs-multitenancy), [rate limiting](https://www.inngest.com/docs/guides/rate-limiting?ref=agentkit-docs-multitenancy) or [priority](https://www.inngest.com/docs/guides/priority?ref=agentkit-docs-multitenancy).

## Going further

<CardGroup>
  <Card title="Customizing the retries" icon="arrows-rotate" href="/advanced-patterns/retries">
    Learn how to customize the retries of your multi-steps tools.
  </Card>
</CardGroup>


# Configuring Retries
Source: https://agentkit.inngest.com/advanced-patterns/retries

Configure retries for your AgentKit network Agents and Tool calls.

Using AgentKit alongside Inngest enables automatic retries for your AgentKit network Agents and Tools calls.

The default retry policy is to retry 4 times with exponential backoff and can be configured by following the steps below.

<Info>
  **Prerequisites**

  Your AgentKit network [must be configured with Inngest](/getting-started/local-development#1-install-the-inngest-package).
</Info>

## Configuring Retries

Configuring a custom retry policy is done by transforming your AgentKit network into an Inngest function.

### Transforming your AgentKit network into an Inngest function

First, you'll need to create an Inngest Client:

```ts src/inngest/client.ts theme={"system"}
import { Inngest } from "inngest";

const inngest = new Inngest({
  id: "my-agentkit-network",
});
```

Then, transform your AgentKit network into an Inngest function as follows:

```ts src/inngest/agent-network.ts {19-30, 33} theme={"system"}
import { createAgent, createNetwork, openai } from "@inngest/agent-kit";
import { createServer } from "@inngest/agent-kit/server";

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

const deepResearchAgent = createAgent({
  name: "Deep Research Agent",
  tools: [
    /* ... */
  ],
});

const network = createNetwork({
  name: "My Network",
  defaultModel: openai({ model: "gpt-4o" }),
  agents: [deepResearchAgent],
});

const deepResearchNetworkFunction = inngest.createFunction(
  {
    id: "deep-research-network",
  },
  {
    event: "deep-research-network/run",
  },
  async ({ event, step }) => {
    const { input } = event.data;
    return network.run(input);
  }
);

const server = createServer({
  functions: [deepResearchNetworkFunction],
});

server.listen(3010, () => console.log("Agent kit running!"));
```

The `network.run()` is now performed by the Inngest function.

Don't forget to register the function with `createServer`'s `functions` property.

### Configuring a custom retry policy

We can now configure the capacity by user by adding concurrency and throttling configuration to our Inngest function:

```ts src/inngest/agent-network.ts {8} theme={"system"}
import { createAgent, createNetwork, openai } from '@inngest/agent-kit';
import { createServer } from '@inngest/agent-kit/server';

import { inngest } from './inngest/client';

// network and agent definitions..

const deepResearchNetworkFunction = inngest.createFunction({ 
  id: 'deep-research-network',
  retries: 1
}, {
  event: "deep-research-network/run"
}, async ({ event, step }) => {
    const { input } = event.data;

    return network.run(input);
})

const server = createServer({
  functions: [deepResearchNetworkFunction],
});

server.listen(3010, () => console.log("Agent kit running!"));
```

Your AgentKit network will now retry once on any failure happening during a single execution cycle of your network.

## Going further

<CardGroup>
  <Card title="Configuring Multitenancy" icon="arrows-rotate" href="/advanced-patterns/multitenancy">
    Learn how to configure user-based capacity for your AgentKit network.
  </Card>
</CardGroup>


# Deterministic state routing
Source: https://agentkit.inngest.com/advanced-patterns/routing

State based routing in Agent Networks

State based routing is a deterministic approach to managing agent workflows, allowing for more reliable, testable, and maintainable AI agent systems. This documentation covers the core concepts and implementation details based on the Inngest AgentKit framework.

## Core Concepts

State based routing models agent workflows as a state machine where:

* Each agent has a specific goal within a larger network
* The network combines agents to achieve an overall objective, with shared state modified by each agent
* The network's router inspects state and determines which agent should run next
* The network runs in a loop, calling the router on each iteration until all goals are met
* Agents run with updated conversation history and state on each loop iteration

## Benefits

Unlike fully autonomous agents that rely on complex prompts to determine their own actions, state based routing:

* Makes agent behavior more predictable
* Simplifies testing and debugging
* Allows for easier identification of failure points
* Provides clear separation of concerns between agents

## Implementation Structure

A state based routing system consists of:

1. State Definition

Define structured data that represents the current progress of your workflow:

```typescript theme={"system"}
export interface AgentState {
  // files stores all files that currently exist in the repo.
  files?: string[];

  // plan is the plan created by the planning agent.  It is optional
  // as, to begin with, there is no plan.  This is set by the planning
  // agent's tool.
  plan?: {
    thoughts: string;
    plan_details: string;
    edits: Array<{
      filename: string;
      idea: string;
      reasoning: string;
    }>;
  },

  // done indicates whether we're done editing files, and terminates the
  // network when true.
  done: boolean;
}
```

2. Network and router implementation

Create a router function that inspects state and returns the appropriate agent:

```typescript theme={"system"}
export const codeWritingNetwork = createNetwork<AgentState>({
  name: "Code writing network",
  agents: [], // We'll add these soon.
  router: ({ network }): Agent | undefined => {
    // The router inspects network state to figure out which agent to call next.

    if (network.state.data.done) {
        // We're done editing.  This is set when the editing agent finishes
        // implementing the plan.
        //
        // At this point, we could hand off to another agent that tests, critiques,
        // and validates the edits.  For now, return undefined to signal that
        // the network has finished.
        return;
    }
  
    // By default, there is no plan and we should use the planning agent to read and
    // understand files.  The planning agent's `create_plan` tool modifies state once
    // it's gathered enough context, which will then cause the router loop to pass
    // to the editing agent below.
    if (network.state.data.plan === undefined) {
        return planningAgent;
    }
  
    // There is a plan, so switch to the editing agent to begin implementing.
    //
    // This lets us separate the concerns of planning vs editing, including using differing
    // prompts and tools at various stages of the editing process.
    return editingAgent;
  }
}
```

A router has the following definition:

```typescript theme={"system"}
// T represents the network state's type.
type RouterFunction<T> = (args: {
  input: string;
  network: NetworkRun<T>;
  stack: Agent<T>[];
  callCount: number;
  lastResult?: InferenceResult;
}) => Promise<Agent<T> | undefined>;
```

The router has access to:

* `input`: The original input string passed to the network
* `network`: The current network run instance with state
* `stack`: Array of pending agents to be executed
* `callCount`: Number of agent invocations made
* `lastResult`: The most recent inference result from the last agent execution

3. Agent Definition

Define agents with specific goals and tools.  Tools modify the network's state.  For example, a classification agent
may have a tool which updates the state's `classification` property, so that in the next network loop we can
determine which new agent to run for the classified request.

```typescript theme={"system"}
// This agent accepts the network state's type, so that tools are properly typed and can
// modify state correctly.
export const planningAgent = createAgent<AgentState>({
  name: "Planner",
  description: "Plans the code to write and which files should be edited",
  tools: [
    listFilesTool,

    createTool({
      name: "create_plan",
      description:
        "Describe a formal plan for how to fix the issue, including which files to edit and reasoning.",
      parameters: z.object({
        thoughts: z.string(),
        plan_details: z.string(),
        edits: z.array(
          z.object({
            filename: z.string(),
            idea: z.string(),
            reasoning: z.string(),
          })
        ),
      }),

      handler: async (plan, opts:  Tool.Options<AgentState>) => {
        // Store this in the function state for introspection in tracing.
        await opts.step?.run("plan created", () => plan);
        if (opts.network) {
          opts.network.state.data.plan = plan;
        }
      },
    }),
  ],

  // Agent prompts can also inspect network state and conversation history.
  system: ({ network }) => `
    You are an expert Python programmer working on a specific project: ${network?.state.data.repo}.

    You are given an issue reported within the project.  You are planning how to fix the issue by investigating the report,
    the current code, then devising a "plan" - a spec - to modify code to fix the issue.

    Your plan will be worked on and implemented after you create it.   You MUST create a plan to
    fix the issue.  Be thorough. Think step-by-step using available tools.

    Techniques you may use to create a plan:
    - Read entire files
    - Find specific classes and functions within a file
  `,
});
```

## Execution Flow

When the network runs:

* The network router inspects the current state
* It returns an agent to run based on state conditions (or undefined to quit)
* The agent executes with access to previous conversation history, current state, and tools
* Tools update the state with new information
* The router runs again with updated state and conversation history
* This continues until the router returns without an agent (workflow complete)

## Best Practices

* **Keep agent goals focused and specific**:  Each agent should have a specific goal, and your network should combine agents to solve a larger problem.  This makes agents easy to design and test, and it makes routing logic far easier.
* **Design state to clearly represent workflow progress**:  Moving state out of conversation history and into structured data makes debugging agent workflows simple.
* **Use tools to update state in a structured way**:  Tools allow you to extract structured data from agents and modify state, making routing easy.
* **Implement iteration limits to prevent infinite loops**:  The router has a `callCount` parameter allowing you to quit early.

## Error Handling

When deployed to [Inngest](https://www.inngest.com), AgentKit provides built-in error handling:

* Automatic retries for failed agent executions
* State persistence between retries
* Ability to inspect state at any point in the workflow
* Tracing capabilities for debugging


# Changelog
Source: https://agentkit.inngest.com/changelog/overview

Recent releases, new features, and fixes.

<Update label="2025-03-11" description="v0.5.0">
  * Introducing support for [Grok models](/reference/model-grok)
  * Adding support for [Gemini latest models](/reference/model-gemini)
</Update>

<Update label="2025-03-06" description="v0.4.0">
  * Add support for model hyper params (ex: temperature, top\_p, etc)
    * Breaking change: `anthropic()` `max_tokens` options has been moved in `defaultParameters`
  * Add support OpenAI o3-mini, gpt-4.5, and more
  * [Integration with Browserbase](/integrations/browserbase)
</Update>

<Update label="2025-02-19" description="v0.3.0">
  * remove `server` export to allow non-Node runtimes
  * allow tools with no parameters
  * [Integration with E2B Code Interpreter](/integrations/e2b)
</Update>

<Update label="2025-01-29" description="v0.2.2">
  * Allow specifying [Inngest functions as tools](/advanced-patterns/multi-steps-tools)
  * Inngest is now an optional dependency
</Update>

<Update label="2025-01-16" description="v0.2.1">
  * Fixed OpenAI adapter to safely parse non-string tool return values for Function calling
  * Various documentation improvements
</Update>

<Update label="2025-01-16" description="v0.2.0">
  * Added support for Model Context Protocol (MCP) tool calling
  * Added basic development server
  * Fixed Anthropic model to ensure proper message handling
  * Improved code samples and concepts documentation
  * Added comprehensive quick start guide
  * Fixed bundling issues
  * Improved model exports for better discovery
  * Various cross-platform compatibility improvements
</Update>

<Update label="2024-12-19" description="v0.1.2">
  * Fixed state reference handling in agents
  * Updated SWEBench example configuration
  * Various stability improvements
</Update>

<Update label="2024-12-19" description="v0.1.1">
  * Fixed network to agent state propagation in run
  * Improved git clone handling in SWEBench example
  * Various minor improvements
</Update>

<Update label="2024-12-19" description="v0.1.0">
  * Initial release of AgentKit
  * Core framework implementation with lifecycle management
  * Support for OpenAI and Anthropic models
  * Network and Agent architecture with state management
  * ReAct implementation for networks
  * Tool calling support for agents
  * Added SWEBench example
  * Comprehensive documentation structure
  * Stepless model/network/agent instantiations
</Update>


# Agents
Source: https://agentkit.inngest.com/concepts/agents

Create agents to accomplish specific tasks with tools inside a network.

Agents are the core of AgentKit. Agents are *stateless* entities with a defined goal and an optional set of [Tools](/concepts/tools) that can be used to accomplish a goal.

Agents can be called individually or, more powerfully, composed into a [Network](/concepts/networks) with multiple agents that can work together with persisted [State](/concepts/state).

At the most basic level, an Agent is a wrapper around a specific provider's [model](/concepts/models), OpenAI gpt-4 for example, and a set of of [tools](/concepts/tools).

## Creating an Agent

To create a simple Agent, all that you need is a `name`, `system` prompt and a `model`. All configuration options are detailed in the `createAgent` [reference](/reference/agent).

Here is a simple agent created using the `createAgent` function:

```ts theme={"system"}
import { createAgent, openai } from '@inngest/agent-kit';

const codeWriterAgent = createAgent({
  name: 'Code writer',
  system:
    'You are an expert TypeScript programmer.  Given a set of asks, you think step-by-step to plan clean, ' +
    'idiomatic TypeScript code, with comments and tests as necessary.' +
    'Do not respond with anything else other than the following XML tags:' +
    '- If you would like to write code, add all code within the following tags (replace $filename and $contents appropriately):' +
    "  <file name='$filename.ts'>$contents</file>",
  model: openai('gpt-4o-mini'),
});
```

<Tip>
  While `system` prompts can be static strings, they are more powerful when they
  are [dynamic system prompts](#dynamic-system-prompts) defined as callbacks
  that can add additional context at runtime.
</Tip>

Any Agent can be called using `run()` with a user prompt. This performs an inference call to the model with the system prompt as the first message and the input as the user message.

```ts theme={"system"}
const { output } = codeWriterAgent.run(
  'Write a typescript function that removes unnecessary whitespace',
);
console.log(output);
// [{ role: 'assistant', content: 'function removeUnecessaryWhitespace(...' }]
```

<Tip>
  When including your Agent in a Network, a `description` is required. Learn
  more about [using Agents in Networks here](#using-agents-in-networks).
</Tip>

## Adding tools

[Tools](/concepts/tools) are functions that extend the capabilities of an Agent. Along with the prompt (see `run()`), Tools are included in calls to the language model through features like OpenAI's "[function calling](https://platform.openai.com/docs/guides/function-calling)" or Claude's "[tool use](https://docs.anthropic.com/en/docs/build-with-claude/tool-use)."

Tools are defined using the `createTool` function and are passed to agents via the `tools` parameter:

```ts theme={"system"}
import { createAgent, createTool, openai } from '@inngest/agent-kit';

const listChargesTool = createTool({
  name: 'list_charges',
  description:
    "Returns all of a user's charges. Call this whenever you need to find one or more charges between a date range.",
  parameters: z.array(
    z.object({
      userId: z.string(),
    }),
  ),
  handler: async (output, { network, agent, step }) => {
    // output is strongly typed to match the parameter type.
  },
});

const supportAgent = createAgent({
  name: 'Customer support specialist',
  system: 'You are an customer support specialist...',
  model: openai('gpt-3.5-turbo'),
  tools: [listChargesTool],
});
```

When `run()` is called, any step that the model decides to call is immediately executed before returning the output. Read the "[How agents work](#how-agents-work)" section for additional information.

Learn more about Tools in [this guide](/concepts/tools).

## How Agents work

Agents themselves are relatively simple. When you call `run()`, there are several steps that happen:

<Steps>
  <Step title="Preparing the prompts">
    The initial messages are created using the `system` prompt, the `run()` user
    prompt, and [Network State](/concepts/network-state), if the agent is part
    of a [Network](/concepts/networks).

    <Info>
      For added control, you can dynamically modify the Agent's prompts before the next step using the `onStart` [lifecycle hook](#lifecycle-hooks).
    </Info>
  </Step>

  <Step title="Inference call">
    An inference call is made to the provided [`model`](/concepts/models) using Inngest's [`step.ai`](https://www.inngest.com/docs/features/inngest-functions/steps-workflows/step-ai-orchestration#step-tools-step-ai). `step.ai` automatically retries on failure and caches the result for durability.

    The result is parsed into an `InferenceResult` object that contains all messages, tool calls and the raw API response from the model.

    <Info>
      To modify the result prior to calling tools, use the optional `onResponse` [lifecycle hook](#lifecycle-hooks).
    </Info>
  </Step>

  <Step title="Tool calling">
    If the model decides to call one of the available `tools`, the Tool is automatically called.

    <Info>
      After tool calling is complete, the `onFinish` [lifecycle hook](#lifecycle-hooks) is called with the updated `InferenceResult`. This enables you to modify or inspect the output of the called tools.
    </Info>
  </Step>

  <Step title="Complete">
    The result is returned to the caller.
  </Step>
</Steps>

### Lifecycle hooks

Agent lifecycle hooks can be used to intercept and modify how an Agent works enabling dynamic control over the system:

```tsx theme={"system"}
import { createAgent, openai } from '@inngest/agent-kit';

const agent = createAgent({
  name: 'Code writer',
  description: 'An expert TypeScript programmer which can write and debug code.',
  system: '...',
  model: openai('gpt-3.5-turbo'),
  lifecycle: {
    onStart: async ({ prompt,  network: { state }, history }) => {
      // Dynamically alter prompts using Network state and history.

      return { prompt, history }
    },
  },
});
```

As mentioned in the "[How Agents work](#how-agents-work)" section, there are a few lifecycle hooks that can be defined on the Agent's `lifecycle` options object.

* Dynamically alter prompts using Network [State](/concepts/state) or the Network's history.
* Parse output of model after an inference call.

Learn more about lifecycle hooks and how to define them in [this reference](/reference/create-agent#lifecycle).

## System prompts

An Agent's system prompt can be defined as a string or an async callback. When Agents are part of a [Network](/concepts/networks), the Network [State](/concepts/state) is passed as an argument to create dynamic prompts, or instructions, based on history or the outputs of other Agents.

### Dynamic system prompts

Dynamic system prompts are very useful in agentic workflows, when multiple models are called in a loop, prompts can be adjusted based on network state from other call outputs.

```ts theme={"system"}
const agent = createAgent({
  name: 'Code writer',
  description:
    'An expert TypeScript programmer which can write and debug code.',

  // The system prompt can be dynamically created at runtime using Network state:
  system: async ({ network }) => {
    // A default base prompt to build from:
    const basePrompt =
      'You are an expert TypeScript programmer. ' +
      'Given a set of asks, think step-by-step to plan clean, ' +
      'idiomatic TypeScript code, with comments and tests as necessary.';

    // Inspect the Network state, checking for existing code saved as files:
    const files: Record<string, string> | undefined = network.state.data.files;
    if (!files) {
      return basePrompt;
    }

    // Add the files from Network state as additional context automatically
    let additionalContext = 'The following code already exists:';
    for (const [name, content] of Object.entries(files)) {
      additionalContext += `<file name='${name}'>${content}</file>`;
    }
    return `${basePrompt} ${additionalContext}`;
  },
});
```

### Static system prompts

Agents may also just have static system prompts which are more useful for simpler use cases.

```ts theme={"system"}
const codeWriterAgent = createAgent({
  name: 'Copy editor',
  system:
    `You are an expert copy editor. Given a draft article, you provide ` +
    `actionable improvements for spelling, grammar, punctuation, and formatting.`,
  model: openai('gpt-3.5-turbo'),
});
```

## Using Agents in Networks

Agents are the most powerful when combined into [Networks](/concepts/networks). Networks include [state](/concepts/state) and [routers](/concepts/routers) to create stateful workflows that can enable Agents to work together to accomplish larger goals.

### Agent descriptions

Similar to how [Tools](/concepts/tools) have a `description` that enables an LLM to decide when to call it, Agents also have an `description` parameter. This is *required* when using Agents within Networks. Here is an example of an Agent with a description:

```ts theme={"system"}
const codeWriterAgent = createAgent({
  name: 'Code writer',
  description:
    'An expert TypeScript programmer which can write and debug code. Call this when custom code is required to complete a task.',
  system: `...`,
  model: openai('gpt-3.5-turbo'),
});
```


# Deployment
Source: https://agentkit.inngest.com/concepts/deployment

Deploy your AgentKit networks to production.

Deploying an AgentKit network to production is straightforward but there are a few things to consider:

* **Scalability**: Your Network Agents rely on tools which interact with external systems. You'll need to ensure that your deployment environment can scale to handle the requirements of your network.
* **Reliability**: You'll need to ensure that your AgentKit network can handle failures and recover gracefully.
* **Multitenancy**: You'll need to ensure that your AgentKit network can handle multiple users and requests concurrently without compromising on performance or security.

All the above can be easily achieved by using Inngest alongside AgentKit.
By installing the Inngest SDK, your AgentKit network will automatically benefit from:

* [**Multitenancy support**](/advanced-patterns/multitenancy) with fine grained concurrency and throttling configuration
* **Retrieable and [parallel tool calls](/advanced-patterns/retries)** for reliable and performant tool usage
* **LLM requests offloading** to improve performance and reliability for Serverless deployments
* **Live and detailed observability** with step-by-step traces including the Agents inputs/outputs and token usage

You will find below instructions to configure your AgentKit network deployment with Inngest.

## Deploying your AgentKit network with Inngest

Deploying your AgentKit network with Inngest to benefit from automatic retries, LLM requests offloading and live observability only requires
a few steps:

### 1. Install the Inngest SDK

<CodeGroup>
  ```shell npm theme={"system"}
  npm install inngest
  ```

  ```shell pnpm theme={"system"}
  pnpm install inngest
  ```

  ```shell yarn theme={"system"}
  yarn add inngest
  ```
</CodeGroup>

### 2. Serve your AgentKit network over HTTP

Update your AgentKit network to serve over HTTP as follows:

```ts {1, 8-13} theme={"system"}
import { createNetwork } from '@inngest/agent-kit';
import { createServer } from '@inngest/agent-kit/server';

const network = createNetwork({
  name: 'My Network',
  agents: [/* ... */],
});

const server = createServer({
  networks: [network],
});

server.listen(3010, () => console.log("Agent kit running!"));
```

### 3. Deploy your AgentKit network

**Configuring environment variables**

[Create an Inngest account](https://www.inngest.com/?ref=agentkit-docs-deployment) and open the top right menu to access your Event Key and Signing Key:

<Frame>
  <img alt="Inngest Event Key and Signing Key" />
</Frame>

Then configure the following environment variables into your deployment environment (*ex: AWS, Vercel, GCP*):

* `INNGEST_API_KEY`: Your Event Key
* `INNGEST_SIGNING_KEY`: Your Signing Key

**Deploying your AgentKit network**

You can now deploy your AgentKit network to your preferred cloud provider.
Once deployed, copy the deployment URL for the final configuration step.

### 4. Sync your AgentKit network with the Inngest Platform

On your Inngest dashboard, click on the "Sync new app" button at the top right of the screen.

Then, paste the deployment URL into the "App URL" by adding `/api/inngest` to the end of the URL:

<Frame>
  <img alt="Inngest Event Key and Signing Key" />
</Frame>

<Info>
  **You sync is failing?**

  Read our [troubleshooting guide](https://www.inngest.com/docs/apps/cloud?ref=agentkit-docs-deployment#troubleshooting) for more information.
</Info>

Once the sync succeeds, you can navigate to the *Functions* tabs where you will find your AgentKit network:

<Frame>
  <img alt="Inngest Event Key and Signing Key" />
</Frame>

Your AgentKit network can now be triggered manually from the Inngest Dashboard or [from your app using `network.run()`](/concepts/networks).

## Configuring Multitenancy and Retries

<CardGroup>
  <Card title="Multitenancy" icon="users" href="/advanced-patterns/multitenancy">
    Configure usage limits based on users or organizations.
  </Card>

  <Card title="Retries" icon="arrows-rotate" href="/advanced-patterns/retries">
    Learn how to configure retries for your AgentKit Agents and Tools.
  </Card>
</CardGroup>


# History
Source: https://agentkit.inngest.com/concepts/history

Learn how to persist conversations for your agents and networks

## Overview

AgentKit enables persistent conversations that maintain context across multiple runs. By implementing a **History Adapter**, you can connect your agents and networks to any database or storage solution, allowing conversations to resume exactly where they left off.

A History Adapter is a configuration object that bridges AgentKit's execution lifecycle with your database. It tells AgentKit how to:

1. **Create** new conversation threads
2. **Load** existing conversation history
3. **Save** new messages and results

AgentKit is database-agnostic. You can use PostgreSQL, MongoDB, Redis, or any
storage solution by implementing the `HistoryConfig` interface.

The adapter is passed to `createAgent()` or `createNetwork()` and AgentKit automatically calls your adapter's methods at the appropriate times during execution.

### HistoryConfig Interface

The `HistoryConfig` interface has four optional methods. Below is an expanded view of the interface showing the context and parameters passed to each method.

```typescript theme={"system"}
import type {
  State,
  NetworkRun,
  AgentResult,
  GetStepTools,
  StateData,
} from "@inngest/agent-kit";

interface HistoryConfig<T extends StateData> {
  /**
   * Creates a new conversation thread or ensures it exists.
   * Invoked at the start of a run to initialize the thread.
   */
  createThread?: (ctx: {
    state: State<T>; // The current state, including your custom data
    input: string; // The user's input string
    network?: NetworkRun<T>; // The network instance (if applicable)
    step?: GetStepTools; // Inngest step tools for durable execution
  }) => Promise<{ threadId: string }>;

  /**
   * Retrieves conversation history from your database.
   * Invoked after thread initialization if no history is provided by the client.
   */
  get?: (ctx: {
    threadId?: string; // The ID of the conversation thread
    state: State<T>;
    input: string;
    network: NetworkRun<T>;
    step?: GetStepTools;
  }) => Promise<AgentResult[]>;

  /**
   * Saves the user's message at the beginning of a run.
   * Invoked immediately after thread initialization, before any agents run.
   */
  appendUserMessage?: (ctx: {
    threadId?: string;
    userMessage: {
      id: string; // Canonical, client-generated message ID
      content: string;
      role: "user";
      timestamp: Date;
    };
    state: State<T>;
    input: string;
    network: NetworkRun<T>;
    step?: GetStepTools;
  }) => Promise<void>;

  /**
   * Saves new agent results to your database after a run.
   * Invoked at the end of a successful agent or network run.
   */
  appendResults?: (ctx: {
    threadId?: string;
    newResults: AgentResult[]; // The new results generated during this run
    state: State<T>;
    input: string;
    network: NetworkRun<T>;
    step?: GetStepTools;
  }) => Promise<void>;
}
```

#### `createThread`

* Creates a new conversation thread in your database or ensures an existing thread is present
* Invoked at the start of a run to initialize the thread
* **Important**: If a `threadId` already exists in the state, your adapter should upsert (insert or update) to ensure the thread exists in storage
* Returns an object with the `threadId`

#### `get`

* Retrieves conversation history from your database
* Invoked after thread initialization, but **only if**:
  * A `threadId` is present in the state
  * The client didn't provide `results` or `messages`
  * The thread was not just created in this run (client provided the threadId)
* Returns an array of `AgentResult[]` representing the conversation history
* **Recommended**: Include both user messages and agent results by converting user messages to `AgentResult` objects with `agentName: "user"` to preserve conversation order

#### `appendUserMessage`

* Saves the user's message immediately at the beginning of a run
* Invoked after thread initialization but before any agents execute
* Ensures user intent is captured even if the agent run fails (enables "regenerate" workflows)
* Receives the user's message with a canonical, client-generated ID for idempotency

#### `appendResults`

* Saves new agent results to your database after a network or agent run
* Invoked at the end of a successful agent or network run
* Receives only the *new* results generated during this run (AgentKit automatically filters out historical results to prevent duplicates)

***

## Usage

Here's a complete example of creating a network with history persistence:

```typescript theme={"system"}
import {
  createNetwork,
  createAgent,
  createState,
  openai,
} from "@inngest/agent-kit";
import { db } from "./db"; // Your database client

// Define your history adapter with all four methods
const conversationHistoryAdapter: HistoryConfig<any> = {
  // 1. Create new conversation threads (or ensure they exist)
  createThread: async ({ state, input }) => {
    // If a threadId already exists, upsert to ensure it's in the database
    if (state.threadId) {
      await db.thread.upsert({
        where: { id: state.threadId },
        update: { updatedAt: new Date() },
        create: {
          id: state.threadId,
          userId: state.data.userId,
          title: input.slice(0, 50),
          createdAt: new Date(),
        },
      });
      return { threadId: state.threadId };
    }

    // Otherwise, create a new thread
    const thread = await db.thread.create({
      data: {
        userId: state.data.userId,
        title: input.slice(0, 50), // First 50 chars as title
        createdAt: new Date(),
      },
    });
    return { threadId: thread.id };
  },

  // 2. Load conversation history (including user messages)
  get: async ({ threadId }) => {
    if (!threadId) return [];

    const messages = await db.message.findMany({
      where: { threadId },
      orderBy: { createdAt: "asc" },
    });

    // Transform ALL messages (user + agent) to AgentResult format
    // This preserves the complete conversation order
    return messages.map((msg) => {
      if (msg.role === "user") {
        // Convert user messages to AgentResult with agentName: "user"
        return new AgentResult(
          "user",
          [
            {
              type: "text" as const,
              role: "user" as const,
              content: msg.content,
              stop_reason: "stop",
            },
          ],
          [],
          new Date(msg.createdAt)
        );
      } else {
        // Return agent results
        return new AgentResult(
          msg.agentName,
          [
            {
              type: "text" as const,
              role: "assistant" as const,
              content: msg.content,
            },
          ],
          [],
          new Date(msg.createdAt)
        );
      }
    });
  },

  // 3. Save user message immediately (before agents run)
  appendUserMessage: async ({ threadId, userMessage }) => {
    if (!threadId) return;

    await db.message.create({
      data: {
        messageId: userMessage.id, // Use canonical client-generated ID
        threadId,
        role: "user",
        content: userMessage.content,
        createdAt: userMessage.timestamp,
      },
    });
  },

  // 4. Save agent results after the run
  appendResults: async ({ threadId, newResults }) => {
    if (!threadId) return;

    // Save only agent responses (user message already saved)
    for (const result of newResults) {
      const content = result.output
        .filter((msg) => msg.type === "text")
        .map((msg) => msg.content)
        .join("\n");

      await db.message.create({
        data: {
          messageId: result.id || crypto.randomUUID(), // Use result.id if available
          threadId,
          role: "assistant",
          agentName: result.agentName,
          content,
          checksum: result.checksum, // For idempotency
          createdAt: result.createdAt,
        },
      });
    }
  },
};
```

***

Once you've created your adapter, pass it to the `history` property when creating an agent or network:

<CodeGroup>
  ```typescript Agent theme={"system"}
  import { createAgent } from "@inngest/agent-kit";
  import { postgresHistoryAdapter } from "./my-postgres-adapter";

  const chatAgent = createAgent({
    name: "chat-agent",
    system: "You are a helpful assistant.",
    history: postgresHistoryAdapter, // Add your adapter here
  });

  // Now the agent will automatically persist conversations
  await chatAgent.run("Hello!", {
    state: createState({ userId: "user123" }, { threadId: "thread-456" }),
  });
  ```

  ```typescript Network theme={"system"}
  import { createNetwork, createAgent } from "@inngest/agent-kit";
  import { postgresHistoryAdapter } from "./my-postgres-adapter";

  const chatAgent = createAgent({
    name: "chat-agent",
    system: "You are a helpful assistant.",
  });

  const chatNetwork = createNetwork({
    name: "Chat Network",
    agents: [chatAgent],
    history: postgresHistoryAdapter, // Add your adapter here
  });

  // The entire network will use persistent conversations
  await chatNetwork.run("Hello!");
  ```
</CodeGroup>

***

## Persistence Patterns

AgentKit supports two distint patterns for managing conversation history.

### Server-Authoritative

The client sends a message with a `threadId`. AgentKit automatically loads the full conversation context from your database before the network runs.

```typescript theme={"system"}
// Client sends just the threadId
const state = createState(
  { userId: "user123" },
  { threadId: "existing-thread-id" }
);

await chatNetwork.run("Continue our conversation", { state });
// AgentKit calls history.get() to load full context for all agents
```

**Use case**: Perfect for restoring conversations after page refresh or when opening the app on a new device.

### Client-Authoritative (Performance Optimized)

The client maintains conversation state locally and sends the complete history with each request. AgentKit detects this and skips the database read for better performance.

```typescript theme={"system"}
// Client sends the full conversation history
const state = createState(
  { userId: "user123" },
  {
    threadId: "thread-id",
    results: previousConversationResults, // Full history from client
  }
);

await chatNetwork.run("New message", { state });
// AgentKit skips history.get() call - faster performance!
// Still calls appendUserMessage() and appendResults() to save new messages
```

**Use case**: Ideal for interactive chat applications where the frontend maintains conversation state and fetches messages from an existing/separate API

**Note**: Providing either `results` or `messages` to `createState` will disable the `history.get()` call, enabling this client-authoritative pattern.

### Server/Client Hybrid Pattern

You can combine the Server-Authoritative and Client-Authoritative patterns for an optimal user experience. This hybrid approach allows for fast initial conversation loading and high-performance interactive chat.

1. **Initial Load (Server-Authoritative):** When a user opens a conversation thread, the client sends only the `threadId`. AgentKit fetches the history from your database using `history.get()`. The application then hydrates the client-side state with this history.
2. **Interactive Session (Client-Authoritative):** For all subsequent requests within the session, the client sends the full, up-to-date history (`results` or `messages`) along with the `threadId`. AgentKit detects the client-provided history and skips the database read, resulting in a faster response.

**Use case**: Ideal for interactive chat applications where the frontend maintains conversation state but lets AgentKit fetch messages via their history adapter

## How Thread IDs Are Managed

AgentKit offers a flexible system for managing conversation thread IDs, ensuring that history is handled correctly whether you're starting a new conversation or continuing an existing one. Here's how AgentKit determines which `threadId` to use:

### Thread Initialization Flow

| Scenario                        | `threadId` provided? | `createThread` exists?  | Behavior                                                     |
| ------------------------------- | -------------------- | ----------------------- | ------------------------------------------------------------ |
| **Resume existing thread**      | ✅ Yes                | ✅ Yes                   | Calls `createThread` to upsert/ensure thread exists in DB    |
| **Resume existing thread**      | ✅ Yes                | ❌ No                    | Uses provided `threadId` directly                            |
| **New conversation**            | ❌ No                 | ✅ Yes                   | Calls `createThread` to create new thread and get `threadId` |
| **New conversation (fallback)** | ❌ No                 | ❌ No (but `get` exists) | Auto-generates UUID as `threadId`                            |

1. **Explicit `threadId` with `createThread`:** When you provide a `threadId` and your adapter has a `createThread` method, AgentKit calls `createThread` to ensure the thread exists in your database. Your adapter should implement an **upsert** pattern (insert if new, update if exists) to handle both new and existing threads gracefully.

   ```typescript theme={"system"}
   // Continue a specific, existing conversation
   const state = createState(
     { userId: "user-123" },
     { threadId: "existing-thread-id-123" }
   );
   await network.run("Let's pick up where we left off.", { state });
   // createThread is called to ensure thread exists in DB
   // Then history.get() loads the conversation history
   ```

2. **Automatic Creation via `createThread`:** If you don't provide a `threadId`, AgentKit checks if your history adapter has a `createThread` method. If so, AgentKit calls it to create a new conversation thread in your database. Your `createThread` function is responsible for generating and returning the new unique `threadId`. This is the recommended approach for starting new conversations, as it ensures a record is created in your backend from the very beginning.

   ```typescript theme={"system"}
   // Start a new conversation
   const state = createState({ userId: "user-123" });
   await network.run("Hello!", { state });
   // createThread is called to create a new thread
   // state.threadId is set to the new thread ID
   ```

3. **Automatic Generation (Fallback):** In cases where you don't provide a `threadId` and your history adapter does *not* have a `createThread` method but *does* have a `get` method, AgentKit provides a fallback. It will automatically generate a standard UUID and assign it as the `threadId` for the current run. This convenience ensures the conversation can proceed with a unique identifier for saving and loading history, even without an explicit creation step.

   ```typescript theme={"system"}
   // Fallback: UUID is generated automatically
   const state = createState({ userId: "user-123" });
   await network.run("Hello!", { state });
   // state.threadId is set to a new UUID
   // appendUserMessage and appendResults can use this ID
   ```

## Best Practices

<AccordionGroup>
  <Accordion title="Implement Idempotency with Message IDs and Checksums">
    Use unique constraints on `message_id` and `checksum` to prevent duplicate messages during retries or streaming scenarios.

    ```sql theme={"system"}
    CREATE TABLE messages (
      id SERIAL PRIMARY KEY,
      message_id UUID NOT NULL,
      thread_id UUID NOT NULL,
      message_type TEXT NOT NULL, -- 'user' or 'agent'
      content TEXT,
      checksum TEXT NOT NULL,
      created_at TIMESTAMP DEFAULT NOW(),
      UNIQUE(thread_id, message_id), -- Prevent duplicate message IDs
      UNIQUE(thread_id, checksum)    -- Prevent duplicate content
    );
    ```

    ```typescript theme={"system"}
    appendUserMessage: async ({ threadId, userMessage }) => {
      await db.message.create({
        data: {
          messageId: userMessage.id, // Use canonical client ID
          threadId,
          content: userMessage.content,
          checksum: generateChecksum(userMessage),
        },
      });
    },

    appendResults: async ({ threadId, newResults }) => {
      for (const result of newResults) {
        await db.message.create({
          data: {
            messageId: result.id || crypto.randomUUID(),
            threadId,
            checksum: result.checksum, // Built-in checksum
            // ... other fields
          },
        });
      }
    }
    ```
  </Accordion>

  <Accordion title="Leverage Inngest's Durable Steps">
    Wrap database operations in `step.run()` for automatic retries and durability.

    ```typescript theme={"system"}
    appendUserMessage: async ({ threadId, userMessage, step }) => {
      if (step) {
        return await step.run("save-user-message", async () => {
          return await db.saveMessage(threadId, userMessage);
        });
      }
      return await db.saveMessage(threadId, userMessage);
    }
    ```
  </Accordion>

  <Accordion title="Handle Missing Threads Gracefully">
    If a thread doesn't exist, return an empty array rather than throwing an error.

    ```typescript theme={"system"}
    get: async ({ threadId }) => {
      if (!threadId) return [];
      
      const messages = await db.getMessages(threadId);
      return messages || []; // Handle null/undefined gracefully
    }
    ```
  </Accordion>

  <Accordion title="Index Your Database Properly">
    Ensure you have indexes on key columns for fast queries.

    ```sql theme={"system"}
    CREATE INDEX idx_messages_thread_id ON messages(thread_id);
    CREATE INDEX idx_messages_created_at ON messages(created_at);
    CREATE INDEX idx_messages_type ON messages(message_type);
    CREATE INDEX idx_messages_message_id ON messages(message_id);
    ```
  </Accordion>

  <Accordion title="Return Complete Conversation History">
    Include both user messages and agent results in your `get()` method to preserve conversation order.

    ```typescript theme={"system"}
    get: async ({ threadId }) => {
      const messages = await db.message.findMany({
        where: { threadId },
        orderBy: { createdAt: "asc" },
      });
      
      // Convert ALL messages (user + agent) to AgentResult format
      return messages.map((msg) => {
        if (msg.role === "user") {
          return new AgentResult("user", [
            { type: "text", role: "user", content: msg.content }
          ], [], new Date(msg.createdAt));
        } else {
          return new AgentResult(msg.agentName, [
            { type: "text", role: "assistant", content: msg.content }
          ], [], new Date(msg.createdAt));
        }
      });
    }
    ```
  </Accordion>

  <Accordion title="Implement Upsert in createThread">
    Handle both new and existing threads gracefully by implementing an upsert pattern.

    ```typescript theme={"system"}
    createThread: async ({ state }) => {
      if (state.threadId) {
        // Upsert: ensure existing thread is in DB
        await db.thread.upsert({
          where: { id: state.threadId },
          update: { updatedAt: new Date() },
          create: { id: state.threadId, userId: state.data.userId },
        });
        return { threadId: state.threadId };
      }
      
      // Create new thread
      const thread = await db.thread.create({
        data: { userId: state.data.userId },
      });
      return { threadId: thread.id };
    }
    ```
  </Accordion>
</AccordionGroup>

## Future Enhancements

The history system provides a foundation for advanced features to be released in the coming future including:

* **Database Adapters**: Pre-built adapters for popular databases (coming soon)
* **Progressive Summarization**: Automatic conversation compression for long threads
* **Search & Retrieval**: Semantic search across conversation history

## Complete Example

Check out the [AgentKit Starter](https://github.com/inngest/agent-kit/tree/main/examples/agentkit-starter) for a complete implementation featuring:

* PostgreSQL history adapter
* ChatGPT-style UI with thread management
* Real-time streaming responses
* Both server and client-authoritative patterns

The starter includes everything you need to build a conversational AI application with persistent history.


# Memory
Source: https://agentkit.inngest.com/concepts/memory

Learn how to give your agents long-term, reflective memory using Mem0.

## Overview

AgentKit allows you to equip your agents with long-term memory, enabling them to recall past interactions, learn user preferences, and maintain context across conversations. By integrating with [Mem0](https://docs.mem0.ai/overview), you can build sophisticated agents that offer personalized and context-aware experiences.

A key advantage of combining Mem0 with AgentKit is the power of Inngest for handling memory operations. When an agent needs to create, update, or delete a memory, it can send an event to Inngest for durable background processing. This means:

<CardGroup>
  <Card title="Faster Responses" icon="bolt-lightning">
    Your agent can respond to the user immediately, without waiting for database
    writes to complete.
  </Card>

  <Card title="Durable Background Processing" icon="arrows-rotate">
    The memory operation runs reliably in the background as a separate, durable
    Inngest function. If it fails, Inngest automatically retries it.
  </Card>
</CardGroup>

## Memory Tools

To empower your agent with memory, you need to provide it with tools. How you design these tools can significantly impact your agent's behavior, performance, and reliability. AgentKit supports multiple patterns for memory tools, allowing you to choose the best fit for your use case.

The core idea is to abstract memory operations (create, read, update, delete) into tools that an agent can call. These tools can then use Inngest to perform the actual database writes asynchronously, ensuring the agent remains responsive.

```typescript theme={"system"}
// From examples/mem0-memory/memory-tools.ts

const createMemoriesTool = createTool({
  name: "create_memories",
  description: "Save one or more new pieces of information to memory.",
  parameters: z.object({
    statements: z
      .array(z.string())
      .describe("The pieces of information to memorize."),
  }),
  handler: async ({ statements }, { step }) => {
    // 1. Send an event to an Inngest function for background processing
    await step?.sendEvent("send-create-memories-event", {
      name: "app/memories.create",
      data: {
        statements,
      },
    });
    // 2. Return immediately to the user
    return `I have scheduled the creation of ${statements.length} new memories.`;
  },
});

// A separate Inngest function handles the event
const addMemoriesFn = inngest.createFunction(
  { id: "add-memories" },
  { event: "app/memories.create" },
  async ({ event }) => {
    // 3. Perform the durable memory operation
    const { statements } = event.data;
    await mem0.add(statements.map((s) => ({ role: "user", content: s })));
    return { status: `Added ${statements.length} memories.` };
  }
);
```

Let's explore two common patterns for designing and integrating these tools into agents.

### Pattern 1: Granular, Single-Purpose Tools

This pattern involves creating a distinct tool for each memory operation:

* `create_memories`: Adds new information.
* `recall_memories`: Retrieves existing information.
* `update_memories`: Corrects or changes existing information.
* `delete_memories`: Removes information.

This gives the agent fine-grained control, but requires it to make more decisions and more tool calls.

Here's how you might define the `recall_memories` and `create_memories` tools:

```typescript theme={"system"}
// From examples/voice-assistant/tools/memory.ts

const recallMemoriesTool = createTool({
  name: "recall_memories",
  description: `Recall memories relevant to one or more queries. Can run multiple queries in parallel.`,
  parameters: z.object({
    queries: z
      .array(z.string())
      .describe(
        `The questions to ask your memory to find relevant information.`
      ),
  }),
  handler: async ({ queries }, { step, network }) => {
    // ... implementation to search memories ...
  },
});

const createMemoriesTool = createTool({
  name: "create_memories",
  description: "Save one or more new pieces of information to memory.",
  parameters: z.object({
    statements: z
      .array(z.string())
      .describe("The pieces of information to memorize."),
  }),
  handler: async ({ statements }, { step }) => {
    await step?.sendEvent("send-create-memories-event", {
      name: "app/memories.create",
      data: { statements },
    });
    return `I have scheduled the creation of ${statements.length} new memories.`;
  },
});
```

This approach is used in the **Autonomous Agent** pattern described below, where a single, powerful LLM is prompted to reason about which of the specific tools to use at each turn.

### Pattern 2: Consolidated Tools

This pattern simplifies the agent's job by consolidating write operations into a single tool.

* `recall_memories`: Same as above, for reading.
* `manage_memories`: A single tool that handles creating, updating, *and* deleting memories in one atomic action.

This reduces the number of tools the agent needs to know about and can make its behavior more predictable. It's particularly effective in structured, multi-agent workflows.

The `manage_memories` tool can accept lists of creations, updates, and deletions, and then send corresponding events to Inngest.

```typescript theme={"system"}
// From examples/voice-assistant/tools/memory.ts

const manageMemoriesTool = createTool({
  name: "manage_memories",
  description: `Create, update, and/or delete memories in a single atomic operation. This is the preferred way to modify memories.`,
  parameters: z.object({
    creations: z
      .array(z.string())
      .optional()
      .describe("A list of new statements to save as memories."),
    updates: z
      .array(
        z.object({
          id: z.string().describe("The unique ID of the memory to update."),
          statement: z
            .string()
            .describe("The new, corrected information to save."),
        })
      )
      .optional()
      .describe("A list of memories to update."),
    deletions: z
      .array(
        z.object({
          id: z.string().describe("The unique ID of the memory to delete."),
        })
      )
      .optional()
      .describe("A list of memories to delete."),
  }),
  handler: async ({ creations, updates, deletions }, { step }) => {
    // Send events to Inngest for background processing
    if (creations?.length) {
      await step?.sendEvent("create-memories", {
        name: "app/memories.create",
        data: { statements: creations },
      });
    }
    if (updates?.length) {
      await step?.sendEvent("update-memories", {
        name: "app/memories.update",
        data: { updates },
      });
    }
    if (deletions?.length) {
      await step?.sendEvent("delete-memories", {
        name: "app/memories.delete",
        data: { deletions },
      });
    }
    return `Scheduled memory operations.`;
  },
});
```

This consolidated `manage_memories` tool is a perfect fit for a **multi-agent network**, where a dedicated "Memory Updater" agent has the single, clear responsibility of calling this tool at the end of a conversation - only running once with a tool that can emit many events / memory operations.

***

## Deterministic vs Non-Deterministic Memory

There are two primary patterns for integrating memory into your agents:

1. **Autonmous Agent w/ Tools (Non-Deterministic):** A single, powerful agent is given memory-related tools and decides for itself when and how to use them based on its system prompt and the conversation. This approach offers maximum flexibility and autonomy.
2. **Multi-Agent or Lifecycle-based (Deterministic):** The process is broken down into a structured sequence of specialized agents (e.g., one for retrieval, one for responding, one for updating memory), orchestrated by a code-based router. This approach provides predictability and control.

Let's explore both!

### Pattern 1: Autonomous Agent with Memory Tools

In this setup, a single agent is responsible for all tasks. Its system prompt instructs it to follow a **recall-reflect-respond** process. The agent uses its own reasoning (powered by the LLM) to decide which memory tool to use, making the flow non-deterministic.

#### Example Agent

Here is an agent designed to manage its own memory. Note the detailed system prompt guiding its behavior.

```typescript theme={"system"}
// From examples/mem0-memory/index.ts
const mem0Agent = createAgent({
  name: "reflective-mem0-agent",
  description:
    "An agent that can reflect on and manage its memories using mem0.",
  system: `
    You are an assistant with a dynamic, reflective memory. You must actively manage your memories to keep them accurate
    and strategically for search queries to retrieve the most relevant memories related to the user and their query.

    On every user interaction, you MUST follow this process:
    1.  **RECALL**: Use the 'recall_memories' tool with a list of queries relevant to the user's input to get context.
    2.  **ANALYZE & REFLECT**:
        - Compare the user's new statement with the memories you recalled.
        - If there are direct contradictions, you MUST use the 'update_memories' tool to correct the old memories.
        - If old memories are now irrelevant or proven incorrect based on the discussion, you MUST use the 'delete_memories' tool.
        - If this is brand new information that doesn't conflict, you may use the 'create_memories' tool.
    3.  **RESPOND**: Never make mention to the user of any memory operations you have executed.
`,
  tools: [
    createMemoriesTool,
    recallMemoriesTool,
    updateMemoriesTool,
    deleteMemoriesTool,
  ],
  model: openai({ model: "gpt-4o" }),
});
```

#### Execution Flow

The agent's internal monologue drives the process, deciding which tools to call in sequence.

```mermaid theme={"system"}
sequenceDiagram
    participant U as User
    participant AK as AgentKit Server
    participant A as Autonomous Agent
    participant T as Memory Tools
    participant I as Inngest
    participant M as Mem0 SDK

    U->>AK: User Input
    AK->>A: agent.run(input)

    A->>T: recall_memories(...)
    Note over T: Agent generates multiple<br/>search queries
    T->>M: Parallel .search() calls
    M-->>T: Returns memories
    T-->>A: Returns unique memories

    A->>A: ANALYZE & REFLECT
    A->>T: update_memories(...) or delete_memories(...) etc.
    T->>I: sendEvent('app/memories.update')

    Note over I,M: Background Processing
    I-->>M: Listens for event
    I-->>M: .update(id, statement)
    M-->>I: Success

    T-->>A: "Scheduled"

    A->>A: FORMULATE RESPONSE
    A-->>AK: Final response
    AK-->>U: Streams response
```

Pros:

* **Flexibility & Autonomy:** The agent can handle unforeseen scenarios by reasoning about which tools to use.

* **Simpler Setup:** Requires only one
  agent and a comprehensive prompt.

Cons:

* **Unpredictability:** The agent's behavior can be inconsistent. It might
  get stuck in loops, call tools in the wrong order, or fail to answer the
  user's question directly.

* **Complex Prompting:** The system prompt must be
  carefully engineered to cover all cases, which can be brittle and hard to
  maintain.

### Pattern 2: Multi-Agent Network for Memory

To address the unpredictability of a single autonomous agent, you can use a deterministic, multi-agent network. The workflow is broken down into a sequence of specialized agents orchestrated by a [code-based router](https://agentkit.inngest.com/concepts/routers#code-based-routers-supervised-routing).

#### Example Agents & Router

The process is divided into three distinct steps, each handled by a dedicated agent:

1. **Memory Retrieval Agent**: Its sole job is to use the `recall_memories` tool.
2. **Personal Assistant Agent**: Has no tools. Its only job is to synthesize the final answer for the user based on the retrieved memories and history.
3. **Memory Updater Agent**: Reviews the *entire* conversation and uses a `manage_memories` tool to perform all necessary creations, updates, and deletions in one go.

```typescript theme={"system"}
// From examples/mem0-memory/multi-agent.ts

// 1. Retrieval Agent
const memoryRetrievalAgent = createAgent({
  name: "memory-retrieval-agent",
  description: "Retrieves relevant memories based on the user query.",
  system: `Your only job is to use the 'recall_memories' tool. ...`,
  tools: [recallMemoriesTool],
  // ...
});

// 2. Assistant Agent
const personalAssistantAgent = createAgent({
  name: "personal-assistant-agent",
  description: "A helpful personal assistant that answers user questions.",
  system: `Answer the user's question based on the conversation history...`,
  // No tools
  // ...
});

// 3. Updater Agent
const memoryUpdaterAgent = createAgent({
  name: "memory-updater-agent",
  description: "Reflects on the conversation and updates memories.",
  system: `Analyze the entire conversation history... you MUST use the 'manage_memories' tool...`,
  tools: [manageMemoriesTool],
  // ...
});

// The Router enforces the sequence
const multiAgentMemoryNetwork = createNetwork({
  name: "multi-agent-memory-network",
  agents: [memoryRetrievalAgent, personalAssistantAgent, memoryUpdaterAgent],
  router: async ({ callCount }) => {
    if (callCount === 0) return memoryRetrievalAgent;
    if (callCount === 1) return personalAssistantAgent;
    if (callCount === 2) return memoryUpdaterAgent;
    return undefined; // Stop the network
  },
  // ...
});
```

#### Execution Flow

The router guarantees a predictable, step-by-step execution path.

```mermaid theme={"system"}
sequenceDiagram
    participant U as User
    participant AK as AgentKit Server
    participant R as Router
    participant RA as Retrieval Agent
    participant PA as Assistant Agent
    participant UA as Updater Agent
    participant T as Memory Tools
    participant I as Inngest
    participant M as Mem0 SDK

    U->>AK: User Input
    AK->>R: network.run(input)

    R->>RA: (callCount == 0)
    RA->>T: recall_memories(...)
    T-->>RA: returns unique memories

    R->>PA: (callCount == 1)
    PA->>PA: Synthesizes answer
    PA-->>R: Final answer

    R->>UA: (callCount == 2)
    UA->>T: manage_memories(...)
    T->>I: sendEvent (create/update/delete)

    Note over I,M: Background Processing
    I-->>M: Handles memory ops
    M-->>I: Success

    T-->>UA: "Scheduled"

    R->>AK: Network finished
    AK-->>U: Streams final answer
```

Pros:

* **Predictability & Control:** The workflow is explicit and reliable. Each
  agent has a single, well-defined responsibility.

* **Maintainability:** It's
  easier to debug and modify a specific part of the process without affecting
  the others.

Cons:

* **More Boilerplate:** Requires defining multiple agents and a router,
  which can be more verbose for simple use cases.

* **Less Flexible:** The
  rigid structure may not adapt as well to unexpected conversational turns
  compared to an autonomous agent which can determine on its own - when memories should be retrieved.

***

## Advanced Patterns

### State-Based Memory Retrieval / Routing

Instead of `callCount`, you can use the network state to create more flexible and explicit routing logic. This is powerful when different agents have different memory needs.

```typescript theme={"system"}
// Define your network state interface
interface NetworkState {
  memoriesRetrieved?: boolean;
  assistantResponded?: boolean;
}

// Use state-based routing
const network = createNetwork<NetworkState>({
  //...
  router: async ({ network }) => {
    const state = network.state.data;

    if (!state.memoriesRetrieved) {
      // In a real implementation, the agent's tool would set this state
      // For example: network.state.data.memoriesRetrieved = true;
      return memoryRetrievalAgent;
    }
    if (!state.assistantResponded) {
      return personalAssistantAgent;
    }
    return memoryUpdaterAgent;
  },
});
```

### Lifecycle Integration

For a more seamless approach, you can integrate memory operations directly into an agent's or network's lifecycle hooks, avoiding the need for explicit memory tools.

* **`onStart`**: Fetch memories *before* an agent runs and inject them into the prompt.
* **`onFinish`**: Analyze the conversation *after* an agent has run and schedule memory updates.

```typescript theme={"system"}
const agentWithLifecycleMemory = createAgent({
  // ... agent config ...
  lifecycle: {
    async onStart({ input, prompt }) {
      // 1. Fetch memories using a custom utility
      const memories = await recallMemoriesForAgent(input);
      // 2. Add memories to the prompt for context
      const memoryMessages = formatMemoriesAsMessages(memories);
      prompt.push(...memoryMessages);
      return { prompt, stop: false };
    },
    async onFinish({ result, network }) {
      // 3. Analyze the full conversation to decide on memory operations.
      await analyzeAndManageMemories(result, network.state.data);
    },
  },
});
```

## Complete Example

Check out the [Mem0 Memory Example](https://github.com/inngest/agent-kit/tree/main/examples/mem0-memory) for a complete implementation featuring:

* Both single-agent and multi-agent patterns.
* Asynchronous memory operations with Inngest.
* A local Qdrant vector store setup with Docker.


# Models
Source: https://agentkit.inngest.com/concepts/models

Leverage different provider's models across Agents.

Within AgentKit, models are adapters that wrap a given provider (ex. OpenAI, Anthropic)'s specific model version (ex. `gpt-3.5`).

Each [Agent](/concepts/agents) can each select their own model to use and a [Network](/concepts/networks) can select a default model.

```ts theme={"system"}
import { openai, anthropic, gemini } from "@inngest/agent-kit";
```

## How to use a model

### Create a model instance

<Info>
  Each model helper will first try to get the API Key from the environment
  variable. The API Key can also be provided with the `apiKey` option to the
  model helper.
</Info>

<CodeGroup>
  ```ts OpenAI theme={"system"}
  import { openai, createAgent } from "@inngest/agent-kit";


  const model = openai({ model: "gpt-3.5-turbo" });
  const modelWithApiKey = openai({ model: "gpt-3.5-turbo", apiKey: "sk-..." });

  ```

  ```ts Anthropic theme={"system"}
  import { anthropic, createAgent } from "@inngest/agent-kit";


  const model = anthropic({ model: "claude-3-5-haiku-latest" });

  const modelWithBetaFlags = anthropic({
    model: "claude-3-5-haiku-latest",
    betaHeaders: ["prompt-caching-2024-07-31"],
  });

  const modelWithApiKey = anthropic({
    model: "claude-3-5-haiku-latest",
    apiKey: "sk-...",
    // Note: max_tokens is required for Anthropic models
    defaultParameters: { max_tokens: 4096 },
  });
  ```

  ```ts Gemini theme={"system"}
  import { gemini, createAgent } from "@inngest/agent-kit";

  const model = gemini({ model: "gemini-1.5-flash" });
  ```
</CodeGroup>

### Configure model hyper parameters (temperature, etc.)

You can configure the model hyper parameters (temperature, etc.) by passing the `defaultParameters` option:

<CodeGroup>
  ```ts OpenAI theme={"system"}
  import { openai, createAgent } from "@inngest/agent-kit";

  const model = openai({
    model: "gpt-3.5-turbo",
    defaultParameters: { temperature: 0.5 },
  });
  ```

  ```ts Anthropic theme={"system"}
  import { anthropic, createAgent } from "@inngest/agent-kit";

  const model = anthropic({
    model: "claude-3-5-haiku-latest",
    defaultParameters: { temperature: 0.5, max_tokens: 4096 },

  });
  ```

  ```ts Gemini theme={"system"}
  import { gemini, createAgent } from "@inngest/agent-kit";


  const model = gemini({
    model: "gemini-1.5-flash",
    defaultParameters: { temperature: 0.5 },
  });
  ```
</CodeGroup>

<Info>
  The full list of hyper parameters can be found in the [types definition of
  each
  model](https://github.com/inngest/inngest-js/tree/main/packages/ai/src/models).
</Info>

### Providing a model instance to an Agent

```ts theme={"system"}
import { createAgent } from "@inngest/agent-kit";

const supportAgent = createAgent({
  model: openai({ model: "gpt-3.5-turbo" }),
  name: "Customer support specialist",
  system: "You are an customer support specialist...",
  tools: [listChargesTool],
});
```

### Providing a model instance to a Network

<Info>
  The provided `defaultModel` will be used for all Agents without a model
  specified. It will also be used by the "[Default Routing
  Agent](/concepts/routers#default-routing-agent-autonomous-routing)" if
  enabled.
</Info>

```ts theme={"system"}
import { createNetwork } from "@inngest/agent-kit";

const network = createNetwork({
  agents: [supportAgent],
  defaultModel: openai({ model: "gpt-4o" }),
});
```

## List of supported models

For a full list of supported models, you can always check [the models directory here](https://github.com/inngest/inngest-js/tree/main/packages/ai/src/models).

<CodeGroup>
  ```plaintext OpenAI theme={"system"}
  "gpt-4.5-preview"
  "gpt-4o"
  "chatgpt-4o-latest"
  "gpt-4o-mini"
  "gpt-4"
  "o1"
  "o1-preview"
  "o1-mini"
  "o3-mini"
  "gpt-4-turbo"
  "gpt-3.5-turbo"
  ```

  ```plaintext Anthropic theme={"system"}
  "claude-3-5-haiku-latest"
  "claude-3-5-haiku-20241022"
  "claude-3-5-sonnet-latest"
  "claude-3-5-sonnet-20241022"
  "claude-3-5-sonnet-20240620"
  "claude-3-opus-latest"
  "claude-3-opus-20240229"
  "claude-3-sonnet-20240229"
  "claude-3-haiku-20240307"
  "claude-2.1"
  "claude-2.0"
  "claude-instant-1.2";
  ```

  ```plaintext Gemini theme={"system"}
  "gemini-1.5-flash"
  "gemini-1.5-flash-8b"
  "gemini-1.5-pro"
  "gemini-1.0-pro"
  "text-embedding-004"
  "aqa"
  ```

  ```plaintext Grok theme={"system"}
  "grok-2-1212"
  "grok-2"
  "grok-2-latest"
  "grok-3"
  "grok-3-latest"
  "grok-4"
  "grok-4-latest"
  ```
</CodeGroup>

### Environment variable used for each model provider

* OpenAI: `OPENAI_API_KEY`
* Anthropic: `ANTHROPIC_API_KEY`
* Gemini: `GEMINI_API_KEY`
* Grok: `XAI_API_KEY`

## Contribution

Is there a model that you'd like to see included in AgentKit? Open an issue, create a pull request, or chat with the team on [Discord in the #ai channel](https://www.inngest.com/community).

<Card title="Contribute on GitHub" icon="github" href="https://github.com/inngest/agent-kit">
  Fork, clone, and open a pull request.
</Card>


# Networks
Source: https://agentkit.inngest.com/concepts/networks

Combine one or more agents into a Network.

Networks are **Systems of [Agents](/concepts/agents)**. Use Networks to create powerful AI workflows by combining multiple Agents.

A network contains three components:

* The [Agents](/concepts/agents) that the network can use to achieve a goal
* A [State](/concepts/state) including past messages and a key value store, shared between Agents and the Router
* A [Router](/concepts/routers), which chooses whether to stop or select the next agent to run in the loop

Here's a simple example:

```tsx theme={"system"}
import { createNetwork, openai } from '@inngest/agent-kit';

// searchAgent and summaryAgent definitions...

// Create a network with two agents.
const network = createNetwork({
  agents: [searchAgent, summaryAgent],
});

// Run the network with a user prompt
await network.run('What happened in the 2024 Super Bowl?');
```

By calling `run()`, the network runs a core loop to call one or more agents to find a suitable answer.

## How Networks work

Networks can be thought of as while loops with memory ([State](/concepts/state)) that call Agents and Tools until the Router determines that there is no more work to be done.

<Steps>
  <Step title="Create the Network of Agents">
    You create a network with a list of available [Agents](/concepts/agents).
    Each Agent can use a different [model and inference
    provider](/concepts/models).
  </Step>

  <Step title="Provide the staring prompt">
    You give the network a user prompt by calling `run()`.
  </Step>

  <Step title="Core execution loop">
    The network runs its core loop:

    <Steps>
      <Step title="Call the Network router">
        The [Router](/concepts/routers) decides the first Agent to run with your
        input.
      </Step>

      <Step title="Run the Agent">
        Call the Agent with your input. This also runs the agent's
        [lifecycles](/concepts/agents#lifecycle-hooks), and any
        [Tools](/concepts/tools) that the model decides to call.
      </Step>

      <Step title="Store the result">
        Stores the result in the network's [State](/concepts/state). State can
        be accessed by the Router or other Agent's Tools in future loops.
      </Step>

      <Step title="Call the the Router again ↩️">
        Return to the top of the loop and calls the Router with the new State.
        The Router can decide to quit or run another Agent.
      </Step>
    </Steps>
  </Step>
</Steps>

## Model configuration

A Network must provide a default model which is used for routing between Agents and for Agents that don't have one:

```tsx theme={"system"}
import { createNetwork, openai } from '@inngest/agent-kit';

// searchAgent and summaryAgent definitions...

const network = createNetwork({
  agents: [searchAgent, summaryAgent],
  defaultModel: openai({ model: 'gpt-4o' }),
});
```

<Info>
  A Network not defining a `defaultModel` and composed of Agents without model will throw an error.
</Info>

### Combination of multiple models

Each Agent can specify it's own model to use so a Network may end up using multiple models. Here is an example of a Network that defaults to use an OpenAI model, but the `summaryAgent` is configured to use an Anthropic model:

```tsx theme={"system"}
import { createNetwork, openai, anthropic } from '@inngest/agent-kit';

const searchAgent = createAgent({
  name: 'Search',
  description: 'Search the web for information',
});

const summaryAgent = createAgent({
  name: 'Summary',
  description: 'Summarize the information',
  model: anthropic({ model: 'claude-3-5-sonnet' }),
});

// The searchAgent will use gpt-4o, while the summaryAgent will use claude-3-5-sonnet.
const network = createNetwork({
  agents: [searchAgent, summaryAgent],
  defaultModel: openai({ model: 'gpt-4o' }),
});
```

## Routing & maximum iterations

### Routing

A Network can specify an optional `defaultRouter` function that will be used to determine the next Agent to run.

```ts theme={"system"}
import { createNetwork } from '@inngest/agent-kit';

// classifier and writer Agents definition...

const network = createNetwork({
  agents: [classifier, writer],
  router: ({ lastResult, callCount }) => {
    // retrieve the last message from the output
    const lastMessage = lastResult?.output[lastResult?.output.length - 1];
    const content = lastMessage?.type === 'text' ? lastMessage?.content as string : '';
    // First call: use the classifier
    if (callCount === 0) {
      return classifier;
    }
    // Second call: if it's a question, use the writer
    if (callCount === 1 && content.includes('question')) {
      return writer;
    }
    // Otherwise, we're done!
    return undefined;
  },
});
```

Refer to the [Router](/concepts/routers) documentation for more information about how to create a custom Router.

### Maximum iterations

A Network can specify an optional `maxIter` setting to limit the number of iterations.

```tsx theme={"system"}
import { createNetwork } from '@inngest/agent-kit';

// searchAgent and summaryAgent definitions...

const network = createNetwork({
  agents: [searchAgent, summaryAgent],
  defaultModel: openai({ model: 'gpt-4o' }),
  maxIter: 10,
});
```

<Info>
  Specifying a `maxIter` option is useful when using a [Default Routing Agent](/concepts/routers#default-routing-agent-autonomous-routing) or a [Hybrid Router](/concepts/routers#hybrid-code-and-agent-routers-semi-supervised-routing) to avoid infinite loops.

  A Routing Agent or Hybrid Router rely on LLM calls to make decisions, which means that they can sometimes fail to identify a final condition.
</Info>

### Combining `maxIter` and `defaultRouter`

You can combine `maxIter` and `defaultRouter` to create a Network that will stop after a certain number of iterations or when a condition is met.

However, please note that the `maxIter` option can prevent the `defaultRouter` from being called (For example, if `maxIter` is set to 1, the `defaultRouter` will only be called once).

## Providing a default State

A Network can specify an optional `defaultState` setting to provide a default [State](/concepts/state).

```tsx theme={"system"}
import { createNetwork } from '@inngest/agent-kit';

// searchAgent and summaryAgent definitions...

const network = createNetwork({
  agents: [searchAgent, summaryAgent],
  defaultState: new State({
    foo: 'bar',
  }),
});
```

Providing a `defaultState` can be useful to persist the state in database between runs or initialize your network with external data.


# Routers
Source: https://agentkit.inngest.com/concepts/routers

Customize how calls are routed between Agents in a Network.

The purpose of a Network's **Router** is to decide what [Agent](/concepts/agents) to call based off the current Network [State](/concepts/state).

## What is a Router?

A router is a function that gets called after each agent runs, which decides whether to:

1. Call another agent (by returning an `Agent`)
2. Stop the network's execution loop (by returning `undefined`)

The routing function gets access to everything it needs to make this decision:

* The [Network](/concepts/networks) object itself, including it's [State](/concepts/state).
* The stack of [Agents](/concepts/agents) to be called.
* The number of times the Network has called Agents (*the number of iterations*).
* The result from the previously called Agent in the Network's execution loop.

For more information about the role of a Router in a Network, read about [how Networks work](/concepts/networks#how-networks-work).

## Using a Router

<Tip>
  Providing a custom Router to your Network is optional. If you don't provide
  one, the Network will use the "Default Router" Routing Agent.
</Tip>

Providing a custom Router to your Network can be achieved using 3 different patterns:

* **Writing a custom [Code-based Router](/concepts/routers#code-based-routers-supervised-routing)**: Define a function that makes decisions based on the current [State](/concepts/state).
* **Creating a [Routing Agent](/concepts/routers#routing-agent-autonomous-routing)**: Leverages LLM calls to decide which Agents should be called next based on the current [State](/concepts/state).
* **Writing a custom [Hybrid Router](/concepts/routers#hybrid-code-and-agent-routers-semi-supervised-routing)**: Mix code and agent-based routing to get the best of both worlds.

## Creating a custom Router

Custom Routers can be provided by defining a `defaultRouter` function returning either an instance of an `Agent` object or `undefined`.

```ts theme={"system"}
import { createNetwork } from "@inngest/agent-kit";

// classifier and writer Agents definition...

const network = createNetwork({
  agents: [classifier, writer],
  router: ({ lastResult, callCount }) => {
    // retrieve the last message from the output
    const lastMessage = lastResult?.output[lastResult?.output.length - 1];
    const content =
      lastMessage?.type === "text" ? (lastMessage?.content as string) : "";
    // First call: use the classifier
    if (callCount === 0) {
      return classifier;
    }
    // Second call: if it's a question, use the writer
    if (callCount === 1 && content.includes("question")) {
      return writer;
    }
    // Otherwise, we're done!
    return undefined;
  },
});
```

The `defaultRouter` function receives a number of arguments:

```ts @inngest/agent-kit theme={"system"}
interface RouterArgs {
  network: Network; // The entire network, including the state and history
  stack: Agent[]; // Future agents to be called
  callCount: number; // Number of times the Network has called agents
  lastResult?: InferenceResult; // The the previously called Agent's result
}
```

The available arguments can be used to build the routing patterns described below.

## Routing Patterns

### Tips

* Start simple with code-based routing for predictable behavior, then add agent-based routing for flexibility.
* Remember that routers can access the network's [state](/concepts/state)
* You can return agents that weren't in the original network
* The router runs after each agent call
* Returning `undefined` stops the network's execution loop

That's it! Routing is what makes networks powerful - it lets you build workflows that can be as simple or complex as you need.

### Code-based Routers (supervised routing)

The simplest way to route is to write code that makes decisions. Here's an example that routes between a classifier and a writer:

```ts theme={"system"}
import { createNetwork } from "@inngest/agent-kit";

// classifier and writer Agents definition...

const network = createNetwork({
  agents: [classifier, writer],
  router: ({ lastResult, callCount }) => {
    // retrieve the last message from the output
    const lastMessage = lastResult?.output[lastResult?.output.length - 1];
    const content =
      lastMessage?.type === "text" ? (lastMessage?.content as string) : "";
    // First call: use the classifier
    if (callCount === 0) {
      return classifier;
    }
    // Second call: if it's a question, use the writer
    if (callCount === 1 && content.includes("question")) {
      return writer;
    }
    // Otherwise, we're done!
    return undefined;
  },
});
```

Code-based routing is great when you want deterministic, predictable behavior. It's also the fastest option since there's no LLM calls involved.

### Routing Agent (autonomous routing)

Without a `defaultRouter` defined, the network will use the "Default Routing Agent" to decide which agent to call next.
The "Default Routing Agent" is a Routing Agent provided by Agent Kit to handle the default routing logic.

You can create your own Routing Agent by using the [`createRoutingAgent`](/reference/network-router#createroutingagent) helper function:

```ts theme={"system"}
import { createRoutingAgent } from "@inngest/agent-kit";

const routingAgent = createRoutingAgent({
  name: "Custom routing agent",
  description: "Selects agents based on the current state and request",
  lifecycle: {
    onRoute: ({ result, network }) => {
      // custom logic...
    },
  },
});

// classifier and writer Agents definition...

const network = createNetwork({
  agents: [classifier, writer],
  router: routingAgent,
});
```

<Warning>
  Routing Agents look similar to Agents but are designed to make routing
  decisions: - Routing Agents cannot have Tools. - Routing Agents provides a
  single `onRoute` lifecycle method.
</Warning>

### Hybrid code and agent Routers (semi-supervised routing)

And, of course, you can mix code and agent-based routing. Here's an example that uses code for the first step, then lets an agent take over:

```tsx theme={"system"}
import { createNetwork, getDefaultRoutingAgent } from "@inngest/agent-kit";

// classifier and writer Agents definition...

const network = createNetwork({
  agents: [classifier, writer],
  router: ({ callCount }) => {
    // Always start with the classifier
    if (callCount === 0) {
      return classifier;
    }
    // Then let the routing agent take over
    return getDefaultRoutingAgent();
  },
});
```

This gives you the best of both worlds:

* Predictable first steps when you know what needs to happen
* Flexibility when the path forward isn't clear

### Using state in Routing

The router is the brain of your network - it decides which agent to call next. You can use state to make smart routing decisions:

```tsx theme={"system"}
import { createNetwork } from '@inngest/agent-kit';

// mathAgent and contextAgent Agents definition...

const network = createNetwork({
  agents: [mathAgent, contextAgent],
  router: ({ network, lastResult }): Agent | undefined => {
    // Check if we've solved the problem
    const solution = network.state.data.solution;
    if (solution) {
      // We're done - return undefined to stop the network
      return undefined;
    }

    // retrieve the last message from the output
    const lastMessage = lastResult?.output[lastResult?.output.length - 1];
    const content = lastMessage?.type === 'text' ? lastMessage?.content as string : '';

    // Check the last result to decide what to do next
    if (content.includes('need more context')) {
      return contextAgent;
    }

    return mathAgent;
  };
});
```

## Related Concepts

<CardGroup>
  <Card title="Networks" icon="route" href="/concepts/networks">
    Networks combines the State and Router to execute Agent workflows.
  </Card>

  <Card title="State" icon="database" href="/concepts/state">
    State is a key-value store that can be used to store data between Agents.
  </Card>
</CardGroup>


# State
Source: https://agentkit.inngest.com/concepts/state

Shared memory, history, and key-value state for Agents and Networks.

State is shared memory, or context, that is be passed between different [Agents](/concepts/agents) in a [Networks](/concepts/networks). State is used to store message history and build up structured data from tools.

State enables agent workflows to execute in a loop and contextually make decisions. Agents continuously build upon and leverage this context to complete complex tasks.

AgentKit's State stores data in two ways:

* **History of messages** - A list of prompts, responses, and tool calls.
* **Fully typed state data** - Typed state that allows you to build up structured data from agent calls, then implement [deterministic state-based routing](/advanced-patterns/routing) to easily model complex agent workflows.

Both history and state data are used automatically by the Network to store and provide context to the next Agent.

## History

The history system maintains a chronological record of all Agent interactions in your Network.

Each interaction is stored as an `InferenceResult`. Refer to the [InferenceResult reference](/reference/state#inferenceresult) for more information.

## Typed state

State contains typed data that can be used to store information between Agent calls, update agent prompts, and manage routing.  Networks, agents,
and tools use this type in order to set data:

```ts theme={"system"}

export interface NetworkState {
  // username is undefined until extracted and set by a tool
  username?: string;
}

// You can construct typed state with optional defaults, eg. from memory.
const state = createState<NetworkState>({
  username: "default-username",
});

console.log(state.data.username); // 'default-username'
state.data.username = "Alice";
console.log(state.data.username); // 'Alice'
```

Common uses for data include:

* Storing intermediate results that other Agents might need within lifecycles
* Storing user preferences or context
* Passing data between Tools and Agents
* State based routing

<Tip>
  The `State`'s data is only retained for a single `Network`'s run.
  This means that it is only short-term memory and is not persisted across
  different Network `run()` calls.

  You can implement memory by inspecting a network's state after it has
  finished running.
</Tip>

State, which is required by [Networks](/concepts/networks), has many uses across various AgentKit components.

Refer to the [State reference](/reference/state#reading-and-modifying-state-states-data) for more information.

## Using state in tools

State can be leveraged in a Tool's `handler` method to get or set data. Here is an example of a Tool that uses `kv` as a temporary store for files and their contents that are being written by the Agent.

```ts theme={"system"}
const writeFiles = createTool({
  name: "write_files",
  description: "Write code with the given filenames",
  parameters: z.object({
    files: z.array(
      z.object({
        filename: z.string(),
        content: z.string(),
      })
    ),
  }),
  handler: (output, { network }) => {
    // files is the output from the model's response in the format above.
    // Here, we store OpenAI's generated files in the response.
    const files = network.state.data.files || {};
    for (const file of output.files) {
      files[file.filename] = file.content;
    }
    network.state.data.files = files;
  },
});
```


# Tools
Source: https://agentkit.inngest.com/concepts/tools

Extending the functionality of Agents for structured output or performing tasks.

Tools are functions that extend the capabilities of an [Agent](/concepts/agents). Tools have two core uses:

* Calling code, enabling models to interact with systems like your own database or external APIs.
* Turning unstructured inputs into structured responses.

A list of all available Tools and their configuration is sent in [an Agent's inference calls](/concepts/agents#how-agents-work) and a model may decide that a certain tool or tools should be called to complete the task. Tools are included in an Agent's calls to language models through features like OpenAI's "[function calling](https://platform.openai.com/docs/guides/function-calling)" or Claude's "[tool use](https://docs.anthropic.com/en/docs/build-with-claude/tool-use)."

## Creating a Tool

Each Tool's `name`, `description`, and `parameters` are part of the function definition that is used by model to learn about the tool's capabilities and decide when it should be called. The `handler` is the function that is executed by the Agent if the model decides that a particular Tool should be called.

Here is a simple tool that lists charges for a given user's account between a date range:

```ts theme={"system"}
import { createTool } from '@inngest/agent-kit';

const listChargesTool = createTool({
  name: 'list_charges',
  description:
    "Returns all of a user's charges. Call this whenever you need to find one or more charges between a date range.",
  parameters: z.object({
    userId: z.string(),
    created: z.object({
      gte: z.string().date(),
      lte: z.string().date(),
    }),
  }),
  handler: async ({ userId, created }, { network, agent, step }) => {
    // input is strongly typed to match the parameter type.
    return [{...}]
  },
});
```

Writing quality `name` and `description` parameters help the model determine when the particular Tool should be called.

### Optional parameters

Optional parameters should be defined using `.nullable()` (not `.optional()`):

```ts {7-10} theme={"system"}
const listChargesTool = createTool({
  name: 'list_charges',
  description:
    "Returns all of a user's charges. Call this whenever you need to find one or more charges between a date range.",
  parameters: z.object({
    userId: z.string(),
    created: z.object({
      gte: z.string().date(),
      lte: z.string().date(),
    }).nullable(),
  }),
  handler: async ({ userId, created }, { network, agent, step }) => {
    // input is strongly typed to match the parameter type.
    return [{...}]
  },
});
```

## Examples

You can find multiple examples of tools in the below GitHub projects:

<CardGroup>
  <Card title="Hacker News Agent with Render and Inngest" href="https://github.com/inngest/agentkit-render-tutorial" icon="github">
    A tutorial showing how to create a Hacker News Agent using AgentKit Code-style routing and Agents with tools.
  </Card>

  <Card title="AgentKit SWE-bench" href="https://github.com/inngest/agent-kit/tree/main/examples/swebench#readme" icon="github">
    This AgentKit example uses the SWE-bench dataset to train an agent to solve coding problems. It uses advanced tools to interact with files and codebases.
  </Card>
</CardGroup>


# Examples
Source: https://agentkit.inngest.com/examples/overview



Explore the following examples to see AgentKit Concepts (*Agents, Tools, ...*) in action:

## Tutorials

<CardGroup>
  <Card title="Build an Agent to chat with code" href="/ai-agents-in-practice/ai-workflows" icon="book">
    This example shows how to leverages AgentKit's Agent to build an assistant that explain code.

    <span>Agents</span>
  </Card>

  <Card title="Hacker News Agent with Render and Inngest" href="/ai-agents-in-practice/ai-workflows" icon="book">
    A tutorial showing how to create a Hacker News Agent using AgentKit Code-style routing and Agents with tools.

    <span>Agents</span>
    <span>Tools</span>
    <span>Network</span>
    <span>State</span>

    <br />

    <span>Code-based Router</span>
  </Card>
</CardGroup>

<br />

## MCP as tools examples

<CardGroup>
  <Card title="Neon Assistant Agent (using MCP)" href="https://github.com/inngest/agent-kit/tree/main/examples/mcp-neon-agent/#readme" icon="github">
    This examples shows how to use the [Neon MCP Smithery Server](https://smithery.ai/server/neon/) to build a Neon Assistant Agent that can help you manage your Neon databases.

    <br />

    <span>Agents</span>
    <span>Tools</span>
    <span>Network</span>
    <span>Integrations</span>

    <br />

    <span>Code-based Router</span>
  </Card>
</CardGroup>

<br />

## Code Examples

<CardGroup>
  <Card title={`Support Agent with "Human in the loop"`} href="https://github.com/inngest/agent-kit/tree/main/examples/support-agent-human-in-the-loop#readme" icon="github">
    This AgentKit example shows how to build a Support Agent Network with a "Human in the loop" pattern.

    <span>Agents</span>
    <span>Tools</span>
    <span>Network</span>

    <br />

    <span>Agent Router</span>
  </Card>

  <Card title="AgentKit SWE-bench" href="https://github.com/inngest/agent-kit/tree/main/examples/swebench#readme" icon="github">
    This AgentKit example uses the SWE-bench dataset to train an agent to solve coding problems. It uses advanced tools to interact with files and codebases.

    <span>Agents</span>
    <span>Tools</span>
    <span>Network</span>

    <br />

    <span>Code-based Router</span>
  </Card>

  <Card title="Coding Agent with E2B sandboxes" href="https://github.com/inngest/agent-kit/tree/main/examples/e2b-coding-agent#readme" icon="github">
    This AgentKit example uses E2B sandboxes to build a coding agent that can write code in any language.

    <span>Agents</span>
    <span>Tools</span>
    <span>Network</span>
    <span>Integrations</span>

    <br />

    <span>Code-based Router</span>
  </Card>

  <Card title="Coding Agent powered by Daytona infrastructure" href="https://github.com/inngest/agent-kit/tree/main/examples/daytona-coding-agent#readme" icon="github">
    This AgentKit example uses Daytona to build a fully autonomous coding agent that performs software development tasks

    <span>Agents</span>
    <span>Tools</span>
    <span>Network</span>
    <span>State</span>

    <br />

    <span>Integrations</span>
    <span>Code-based Router</span>
  </Card>
</CardGroup>


# Installation
Source: https://agentkit.inngest.com/getting-started/installation

How to install AgentKit

Install the AgentKit [npm package](https://www.npmjs.com/package/@inngest/agent-kit) and [Inngest](https://www.npmjs.com/package/inngest) using your favorite package manager:

<CodeGroup>
  ```shell npm theme={"system"}
  npm install @inngest/agent-kit inngest
  ```

  ```shell pnpm theme={"system"}
  pnpm install @inngest/agent-kit inngest
  ```

  ```shell yarn theme={"system"}
  yarn add @inngest/agent-kit inngest
  ```
</CodeGroup>

<Note>
  **Important:** Starting with AgentKit v0.8.0, `inngest` is a required peer
  dependency. You must install both packages together to ensure proper runtime
  compatibility and prevent conflicts.
</Note>

## Beyond installation

<CardGroup>
  <Card title="Local development" href="/getting-started/local-development" icon="laptop">
    Discover Inngest's Dev Server with live traces and logs.
  </Card>

  <Card title="Deployment to production" href="/getting-started/deployment" icon="cloud">
    Add concurrency and throttling to your AgentKit network and deploy it to
    Inngest.
  </Card>
</CardGroup>


# Local development
Source: https://agentkit.inngest.com/getting-started/local-development

Run AgentKit locally with live traces and logs.

Developing AgentKit applications locally is a breeze when combined with the [Inngest Dev Server](https://www.inngest.com/docs/dev-server).

The Inngest Dev Server is a local development tool that provides live traces and logs for your AgentKit applications, providing a
quicker feedback loop and full visibility into your AgentKit's state and Agent LLM calls:

<video />

## Using AgentKit with the Inngest Dev Server

### 1. Install the `inngest` package

To use AgentKit with the Inngest Dev Server, you need to install the `inngest` package.

<CodeGroup>
  ```shell npm theme={"system"}
  npm install inngest
  ```

  ```shell pnpm theme={"system"}
  pnpm install inngest
  ```

  ```shell yarn theme={"system"}
  yarn add inngest
  ```
</CodeGroup>

### 2. Expose your AgentKit network over HTTP

The Inngest Dev Server needs to be able to trigger your AgentKit network over HTTP.
If your AgentKit network runs as a CLI, a few lines changes will make it available over HTTP:

```ts {1, 8-13} theme={"system"}
import { createNetwork } from '@inngest/agent-kit';
import { createServer } from '@inngest/agent-kit/server';

const network = createNetwork({
  name: 'My Network',
  agents: [/* ... */],
});

const server = createServer({
  networks: [network],
});

server.listen(3010, () => console.log("Agent kit running!"));
```

Now, starting your AgentKit script will make it available over HTTP.

Let's now trigger our AgentKit network from the Inngest Dev Server.

### 3. Trigger your AgentKit network from the Inngest Dev Server

You can start the Inngest Dev Server with the following command:

```shell theme={"system"}
npx inngest-cli@latest dev
```

And navigate to the Inngest Dev Server by opening [http://127.0.0.1:8288](http://127.0.0.1:8288) in your browser.

You can now explore the Inngest Dev Server features:

## Features

### Triggering your AgentKit network

You can trigger your AgentKit network by clicking on the "Trigger" button in the Inngest Dev Server from the "Functions" tab.
In the opened, add an `input` property with the input you want to pass to your AgentKit network:

<img alt="Inngest Dev Server function list" />

Then, click on the "Run" button to trigger your AgentKit network"

<img alt="Inngest Dev Server invoke function modal" />

### Inspect AgentKit Agents token usage, input and output

In the run view of your AgentKit network run, the Agents step will be highlighted with a ✨ green icon.
By expanding the step, you can inspect the Agents:

* The **model used**, ex: `gpt-4o`
* The **token usage** detailed as prompt tokens, completion tokens, and total tokens
* The **input** provided to the Agent
* The **output** provided by the Agent

<img alt="Inngest Dev Server agent run" />

<Info>
  **Tips**

  You can force line breaks to **make the input and output more readable** using the following button: <img alt="Inngest Dev Server agent run" />

  You can **expand the input and output view to show its full content** using the following button: <img alt="Inngest Dev Server agent run" />

  You can **update the input of an AgentKit Agent and trigger a rerun from this step** of the AgentKit network (*see below*)
</Info>

### Rerun an AgentKit Agent with a different prompt

On a given AgentKit Agent run, you can update the input of the Agent and trigger a rerun from this step of the AgentKit network.

First, click on the "Rerun with new prompt" button under the input area.
Then, the following modal will open:

<img alt="Inngest Dev Server agent run" />


# Quick start
Source: https://agentkit.inngest.com/getting-started/quick-start

Learn the basics of AgentKit in a few minutes.

In this tutorial, you will create an [Agent](/concepts/agents) and run it within a [Network](/concepts/networks) using AgentKit.

<Info>
  Follow this guide by forking the [quick-start](https://github.com/inngest/agent-kit/tree/main/examples/quick-start) example locally by running:

  ```shell theme={"system"}
  npx git-ripper https://github.com/inngest/agent-kit/tree/main/examples/quick-start
  ```
</Info>

## Creating a single agent

<Steps>
  <Step title="Install AgentKit">
    Within an existing project, install AgentKit and Inngest from npm:

    <CodeGroup>
      ```shell npm theme={"system"}
      npm install @inngest/agent-kit inngest
      ```

      ```shell pnpm theme={"system"}
      pnpm install @inngest/agent-kit inngest
      ```

      ```shell yarn theme={"system"}
      yarn add @inngest/agent-kit inngest
      ```
    </CodeGroup>

    <Note>
      **Important:** Starting with AgentKit v0.9.0, `inngest` is a required peer dependency. You must install both packages together to ensure proper runtime compatibility and prevent conflicts.
    </Note>

    You can always find the latest release version on [npm](https://www.npmjs.com/package/@inngest/agent-kit).

    <Accordion title="Don't have an existing project?">
      To create a new project, create a new directory and initialize it using your package manager:

      <CodeGroup>
        ```shell npm theme={"system"}
        mkdir my-agent-kit-project && npm init
        ```

        ```shell pnpm theme={"system"}
        mkdir my-agent-kit-project && pnpm init
        ```

        ```shell yarn theme={"system"}
        mkdir my-agent-kit-project && yarn init
        ```
      </CodeGroup>
    </Accordion>
  </Step>

  <Step title="Create an agent">
    To start, we'll create our first "[Agent](/concepts/agents)." An Agent is an entity that has a specific role to answer questions or perform tasks (see "tools" below).

    Let's create a new file, `index.ts`. Using the `createAgent` constructor, give your agent a `name`, a `description`, and its initial `system` prompt. The `name` and `description` properties are used to help the LLM determine which Agent to call.

    You'll also specify which `model` you want the agent to use. Here we'll use Anthropic's [Claude 3.5 Haiku](https://docs.anthropic.com/en/docs/about-claude/models) model. ([Model reference](/concepts/models))

    Your agent can be whatever you want, but in this quick start, we'll create a PostgreSQL database administrator agent:

    ```ts index.ts theme={"system"}
    import { createAgent, anthropic } from '@inngest/agent-kit';

    const dbaAgent = createAgent({
      name: 'Database administrator',
      description: 'Provides expert support for managing PostgreSQL databases',
      system:
        'You are a PostgreSQL expert database administrator. ' +
        'You only provide answers to questions related to PostgreSQL database schema, indexes, and extensions.',
      model: anthropic({
        model: 'claude-3-5-haiku-latest',
        defaultParameters: {
          max_tokens: 1000,
        },
      }),
    });
    ```

    You'll also need to set your provider API keys as environment variables:

    ```shell terminal theme={"system"}
    export ANTHROPIC_API_KEY=sk-ant-api03-XXXXXX....
    ```
  </Step>

  <Step title="Run the server">
    Next, we'll create an HTTP server to run our agent. In the same file as our Agent definition:

    ```ts index.ts theme={"system"}
    import { createAgent, anthropic } from '@inngest/agent-kit';
    import { createServer } from '@inngest/agent-kit/server';
    // ...
    const server = createServer({
      agents: [dbaAgent],
    });
    server.listen(3000, () => console.log('AgentKit server running!'));
    ```

    Now we can run our AgentKit server using [`npx`](https://docs.npmjs.com/cli/v8/commands/npx) and [`tsx`](https://tsx.is/) (for easy TypeScript execution):

    ```shell terminal theme={"system"}
    npx tsx ./index.ts
    ```
  </Step>

  <Step title="Test our agent">
    To test our agent, we'll use the [Inngest dev server](https://www.inngest.com/docs/local-development) to visually debug our agents. Using `npx`, we'll start the server and point it to our AgentKit server:

    ```shell terminal theme={"system"}
    npx inngest-cli@latest dev -u http://localhost:3000/api/inngest
    ```

    Now, open the dev server and select the functions tab (`http://localhost:8288/functions`) and click the "Invoke" button:

    <img alt="Inngest Dev Server function list" />

    In the Invoke function modal, specify the input prompt for your agent and click the "Invoke function" button:

    <img alt="Inngest Dev Server invoke function modal" />

    ```json Invoke payload theme={"system"}
    {
      "data": {
        "input": "How do I aggregate an integer column across a date column by week?"
      }
    }
    ```

    You'll be redirected to watch the agent run and view the output:

    <img alt="Inngest Dev Server agent run" />
  </Step>
</Steps>

A key benefit of AgentKit is the ability to create a system of agents called a
"[Network](/concepts/networks)." Networks are used to create AI Agents by combining
multiple specialized [Agents](/concepts/agents) to answer more complex questions.
Let's transform our single agent into a network of two agents, capable of helping with
both database administration and security questions.

## Creating a multi-agent network

<Steps>
  <Step title="Adding a second Agent">
    Agents collaborate in a Network by sharing a common [State](/concepts/state).

    Let's update our Database Administrator Agent to include a tool to save the answer to the question in the database:

    ```ts {13-24} theme={"system"}
    const dbaAgent = createAgent({
      name: "Database administrator",
      description: "Provides expert support for managing PostgreSQL databases",
      system:
        "You are a PostgreSQL expert database administrator. " +
        "You only provide answers to questions related to PostgreSQL database schema, indexes, and extensions.",
      model: anthropic({
        model: "claude-3-5-haiku-latest",
        defaultParameters: {
          max_tokens: 4096,
        },
      }),
      tools: [
        createTool({
          name: "save_answer",
          description: "Save the answer to the questions",
          parameters: z.object({
            answer: z.string(),
          }),
          handler: async ({ answer }, { network }: Tool.Options<NetworkState>) => {
            network.state.data.dba_agent_answer = answer;
          },
        }),
      ],
    });
    ```

    <Info>
      [Tools](/concepts/tools) are based on [Tool
      Calling](https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/overview),
      enabling your Agent to interact with the [State](/concepts/state) of the
      Network, store data in external databases, or dynamically fetch data from
      third-party APIs.
    </Info>

    Let's now create a second *Database Security* Agent:

    ```ts {6-11, 26} theme={"system"}
    import { createAgent, anthropic } from "@inngest/agent-kit";

    // ...

    const securityAgent = createAgent({
      name: "Database Security Expert",
      description:
        "Provides expert guidance on PostgreSQL security, access control, audit logging, and compliance best practices",
      system:
        "You are a PostgreSQL security expert. " +
        "You only provide answers to questions related to PostgreSQL security topics such as encryption, access control, audit logging, and compliance best practices.",
      model: anthropic({
        model: "claude-3-5-haiku-latest",
        defaultParameters: {
          max_tokens: 1000,
        },
      }),
      tools: [
        createTool({
          name: "save_answer",
          description: "Save the answer to the questions",
          parameters: z.object({
            answer: z.string(),
          }),
          handler: async ({ answer }, { network }: Tool.Options<NetworkState>) => {
            network.state.data.security_agent_answer = answer;
          },
        }),
      ],
    });
    ```

    Our second Security Expert Agent is similar to the first, but with a different system prompt specifically for security questions.

    We can now create a network combining our "Database Administrator" and "Database Security" Agents, which enables us to answer more complex questions.
  </Step>

  <Step title="Creating a Network">
    Create a network using the `createNetwork` constructor. Define a `name` and include our agents from the previous step in the `agents` array.

    You must also configure a `router` that the [*Router*](/concepts/routers) will use to determine which agent to call:

    ```ts {14, 15-25} theme={"system"}
    import { /*...*/ createNetwork } from "@inngest/agent-kit";

    export interface NetworkState {
      // answer from the Database Administrator Agent
      dba_agent_answer?: string;

      // answer from the Security Expert Agent
      security_agent_answer?: string;
    }

    // ...
    const devOpsNetwork = createNetwork<NetworkState>({
      name: "DevOps team",
      agents: [dbaAgent, securityAgent],
      router: async ({ network }) => {
        if (!network.state.data.security_agent_answer) {
          return securityAgent;
        } else if (
          network.state.data.security_agent_answer &&
          network.state.data.dba_agent_answer
        ) {
          return;
        }
        return dbaAgent;
      },
    });

    const server = createServer({
      agents: [dbaAgent, securityAgent],
      networks: [devOpsNetwork],
    });
    ```

    The highlighted lines are the key parts of our AI Agent behavior:

    * The `agents` property defines the agents that are part of the network
    * The `router` function defines the logic for which agent to call next. In this example, we call the Database Administrator Agent followed by the Security Expert Agent before ending the network (by returning `undefined`).
  </Step>

  <Step title="Test our network">
    We'll use the same approach to test our network as we did above.

    With your Inngest dev server running, open the dev server and select the functions tab (`http://localhost:8288/functions`) and click the "Invoke" button of the *DevOps team* function with the following payload:

    ```json Invoke payload theme={"system"}
    {
      "data": {
        "input": "I am building a Finance application. Help me answer the following 2 questions: \n - How can I scale my application to millions of requests per second? \n - How should I design my schema to ensure the safety of each organization's data?"
      }
    }
    ```

    The network will now run through the Agents to answer the questions:

    <img alt="Inngest Dev Server agent run" />

    You can inspect the answers of each Agent by selecting the *Finalization* step and inspecting the JSON payload in the right panel:

    <img alt="Inngest Dev Server agent run" />
  </Step>
</Steps>

## Next steps

Congratulations! You've now created your first AI Agent with AgentKit.

In this guide, you've learned that:

* [**Agents**](/concepts/agents) are the building blocks of AgentKit. They are used to call a single model to answer specific questions or perform tasks.
* [**Networks**](/concepts/networks) are groups of agents that can work together to achieve more complex goals.
* [**Routers**](/concepts/routers), combined with [**State**](/concepts/state), enable you to control the flow of your Agents.

The following guides will help you build more advanced AI Agents:

<CardGroup>
  <Card title="Adding Tools to Agents" href="/concepts/tools" icon="gear">
    Let your Agent act and gather data with tools
  </Card>

  <Card title="Implementing reasoning-based routing" href="/concepts/routers" icon="brain">
    Learn how to dynamically route between agents
  </Card>
</CardGroup>

You can also explore the following examples to see how to use AgentKit in more complex scenarios:

<CardGroup>
  <Card title={`Support Agent with "Human in the loop"`} href="https://github.com/inngest/agent-kit/tree/main/examples/support-agent-human-in-the-loop#readme" icon="github">
    This AgentKit example shows how to build a Support Agent Network with a "Human
    in the loop" pattern.
  </Card>

  <Card title="AgentKit SWE-bench" href="https://github.com/inngest/agent-kit/tree/main/examples/swebench#readme" icon="github">
    This AgentKit example uses the SWE-bench dataset to train an agent to solve coding problems. It uses advanced tools to interact with files and codebases.
  </Card>
</CardGroup>


# Code Assistant v2: Complex code analysis
Source: https://agentkit.inngest.com/guided-tour/agentic-workflows

Use AgentKit Tools and Custom Router to add agentic capabilities.

## Overview

Our [Code Assistant v1](/ai-agents-in-practice/ai-workflows), relying on a RAG workflow, had limited capabilities linked to its lack of reasoning.
The second version of our Code Assistant will introduce reasoning capabilities to adapt analysis based on the user's input:

```typescript theme={"system"}
const {
  state: { kv },
} = await network.run(
  `Analyze the files/example.ts file by suggesting improvements and documentation.`
);
console.log("Analysis:", kv.get("summary"));

// Analysis: The code analysis suggests several key areas for improvement:

// 1. Type Safety and Structure:
// - Implement strict TypeScript configurations
// - Add explicit return types and interfaces
// - Break down complex functions
// - Follow Single Responsibility Principle
// - Implement proper error handling

// 2. Performance Optimization:
// - Review and optimize critical operations
// ...
```

These agentic (reasoning) capabilities are introduced by the following AgentKit concepts:

* **[Tools](/concepts/tools)**: Enables [Agents](/concepts/agents) to interact with their environment (ex: file system or shared State).
* **[Router](/concepts/router)**: Powers the flow of the conversation between Agents.
* **[Network](/concepts/network)**: Add a shared [State](/concepts/state) to share information between Agents.

Let's learn these concepts in practice.

## Setup

Similarly to the [Code Assistant v1](/ai-agents-in-practice/ai-workflows), perform the following steps to setup your project:

<AccordionGroup>
  <Accordion title="1. Initialize your project">
    <CodeGroup>
      ```bash npm theme={"system"}
      npm init
      ```

      ```bash pnpm theme={"system"}
      pnpm init
      ```

      ```bash yarn theme={"system"}
      yarn init
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="2. Install the required dependencies">
    <CodeGroup>
      ```bash npm theme={"system"}
      npm install @inngest/agent-kit inngest zod
      ```

      ```bash pnpm theme={"system"}
      pnpm install @inngest/agent-kit inngest zod
      ```

      ```bash yarn theme={"system"}
      yarn add @inngest/agent-kit zod
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="3. Add TypeScript support">
    <CodeGroup>
      Install the following dev dependencies:

      ```bash npm theme={"system"}
      npm install -D tsx @types/node
      ```

      ```bash pnpm theme={"system"}
      pnpm install -D tsx @types/node
      ```

      ```bash yarn theme={"system"}
      yarn add -D tsx @types/node
      ```
    </CodeGroup>

    And add the following scripts to your `package.json`:

    ```json theme={"system"}
    "scripts": {
        "start": "tsx ./index.ts"
    }
    ```
  </Accordion>

  <Accordion title="4. Download the example code file">
    <CodeGroup>
      ```bash theme={"system"}
      mkdir files
      cd files
      wget https://raw.githubusercontent.com/inngest/agent-kit/main/examples/code-assistant-agentic/files/example.ts
      cd -
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

You are now set up, let's implement the v2 of our Code Assistant.

## Implementing our Code Assistant v2

### Overview of the agentic workflow

Our Code Assistant v2 introduces reasoning to perform tailored recommendations based on a given code file: refactoring, documentation, etc.

To achieve this behavior, we will need to:

* Create a `code_assistant_agent` Agent that will load a given filename from disk and plan a workflow using the following available [Agents](/concepts/agents):
  * `analysis_agent` that will analyze the code file and suggest improvements
  * `documentation_agent` that will generate documentation for the code file
* Finally, create a `summarization_agent` Agent that will generate a summary of the suggestions made by other agents

Compared to our [Code Assistant v1](/ai-agents-in-practice/ai-workflows), this new version does not consist of simple retrieval and generations steps.
Instead, it introduces more flexibility by enabling LLM models to plan actions and select tools to use.

Let's see how to implement the Agents.

### A Network of Agents

Our Code Assistant v2 is composed of 4 Agents collaborating together to analyze a given code file.
Such collaboration is made possible by using a [Network](/concepts/network) to orchestrate the Agents and share [State](/concepts/state) between them.

Unlike the [Code Assistant v1](/ai-agents-in-practice/ai-workflows), the user prompt will be passed to the network instead of an individual Agent:

```typescript theme={"system"}
await network.run(
  `Analyze the files/example.ts file by suggesting improvements and documentation.`
);
```

To successfully run, a `Network` relies on:

* A Router to **indicate which Agent should be run next**
* **A shared State**, updated by the Agents' LLM responses and **tool calls**

Let's start by implementing our Agents and registering them into the Network.

### Creating Agents with Tools

<Note>
  Attaching Tools to an Agent helps to:

  * Enrich dynamically the Agent context with dynamic data
  * Store the Agent results in the shared State

  Learn more about [Tools](/concepts/tools).
</Note>

**The Analysis and Documentation Agents**

Our first two analysis Agents are straightforward:

```typescript {5, 10} theme={"system"}
import { createAgent } from "@inngest/agent-kit";

const documentationAgent = createAgent({
  name: "documentation_agent",
  system: "You are an expert at generating documentation for code",
});

const analysisAgent = createAgent({
  name: "analysis_agent",
  system: "You are an expert at analyzing code and suggesting improvements",
});
```

Defining task specific LLM calls (Agents) is a great way to make the LLM reasoning more efficient and avoid unnecessary generations.

Our `documentation_agent` and `analysis_agent` are currently stateless and need to be *connected* to the Network by saving their suggestions into the shared State.

For this, we will create our first Tool using [`createTool`](/reference/create-tool):

```typescript {2-6} theme={"system"}
const saveSuggestions = createTool({
  name: "save_suggestions",
  description: "Save the suggestions made by other agents into the state",
  parameters: z.object({
    suggestions: z.array(z.string()),
  }),
  handler: async (input, { network }) => {
    const suggestions = network?.state.kv.get("suggestions") || [];
    network?.state.kv.set("suggestions", [
      ...suggestions,
      ...input.suggestions,
    ]);
    return "Suggestions saved!";
  },
});
```

<Tip>
  A Tool is a function that can be called by an Agent.

  The `name`, `description` and `parameters` are used by the Agent to understand what the Tool does and what it expects as input.

  The `handler` is the function that will be called when the Tool is used. `save_suggestions`'s handler relies on the [Network's State `kv` (key-value store)](/reference/state#reading-and-modifying-state-state-kv) API to share information with other Agents.

  Learn more about the [createTool()](/reference/create-tool) API.
</Tip>

The `save_suggestions` Tool is used by both `documentation_agent` and `analysis_agent` to save their suggestions into the shared State:

```typescript {8,14} theme={"system"}
import { createAgent } from "@inngest/agent-kit";

// `save_suggestions` definition...

const documentationAgent = createAgent({
  name: "documentation_agent",
  system: "You are an expert at generating documentation for code",
  tools: [saveSuggestions],
});

const analysisAgent = createAgent({
  name: "analysis_agent",
  system: "You are an expert at analyzing code and suggesting improvements",
  tools: [saveSuggestions],
});
```

Our `documentation_agent` and `analysis_agent` are now connected to the Network and will save their suggestions into the shared State.

Let's now create our `code_assistant_agent` that will read the code file from disk and plan the workflow to run.

**The Code Assistant Agent**

Let's jump into the action by looking at the full implementation of our `code_assistant_agent`:

```typescript {3, 18, 31} theme={"system"}
const codeAssistantAgent = createAgent({
  name: "code_assistant_agent",
  system: ({ network }) => {
    const agents = Array.from(network?.agents.values() || [])
      .filter(
        (agent) =>
          !["code_assistant_agent", "summarization_agent"].includes(agent.name)
      )
      .map((agent) => `${agent.name} (${agent.system})`);
    return `From a given user request, ONLY perform the following tool calls:
- read the file content
- generate a plan of agents to run from the following list: ${agents.join(", ")}

Answer with "done" when you are finished.`;
  },
  tools: [
    createTool({
      name: "read_file",
      description: "Read a file from the current directory",
      parameters: z.object({
        filename: z.string(),
      }),
      handler: async (input, { network }) => {
        const filePath = join(process.cwd(), `files/${input.filename}`);
        const code = readFileSync(filePath, "utf-8");
        network?.state.kv.set("code", code);
        return "File read!";
      },
    }),
    createTool({
      name: "generate_plan",
      description: "Generate a plan of agents to run",
      parameters: z.object({
        plan: z.array(z.string()),
      }),
      handler: async (input, { network }) => {
        network?.state.kv.set("plan", input.plan);
        return "Plan generated!";
      },
    }),
  ],
});
```

The highlighted lines emphasize three important parts of the `code_assistant_agent`:

* The [`system` property](/reference/create-agent#param-system) can take a function receiving the current Network state as argument, enabling more flexibility in the Agent's behavior

  * Here, the `system` function is used to generate a prompt for the LLM based on the available Agents in the Network, enabling the LLM to plan the workflow to run

* The `code_assistant_agent` relies on two Tools to achieve its goal:
  * `read_file` to read the code file from disk and save it into the shared State
  * `generate_plan` to generate a plan of agents to run and save it into the shared State

The pattern of dynamic `system` prompt and tools are also used by the `summarization_agent` to generate a summary of the suggestions made by other agents.

**The Summarization Agent**

```typescript {3, 10} theme={"system"}
const summarizationAgent = createAgent({
  name: "summarization_agent",
  system: ({ network }) => {
    const suggestions = network?.state.kv.get("suggestions") || [];
    return `Save a summary of the following suggestions:
    ${suggestions.join("\n")}`;
  },
  tools: [
    createTool({
      name: "save_summary",
      description:
        "Save a summary of the suggestions made by other agents into the state",
      parameters: z.object({
        summary: z.string(),
      }),
      handler: async (input, { network }) => {
        network?.state.kv.set("summary", input.summary);
        return "Saved!";
      },
    }),
  ],
});
```

<Note>
  The `summarization_agent` is a good example on how the State can be used to
  store intermediate results and pass them to the next Agent: - the
  `suggestions` are stored in the State by the `documentation_agent` and
  `analysis_agent` - the `summarization_agent` will read the `suggestions` from
  the State and generate a summary - the summary is then stored in the State as
  the `summary` key
</Note>

Our four Agents are now propely defined and connected to the Network's State.

Let's now configure our Network to run the Agents with a Router.

### Assembling the Network

An AgentKit [Network](/concepts/network) is defined by a set of Agents and an optional `defaultModel`:

```typescript {7-16} theme={"system"}
import { createNetwork, anthropic } from "@inngest/agent-kit";

// Agent and Tools definitions...

const network = createNetwork({
  name: "code-assistant-v2",
  agents: [
    codeAssistantAgent,
    documentationAgent,
    analysisAgent,
    summarizationAgent,
  ],
  defaultModel: anthropic({
    model: "claude-3-5-sonnet-latest",
    max_tokens: 4096,
  }),
});
```

<Tip>
  The `defaultModel` will be applied to all Agents part of the Network.
  A model can also be set on an individual Agent by setting the `model` property.

  Learn more about the [Network Model configuration](/concepts/networks#model-configuration).
</Tip>

Our Code Assistant v2 is missing a final piece: the Router.
Without a Router, the Network will not know which Agent to run next.

**Implementing the Router**

As stated in the [workflow overview](#overview-of-the-agentic-workflow), our Code Assistant v2 is an agentic worflow composed of the following steps:

1. The `code_assistant_agent` will read the code file from disk and generate a plan of agents to run
2. Depending on the plan, the Network will run the next Agent in the plan (*ex: `analysis_agent` and `documentation_agent`*)
3. Finally, the `summarization_agent` will generate a summary of the suggestions made by other agents

AgentKit's Router enables us to implement such dynamic workflow with code by providing a `defaultRouter` function:

```typescript {9-24} theme={"system"}
const network = createNetwork({
  name: "code-assistant-v2",
  agents: [
    codeAssistantAgent,
    documentationAgent,
    analysisAgent,
    summarizationAgent,
  ],
  router: ({ network }) => {
    if (!network?.state.kv.has("code") || !network?.state.kv.has("plan")) {
      return codeAssistantAgent;
    } else {
      const plan = (network?.state.kv.get("plan") || []) as string[];
      const nextAgent = plan.pop();
      if (nextAgent) {
        network?.state.kv.set("plan", plan);
        return network?.agents.get(nextAgent);
      } else if (!network?.state.kv.has("summary")) {
        return summarizationAgent;
      } else {
        return undefined;
      }
    }
  },
  defaultModel: anthropic({
    model: "claude-3-5-sonnet-latest",
    max_tokens: 4096,
  }),
});
```

<Note>
  **How does a Router work?**

  The Router is a function called by the Network when starting a new run and between each Agent call.

  The provided Router function (`defaultRouter`) receives a `network` argument granting access to the Network's state and Agents.

  Learn more about the [Router](/concepts/router).
</Note>

Let's have a closer look at the Router implementation:

```typescript theme={"system"}
const router = ({ network }) => {
  // the first iteration of the network will have an empty state
  //  also, the first run of `code_assistant_agent` will store the `code`,
  //  requiring a second run to generate the plan
  if (!network?.state.kv.has("code") || !network?.state.kv.has("plan")) {
    return codeAssistantAgent;
  } else {
    // once the `plan` available in the state, we iterate over the agents to execute
    const plan = (network?.state.kv.get("plan") || []) as string[];
    const nextAgent = plan.pop();
    if (nextAgent) {
      network?.state.kv.set("plan", plan);
      return network?.agents.get(nextAgent);
      // we no agents are left to run, we generate a summary
    } else if (!network?.state.kv.has("summary")) {
      return summarizationAgent;
      // if no agent are left to run and a summary is available, we are done
    } else {
      return undefined;
    }
  }
};
```

Our Code Assistant v2 iteration is now complete. Let's run it!

## Running the Code Assistant v2

First, go to your Anthropic dashboard and create a new API key.

Then, run the following command to execute our Code Assistant:

<CodeGroup>
  ```bash npm theme={"system"}
  ANTHROPIC_API_KEY=<your-api-key> npm run start
  ```

  ```bash pnpm theme={"system"}
  ANTHROPIC_API_KEY=<your-api-key> pnpm run start
  ```

  ```bash yarn theme={"system"}
  ANTHROPIC_API_KEY=<your-api-key> yarn run start
  ```
</CodeGroup>

The following output should be displayed in your terminal:

```txt theme={"system"}
Analysis: The code analysis suggests several key areas for improvement:

1. Type Safety and Structure:
- Implement strict TypeScript configurations
- Add explicit return types and interfaces
- Break down complex functions
- Follow Single Responsibility Principle
- Implement proper error handling

2. Performance Optimization:
- Review and optimize critical operations
- Consider caching mechanisms
- Improve data processing efficiency

3. Documentation:
- Add comprehensive JSDoc comments
- Document complex logic and assumptions
- Create detailed README
- Include setup and usage instructions
- Add code examples
```

<Note>
  Updating the `files/example.ts` by applying the suggestions and running the Code Assistant again will yield a different planning with a different summary.

  Try it out!
</Note>

## What we've learned so far

Let's recap what we've learned so far:

* **Agentic workflows**, compared to RAG workflows, **are more flexible** and can be used to perform more complex tasks
* **Combining multiple Agents improves the accuracy** of the LLM reasoning and can save tokens
* **AgentKit enables to combine multiple Agents** into a [Network](/concepts/networks), connected by a common [State](/concepts/state)
* **AgentKit's Router enables to implement our workflow with code**, keeping control over our reasoning planning

## Next steps

This Code Assistant v2 shines by its analysis capabilities, but cannot be qualified as an AI Agent.

In the next version of our Code Assistant, we will transform it into a semi-autonomous AI Agent that can solve bugs and improve code of a small project.

<Card title="Code Assistant v3: Autonomous Code Assistant" href="/ai-agents-in-practice/ai-agents" icon="brain">
  The final version update of our Code Assistant will transform it into a
  semi-autonomous AI Agent.
</Card>


# Code Assistant v3: Autonomous Bug Solver
Source: https://agentkit.inngest.com/guided-tour/ai-agents

Build a custom Agent Router to autonomously solve bugs.

## Overview

Our [Code Assistant v2](/ai-agents-in-practice/agentic-workflows) introduced some limited reasoning capabilities through Tools and a Network of Agents.
This third version will transform our Code Assistant into a semi-autonomous AI Agent that can solve bugs and improve code.

Our AI Agent will operate over an Express API project containing bugs:

```txt theme={"system"}
/examples/code-assistant-agent/project
├── package.json
├── tsconfig.json
├── src
│   ├── index.ts
│   ├── routes
│   │   ├── users.ts
│   │   └── posts.ts
│   ├── models
│   │   ├── user.ts
│   │   └── post.ts
│   └── db.ts
└── tests
    ├── users.test.ts
    └── posts.test.ts

```

Given a prompt such as:

```txt theme={"system"}
Can you help me fix the following error?
1. TypeError: Cannot read properties of undefined (reading 'body')
   at app.post (/project/src/routes/users.ts:10:23)
```

Our Code Assistant v3 will autonomously navigate through the codebase and fix the bug by updating the impacted files.

This new version relies on previously covered concepts such as [Tools](/concepts/tools), [Agents](/concepts/agent), and [Networks](/concepts/network) but introduces
the creation of a custom [Router Agent](/concepts/routers#routing-agent-autonomous-routing) bringing routing autonomy to the AI Agent.

Let's learn these concepts in practice.

## Setup

Similarly to the [Code Assistant v2](/ai-agents-in-practice/agentic-workflows), perform the following steps to setup your project:

<AccordionGroup>
  <Accordion title="1. Initialize your project">
    <CodeGroup>
      ```bash npm theme={"system"}
      npm init
      ```

      ```bash pnpm theme={"system"}
      pnpm init
      ```

      ```bash yarn theme={"system"}
      yarn init
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="2. Install the required dependencies">
    <CodeGroup>
      ```bash npm theme={"system"}
      npm install @inngest/agent-kit inngest zod
      ```

      ```bash pnpm theme={"system"}
      pnpm install @inngest/agent-kit inngest zod
      ```

      ```bash yarn theme={"system"}
      yarn add @inngest/agent-kit zod
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="3. Add TypeScript support">
    <CodeGroup>
      ```bash npm theme={"system"}
      npm install -D tsx @types/node
      ```

      ```bash pnpm theme={"system"}
      pnpm install -D tsx @types/node
      ```

      ```bash yarn theme={"system"}
      yarn add -D tsx @types/node
      ```
    </CodeGroup>

    And add the following scripts to your `package.json`:

    ```json theme={"system"}
    "scripts": {
        "start": "tsx ./index.ts"
    }
    ```
  </Accordion>
</AccordionGroup>

You are now set up, let's implement our autonomous Code Assistant.

## Implementing our Code Assistant v3

### Overview of the autonomous workflow

Our Code Assistant v3 introduces autonomy through a specialized Router Agent that orchestrates two task-specific Agents:

* `plannerAgent`: Analyzes code and plans fixes using code search capabilities
* `editorAgent`: Implements the planned fixes using file system operations

The Router Agent acts as the "brain" of our Code Assistant, deciding which Agent to use based on the current context and user request.

Let's implement each component of our autonomous workflow.

### Implementing the Tools

Our Code Assistant v3 needs to interact with the file system and search through code. Let's implement these capabilities as Tools:

```typescript {10, 12, 28} theme={"system"}
import { createTool } from "@inngest/agent-kit";

const writeFile = createTool({
  name: "writeFile",
  description: "Write a file to the filesystem",
  parameters: z.object({
    path: z.string().describe("The path to the file to write"),
    content: z.string().describe("The content to write to the file"),
  }),
  handler: async ({ path, content }) => {
    try {
      let relativePath = path.startsWith("/") ? path.slice(1) : path;
      writeFileSync(relativePath, content);
      return "File written";
    } catch (err) {
      console.error(`Error writing file ${path}:`, err);
      throw new Error(`Failed to write file ${path}`);
    }
  },
});

const readFile = createTool({
  name: "readFile",
  description: "Read a file from the filesystem",
  parameters: z.object({
    path: z.string().describe("The path to the file to read"),
  }),
  handler: async ({ path }) => {
    try {
      let relativePath = path.startsWith("/") ? path.slice(1) : path;
      const content = readFileSync(relativePath, "utf-8");
      return content;
    } catch (err) {
      console.error(`Error reading file ${path}:`, err);
      throw new Error(`Failed to read file ${path}`);
    }
  },
});

const searchCode = createTool({
  name: "searchCode",
  description: "Search for a given pattern in a project files",
  parameters: z.object({
    query: z.string().describe("The query to search for"),
  }),
  handler: async ({ query }) => {
    const searchFiles = (dir: string, searchQuery: string): string[] => {
      const results: string[] = [];
      const walk = (currentPath: string) => {
        const files = readdirSync(currentPath);
        for (const file of files) {
          const filePath = join(currentPath, file);
          const stat = statSync(filePath);
          if (stat.isDirectory()) {
            walk(filePath);
          } else {
            try {
              const content = readFileSync(filePath, "utf-8");
              if (content.includes(searchQuery)) {
                results.push(filePath);
              }
            } catch (err) {
              console.error(`Error reading file ${filePath}:`, err);
            }
          }
        }
      };
      walk(dir);
      return results;
    };
    const matches = searchFiles(process.cwd(), query);
    return matches.length === 0
      ? "No matches found"
      : `Found matches in following files:\n${matches.join("\n")}`;
  },
});
```

<Note>
  Some notes on the highlighted lines:

  * As noted in the ["Building Effective Agents" article](https://www.anthropic.com/research/building-effective-agents) from Anthropic, Tools based on file system operations are most effective when provided with absolute paths.
  * Tools performing action such as `writeFile` should always return a value to inform the Agent that the action has been completed.
</Note>

These Tools provide our Agents with the following capabilities:

* `writeFile`: Write content to a file
* `readFile`: Read content from a file
* `searchCode`: Search for patterns in project files

Let's now create our task-specific Agents.

### Creating the Task-Specific Agents

Our Code Assistant v3 relies on two specialized Agents:

```typescript theme={"system"}
import { createAgent } from "@inngest/agent-kit";

const plannerAgent = createAgent({
  name: "planner",
  system: "You are an expert in debugging TypeScript projects.",
  tools: [searchCode],
});

const editorAgent = createAgent({
  name: "editor",
  system: "You are an expert in fixing bugs in TypeScript projects.",
  tools: [writeFile, readFile],
});
```

Each Agent has a specific role:

* `plannerAgent` uses the `searchCode` Tool to analyze code and plan fixes
* `editorAgent` uses the `readFile` and `writeFile` Tools to implement fixes

Separating the Agents into two distinct roles will enable our AI Agent to better *"divide and conquer"* the problem to solve.

Let's now implement the Router Agent that will bring the reasoning capabilities to autonomously orchestrate these Agents.

### Implementing the Router Agent

The [Router Agent](/concepts/routers#routing-agent-autonomous-routing) is the "brain" of our Code Assistant, deciding which Agent to use based on the context.

The router developed in the [Code Assistant v2](/ai-agents-in-practice/agentic-workflows) was a function that decided which Agent to call next
based on the progress of the workflow. Such router made a Agent deterministic, but lacked the reasoning capabilities to autonomously orchestrate the Agents.

In this version, we will provide an Agent as a router, called a Router Agent.
By doing so, we can leverage the reasoning capabilities of the LLM to autonomously orchestrate the Agents around a given goal (here, fixing the bug).

Creating a Router Agent is done by using the [`createRoutingAgent`](/reference/network-router#createroutingagent) helper function:

```typescript {5, 38, 70} theme={"system"}
import { createRoutingAgent } from "@inngest/agent-kit";

const router = createRoutingAgent({
  name: "Code Assistant routing agent",
  system: async ({ network }): Promise<string> => {
    if (!network) {
      throw new Error(
        "The routing agent can only be used within a network of agents"
      );
    }
    const agents = await network?.availableAgents();
    return `You are the orchestrator between a group of agents. Each agent is suited for a set of specific tasks, and has a name, instructions, and a set of tools.
      
      The following agents are available:
      <agents>
      ${agents
        .map((a) => {
          return `
        <agent>
          <name>${a.name}</name>
          <description>${a.description}</description>
          <tools>${JSON.stringify(Array.from(a.tools.values()))}</tools>
        </agent>`;
        })
        .join("\n")}
      </agents>
      
      Follow the set of instructions:
      
      <instructions>
      Think about the current history and status.
      If the user issue has been fixed, call select_agent with "finished"
      Otherwise, determine which agent to use to handle the user's request, based off of the current agents and their tools.
      
      Your aim is to thoroughly complete the request, thinking step by step, choosing the right agent based off of the context.
      </instructions>`;
  },
  tools: [
    createTool({
      name: "select_agent",
      description:
        "select an agent to handle the input, based off of the current conversation",
      parameters: z
        .object({
          name: z
            .string()
            .describe("The name of the agent that should handle the request"),
        })
        .strict(),
      handler: ({ name }, { network }) => {
        if (!network) {
          throw new Error(
            "The routing agent can only be used within a network of agents"
          );
        }
        if (name === "finished") {
          return undefined;
        }
        const agent = network.agents.get(name);
        if (agent === undefined) {
          throw new Error(
            `The routing agent requested an agent that doesn't exist: ${name}`
          );
        }
        return agent.name;
      },
    }),
  ],
  tool_choice: "select_agent",
  lifecycle: {
    onRoute: ({ result }) => {
      const tool = result.toolCalls[0];
      if (!tool) {
        return;
      }
      const agentName = (tool.content as any).data || (tool.content as string);
      if (agentName === "finished") {
        return;
      } else {
        return [agentName];
      }
    },
  },
});
```

Looking at the highlighted lines, we can see that a Router Agent mixes features from regular Agents and a function Router:

1. A Router Agent is a regular Agent with a `system` function that returns a prompt
2. A Router Agent can use [Tools](/concepts/tools) to interact with the environment
3. Finally, a Router Agent can also define lifecycle callbacks, [like Agents do](/concepts/agents#lifecycle-hooks)

Let's now dissect how this Router Agent works:

1. The `system` function is used to define the prompt dynamically based on the Agents available in the Network
   * You will notice that the prompt explicitly ask to call a "finished" tool when the user issue has been fixed
2. The `select_agent` Tool is used to validate that the Agent selected is available in the Network
   * The tool ensures that the "finished" edge case is handled
3. The `onRoute` lifecycle callback is used to determine which Agent to call next
   * This callback stops the conversation when the user issue has been fixed (when the "finished" Agent is called)

This is it! Using this prompt, our Router Agent will orchestrate the Agents until the given bug is fixed.

### Assembling the Network

Finally, assemble the Network of Agents and Router Agent:

```typescript theme={"system"}
const network = createNetwork({
  name: "code-assistant-v3",
  agents: [plannerAgent, editorAgent],
  defaultModel: anthropic({
    model: "claude-3-5-sonnet-latest",
    max_tokens: 4096,
  }),
  router: router,
});
```

Our Code Assistant v3 is now complete and ready to be used!

## Running our Code Assistant v3

First, go to your Anthropic dashboard and create a new API key.

Then, run the following command to start the server:

<CodeGroup>
  ```bash npm theme={"system"}
  ANTHROPIC_API_KEY=<your-api-key> npm run start
  ```

  ```bash pnpm theme={"system"}
  ANTHROPIC_API_KEY=<your-api-key> pnpm run start
  ```

  ```bash yarn theme={"system"}
  ANTHROPIC_API_KEY=<your-api-key> yarn run start
  ```
</CodeGroup>

Your Code Assistant is now running at `http://localhost:3010` and ready to help fix bugs in your TypeScript projects!

## What we've learned so far

Let's recap what we've learned so far:

* **Autonomous AI Agents** can be built by using [**Router Agents**](/concepts/routers#routing-agent-autonomous-routing), which act as the "brain" of an autonomous system by orchestrating other Agents
* **Tools** provide Agents with capabilities to interact with their environment


# Code Assistant v1: Explaining a given code file
Source: https://agentkit.inngest.com/guided-tour/ai-workflows

Leveraging AgentKit's Agent concept to power a RAG workflow.

## Overview

As discussed in the [introduction](/ai-agents-in-practice/overview), developing AI applications is a pragmatic approach requiring
to start simple and iterate towards complexity.

Following this approach, this first version of our Code Assistant will be able to explain a given code file:

```typescript theme={"system"}
const filePath = join(process.cwd(), `files/example.ts`);
const code = readFileSync(filePath, "utf-8");

const { lastMessage } = await codeAssistant.run(`What the following code does?

${code}
`);

console.log(lastMessage({ type: "text" }).content);
// This file (example.ts) is a TypeScript module that provides a collection of type-safe sorting helper functions. It contains five main sorting utility functions:

// 1. `sortNumbers(numbers: number[], descending = false)`
//    - Sorts an array of numbers in ascending (default) or descending order
//    - Takes an array of numbers and an optional boolean to determine sort direction

// 2. `sortStrings(strings: string[], options)`
//    - Sorts strings alphabetically with customizable options
//    - Options include:
//      - caseSensitive (default: false)
//      - descending (default: false)

// ...
```

To implement this capability, we will build a AI workflow leveraging a first important concept of AgentKit:

* [Agents](/concepts/agents): Agents act as a wrapper around the LLM (ex: Anthropic), providing a structured way to interact with it.

Let's start our Code Assistant by installing the required dependencies:

## Setup

Follow the below steps to setup your project:

<AccordionGroup>
  <Accordion title="1. Initialize your project">
    <CodeGroup>
      ```bash npm theme={"system"}
      npm init
      ```

      ```bash pnpm theme={"system"}
      pnpm init
      ```

      ```bash yarn theme={"system"}
      yarn init
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="2. Install the required dependencies">
    <CodeGroup>
      ```bash npm theme={"system"}
      npm install @inngest/agent-kit inngest
      ```

      ```bash pnpm theme={"system"}
      pnpm install @inngest/agent-kit inngest
      ```

      ```bash yarn theme={"system"}
      yarn add @inngest/agent-kit inngest
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="3. Add TypeScript support">
    <CodeGroup>
      ```bash npm theme={"system"}
      npm install -D tsx @types/node
      ```

      ```bash pnpm theme={"system"}
      pnpm install -D tsx @types/node
      ```

      ```bash yarn theme={"system"}
      yarn add -D tsx @types/node
      ```

      And add the following scripts to your `package.json`:

      ```json theme={"system"}
      "scripts": {
          "start": "tsx ./index.ts"
      }
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="4. Download the example code file">
    <CodeGroup>
      ```bash theme={"system"}
      wget https://raw.githubusercontent.com/inngest/agent-kit/main/examples/code-assistant-rag/files/example.ts
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

You are now set up, let's implement the first version of our Code Assistant.

## Implementing our Code Assistant v1

Our first version of our Code Assistant takes the shape of a RAG workflow.
A RAG workflow is a specific type of AI workflow that generally consist of two steps: retrieval (fetching relevant information) and generation (creating a response with a LLM).

Our Code Assistant will have following two steps:

* **A retrieval step** reads the content of a local file specified by the user.
* **A generation step** uses Anthropic to analyze the code and provide a detailed explanation of what it does.

Let's start by implementing the retrieval step.

### The retrieval step: loading the code file

We earlier downloaded the `example.ts` file locally, let's load it in our code by creating a `index.ts` file:

```typescript {5-7} theme={"system"}
import { readFileSync } from "fs";
import { join } from "path";

async function main() {
  // First step: Retrieval
  const filePath = join(process.cwd(), `files/example.ts`);
  const code = readFileSync(filePath, "utf-8");
}

main();
```

Our example code is now ready to be analyzed. Let's now implement the generation step.

### The generation step using AgentKit's Agent

As covered in the introduction, [AgentKit's `createAgent()`](/reference/create-agent) is a wrapper around the LLM, providing a structured way to interact with it with 3 main properties:

* `name`: A unique identifier for the agent.
* `system`: A description of the agent's purpose.
* `model`: The LLM to use.

Let's add configure our Agent with Anthropic's `claude-3-5-sonnet-latest` model by updating our `index.ts` file:

```typescript {5-13} theme={"system"}
import { readFileSync } from "fs";
import { join } from "path";
import { anthropic, createAgent } from "@inngest/agent-kit";

const codeAssistant = createAgent({
  name: "code_assistant",
  system:
    "An AI assistant that helps answer questions about code by reading and analyzing files",
  model: anthropic({
    model: "claude-3-5-sonnet-latest",
    max_tokens: 4096,
  }),
});

async function main() {
  // First step: Retrieval
  const filePath = join(process.cwd(), `files/example.ts`);
  const code = readFileSync(filePath, "utf-8");
}

main();
```

Let's now update our `main()` function to use our `codeAssistant` Agent in the generation step:

```typescript {21-29} theme={"system"}
/* eslint-disable */
import { readFileSync } from "fs";
import { join } from "path";
import { anthropic, createAgent } from "@inngest/agent-kit";

// Create the code assistant agent
const codeAssistant = createAgent({
  name: "code_assistant",
  system:
    "An AI assistant that helps answer questions about code by reading and analyzing files",
  model: anthropic({
    model: "claude-3-5-sonnet-latest",
    max_tokens: 4096,
  }),
});

async function main() {
  // First step: Retrieval
  const filePath = join(process.cwd(), `files/example.ts`);
  const code = readFileSync(filePath, "utf-8");
  // Second step: Generation
  const { output } = await codeAssistant.run(`What the following code does?

  ${code}
  `);
  const lastMessage = output[output.length - 1];
  const content =
    lastMessage?.type === "text" ? (lastMessage?.content as string) : "";
  console.log(content);
}

main();
```

Let's review the above code:

1. We load the `example.ts` file in memory.
2. We invoke our Code Assistant using the `codeAssistant.run()` method.
3. We retrieve the last message from the `output` array.
4. We log the content of the last message to the console.

Let's now look at our assistant explanation.

## Running our Code Assistant v1

First, go to your Anthropic dashboard and create a new API key.

Then, run the following command to execute our Code Assistant:

<CodeGroup>
  ```bash npm theme={"system"}
  ANTHROPIC_API_KEY=<your-api-key> npm run start
  ```

  ```bash pnpm theme={"system"}
  ANTHROPIC_API_KEY=<your-api-key> pnpm run start
  ```

  ```bash yarn theme={"system"}
  ANTHROPIC_API_KEY=<your-api-key> yarn run start
  ```
</CodeGroup>

The following output should be displayed in your terminal:

```
This code is a collection of type-safe sorting utility functions written in TypeScript. Here's a breakdown of each function:

1. `sortNumbers(numbers: number[], descending = false)`
- Sorts an array of numbers in ascending (default) or descending order
- Returns a new sorted array without modifying the original

2. `sortStrings(strings: string[], options)`
- Sorts an array of strings alphabetically
- Accepts options for case sensitivity and sort direction
- Default behavior is case-insensitive ascending order
- Returns a new sorted array

3. `sortByKey<T>(items: T[], key: keyof T, descending = false)`
- Sorts an array of objects by a specific key
- Handles both number and string values
- Generic type T ensures type safety
- Returns a new sorted array

4. `sortByMultipleKeys<T>(items: T[], sortKeys: Array<...>)`
- Sorts an array of objects by multiple keys in order
- Each key can have its own sort configuration (descending, case sensitivity)
- Continues to next key if values are equal
- Returns a new sorted array

...
```

Congratulations! You've just built your first AI workflow using AgentKit.

## What we've learned so far

Let's recap what we've learned so far:

* **A RAG workflow** is a specific type of AI workflow that generally consist of two steps: retrieval (fetching relevant information) and generation (creating a response with a LLM).
  * *Note that most RAG workflows in production consist of more than two steps and combine multiple sources of information and generation steps. You can see an example in [this blog post](https://www.inngest.com/blog/next-generation-ai-workflows?ref=agentkit-docs).*
* **AgentKit's `createAgent()`** is a wrapper around the LLM, providing a structured way to interact with a LLM model.
  * *The use of a single Agent is often sufficient to power chatbots or extract structured data from a given text.*

## Next steps

Our Code Assistant v1 is a static AI workflow that only works with the `example.ts` file.

In the next version of our Code Assistant, we will make it dynamic by allowing the user to specify the file to analyze and also enable our Agent to perform more complete analysis.

<Card title="Code Assistant v2: Complex code analysis" href="/ai-agents-in-practice/agentic-workflows" icon="bolt">
  Our next Code Assistant version will rely on Agentic workflows to perform more
  complex code analysis.
</Card>


# The three levels of AI apps
Source: https://agentkit.inngest.com/guided-tour/overview

A comprehensive guide to building AI Agents with AgentKit

AI Agents can be a complex topic to understand and differentiate from RAG, AI workflows, Agentic workflows, and more.
This guide will provide a definition of AI Agents with practical examples inspired by the [Building effective agents](https://www.anthropic.com/research/building-effective-agents) manifesto from Anthropic.

Developing AI applications leverages multiple patterns from AI workflows with static steps to fully autonomous AI Agents, each fitting specific use cases.
The best way to start is to begin simple and iterate towards complexity.

This guide features a Code Assistant that will will progressively evolve from a static AI workflow to an autonomous AI Agent.

Below are the different versions of our Code Assistant, each progressively adding more autonomy and complexity:

<Card title={<div className="flex items-center gap-2"><span className="border-primary dark:border-primary-light bg-primary/10 text-primary text-xs dark:text-primary-light dark:bg-primary-light/10 rounded-xl px-2 py-1">v1</span> {"Explaining a given code file"}</div>} href="/guided-tour/ai-workflows">
  The first version starts as a AI workflow using a tool to provide a file as context to the LLM (RAG).
</Card>

<Card title={<div className="flex items-center gap-2"><span className="border-primary dark:border-primary-light bg-primary/10 text-primary text-xs dark:text-primary-light dark:bg-primary-light/10 rounded-xl px-2 py-1">v2</span> {"Performing complex code analysis"}</div>} href="/guided-tour/agentic-workflows">
  Then, we will add Agentic capabilities to our assistant to enable it more complex analysis.
</Card>

<Card title={<div className="flex items-center gap-2"><span className="border-primary dark:border-primary-light bg-primary/10 text-primary text-xs dark:text-primary-light dark:bg-primary-light/10 rounded-xl px-2 py-1">v3</span> {"Autonomously reviewing a pull request"}</div>} href="/guided-tour/ai-agents">
  Finally, we will add more autonomy to our assistant, transforming it into a semi-autonomous AI Agent.
</Card>

<Card title={<div className="flex items-center gap-2"><span className="border-primary dark:border-primary-light bg-primary/10 text-primary text-xs dark:text-primary-light dark:bg-primary-light/10 rounded-xl px-2 py-1">New</span> {"Pushing our Code Assistant to production"}</div>} href="/concepts/deployment">
  Discover the best practices to deploy your AI Agents to production.
</Card>

Depending on your experience developing AI applications, you can choose to start directly with the second part covering Agentic workflows.

Happy coding!


# Using AgentKit with Browserbase
Source: https://agentkit.inngest.com/integrations/browserbase

Develop AI Agents that can browse the web

[Browserbase](https://www.browserbase.com/) provides managed [headless browsers](https://docs.browserbase.com/introduction/what-is-headless-browser) to
enable Agents to browse the web autonomously.

There are two ways to use Browserbase with AgentKit:

* **Create your own Browserbase tools**: useful if you want to build simple actions on webpages with manual browser control.
* **Use Browserbase's [Stagehand](https://www.stagehand.dev/) library as tools**: a better approach for autonomous browsing and resilient scraping.

## Building AgentKit tools using Browserbase

Creating AgentKit [tools](/concepts/tools) using the Browserbase TypeScript SDK is straightforward.

<Steps>
  <Step title="Install AgentKit">
    Within an existing project, install AgentKit, Browserbase and Playwright core:

    <CodeGroup>
      ```shell npm theme={"system"}
      npm install @inngest/agent-kit inngest @browserbasehq/sdk playwright-core
      ```

      ```shell pnpm theme={"system"}
      pnpm install @inngest/agent-kit inngest @browserbasehq/sdk playwright-core
      ```

      ```shell yarn theme={"system"}
      yarn add @inngest/agent-kit inngest @browserbasehq/sdk playwright-core
      ```
    </CodeGroup>

    <Accordion title="Don't have an existing project?">
      To create a new project, create a new directory then initialize using your package manager:

      <CodeGroup>
        ```shell npm theme={"system"}
        mkdir my-agent-kit-project && npm init
        ```

        ```shell pnpm theme={"system"}
        mkdir my-agent-kit-project && pnpm init
        ```

        ```shell yarn theme={"system"}
        mkdir my-agent-kit-project && yarn init
        ```
      </CodeGroup>
    </Accordion>
  </Step>

  <Step title="2. Setup an AgentKit Newtork with an Agent">
    Create a Agent and its associated Network, for example a Reddit Search Agent:

    ```typescript theme={"system"}
    import {
      anthropic,
      createAgent,
      createNetwork,
    } from "@inngest/agent-kit";

    const searchAgent = createAgent({
      name: "reddit_searcher",
      description: "An agent that searches Reddit for relevant information",
      system:
      "You are a helpful assistant that searches Reddit for relevant information.",
    });

    // Create the network
    const redditSearchNetwork = createNetwork({
      name: "reddit_search_network",
      description: "A network that searches Reddit using Browserbase",
      agents: [searchAgent],
      maxIter: 2,
      defaultModel: anthropic({
      model: "claude-3-5-sonnet-latest",
      max_tokens: 4096,
    });

    ```
  </Step>

  <Step title="Create a Browserbase tool">
    Let's configure the Browserbase SDK and create a tool that can search Reddit:

    ```typescript {5, 8-9, 11-13} theme={"system"}
    import {
      anthropic,
      createAgent,
      createNetwork,
      createTool,
    } from "@inngest/agent-kit";
    import { z } from "zod";
    import { chromium } from "playwright-core";
    import Browserbase from "@browserbasehq/sdk";

    const bb = new Browserbase({
      apiKey: process.env.BROWSERBASE_API_KEY as string,
    });

    // Create a tool to search Reddit using Browserbase
    const searchReddit = createTool({
      name: "search_reddit",
      description: "Search Reddit posts and comments",
      parameters: z.object({
        query: z.string().describe("The search query for Reddit"),
      }),
      handler: async ({ query }, { step }) => {
        return await step?.run("search-on-reddit", async () => {
          // Create a new session
          const session = await bb.sessions.create({
            projectId: process.env.BROWSERBASE_PROJECT_ID as string,
          });

          // Connect to the session
          const browser = await chromium.connectOverCDP(session.connectUrl);
          try {
            const page = await browser.newPage();

            // Construct the search URL
            const searchUrl = `https://search-new.pullpush.io/?type=submission&q=${query}`;

            console.log(searchUrl);

            await page.goto(searchUrl);

            // Wait for results to load
            await page.waitForSelector("div.results", { timeout: 10000 });

            // Extract search results
            const results = await page.evaluate(() => {
              const posts = document.querySelectorAll("div.results div:has(h1)");
              return Array.from(posts).map((post) => ({
                title: post.querySelector("h1")?.textContent?.trim(),
                content: post.querySelector("div")?.textContent?.trim(),
              }));
            });

            console.log("results", JSON.stringify(results, null, 2));

            return results.slice(0, 5); // Return top 5 results
          } finally {
            await browser.close();
          }
        });
      },
    });
    ```

    <Info>
      Configure your `BROWSERBASE_API_KEY` and `BROWSERBASE_PROJECT_ID` in the
      `.env` file. You can find your API key and project ID from the [Browserbase
      dashboard](https://docs.browserbase.com/introduction/getting-started#creating-your-account).
    </Info>

    <Tip>
      We recommend building tools using Browserbase using Inngest's `step.run()` function. This ensures that the tool will only run once across multiple runs.

      More information about using `step.run()` can be found in the [Multi steps tools](/advanced-patterns/multi-steps-tools) page.
    </Tip>
  </Step>
</Steps>

### Example: Reddit Search Agent using Browserbase

You will find a complete example of a Reddit search agent using Browserbase in the Reddit Search Agent using Browserbase example:

<Card title="Reddit Search Agent using Browserbase" href="https://github.com/inngest/agent-kit/tree/main/examples/reddit-search-browserbase-tools#readme" icon="github">
  This examples shows how to build tools using Browserbase to power a Reddit search agent.

  <br />

  <span>
    Agents
  </span>

  <span>
    Tools
  </span>

  <span>
    Network
  </span>

  <span>
    Integrations
  </span>
</Card>

## Enable autonomous browsing with Stagehand

Building AgentKit tools using [Stagehand](https://www.stagehand.dev/) gives more autonomy to your agents.

Stagehand comes with 4 primary API that can be directly used as tools:

* `goto()`: navigate to a specific URL
* `observe()`: observe the current page
* `extract()`: extract data from the current page
* `act()`: take action on the current page

These methods can be easily directly be used as tools in AgentKit, enabling agents to browse the web autonomously.

Below is an example of a simple search agent that uses Stagehand to search the web:

```ts {22, 46-49, 66, 83} theme={"system"}
import { createAgent, createTool } from "@inngest/agent-kit";
import { z } from "zod";
import { getStagehand, stringToZodSchema } from "./utils.js";

const webSearchAgent = createAgent({
  name: "web_search_agent",
  description: "I am a web search agent.",
  system: `You are a web search agent.
  `,
  tools: [
    createTool({
      name: "navigate",
      description: "Navigate to a given URL",
      parameters: z.object({
        url: z.string().describe("the URL to navigate to"),
      }),
      handler: async ({ url }, { step, network }) => {
        return await step?.run("navigate", async () => {
          const stagehand = await getStagehand(
            network?.state.kv.get("browserbaseSessionID")!
          );
          await stagehand.page.goto(url);
          return `Navigated to ${url}.`;
        });
      },
    }),
    createTool({
      name: "extract",
      description: "Extract data from the page",
      parameters: z.object({
        instruction: z
          .string()
          .describe("Instructions for what data to extract from the page"),
        schema: z
          .string()
          .describe(
            "A string representing the properties and types of data to extract, for example: '{ name: string, age: number }'"
          ),
      }),
      handler: async ({ instruction, schema }, { step, network }) => {
        return await step?.run("extract", async () => {
          const stagehand = await getStagehand(
            network?.state.kv.get("browserbaseSessionID")!
          );
          const zodSchema = stringToZodSchema(schema);
          return await stagehand.page.extract({
            instruction,
            schema: zodSchema,
          });
        });
      },
    }),
    createTool({
      name: "act",
      description: "Perform an action on the page",
      parameters: z.object({
        action: z
          .string()
          .describe("The action to perform (e.g. 'click the login button')"),
      }),
      handler: async ({ action }, { step, network }) => {
        return await step?.run("act", async () => {
          const stagehand = await getStagehand(
            network?.state.kv.get("browserbaseSessionID")!
          );
          return await stagehand.page.act({ action });
        });
      },
    }),
    createTool({
      name: "observe",
      description: "Observe the page",
      parameters: z.object({
        instruction: z
          .string()
          .describe("Specific instruction for what to observe on the page"),
      }),
      handler: async ({ instruction }, { step, network }) => {
        return await step?.run("observe", async () => {
          const stagehand = await getStagehand(
            network?.state.kv.get("browserbaseSessionID")!
          );
          return await stagehand.page.observe({ instruction });
        });
      },
    }),
  ],
});
```

<Info>
  These 4 AgentKit tools using Stagehand enables the Web Search Agent to browse the web autonomously.

  The `getStagehand()` helper function is used to retrieve the persisted instance created for the network execution (*see full code below*).
</Info>

You will find the complete example on GitHub:

<Card title="Simple Search Agent using Stagehand" href="https://github.com/inngest/agent-kit/tree/main/examples/simple-search-stagehand/#readme" icon="github">
  This examples shows how to build tools using Stagehand to power a simple search agent.

  <br />

  <span>
    Agents
  </span>

  <span>
    Tools
  </span>

  <span>
    Network
  </span>

  <span>
    Integrations
  </span>
</Card>


# Using AgentKit with Daytona
Source: https://agentkit.inngest.com/integrations/daytona

Build Coding Agents with Daytona's secure and elastic infrastructure for executing AI-generated code

[Daytona](https://www.daytona.io/) provides secure, high-performance infrastructure for running AI-generated code. It's designed for any use case requiring secure sandbox environments and lightning-fast execution: running code, spinning up applications, data analysis, automated testing, CI/CD pipelines and more.

Daytona is the perfect foundation for building autonomous Coding Agents that can scaffold projects, execute scripts, and deliver production-ready solutions.

## Setup

<Steps>
  <Step title="Install AgentKit and Daytona">
    Within an existing project, Install AgentKit and Daytona:

    <CodeGroup>
      ```shell npm theme={"system"}
      npm install @inngest/agent-kit inngest @daytonaio/sdk
      ```

      ```shell pnpm theme={"system"}
      pnpm install @inngest/agent-kit inngest @daytonaio/sdk
      ```

      ```shell yarn theme={"system"}
      yarn add @inngest/agent-kit inngest @daytonaio/sdk
      ```
    </CodeGroup>

    <br />

    <Accordion title="Don't have an existing project?">
      To create a new project, create a new directory then initialize using your package manager:

      <CodeGroup>
        ```shell npm theme={"system"}
        mkdir my-agent-kit-project && npm init
        ```

        ```shell pnpm theme={"system"}
        mkdir my-agent-kit-project && pnpm init
        ```

        ```shell yarn theme={"system"}
        mkdir my-agent-kit-project && yarn init
        ```
      </CodeGroup>
    </Accordion>
  </Step>

  <Step title="Setup the Coding Agent">
    Create a Coding Agent with a system prompt that defines its behavior and select a model with appropriate parameters. In this example, we use Anthropic's Claude model:

    ```typescript theme={"system"}
    import {
      createAgent,
      anthropic,
    } from "@inngest/agent-kit";

    const codingAgent = createAgent({
      name: "Coding Agent",
      description:
        "An autonomous coding agent for building software in a Daytona sandbox",
      system: `You are a coding agent designed to help the user achieve software development tasks. You have access to a Daytona sandbox environment.

    Capabilities:
    - You can execute code snippets or scripts.
    - You can run shell commands to install dependencies, manipulate files, and set up environments.
    - You can create, upload, and organize files and directories to build basic applications and project structures.

    Workspace Instructions:
    - You do not need to define, set up, or specify the workspace directory. Assume you are already inside a default workspace directory that is ready for app creation.
    - All file and folder operations (create, upload, organize) should use paths relative to this default workspace.
    - Do not attempt to create or configure the workspace itself; focus only on the requested development tasks.

    Guidelines:
    - Always analyze the user's request and plan your steps before taking action.
    - Prefer automation and scripting over manual or interactive steps.
    - When installing packages or running commands that may prompt for input, use flags (e.g., '-y') to avoid blocking.
    - If you are developing an app that is served with a development server (e.g. Next.js, React):
      1. Return the port information in the form: DEV_SERVER_PORT=$PORT (replace $PORT with the actual port number).
      2. Start the development server.
      3. After starting the dev server, always check its health in the next iteration. Only mark the task as complete if the health check passes: there must be no stderr output, no errors thrown, and the stdout content must not indicate a problem (such as error messages, stack traces, or failed startup). If any of these are present, diagnose and fix the issue before completing the task.
    - When you have completed the requested task, set the "TASK_COMPLETED" string in your output to signal that the app is finished.
    `,
      model: anthropic({
        model: "claude-3-5-haiku-20241022",
        defaultParameters: {
          max_tokens: 1024,
        },
      }),
    });
    ```
  </Step>

  <Step title="Create the Daytona Tools">
    To fulfill the objectives specified in its system prompt, the Coding Agent needs access to sandbox environments; this is where Daytona steps in.

    The Daytona sandbox environment is exposed to the Coding Agent via tools. Our goal is to define a set of tools that enable the Coding Agent to achieve virtually any coding task.

    In this example, we'll show implementations of `codeRunTool` and `readFileTool`. Note that the code also uses `getSandbox` and `logDebug` utility functions for sandbox management and logging. You can find complete implementations of all coding agent tools and utility functions in the [Daytona Coding Agent example](https://github.com/inngest/agent-kit/tree/main/examples/daytona-coding-agent#readme).

    ```typescript {4, 6-8, 42 - 101} theme={"system"}
    import {
      createAgent,
      anthropic,
      createTool,
    } from "@inngest/agent-kit";
    import { z } from "zod";
    import { CodeRunParams, DaytonaError } from "@daytonaio/sdk";
    import { getSandbox, logDebug } from "./utils.js";

    const codingAgent = createAgent({
      name: "Coding Agent",
      description:
        "An autonomous coding agent for building software in a Daytona sandbox",
    system: `You are a coding agent designed to help the user achieve software development tasks. You have access to a Daytona sandbox environment.

    Capabilities:
    - You can execute code snippets or scripts.
    - You can run shell commands to install dependencies, manipulate files, and set up environments.
    - You can create, upload, and organize files and directories to build basic applications and project structures.

    Workspace Instructions:
    - You do not need to define, set up, or specify the workspace directory. Assume you are already inside a default workspace directory that is ready for app creation.
    - All file and folder operations (create, upload, organize) should use paths relative to this default workspace.
    - Do not attempt to create or configure the workspace itself; focus only on the requested development tasks.

    Guidelines:
    - Always analyze the user's request and plan your steps before taking action.
    - Prefer automation and scripting over manual or interactive steps.
    - When installing packages or running commands that may prompt for input, use flags (e.g., '-y') to avoid blocking.
    - If you are developing an app that is served with a development server (e.g. Next.js, React):
      1. Return the port information in the form: DEV_SERVER_PORT=$PORT (replace $PORT with the actual port number).
      2. Start the development server.
      3. After starting the dev server, always check its health in the next iteration. Only mark the task as complete if the health check passes: there must be no stderr output, no errors thrown, and the stdout content must not indicate a problem (such as error messages, stack traces, or failed startup). If any of these are present, diagnose and fix the issue before completing the task.
    - When you have completed the requested task, set the "TASK_COMPLETED" string in your output to signal that the app is finished.
    `,
      model: anthropic({
        model: "claude-3-5-haiku-20241022",
        defaultParameters: {
          max_tokens: 1024,
        },
      }),
      tools: [
        createTool({
          name: "codeRunTool",
          description: `Executes code in the Daytona sandbox. Use this tool to run code snippets, scripts, or application entry points.
      Parameters:
          - code: Code to execute.
          - argv: Command line arguments to pass to the code.
          - env: Environment variables for the code execution, as key-value pairs.`,
          parameters: z.object({
            code: z.string(),
            argv: z.array(z.string()).nullable(),
            env: z.record(z.string(), z.string()).nullable(),
          }),
          handler: async ({ code, argv, env }, { network }) => {
            try {
              const sandbox = await getSandbox(network);
              const codeRunParams = new CodeRunParams();
              codeRunParams.argv = argv ?? [];
              codeRunParams.env = env ?? {};
              console.log(`[TOOL: codeRunTool]\nParams: ${codeRunParams}\n${code}`);
              const response = await sandbox.process.codeRun(code, codeRunParams);
              const responseMessage = `Code run result: ${response.result}${
                response.artifacts?.stdout
                  ? `\nStdout: ${response.artifacts.stdout}`
                  : ""
              }`;
              logDebug(responseMessage);
              return responseMessage;
            } catch (error) {
              console.error("Error executing code:", error);
              if (error instanceof DaytonaError)
                return `Code execution Daytona error: ${error.message}`;
              else return "Error executing code";
            }
          },
        }),
        createTool({
          name: "readFileTool",
          description: `Reads the contents of a file from the Daytona sandbox. Use this tool to retrieve source code, configuration files, or other assets for analysis or processing.`,
          parameters: z.object({
            filePath: z.string(),
          }),
          handler: async ({ filePath }, { network }) => {
            try {
              const sandbox = await getSandbox(network);
              console.log(`[TOOL: readFileTool]\nFile path: ${filePath}`);
              const fileBuffer = await sandbox.fs.downloadFile(filePath);
              const fileContent = fileBuffer.toString("utf-8");
              const readFileMessage = `Successfully read file: ${filePath}\nContent:\n${fileContent}`;
              logDebug(readFileMessage);
              return fileContent;
            } catch (error) {
              console.error("Error reading file:", error);
              if (error instanceof DaytonaError)
                return `File reading Daytona error: ${error.message}`;
              else return "Error reading file";
            }
          },
        }),
      ],
    });
    ```
  </Step>

  <Step title="Create agent network">
    Create a network with a code-based router that determines when the agent has completed its task and checks if a development server was started to set the data needed for preview generation.

    ```typescript theme={"system"}
    import {
      createNetwork,
    } from "@inngest/agent-kit";
    import { extractTextMessageContent, logDebug } from "./utils.js";

      const network = createNetwork({
        name: "coding-agent-network",
        agents: [codingAgent], // Using codingAgent from previous step
        maxIter: 30,
        defaultRouter: ({ network, callCount }) => {
          const previousIterationMessageContent = extractTextMessageContent(
            network.state.results.at(-1)
          );
          if (previousIterationMessageContent)
            logDebug(`Iteration message:\n${previousIterationMessageContent}\n`);
          console.log(`\n ===== Iteration #${callCount + 1} =====\n`);
          if (callCount > 0) {
            if (previousIterationMessageContent.includes("TASK_COMPLETED")) {
              const isDevServerAppMessage = network.state.results.map((result) => extractTextMessageContent(result)).find((messageContent) =>
                messageContent.includes("DEV_SERVER_PORT")
              );
              if (isDevServerAppMessage) {
                const portMatch = isDevServerAppMessage.match(
                  /DEV_SERVER_PORT=([0-9]+)/
                );
                const port =
                  portMatch && portMatch[1]
                    ? parseInt(portMatch[1], 10)
                    : undefined;
                if (port) network.state.data.devServerPort = port;
              }
              return;
            }
          }
          return codingAgent;
        },
    });
    ```
  </Step>
</Steps>

<Tip>
  For a more comprehensive guide on using this coding agent, check out the [Daytona documentation](https://www.daytona.io/docs/en/inngest-agentkit-coding-agent/)
</Tip>

## Examples

<CardGroup>
  <Card title="Coding Agent powered by Daytona infrastructure" href="https://github.com/inngest/agent-kit/tree/main/examples/daytona-coding-agent#readme" icon="github">
    This AgentKit example uses Daytona to build a fully autonomous coding agent that performs software development tasks

    <span>Agents</span>
    <span>Tools</span>
    <span>Network</span>
    <span>State</span>
    <span>Integrations</span>
    <span>Code-based Router</span>
  </Card>
</CardGroup>


# Using AgentKit with E2B
Source: https://agentkit.inngest.com/integrations/e2b

Develop Coding Agents using E2B Sandboxes as tools

[E2B](https://e2b.dev) is an open-source runtime for executing AI-generated code in secure cloud sandboxes. Made for agentic & AI use cases.

E2B is a perfect fit to build Coding Agents that can write code, fix bugs, and more.

## Setup

<Steps>
  <Step title="Install AgentKit and E2B">
    Within an existing project, Install AgentKit and E2B from npm:

    <CodeGroup>
      ```shell npm theme={"system"}
      npm install @inngest/agent-kit inngest @e2b/code-interpreter
      ```

      ```shell pnpm theme={"system"}
      pnpm install @inngest/agent-kit inngest @e2b/code-interpreter
      ```

      ```shell yarn theme={"system"}
      yarn add @inngest/agent-kit inngest @e2b/code-interpreter
      ```
    </CodeGroup>

    <br />

    <Accordion title="Don't have an existing project?">
      To create a new project, create a new directory then initialize using your package manager:

      <CodeGroup>
        ```shell npm theme={"system"}
        mkdir my-agent-kit-project && npm init
        ```

        ```shell pnpm theme={"system"}
        mkdir my-agent-kit-project && pnpm init
        ```

        ```shell yarn theme={"system"}
        mkdir my-agent-kit-project && yarn init
        ```
      </CodeGroup>
    </Accordion>
  </Step>

  <Step title="Setup your Coding Agent">
    Create a Agent and its associated Network:

    ```typescript theme={"system"}
    import {
      createAgent,
      createNetwork,
      anthropic
    } from "@inngest/agent-kit";

    const agent = createAgent({
      name: "Coding Agent",
      description: "An expert coding agent",
      system: `You are a coding agent help the user to achieve the described task.

      Once the task completed, you should return the following information:
      <task_summary>
      </task_summary>

      Think step-by-step before you start the task.
      `,
      model: anthropic({
        model: "claude-3-5-sonnet-latest",
        max_tokens: 4096,
      }),
    });

    const network = createNetwork({
      name: "Coding Network",
      agents: [agent],
      defaultModel: anthropic({
        model: "claude-3-5-sonnet-20240620",
        maxTokens: 1000,
      })
    });

    ```
  </Step>

  <Step title="Create the E2B Tools">
    To operate, our Coding Agent will need to create files and run commands.

    Below is an example of how to create the `createOrUpdateFiles` and `terminal` E2B tools:

    ```typescript {5, 23-79} theme={"system"}
    import {
      createAgent,
      createNetwork,
      anthropic,
      createTool
    } from "@inngest/agent-kit";

    const agent = createAgent({
      name: "Coding Agent",
      description: "An expert coding agent",
      system: `You are a coding agent help the user to achieve the described task.

      Once the task completed, you should return the following information:
      <task_summary>
      </task_summary>

      Think step-by-step before you start the task.
      `,
      model: anthropic({
        model: "claude-3-5-sonnet-latest",
        max_tokens: 4096,
      }),
      tools: [
        // terminal use
        createTool({
          name: "terminal",
          description: "Use the terminal to run commands",
          parameters: z.object({
            command: z.string(),
          }),
          handler: async ({ command }, { network }) => {
            const buffers = { stdout: "", stderr: "" };

            try {
              const sandbox = await getSandbox(network);
              const result = await sandbox.commands.run(command, {
                onStdout: (data: string) => {
                  buffers.stdout += data;
                },
                onStderr: (data: string) => {
                  buffers.stderr += data;
                },
              });
              return result.stdout;
            } catch (e) {
              console.error(
                `Command failed: ${e} \nstdout: ${buffers.stdout}\nstderr: ${buffers.stderr}`
              );
              return `Command failed: ${e} \nstdout: ${buffers.stdout}\nstderr: ${buffers.stderr}`;
            }
          },
        }),
        // create or update file
        createTool({
          name: "createOrUpdateFiles",
          description: "Create or update files in the sandbox",
          parameters: z.object({
            files: z.array(
              z.object({
                path: z.string(),
                content: z.string(),
              })
            ),
          }),
          handler: async ({ files }, { network }) => {
            try {
              const sandbox = await getSandbox(network);
              for (const file of files) {
                await sandbox.files.write(file.path, file.content);
              }
              return `Files created or updated: ${files
                .map((f) => f.path)
                .join(", ")}`;
            } catch (e) {
              return "Error: " + e;
            }
          },
        }),
      ]
    });

    const network = createNetwork({
      name: "Coding Network",
      agents: [agent],
      defaultModel: anthropic({
        model: "claude-3-5-sonnet-20240620",
        maxTokens: 1000,
      })
    });

    ```

    You will find the complete example in the [E2B Coding Agent example](https://github.com/inngest/agent-kit/tree/main/examples/e2b-coding-agent#readme).

    <Tip>
      **Designing useful tools**

      As covered in Anthropic's ["Tips for Building AI Agents"](https://www.youtube.com/watch?v=LP5OCa20Zpg),
      the best Agents Tools are the ones that you will need to accomplish the task by yourself.

      Do not map tools directly to the underlying API, but rather design tools that are useful for the Agent to accomplish the task.
    </Tip>
  </Step>
</Steps>

## Examples

<CardGroup>
  <Card title="Replicate Cursor's Agent mode" href="https://github.com/inngest/agent-kit/tree/main/examples/e2b-coding-agent#readme" icon="github">
    This examples shows how to use E2B sandboxes to build a coding agent that can write code and run commands to generate complete project, complete refactoring and fix bugs.

    <br />

    <span>Agents</span>
    <span>Tools</span>
    <span>Network</span>
    <span>Integrations</span>

    <br />

    <span>Code-based Router</span>
  </Card>

  <Card title="AI-powered CSV contacts importer" href="https://github.com/inngest/agent-kit/tree/main/examples/e2b-csv-contacts-importer#readme" icon="github">
    Let's reinvent the CSV upload UX with an AgentKit network leveraging E2B sandboxes.

    <br />

    <span>Agents</span>
    <span>Tools</span>
    <span>Network</span>
    <span>Integrations</span>

    <br />

    <span>Code-based Router</span>
  </Card>
</CardGroup>


# Smithery - MCP Registry
Source: https://agentkit.inngest.com/integrations/smithery

Provide your Agents with hundred of prebuilt tools to interact with

[Smithery](https://smithery.ai/) is an MCP ([Model Context Protocol](https://modelcontextprotocol.io/introduction)) servers registry, listing more than 2,000 MCP servers across multiple use cases:

* Code related tasks (ex: GitHub, [E2B](/integrations/e2b))
* Web Search Integration (ex: Brave, [Browserbase](/integrations/browserbase))
* Database Integration (ex: Neon, Supabase)
* Financial Market Data
* Data & App Analysis
* And more...

## Adding a Smithery MCP Server to your Agent

<Steps>
  <Step title="Install AgentKit">
    Within an existing project, install AgentKit along with the Smithery SDK:

    <CodeGroup>
      ```shell npm theme={"system"}
      npm install @inngest/agent-kit inngest @smithery/sdk
      ```

      ```shell pnpm theme={"system"}
      pnpm install @inngest/agent-kit inngest @smithery/sdk
      ```

      ```shell yarn theme={"system"}
      yarn add @inngest/agent-kit inngest @smithery/sdk
      ```
    </CodeGroup>

    <Accordion title="Don't have an existing project?">
      To create a new project, create a new directory then initialize using your package manager:

      <CodeGroup>
        ```shell npm theme={"system"}
        mkdir my-agent-kit-project && npm init
        ```

        ```shell pnpm theme={"system"}
        mkdir my-agent-kit-project && pnpm init
        ```

        ```shell yarn theme={"system"}
        mkdir my-agent-kit-project && yarn init
        ```
      </CodeGroup>
    </Accordion>
  </Step>

  <Step title="2. Setup an AgentKit Newtork with an Agent">
    Create an Agent and its associated Network, for example a Neon Assistant Agent:

    ```typescript theme={"system"}
    import { z } from "zod";
    import {
      anthropic,
      createAgent,
      createNetwork,
      createTool,
    } from "@inngest/agent-kit";

    const neonAgent = createAgent({
      name: "neon-agent",
      system: `You are a helpful assistant that help manage a Neon account.
      IMPORTANT: Call the 'done' tool when the question is answered.
      `,
      tools: [
        createTool({
          name: "done",
          description: "Call this tool when you are finished with the task.",
          parameters: z.object({
            answer: z.string().describe("Answer to the user's question."),
          }),
          handler: async ({ answer }, { network }) => {
            network?.state.kv.set("answer", answer);
          },
        }),
      ],
    });

    const neonAgentNetwork = createNetwork({
      name: "neon-agent",
      agents: [neonAgent],
      defaultModel: anthropic({
        model: "claude-3-5-sonnet-20240620",
        defaultParameters: {
          max_tokens: 1000,
        },
      }),
      router: ({ network }) => {
        if (!network?.state.kv.get("answer")) {
          return neonAgent;
        }
        return;
      },
    });
    ```
  </Step>

  <Step title="Add the Neon MCP Smithery Server to your Agent">
    Add the [Neon MCP Smithery Server](https://smithery.ai/server/neon/) to your Agent by using `createSmitheryUrl()` from the `@smithery/sdk/config.js` module
    and providing it to the Agent via the `mcpServers` option:

    ```typescript {7, 10-12, 31-39} theme={"system"}
    import {
      anthropic,
      createAgent,
      createNetwork,
      createTool,
    } from "@inngest/agent-kit";
    import { createSmitheryUrl } from "@smithery/sdk/config.js";
    import { z } from "zod";

    const smitheryUrl = createSmitheryUrl("https://server.smithery.ai/neon/ws", {
      neonApiKey: process.env.NEON_API_KEY,
    });

    const neonAgent = createAgent({
      name: "neon-agent",
      system: `You are a helpful assistant that help manage a Neon account.
      IMPORTANT: Call the 'done' tool when the question is answered.
      `,
      tools: [
        createTool({
          name: "done",
          description: "Call this tool when you are finished with the task.",
          parameters: z.object({
            answer: z.string().describe("Answer to the user's question."),
          }),
          handler: async ({ answer }, { network }) => {
            network?.state.kv.set("answer", answer);
          },
        }),
      ],
      mcpServers: [
        {
          name: "neon",
          transport: {
            type: "ws",
            url: smitheryUrl.toString(),
          },
        },
      ],
    });

    const neonAgentNetwork = createNetwork({
      name: "neon-agent",
      agents: [neonAgent],
      defaultModel: anthropic({
        model: "claude-3-5-sonnet-20240620",
        defaultParameters: {
          max_tokens: 1000,
        },
      }),
      router: ({ network }) => {
        if (!network?.state.kv.get("answer")) {
          return neonAgent;
        }
        return;
      },
    });
    ```

    <Warning>
      Integrating Smithery with AgentKit requires using the `createSmitheryUrl()` function to create a valid URL for the MCP server.

      Most Smithery servers instruct to use the `createTransport()` function which is not supported by AgentKit.
      To use the `createSmitheryUrl()` function, simply append `/ws` to the end of the Smithery server URL provided by Smithery.
    </Warning>
  </Step>
</Steps>

You will find the complete example on GitHub:

<Card title="Neon Assistant Agent (using MCP)" href="https://github.com/inngest/agent-kit/tree/main/examples/mcp-neon-agent/#readme" icon="github">
  This examples shows how to use the [Neon MCP Smithery Server](https://smithery.ai/server/neon/) to build a Neon Assistant Agent that can help you manage your Neon databases.

  <br />

  <span>
    Agents
  </span>

  <span>
    Tools
  </span>

  <span>
    Network
  </span>

  <span>
    Integrations
  </span>

  <br />

  <span>
    Code-based Router
  </span>
</Card>


# AgentKit
Source: https://agentkit.inngest.com/overview

A TypeScript library to create and orchestrate AI Agents.

AgentKit is a framework to build AI Agents, from single model inference calls to multi-agent systems that use tools. Designed with orchestration at its core, AgentKit enables developers to build, test, and deploy reliable AI applications at scale.

With AgentKit, you get:

✨ **Simple and composable primitives** to build from simple Support Agents to semi-autonomous Coding Agents.

🧠 **Support for [OpenAI, Anthropic, Gemini](/concepts/models)** and all OpenAI API compatible models.

🛠️ **Powerful tools building API** with support for [MCP as tools](/advanced-patterns/mcp).

🔌 **Integrates** with your favorite AI libraries and products (ex: [E2B](/integrations/e2b), [Browserbase](/integrations/browserbase), [Smithery](/integrations/smithery), [Daytona](/integrations/daytona)).

⚡ **Stream live updates** to your UI with [UI Streaming](/advanced-patterns/legacy-ui-streaming).

📊 **[Local Live traces](/getting-started/local-development) and input/output logs** when combined with the Inngest Dev Server.

<br />

New to AI Agents? Follow our [Guided Tour](/guided-tour/overview) to learn how to build your first AgentKit application.

All the above sounds familiar? Check our **[Getting started section](#getting-started)** or the **["How AgentKit works" section](#how-agentkit-works)** to learn more about AgentKit's architecture.

## Getting started

<CardGroup>
  <Card title="Quick start" href="/getting-started/quick-start">
    Jump into the action by building your first AgentKit application.
  </Card>

  <Card title="Examples" href="/examples/overview">
    Looking for inspiration? Check out our examples to see how AgentKit can be
    used.
  </Card>

  <Card title="Concepts" href="/concepts/agents">
    Learn the core concepts of AgentKit.
  </Card>

  <Card title="SDK Reference" href="/reference/introduction">
    Ready to dive into the code? Browse the SDK reference to learn more about
    AgentKit's primitives.
  </Card>
</CardGroup>

## How AgentKit works

<div>
  <div>
    AgentKit enables developers to compose simple single-agent systems or entire
    *systems of agents* in which multiple agents can work together.
    **[Agents](/concepts/agents)** are combined into
    **[Networks](concepts/networks)** which include a
    **[Router](concepts/routers)** to determine which Agent should be called.
    Their system's memory is recorded as Network **[State](concepts/state)** which
    can be used by the Router, Agents or **[Tools](concepts/tools)** to
    collaborate on tasks.
  </div>

  <div>
    <Frame>
      <img
        alt="A diagram with the components of AgentKit in an AgentKit
Network"
      />
    </Frame>
  </div>
</div>

The entire system is orchestration-aware and allows for customization at runtime for dynamic, powerful AI workflows and agentic systems. Here is what a simple Network looks like in code:

```ts theme={"system"}
import {
  createNetwork,
  createAgent,
  openai,
  anthropic,
} from "@inngest/agent-kit";
import { searchWebTool } from "./tools";

const navigator = createAgent({
  name: "Navigator",
  system: "You are a navigator...",
  tools: [searchWebTool],
});

const classifier = createAgent({
  name: "Classifier",
  system: "You are a classifier...",
  model: openai("gpt-3.5-turbo"),
});

const summarizer = createAgent({
  model: anthropic("claude-3-5-haiku-latest"),
  name: "Summarizer",
  system: "You are a summarizer...",
});

const network = createNetwork({
  agents: [navigator, classifier, summarizer],
  defaultModel: openai({ model: "gpt-4o" }),
});

const input = `Classify then summarize the latest 10 blog posts
  on https://www.deeplearning.ai/blog/`;

const result = await network.run(input, ({ network }) => {
  return defaultRoutingAgent;
});
```

## `llms.txt`

You can access the entire AgentKit docs in markdown format at [agentkit.inngest.com/llms-full.txt](https://agentkit.inngest.com/llms-full.txt). This is useful for passing the entire docs to an LLM, AI-enabled IDE, or similar tool to answer questions about AgentKit.

If your context window is too small to pass the entire docs, you can use the shorter [agentkit.inngest.com/llms.txt](https://agentkit.inngest.com/llms.txt) file which offers a table of contents for LLMs or other developer tools to index the docs more easily.


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

Define an agent

Agents are defined using the `createAgent` function.

```ts theme={"system"}
import { createAgent, agenticOpenai as openai } from '@inngest/agent-kit';

const agent = createAgent({
  name: 'Code writer',
  system:
    'You are an expert TypeScript programmer.  Given a set of asks, you think step-by-step to plan clean, ' +
    'idiomatic TypeScript code, with comments and tests as necessary.' +
    'Do not respond with anything else other than the following XML tags:' +
    '- If you would like to write code, add all code within the following tags (replace $filename and $contents appropriately):' +
    "  <file name='$filename.ts'>$contents</file>",
  model: openai('gpt-4o-mini'),
});
```

## Options

<ParamField type="string">
  The name of the agent. Displayed in tracing.
</ParamField>

<ParamField type="string">
  Optional description for the agent, used for LLM-based routing to help the
  network pick which agent to run next.
</ParamField>

<ParamField type="string">
  The provider model to use for inference calls.
</ParamField>

<ParamField type="string | function">
  The system prompt, as a string or function. Functions let you change prompts
  based off of state and memory.
</ParamField>

<ParamField type="array<TypedTool>">
  Defined tools that an agent can call.

  Tools are created via [`createTool`](/reference/createTool).
</ParamField>

<ParamField type="Lifecycle">
  Lifecycle hooks that can intercept and modify inputs and outputs throughout the stages of execution of `run()`.

  Learn about each [lifecycle](#lifecycle) hook that can be defined below.
</ParamField>

### `lifecycle`

<ParamField type="function">
  Called after the initial prompt messages are created and before the inference call request. The `onStart` hook can be used to:

  * Modify input prompt for the Agent.
  * Prevent the agent from being called by throwing an error.
</ParamField>

<ParamField type="function">
  Called after the inference call request is completed and before tool calling. The `onResponse` hook can be used to:

  * Inspect the tools that the model decided to call.
  * Modify the response prior to tool calling.
</ParamField>

<ParamField type="function">
  Called after tool calling has completed. The `onFinish` hook can be used to:

  * Modify the `InferenceResult` including the outputs prior to the result being added to [Network state](/concepts/network-state).
</ParamField>

<CodeGroup>
  ```ts onStart theme={"system"}
  const agent = createAgent({
    name: 'Code writer',
    lifecycles: {
      onStart: ({
        agent,
        network,
        input,
        system, // The system prompt for the agent
        history, // An array of messages
      }) => {
        // Return the system prompt (the first message), and any history added to the
        // model's conversation.
        return { system, history };
      },
    },
  });
  ```

  ```ts onResponse theme={"system"}
  function onResponse() {}
  ```
</CodeGroup>


# createNetwork
Source: https://agentkit.inngest.com/reference/create-network

Define a network

Networks are defined using the `createNetwork` function.

```ts theme={"system"}
import { createNetwork, openai } from '@inngest/agent-kit';

// Create a network with two agents
const network = createNetwork({
  agents: [searchAgent, summaryAgent],
  defaultModel: openai({ model: 'gpt-4o', step }),
  maxIter: 10,
});
```

## Options

<ParamField type="array<Agent>">
  Agents that can be called from within the `Network`.
</ParamField>

<ParamField type="string">
  The provider model to use for routing inference calls.
</ParamField>

<ParamField type="string">
  The system prompt, as a string or function. Functions let you change prompts
  based off of state and memory
</ParamField>

<ParamField type="array<TypedTool>">
  Defined tools that an agent can call.

  Tools are created via [`createTool`](/reference/createTool).
</ParamField>


# createTool
Source: https://agentkit.inngest.com/reference/create-tool

Provide tools to an agent

Tools are defined using the `createTool` function.

```ts theme={"system"}
import { createTool } from '@inngest/agent-kit';

const tool = createTool({
  name: 'write-file',
  description: 'Write a file to disk with the given contents',
  parameters: {
    type: 'object',
    properties: {
      path: {
        type: 'string',
        description: 'The path to write the file to',
      },
      contents: {
        type: 'string',
        description: 'The contents to write to the file',
      },
    },
    required: ['path', 'contents'],
  },
  handler: async ({ path, contents }, { agent, network }) => {
    await fs.writeFile(path, contents);
    return { success: true };
  },
});
```

## Options

<ParamField type="string">
  The name of the tool. Used by the model to identify which tool to call.
</ParamField>

<ParamField type="string">
  A clear description of what the tool does. This helps the model understand when and how to use the tool.
</ParamField>

<ParamField type="JSONSchema | ZodType">
  A JSON Schema object or Zod type that defines the parameters the tool accepts. This is used to validate the model's inputs and provide type safety.
</ParamField>

<ParamField type="function">
  The function that executes when the tool is called. It receives the validated parameters as its first argument and a context object as its second argument.
</ParamField>

<ParamField type="boolean">
  Option to disable strict validation of the tool parameters.
</ParamField>

<ParamField type="Lifecycle">
  Lifecycle hooks that can intercept and modify inputs and outputs throughout the stages of tool execution.
</ParamField>

### Handler Function

The handler function receives two arguments:

1. `input`: The validated parameters matching your schema definition
2. `context`: An object containing:
   * `agent`: The Agent instance that called the tool
   * `network`: The network instance, providing access to the [`network.state`](/reference/state).

Example handler with full type annotations:

```ts theme={"system"}
import { createTool } from '@inngest/agent-kit';

const tool = createTool({
  name: 'write-file',
  description: 'Write a file to disk with the given contents',
  parameters: {
    type: 'object',
    properties: {
      path: { type: 'string' },
      contents: { type: 'string' },
    },
  },
  handler: async ({ path, contents }, { agent, network }) => {
    await fs.writeFile(path, contents);
    network.state.fileWritten = true;
    return { success: true };
  },
});
```

### `lifecycle`

<ParamField type="function">
  Called before the tool handler is executed. The `onStart` hook can be used to:

  * Modify input parameters before they are passed to the handler
  * Prevent the tool from being called by throwing an error
</ParamField>

<ParamField type="function">
  Called after the tool handler has completed. The `onFinish` hook can be used to:

  * Modify the result before it is returned to the agent
  * Perform cleanup operations
</ParamField>

<CodeGroup>
  ```ts onStart theme={"system"}
  const tool = createTool({
    name: 'write-file',
    lifecycle: {
      onStart: ({ parameters }) => {
        // Validate or modify parameters before execution
        return parameters;
      },
    },
  });
  ```

  ```ts onFinish theme={"system"}
  const tool = createTool({
    name: 'write-file',
    lifecycle: {
      onFinish: ({ result }) => {
        // Modify or enhance the result
        return result;
      },
    },
  });
  ```
</CodeGroup>


# Introduction
Source: https://agentkit.inngest.com/reference/introduction

SDK Reference

## Overview

The Inngest Agent Kit is a TypeScript library is divided into two main parts:

<CardGroup>
  <Card title="Agent APIs" href="/reference/create-agent" icon="head-side-gear">
    All the APIs for creating and configuring agents and tools.
  </Card>

  <Card title="Network APIs" href="/reference/create-network" icon="chart-network">
    All the APIs for creating and configuring networks and routers.
  </Card>
</CardGroup>


# Anthropic Model
Source: https://agentkit.inngest.com/reference/model-anthropic

Configure Anthropic as your model provider

The `anthropic` function configures Anthropic's Claude as your model provider.

```ts theme={"system"}
import { createAgent, anthropic } from "@inngest/agent-kit";

const agent = createAgent({
  name: "Code writer",
  system: "You are an expert TypeScript programmer.",
  model: anthropic({
    model: "claude-3-opus",
    // Note: max_tokens is required for Anthropic models
    defaultParameters: { max_tokens: 4096 },
  }),
});
```

## Configuration

The `anthropic` function accepts a model name string or a configuration object:

```ts theme={"system"}
const agent = createAgent({
  model: anthropic({
    model: "claude-3-opus",
    apiKey: process.env.ANTHROPIC_API_KEY,
    baseUrl: "https://api.anthropic.com/v1/",
    betaHeaders: ["computer-vision"],
    defaultParameters: { temperature: 0.5, max_tokens: 4096 },
  }),
});
```

<Warning>**Note: `defaultParameters.max_tokens` is required.**</Warning>

### Options

<ParamField type="string">
  ID of the model to use. See the [model endpoint
  compatibility](https://docs.anthropic.com/en/docs/about-claude/models) table
  for details on which models work with the Anthropic API.
</ParamField>

<ParamField type="number">
  **This option has been moved to the `defaultParameters` option.**

  <br />

  The maximum number of tokens to generate before stopping.
</ParamField>

<ParamField type="string">
  The Anthropic API key to use for authenticating your request. By default we'll
  search for and use the `ANTHROPIC_API_KEY` environment variable.
</ParamField>

<ParamField type="string[]">
  The beta headers to enable, eg. for computer use, prompt caching, and so on.
</ParamField>

<ParamField type="string">
  The base URL for the Anthropic API.
</ParamField>

<ParamField type="object">
  The default parameters to use for the model (ex: `temperature`, `max_tokens`,
  etc).

  <br />

  **Note: `defaultParameters.max_tokens` is required.**
</ParamField>

### Available Models

```plaintext Anthropic theme={"system"}
"claude-3-5-haiku-latest"
"claude-3-5-haiku-20241022"
"claude-3-5-sonnet-latest"
"claude-3-5-sonnet-20241022"
"claude-3-5-sonnet-20240620"
"claude-3-opus-latest"
"claude-3-opus-20240229"
"claude-3-sonnet-20240229"
"claude-3-haiku-20240307"
"claude-2.1"
"claude-2.0"
"claude-instant-1.2"
```


# Gemini Model
Source: https://agentkit.inngest.com/reference/model-gemini

Configure Google Gemini as your model provider

The `gemini` function configures Google's Gemini as your model provider.

```ts theme={"system"}
import { createAgent, gemini } from "@inngest/agent-kit";

const agent = createAgent({
  name: "Code writer",
  system: "You are an expert TypeScript programmer.",
  model: gemini({ model: "gemini-pro" }),
});
```

## Configuration

The `gemini` function accepts a model name string or a configuration object:

```ts theme={"system"}
const agent = createAgent({
  model: gemini({
    model: "gemini-pro",
    apiKey: process.env.GOOGLE_API_KEY,
    baseUrl: "https://generativelanguage.googleapis.com/v1/",
    defaultParameters: {
      generationConfig: {
        temperature: 1.5,
      },
    },
  }),
});
```

### Options

<ParamField type="string">
  ID of the model to use. See the [model endpoint
  compatibility](https://cloud.google.com/vertex-ai/docs/generative-ai/model-reference/gemini)
  table for details on which models work with the Gemini API.
</ParamField>

<ParamField type="string">
  The Google API key to use for authenticating your request. By default we'll
  search for and use the `GOOGLE_API_KEY` environment variable.
</ParamField>

<ParamField type="string">
  The base URL for the Gemini API.
</ParamField>

<ParamField type="object">
  The default parameters to use for the model.

  See Gemini's [`models.generateContent` reference](https://ai.google.dev/api/generate-content#method:-models.generatecontent).
</ParamField>

### Available Models

```plaintext Gemini theme={"system"}
"gemini-1.5-flash"
"gemini-1.5-flash-8b"
"gemini-1.5-pro"
"gemini-1.0-pro"
"text-embedding-004"
"aqa"
```

For the latest list of available models, see [Google's Gemini model overview](https://cloud.google.com/vertex-ai/docs/generative-ai/model-reference/gemini).

## Limitations

Gemini models do not currently support function without parameters.


# Grok Model
Source: https://agentkit.inngest.com/reference/model-grok

Configure Grok as your model provider

The `grok` function configures Grok as your model provider.

```ts theme={"system"}
import { createAgent, grok } from "@inngest/agent-kit";

const agent = createAgent({
  name: "Code writer",
  system: "You are an expert TypeScript programmer.",
  model: grok({ model: "grok-4-latest" }),
});
```

## Configuration

The `grok` function accepts a model name string or a configuration object:

```ts theme={"system"}
const agent = createAgent({
  model: grok({
    model: "grok-4-latest",
    apiKey: process.env.XAI_API_KEY,
    baseUrl: "https://api.x.ai/v1",
    defaultParameters: { temperature: 0.5 },
  }),
});
```

### Options

<ParamField type="string">
  ID of the model to use.

  See the [xAI models list](https://docs.x.ai/docs/models).
</ParamField>

<ParamField type="string">
  The xAI API key to use for authenticating your request. By default we'll
  search for and use the `XAI_API_KEY` environment variable.
</ParamField>

<ParamField type="string">
  The base URL for the xAI API.
</ParamField>

<ParamField type="object">
  The default parameters to use for the model (ex: `temperature`, `max_tokens`,
  etc).
</ParamField>

### Available Models

```plaintext Gemini theme={"system"}
"grok-2-1212"
"grok-2"
"grok-2-latest"
"grok-3"
"grok-3-latest"
"grok-4"
"grok-4-latest";
```

For the latest list of available models, see [xAI's Grok model overview](https://docs.x.ai/docs/models).

## Limitations

Grok models do not currently support strict function parameters.


# OpenAI Model
Source: https://agentkit.inngest.com/reference/model-openai

Configure OpenAI as your model provider

The `openai` function configures OpenAI as your model provider.

```ts theme={"system"}
import { createAgent, openai } from "@inngest/agent-kit";

const agent = createAgent({
  name: "Code writer",
  system: "You are an expert TypeScript programmer.",
  model: openai({ model: "gpt-4" }),
});
```

## Configuration

The `openai` function accepts a model name string or a configuration object:

```ts theme={"system"}
const agent = createAgent({
  model: openai({
    model: "gpt-4",
    apiKey: process.env.OPENAI_API_KEY,
    baseUrl: "https://api.openai.com/v1/",
    defaultParameters: { temperature: 0.5 },
  }),
});
```

### Options

<ParamField type="string">
  ID of the model to use. See the [model endpoint
  compatibility](https://platform.openai.com/docs/models#model-endpoint-compatibility)
  table for details on which models work with the Chat API.
</ParamField>

<ParamField type="string">
  The OpenAI API key to use for authenticating your request. By default we'll
  search for and use the `OPENAI_API_KEY` environment variable.
</ParamField>

<ParamField type="string">
  The base URL for the OpenAI API.
</ParamField>

<ParamField type="object">
  The default parameters to use for the model (ex: `temperature`, `max_tokens`,
  etc).
</ParamField>

### Available Models

```plaintext OpenAI theme={"system"}
"gpt-4o"
"chatgpt-4o-latest"
"gpt-4o-mini"
"gpt-4"
"o1-preview"
"o1-mini"
"gpt-3.5-turbo"
```


# Network Router
Source: https://agentkit.inngest.com/reference/network-router

Controlling the flow of execution between agents in a Network.

The `defaultRouter` option in `createNetwork` defines how agents are coordinated within a Network. It can be either a [Function Router](#function-router) or a [Routing Agent](#routing-agent).

## Function Router

A function router is provided to the `defaultRouter` option in `createNetwork`.

### Example

```ts theme={"system"}
const network = createNetwork({
  agents: [classifier, writer],
  router: ({ lastResult, callCount, network, stack, input }) => {
    // First call: use the classifier
    if (callCount === 0) {
      return classifier;
    }

    // Get the last message from the output
    const lastMessage = lastResult?.output[lastResult?.output.length - 1];
    const content =
      lastMessage?.type === "text" ? (lastMessage?.content as string) : "";

    // Second call: if it's a question, use the writer
    if (callCount === 1 && content.includes("question")) {
      return writer;
    }

    // Otherwise, we're done!
    return undefined;
  },
});
```

### Parameters

<ParamField type="string">
  The original input provided to the network.
</ParamField>

<ParamField type="Network">
  The network instance, including its state and history.

  See [`Network.State`](/reference/state) for more details.
</ParamField>

<ParamField type="Agent[]">
  The list of future agents to be called. (*internal read-only value*)
</ParamField>

<ParamField type="number">
  The number of agent calls that have been made.
</ParamField>

<ParamField type="InferenceResult">
  The result from the previously called agent.

  See [`InferenceResult`](/reference/state#inferenceresult) for more details.
</ParamField>

### Return Values

| Return Type    | Description                                        |
| -------------- | -------------------------------------------------- |
| `Agent`        | Single agent to execute next                       |
| `Agent[]`      | Multiple agents to execute in sequence             |
| `RoutingAgent` | Delegate routing decision to another routing agent |
| `undefined`    | Stop network execution                             |

## createRoutingAgent()

Creates a new routing agent that can be used as a `defaultRouter` in a network.

### Example

```ts theme={"system"}
import { createRoutingAgent, createNetwork } from "@inngest/agent-kit";

const routingAgent = createRoutingAgent({
  name: "Custom routing agent",
  description: "Selects agents based on the current state and request",
  lifecycle: {
    onRoute: ({ result, network }) => {
      // Get the agent names from the result
      const agentNames = result.output
        .filter((m) => m.type === "text")
        .map((m) => m.content as string);

      // Validate that the agents exist
      return agentNames.filter((name) => network.agents.has(name));
    },
  },
});

// classifier and writer Agents definition...

const network = createNetwork({
  agents: [classifier, writer],
  router: routingAgent,
});
```

### Parameters

<ParamField type="string">
  The name of the routing agent.
</ParamField>

<ParamField type="string">
  Optional description of the routing agent's purpose.
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="function">
      Called after each inference to determine the next agent(s) to call.

      **Arguments:**

      ```ts theme={"system"}
      {
        result: InferenceResult;  // The result from the routing agent's inference
        agent: RoutingAgent;      // The routing agent instance
        network: Network;         // The network instance
      }
      ```

      **Returns:** `string[]` - Array of agent names to call next, or `undefined` to stop execution
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="AiAdapter.Any">
  Optional model to use for routing decisions. If not provided, uses the
  network's `defaultModel`.
</ParamField>

### Returns

Returns a `RoutingAgent` instance that can be used as a network's `defaultRouter`.

## Related APIs

* [`createNetwork`](/reference/create-network)
* [`Network.State`](/reference/state)


# createState
Source: https://agentkit.inngest.com/reference/state

Leverage a Network's State across Routers and Agents.

The `State` class provides a way to manage state and history across a network of agents. It includes key-value storage and maintains a stack of all agent interactions.

The `State` is accessible to all Agents, Tools and Routers as a `state` or `network.state` property.

## Creating State

```ts theme={"system"}
import { createState } from '@inngest/agent-kit';

export interface NetworkState {
  // username is undefined until extracted and set by a tool
  username?: string;
}

const state = createState<NetworkState>({
  username: 'bar',
});

console.log(state.data.username); // 'bar'


const network = createNetwork({
  // ...
});

// Pass in state to each run
network.run("<query>", { state })
```

## Reading and Modifying State's data (`state.data`)

The `State` class provides typed data accesible via the `data` property.

<Info>
  Learn more about the State use cases in the [State](/docs/concepts/state) concept guide.
</Info>

<ParamField type="object<T>">
  A standard, mutable object which can be updated and modified within tools.
</ParamField>

## State History

The State history is passed as a `history` to the lifecycle hooks and via the `network` argument to the Tools handlers to the Router function.

The State history can be retrieved *- as a copy -* using the `state.results` property composed of `InferenceResult` objects:

## InferenceResult

The `InferenceResult` class represents a single agent call as part of the network state. It stores all inputs and outputs for a call.

<ParamField type="Agent">
  The agent responsible for this inference call.
</ParamField>

<ParamField type="string">
  The input passed into the agent's run method.
</ParamField>

<ParamField type="Message[]">
  The input instructions without additional history, including the system prompt, user input, and initial agent assistant message.
</ParamField>

<ParamField type="Message[]">
  The history sent to the inference call, appended to the prompt to form a complete conversation log.
</ParamField>

<ParamField type="Message[]">
  The parsed output from the inference call.
</ParamField>

<ParamField type="ToolResultMessage[]">
  Output from any tools called by the agent.
</ParamField>

<ParamField type="string">
  The raw API response from the call in JSON format.
</ParamField>

## `Message` Types

The state system uses several message types to represent different kinds of interactions:

```ts theme={"system"}
type Message = TextMessage | ToolCallMessage | ToolResultMessage;

interface TextMessage {
  type: "text";
  role: "system" | "user" | "assistant";
  content: string | Array<TextContent>;
  stop_reason?: "tool" | "stop";
}

interface ToolCallMessage {
  type: "tool_call";
  role: "user" | "assistant";
  tools: ToolMessage[];
  stop_reason: "tool";
}

interface ToolResultMessage {
  type: "tool_result";
  role: "tool_result";
  tool: ToolMessage;
  content: unknown;
  stop_reason: "tool";
}
```


# useAgent
Source: https://agentkit.inngest.com/reference/use-agent

React hook for building real-time, multi-threaded AI applications

The `useAgent` hook is the core of the `@inngest/use-agent` package. It's a comprehensive, client-side hook for React that manages real-time, multi-threaded conversations with an AgentKit network. It encapsulates the entire lifecycle of agent interactions, including sending messages, receiving streaming events, handling out-of-order event sequences, and managing connection state.

```tsx theme={"system"}
import { useAgent, AgentProvider } from '@inngest/use-agent';

function App() {
  return (
    <AgentProvider userId="user-123">
      <ChatComponent />
    </AgentProvider>
  );
}

function ChatComponent() {
  const { messages, sendMessage, status, currentThreadId, switchToThread } = useAgent();
  
  // UI to switch threads and display messages...
  
  return <ChatUI messages={messages} onSend={sendMessage} status={status} />;
}
```

## Configuration

The `useAgent` hook accepts a configuration object with the following properties.

### Identity & Connection

<ParamField type="string">
  A unique identifier for the current user. This is used for personalizing agent interactions and routing real-time events. If not provided, it will be inherited from the `AgentProvider`.
</ParamField>

<ParamField type="string">
  A key for targeting subscriptions, enabling collaborative sessions. If not provided, it defaults to the `userId`.
</ParamField>

<ParamField type="IClientTransport">
  An optional transport instance to override the default HTTP transport provided by `AgentProvider`. This allows you to customize how the hook communicates with your backend.
</ParamField>

### Initial State

<ParamField type="string">
  The ID of the conversation thread to load when the hook is first mounted.
</ParamField>

<ParamField type="() => TState">
  A function that returns the current client-side UI state. This state is captured and sent with each user message, allowing agents to have context about what the user is seeing. It can also be used to restore the UI when revisiting a message.
</ParamField>

### Data Fetching & Caching

<ParamField type="function">
  A function to fetch a paginated list of conversation threads for the user. If not provided, the hook uses the default transport method.
</ParamField>

<ParamField type="function">
  A function to fetch the message history for a specific thread. If not provided, the hook uses the default transport method.
</ParamField>

<ParamField type="number">
  The number of threads to fetch per page in pagination requests.
</ParamField>

### Callbacks

<ParamField type="(event, meta) => void">
  A low-level callback invoked for every real-time event processed by the hook. This is useful for building custom UI that reacts to specific agent activities, like showing a "thinking" indicator when a `run.started` event is received.
</ParamField>

<ParamField type="(args) => void">
  A callback fired when a terminal stream event (`stream.ended` or `run.completed`) is received for a thread, indicating the agent has finished its turn.
</ParamField>

<ParamField type="(result) => void">
  A strongly-typed callback that fires when a tool call completes and returns its final output. This is useful for observing or reacting to the data returned by agents' tools.
</ParamField>

<ParamField type="(state, messageId) => void">
  A callback invoked when `rehydrateMessageState` is called. It receives the client state that was captured when the original message was sent, allowing you to restore the UI to its previous state.
</ParamField>

<ParamField type="(threadId) => void">
  A callback that is triggered if `switchToThread` is called with a `threadId` that cannot be found.
</ParamField>

### Behavior

<ParamField type="boolean">
  Enables detailed logging to the console for debugging the hook's internal state and event flow.
</ParamField>

<ParamField type="boolean">
  If `true`, the hook will throw an error if it's not used within an `AgentProvider`. When `false`, it creates a local fallback instance.
</ParamField>

<ParamField type="boolean">
  If `true`, the hook will automatically re-fetch a thread's history if it detects a mismatch between the local message count and the server's message count, ensuring data consistency.
</ParamField>

## Return Values

The `useAgent` hook returns an object containing state and actions to manage conversations.

### Core Agent State

<ParamField type="ConversationMessage[]">
  An array of messages for the currently active thread. Each message contains structured parts that are updated in real-time as events are received.
</ParamField>

<ParamField type="AgentStatus">
  The current activity status of the agent for the active thread. Possible values are: `"ready"`, `"submitted"`, `"streaming"`, or `"error"`.
</ParamField>

<ParamField type="AgentError">
  An object containing details about the last error that occurred. It's `undefined` if there is no error.
</ParamField>

<ParamField type="() => void">
  A function to clear the current error state.
</ParamField>

<ParamField type="boolean">
  Returns `true` if the client is currently connected to the real-time event stream.
</ParamField>

### Core Actions

<ParamField type="(message, options) => Promise<void>">
  Sends a message to the currently active thread.
</ParamField>

<ParamField type="() => Promise<void>">
  Sends a request to the backend to cancel the current agent run for the active thread.
</ParamField>

<ParamField type="(toolCallId, reason) => Promise<void>">
  Approves a tool call that is awaiting human-in-the-loop (HITL) confirmation.
</ParamField>

<ParamField type="(toolCallId, reason) => Promise<void>">
  Denies a tool call that is awaiting human-in-the-loop (HITL) confirmation.
</ParamField>

### Thread Management State

<ParamField type="Thread[]">
  An array of all conversation threads loaded for the user.
</ParamField>

<ParamField type="string | null">
  The ID of the currently active thread.
</ParamField>

<ParamField type="boolean">
  `true` while the initial list of threads is being fetched.
</ParamField>

<ParamField type="boolean">
  `true` if there are more pages of threads to be loaded.
</ParamField>

<ParamField type="string | null">
  Contains an error message if fetching threads failed.
</ParamField>

<ParamField type="boolean">
  `true` only while the selected thread's history has not yet been loaded.
</ParamField>

### Thread Management Actions

<ParamField type="(threadId) => Promise<void>">
  Switches the active conversation to a different thread, loading its history.
</ParamField>

<ParamField type="(threadId) => void">
  Immediately changes the `currentThreadId` without fetching history. Useful for optimistic UI updates before `switchToThread` completes.
</ParamField>

<ParamField type="() => string">
  Creates a new, empty thread locally and returns its generated UUID.
</ParamField>

<ParamField type="(threadId) => Promise<void>">
  Deletes a thread from the backend and removes it from the local state.
</ParamField>

<ParamField type="() => Promise<void>">
  Fetches the next page of threads.
</ParamField>

<ParamField type="() => Promise<void>">
  Refetches the first page of threads to get the latest list.
</ParamField>

### Advanced Actions

<ParamField type="(threadId, message, options) => Promise<void>">
  Sends a message to a specific thread, which may not be the currently active one.
</ParamField>

<ParamField type="(threadId) => Promise<ConversationMessage[]>">
  Manually fetches the message history for a specific thread.
</ParamField>

<ParamField type="(threadId) => void">
  Clears all messages from a specific thread's local state.
</ParamField>

<ParamField type="(threadId, messages) => void">
  Replaces all messages in a specific thread's local state. Useful for manually populating history.
</ParamField>

<ParamField type="(messageId) => void">
  Triggers the `onStateRehydrate` callback with the client state associated with a specific message. Useful for UI features like "edit message" where you need to restore the UI to how it was when the message was sent.
</ParamField>


# Events
Source: https://agentkit.inngest.com/streaming/events



The `use-agent` hook is built on an event-driven architecture. Real-time events are streamed from the server, processed by a state reducer, and used to build the conversation UI incrementally. This document details the events, their purpose, and how you can use them.

## Understanding the Event Lifecycle

<Steps>
  <Step title="Raw Event Streaming">
    A raw message is received from the Inngest realtime websocket connection
  </Step>

  <Step title="Mapping">
    The raw message is passed to an internal `mapToNetworkEvent` function, which transforms it into a standardized, strongly-typed `AgentKitEvent`. Invalid or unrecognized messages are discarded.
  </Step>

  <Step title="Dispatch">
    The valid `AgentKitEvent` is dispatched to the internal `StreamingEngine`.
  </Step>

  <Step title="Reduction">
    The `streaming-reducer` processes the event. It uses a sequencing and buffering mechanism to ensure events are applied in the correct order, even if they arrive out of order.
  </Step>

  <Step title="State Update">
    The reducer applies the event to the state, creating or updating messages and their parts.
  </Step>

  <Step title="UI Render">
    Your React UI re-renders with the new state.
  </Step>

  <Step title="Callbacks">
    If configured, `onEvent`, `onStreamEnded`, or `onToolResult` callbacks are fired, allowing you to react to specific events.
  </Step>
</Steps>

## Core Events Reference

### Run Lifecycle Events

These events manage the overall state of an agent or network execution for a given turn.

#### `run.started`

* **Description**: Marks the beginning of an agent or network execution in response to a user message. This is often the first event in a sequence. It sets the agent's status to `submitted`.
* **Payload (`data`)**:
  * `threadId`: The ID of the thread this run belongs to.
  * `name`: The name of the agent or network that started.
  * `scope`: `"network"` or `"agent"`.
  * `runId`, `parentRunId`, `messageId`.
* **State Impact**: Sets `runActive: true`, `agentStatus: 'submitted'`, and may reset the event processing sequence if it's the start of a new "epoch".

#### `run.completed`

* **Description**: Indicates that an agent or network run has finished its logic. This does *not* mean all streaming is complete. It primarily finalizes any in-flight tool outputs.
* **Payload (`data`)**: `threadId`, `scope`, `runId`, `messageId`, `name`.
* **State Impact**: Finalizes the state of any tools that were in the `executing` state, moving them to `output-available`. The overall agent status is not yet changed to `ready`.

#### `stream.ended`

* **Description**: The final event in a sequence. It indicates that all streaming for a turn is complete and the agent is now idle.
* **Payload (`data`)**: `threadId`, `scope`, `runId`, `messageId`, `name`.
* **State Impact**: Sets `runActive: false` and `agentStatus: 'ready'`. This signals that the system is ready for new user input.

### Content Streaming Events

These events are responsible for building the assistant's response message part by part.

#### `part.created`

* **Description**: Signals the creation of a new part within an assistant message.
* **Payload (`data`)**:
  * `messageId`: The ID of the message this part belongs to.
  * `partId`: The unique ID for this new part.
  * `type`: Either `"text"` or `"tool-call"`.
  * `metadata`: Optional data, often includes `toolName` for tool calls.
* **State Impact**: Adds a new, empty `TextUIPart` or `ToolCallUIPart` to the parts array of the corresponding message.

#### `text.delta`

* **Description**: Streams a chunk of text for a `TextUIPart`.
* **Payload (`data`)**:
  * `messageId`, `partId`.
  * `delta`: The string of text to append.
* **State Impact**: Appends the `delta` content to the specified `TextUIPart`.

#### `part.completed`

* **Description**: Marks a specific message part as complete. The payload varies based on the part type.
* **Payload (`data`)**:
  * `messageId`, `partId`.
  * `type`: Can be `"text"`, `"tool-call"`, or `"tool-output"`.
  * `finalContent`: The complete, final content for the part (e.g., the full text or final tool output).
* **State Impact**:
  * For `"text"`: Sets the part's `status` to `complete`.
  * For `"tool-call"`: Sets the tool's `state` to `input-available` and populates the final `input`.
  * For `"tool-output"`: Sets the tool's `state` to `output-available` and populates the final `output`.

### Tool Call Events

These events are specific to the lifecycle of tool calls made by an agent.

#### `tool_call.arguments.delta`

* **Description**: Streams a chunk of the JSON arguments for a tool call.
* **Payload (`data`)**:
  * `messageId`, `partId`.
  * `delta`: A string chunk of the JSON arguments object.
* **State Impact**: Appends the `delta` to the `input` field of the `ToolCallUIPart`. The reducer attempts to parse the accumulating string as JSON. Sets the tool's `state` to `input-streaming`.

#### `tool_call.output.delta`

* **Description**: Streams a chunk of the output from a tool execution.
* **Payload (`data`)**:
  * `messageId`, `partId`.
  * `delta`: A string chunk of the tool's output.
* **State Impact**: Appends the `delta` to the `output` field of the `ToolCallUIPart`. Sets the tool's `state` to `executing`.

## Consuming Events in Your App

The `useAgent` hook provides callbacks to tap into this event stream.

### `onEvent`

This is the lowest-level callback. It fires for every single valid `AgentKitEvent` that the hook processes, giving you full visibility into the streaming process.

```jsx theme={"system"}
useAgent({
  onEvent: (evt, meta) => {
    console.log('Event received:', evt.event, 'for thread:', meta.threadId);
    if (evt.event === 'run.started') {
      // Show a global "thinking" indicator
    }
  }
})
```

### `onToolResult`

A convenient, strongly-typed callback that fires only when a tool has finished executing and its final output is available (`part.completed` with `type: "tool-output"`).

```jsx theme={"system"}
useAgent<MyAgentConfig>({
  onToolResult: (result) => {
    if (result.toolName === 'getWeather') {
      const weatherData = result.data; // strongly typed!
      // Display a custom weather component
    }
  }
})
```

### `onStreamEnded`

Fires when the entire sequence of events for a turn is complete (`stream.ended`). Useful for triggering actions after the assistant has fully responded.

```jsx theme={"system"}
useAgent({
  onStreamEnded: ({ threadId }) => {
    console.log(`Agent has finished responding in thread ${threadId}.`);
    // Maybe run some analytics or enable the input field
  }
})
```


# Overview
Source: https://agentkit.inngest.com/streaming/overview

Realtime event streaming with AgentKit + useAgent

With a useAgent hook you can seamlessly stream a network of agents, a single agent and durable steps within tools used by your agents. You can think of useAgent as the bridge between durable agents and your user interface.

Instead of stitching together events, workflow steps and token streams - your UI receives structured events that describe lifecycles, content parts, tool calls and completions. This hook consumes these events and maintains your UI state for a single conversation or many conversations in parallel.

Here's a simple example of how you would use the hook in your React component:

```tsx theme={"system"}
import { useAgent } from "@inngest/use-agent";

export function MyAgentUI() {
  const { messages, sendMessage, status } = useAgent();

  const onSubmit = (e) => {
    e.preventDefault();
    const value = new FormData(e.currentTarget).get("input");
    sendMessage(value);
  };

  return (
    <div>
      <ul>
        {messages.map(({ id, role, parts }) => (
          <li key={id}>
            <div>{role}</div>
            {parts.map(({ id, type, content }) =>
              type === "text" ? <div key={id}>{content}</div> : null
            )}
          </li>
        ))}
      </ul>

      <form onSubmit={onSubmit}>
        <input name="input" />
        <button type="submit" disabled={status !== "ready"}>
          Send
        </button>
      </form>
    </div>
  );
}
```

Let's take a closer look at what components, endpoints and other files we will need to wire this all up:

* **Inngest Client (`/api/inngest/client.ts`)**: Initializes Inngest with the `realtimeMiddleware`.
* **Realtime Channel (`/api/inngest/realtime.ts`)**: Defines a typed realtime channel and topic.
* **Chat Route: `/api/chat/route.ts`**: This is a standard Next.js API route. Its only job is to receive a request from the frontend and send an event to Inngest to trigger a function.
* **Token Route: `/api/realtime/token/route.ts`**: This secure endpoint generates a subscription token that the frontend needs to connect to Inngest realtime.
* **Inngest Route: `/api/inngest/route.ts`**: The standard handler that serves all your Inngest functions.

Once you've configured all the foundational endpoints needed for streaming, you'll want to create some agents, define types and integrate this into a UI:

<Steps>
  <Step title="Define server-side types">
    Define your server-side state type, import all your tools and pass them into `createToolManifest` to generate a type that you will use in your UI.

    ```typescript theme={"system"}
    import { createToolManifest, type StateData } from "@inngest/agent-kit";
    import { selectEventsTool } from "./event-matcher";
    import { generateSqlTool } from "./query-writer";

    // server-side state used by networks, routers and agents
    export type AgentState = StateData & {
        userId?: string;
        eventTypes?: string[];
        schemas?: Record<string, unknown>;
        selectedEvents?: { event_name: string; reason: string }[];
        currentQuery?: string;
        sql?: string;
    };

    // a typed manifest of all available tools
    const manifest = createToolManifest([
        generateSqlTool,
        selectEventsTool,
    ] as const);

    export type ToolManifest = typeof manifest;
    ```
  </Step>

  <Step title="Define client-side types">
    Create a `ClientState` type which will type state that your UI will send to your agent backend. This is a great place to pass along important context about the user or what they're doing in your app.

    ```typescript theme={"system"}
    import {
      useAgent,
      type AgentKitEvent,
      type UseAgentsConfig,
      type UseAgentsReturn,
    } from "@inngest/use-agent";

    import type { ToolManifest } from "@/app/api/inngest/functions/agents/types";

    export type ClientState = {
      sqlQuery: string;
      eventTypes: string[];
      schemas: Record<string, unknown> | null;
      currentQuery: string;
    };

    export type AgentConfig = { tools: ToolManifest; state: ClientState };

    export type AgentEvent = AgentKitEvent<ToolManifest>;

    export function useInsightsAgent(
      config: UseAgentsConfig<ToolManifest, ClientState>
    ): UseAgentsReturn<ToolManifest, ClientState> {
      return useAgent<{ tools: ToolManifest; state: ClientState }>(config);
    }
    ```
  </Step>

  <Step title="Create agents and an Inngest function to run them" />

  <Step title="Integrate a useAgent hook into your UI" />
</Steps>

For a deeper dive into streaming agents, check out our [Usage Guide](/streaming/usage-guide).


# Provider
Source: https://agentkit.inngest.com/streaming/provider

A deep dive into the provider for streaming agents

The `AgentProvider` is a React component that creates a shared context for all `useAgent` hooks in your application. While it's optional, using it is highly recommended as it improves performance and ensures configuration consistency.

## Why Use the Provider?

By wrapping your agent-driven components in `AgentProvider`, you get several key benefits:

* **Performance**: A single WebSocket connection is established and shared across all components, reducing network overhead.
* **Consistency**: A shared transport configuration, user context, and channel key are used by all hooks, preventing inconsistencies.
* **Flexibility**: Individual hooks can still override the shared configuration if needed for specific cases.
* **Anonymous Users**: The provider automatically generates and persists a unique ID for anonymous users, allowing them to have a consistent experience across page loads.

## How It Works

`AgentProvider` creates a React Context that provides a shared transport instance, connection, and user information to any `useAgent` hook rendered within it. The hooks will automatically detect and use the context if it's available.

If you don't use the provider, each `useAgent` hook will create its own transport and connection, which is less efficient.

## Usage Patterns

Here are some common ways to use the `AgentProvider`.

### Basic Authenticated User

For an application with logged-in users, pass the user's unique ID to the `userId` prop. This ensures that the agent's context is tied to the correct user.

```tsx theme={"system"}
import { AgentProvider } from "@inngest/use-agent";
import { ChatPage } from "./ChatPage";
import { ThreadsSidebar } from "./ThreadsSidebar";

function App({ userId }) {
  return (
    <AgentProvider userId={userId}>
      <ChatPage />
      <ThreadsSidebar />
    </AgentProvider>
  );
}
```

### Anonymous Users

If your application supports guest users, you can omit the `userId` prop. The provider will automatically create a unique anonymous ID and store it in `sessionStorage` to maintain a consistent experience for the user during their session.

```tsx theme={"system"}
import { AgentProvider } from "@inngest/use-agent";
import { GuestChatInterface } from "./GuestChatInterface";

function App() {
  return (
    <AgentProvider>
      <GuestChatInterface />
    </AgentProvider>
  );
}
```

### Collaborative Sessions

To create shared, collaborative sessions (e.g., a chat where multiple users interact with the same agent in a shared context), you can use the `channelKey` prop. All users who connect with the same `channelKey` will be subscribed to the same real-time channel.

```tsx theme={"system"}
import { AgentProvider } from "@inngest/use-agent";
import { CollaborativeChat } from "./CollaborativeChat";

function ProjectChat({ projectId }) {
  return (
    <AgentProvider channelKey={`project-${projectId}`}>
      <CollaborativeChat />
    </AgentProvider>
  );
}
```

### Custom Transport Configuration

You can customize the HTTP endpoints and headers used by the transport layer by passing a configuration object to the `transport` prop. This is useful if your API routes don't follow the default conventions.

```tsx theme={"system"}
import { AgentProvider } from "@inngest/use-agent";

function App({ userId, getAuthToken }) {
  return (
    <AgentProvider
      userId={userId}
      transport={{
        api: {
          sendMessage: '/api/v2/chat',
          fetchThreads: '/api/v2/threads'
        },
        headers: () => ({
          'Authorization': `Bearer ${getAuthToken()}`,
        })
      }}
    >
      <ChatApp />
    </AgentProvider>
  );
}
```


# Transport
Source: https://agentkit.inngest.com/streaming/transport

A deep dive into the transport layer for streaming agents

AgentKit's UI streaming is designed to be transport-agnostic, giving you the flexibility to use different real-time communication strategies. At its core, AgentKit doesn't manage WebSocket connections or push data to clients directly.

Instead, it provides a powerful `streaming` configuration hook where you provide a `publish` function. AgentKit calls this function with structured data chunks as your agent network executes, and you decide how to send that data to the client.

This decoupled design means you can use any streaming provider that fits your needs.

## Default Transport: Inngest Realtime

For most applications, we recommend using **Inngest Realtime** as the transport layer. It's robust, scalable, and integrates seamlessly with Inngest's durable function execution, providing a resilient and reliable streaming experience.

### How It Works

The data flow with Inngest Realtime involves a few key components on your backend:

1. **Chat Route (`/api/chat/route.ts`)**: A standard API endpoint that receives a message from your UI and sends an event to Inngest to trigger an agent run.
2. **Token Route (`/api/realtime/token/route.ts`)**: A secure endpoint that generates a short-lived subscription token for the client. The client uses this token to connect to a specific Inngest Realtime channel.
3. **Inngest Function**: The function that runs your agent or network. You pass Inngest's `publish` function to AgentKit's `streaming.publish` hook. AgentKit generates the events, and Inngest handles the delivery to the subscribed client.

Here's a look at the end-to-end flow:

```mermaid theme={"system"}
graph TD
  subgraph Client
    UI[React UI with useAgent]
  end

  subgraph Your Backend
    ChatRoute[POST /api/chat]
    TokenRoute[POST /api/realtime/token]
    InngestFn[Inngest Function with AgentKit]
  end

  subgraph Inngest Cloud
    Realtime[Inngest Realtime Service]
  end

  UI -->|Get subscription token| TokenRoute
  TokenRoute -->|Returns token| UI
  UI -->|Connect and subscribe| Realtime
  
  UI -->|Send message| ChatRoute
  ChatRoute -->|Triggers function| InngestFn
  InngestFn -->|Publishes events| Realtime
  Realtime -->|Streams events| UI
```

## Session Transport (In-Memory)

For demos, tutorials, or ephemeral chat experiences where you don't need to persist conversation history, you can use the session transport.

This is a **client-side transport** that manages threads and messages for the current browser tab.

It's important to understand that the session transport still relies on the default HTTP transport to communicate with your backend to initiate agent runs. It doesn't change how the server-side streaming works; it only affects how the conversation history is stored on the client.

This is useful for:

* Building live playgrounds of your agents.
* Creating temporary chat sessions that are discarded when the browser tab is closed.
* Reducing database load for non-essential conversations.

## Other Transports

Because of its decoupled design, you can integrate AgentKit with any real-time provider. To do so, you would create your own `publish` function that sends the event chunks from AgentKit to your provider of choice.

## Overriding Transport Methods

You can override any of the default transport's methods or properties by passing a configuration object to the `transport` prop on either the `AgentProvider` or the `useAgent` hook. This is useful for customizing API endpoints, adding authentication headers, or modifying the request body.

If you provide a partial configuration, it will be merged with the default transport configuration.

### Example: Customizing API routes, headers, and body

```tsx theme={"system"}
import { AgentProvider } from "@inngest/use-agent";

function App({ userId, getAuthToken, getTenantId }) {
  return (
    <AgentProvider
      userId={userId}
      transport={{
        // Use a different base URL for all API calls
        baseURL: 'https://api.example.com/v2',

        // Override the default API endpoints
        api: {
          sendMessage: '/chat',
          fetchThreads: '/threads'
        },
        
        // Add dynamic Authorization header to all requests
        headers: () => ({
          'Authorization': `Bearer ${getAuthToken()}`,
        }),

        // Add a tenantId to the body of all requests
        body: () => ({
          tenantId: getTenantId(),
        })
      }}
    >
      <ChatApp />
    </AgentProvider>
  );
}
```

## Transport API Reference

The `IClientTransport` interface defines the methods that a transport must implement. Here is a reference for each method and its associated data structures.

### `sendMessage(params, options?)`

Sends a message from the user to the agent.

* `params`: `SendMessageParams`
  * `userMessage`: `object`
    * `id`: `string` - A unique client-generated ID for the message.
    * `content`: `string` - The text content of the user's message.
    * `role`: `"user"`
    * `state?`: `Record<string, unknown>` - Optional client-side state to persist with the message.
    * `clientTimestamp?`: `Date` - The timestamp from when the user sent the message.
    * `systemPrompt?`: `string` - An optional system prompt to override the agent's default.
  * `threadId`: `string` - The ID of the conversation thread.
  * `history`: `unknown[]` - The current conversation history from the client.
  * `userId?`: `string` - The ID of the user.
  * `channelKey?`: `string` - The key for a collaborative channel.
* `options?`: `RequestOptions`
* **Returns**: `Promise<{ success: boolean; threadId: string }>`

### `getRealtimeToken(params, options?)`

Fetches a token for connecting to the real-time service.

* `params`: `GetRealtimeTokenParams`
  * `userId?`: `string`
  * `threadId?`: `string`
  * `channelKey?`: `string`
* `options?`: `RequestOptions`
* **Returns**: `Promise<RealtimeToken>`
  * `token`: `string` - The subscription token.
  * `expires?`: `number` - Optional expiration timestamp.
  * `channel?`: `string` - Optional channel information.

### `fetchHistory(params, options?)`

Fetches the message history for a specific thread.

* `params`: `FetchHistoryParams`
  * `threadId`: `string`
* `options?`: `RequestOptions`
* **Returns**: `Promise<unknown[]>` - An array of message objects.

## Experimental Methods

### `fetchThreads(params, options?)`

Fetches a paginated list of conversation threads.

* `params`: `FetchThreadsParams`
  * `userId?`: `string`
  * `channelKey?`: `string`
  * `limit?`: `number`
  * `cursorTimestamp?`: `string`
  * `cursorId?`: `string`
  * `offset?`: `number`
* `options?`: `RequestOptions`
* **Returns**: `Promise<ThreadsPage>`
  * `threads`: `Thread[]` - An array of thread objects.
  * `hasMore`: `boolean` - Indicates if more pages are available.
  * `total`: `number` - The total number of threads.

### `createThread(params, options?)`

Creates a new conversation thread.

* `params`: `CreateThreadParams`
  * `userId?`: `string`
  * `channelKey?`: `string`
  * `title?`: `string`
  * `metadata?`: `Record<string, unknown>`
* `options?`: `RequestOptions`
* **Returns**: `Promise<{ threadId: string; title: string }>`

### `deleteThread(params, options?)`

Deletes a conversation thread.

* `params`: `DeleteThreadParams`
  * `threadId`: `string`
* `options?`: `RequestOptions`
* **Returns**: `Promise<void>`


# Usage Guide
Source: https://agentkit.inngest.com/streaming/usage-guide

A deep dive into streaming agents

Let's build a simple SQL generation agent network with realtime streaming. To kick things off, let's walk through a few endpoints you'll need to wire this all up:

* **Inngest Client (`/api/inngest/client.ts`)**: Initializes Inngest with the `realtimeMiddleware`.
* **Realtime Channel (`/api/inngest/realtime.ts`)**: Defines a typed realtime channel and topic.
* **Chat Route: `/api/chat/route.ts`**: This is a standard Next.js API route. Its only job is to receive a request from the frontend and send an event to Inngest to trigger a function.
* **Token Route: `/api/realtime/token/route.ts`**: This secure endpoint generates a subscription token that the frontend needs to connect to Inngest realtime.
* **Inngest Route: `/api/inngest/route.ts`**: The standard handler that serves all your Inngest functions.

Let's take a closer look at each of these endpoints and what they do...

***

## Set up Inngest for streaming

<Steps>
  <Step title="Inngest Client - /api/inngest/client.ts">
    This file configures the Inngest client and enables the realtime middleware, which is essential for streaming.

    ```tsx theme={"system"}
    // app/api/inngest/client.ts
    import { realtimeMiddleware } from "@inngest/realtime/middleware";
    import { Inngest } from "inngest";

    export const inngest = new Inngest({
      id: "agent-app-client",
      middleware: [realtimeMiddleware()],
    });
    ```
  </Step>

  <Step title="Realtime Channel - /api/inngest/realtime.ts">
    Here, we define a strongly-typed channel for our agent's communications. The `agent_stream` topic is where all message chunks will be published fromAgentKit.

    ```tsx theme={"system"}
    // app/api/inngest/realtime.ts
    import { type AgentMessageChunk } from "@inngest/agent-kit";
    import { channel, topic } from "@inngest/realtime";

    export const createChannel = channel(
      (userId: string) => `user:${userId}`
    ).addTopic(topic("agent_stream").type<AgentMessageChunk>());
    ```
  </Step>

  <Step title="Chat API Route - /api/chat/route.ts">
    This endpoint is the bridge between your frontend and the Inngest backend. It receives the user's message and dispatches an event to trigger the agent network.

    ```tsx theme={"system"}
    // app/api/chat/route.ts
    import { NextRequest, NextResponse } from "next/server";
    import { auth } from "@clerk/nextjs/server"; // Or your auth provider
    import { z } from "zod";
    import { inngest } from "../inngest/client";

    const chatRequestSchema = z.object({
      userMessage: z.object({
        id: z.string(),
        content: z.string(),
        role: z.literal("user"),
      }),
      threadId: z.string().optional(),
      channelKey: z.string(),
    });

    export async function POST(req: NextRequest) {
      try {
        const { userId } = auth();
        if (!userId) {
          return NextResponse.json({ error: "Please sign in" }, { status: 401 });
        }

        const validationResult = chatRequestSchema.safeParse(await req.json());
        if (!validationResult.success) {
          return NextResponse.json({ error: "Invalid request" }, { status: 400 });
        }

        const { userMessage, threadId, channelKey } = validationResult.data;

        await inngest.send({
          name: "agent/chat.requested",
          data: {
            userMessage,
            threadId,
            channelKey,
            userId,
          },
        });

        return NextResponse.json({ success: true });
      } catch (error) {
        return NextResponse.json(
          {
            error: error instanceof Error ? error.message : "Failed to start chat",
          },
          { status: 500 }
        );
      }
    }
    ```
  </Step>

  <Step title="Token API Route">
    **`/api/realtime/token/route.ts`**

    This secure endpoint generates a subscription token that the frontend needs to connect to Inngest realtime.

    ```tsx theme={"system"}
    import { NextRequest, NextResponse } from "next/server";
    import { auth } from "@clerk/nextjs/server"; // or any auth provider
    import { getSubscriptionToken } from "@inngest/realtime";

    import { inngest } from "../../inngest/client";
    import { createChannel } from "../../inngest/realtime";

    export type RequestBody = {
      userId?: string;
      channelKey?: string;
    };

    export async function POST(req: NextRequest) {
      const { userId } = auth(); // authenticate the user
      if (!userId) {
        return NextResponse.json(
          { error: "Please sign in to create a token" },
          { status: 401 }
        );
      }

      try {
        // 1. Get the channel key from the request body and validate it
        const { channelKey } = (await req.json()) as RequestBody;
        if (!channelKey) {
          return NextResponse.json(
            { error: "channelKey is required" },
            { status: 400 }
          );
        }

        // 2. Create a subscription token for the resolved channel
        const token = await getSubscriptionToken(inngest, {
          channel: createChannel(channelKey),
          topics: ["agent_stream"],
        });

        // 3. Return the token
        return NextResponse.json(token);
      } catch (error) {
        // ... handle error response
      }
    }
    ```
  </Step>

  <Step title="Inngest Route - /api/inngest/route.ts">
    This is the standard Next.js route handler for serving all of your Inngest functions.

    ```tsx theme={"system"}
    // app/api/inngest/route.ts
    import { serve } from "inngest/next";
    import { inngest } from "./client";
    import { runAgentNetwork } from "./functions/run-network";

    export const { GET, POST, PUT } = serve({
        client: inngest,
        functions: [runAgentNetwork],
    });
    ```
  </Step>
</Steps>

Now that we have Inngest and our API routes configured, let’s build out the agents. We are going to create a network of 3 agents orchestrated via a simple code based router. The router will ensure that our network runs the following agents in this exact order:

1. **Event Matcher**: Selects 1-5 event names that we should consider for the query

2. **Query Writer**: Generates a SQL query given a list of events & schemas

3. **Summarizer**: Creates a short summary of the query and adds it to message history

Let’s start by creating our event matcher and query writer agents. Each agent will have access to only one tool each which we will ensure is always invoked by defining a static tool\_choice.

```tsx theme={"system"}
import { createAgent, createTool, openai } from "@inngest/agent-kit";
import { z } from "zod";
import type { AgentState } from "./types";

// Define the tool for generating SQL
export const generateSqlTool = createTool({
  name: "generate_sql",
  description: "Provide the final SQL SELECT statement...",
  parameters: z.object({
    sql: z.string().describe("A single valid SELECT statement."),
    title: z.string().describe("Short 20-30 character title for this query"),
    reasoning: z.string().describe("Brief explanation..."),
  }),
  handler: ({ sql, title, reasoning }) => {
    return { sql, title, reasoning };
  },
});

// Define the agent that uses the tool
export const queryWriterAgent = createAgent<AgentState>({
  name: "Insights Query Writer",
  description: "Generates a safe, read-only SQL SELECT statement.",
  system: async ({ network }) => {
    /* ... dynamic system prompt ... */
  },
  model: openai({ model: "gpt-5-nano-2025-08-07" }),
  tools: [generateSqlTool],
  tool_choice: "generate_sql", // Force this tool to be called
});

// Define the event matcher agent
export const selectEventsTool = createTool({
  name: "select_events",
  description:
    "Select 1-5 event names from the provided list that are most relevant to the user's query.",
  parameters: z.object({
    events: z
      .array(
        z.object({
          event_name: z.string(),
          reason: z.string(),
        })
      )
      .min(1)
      .max(6),
  }),
  handler: (args, { network }) => {
    const { events } = args;

    // Persist selection on network state for downstream agents
    network.state.data.selectedEvents = events;

    return {
      selected: events,
      reason: "Selected by the LLM based on the user's query.",
      totalCandidates: network.state.data.eventTypes?.length || 0,
    };
  },
});

export const eventMatcherAgent = createAgent<AgentState>({
  name: "Insights Event Matcher",
  description:
    "Analyzes available events and selects 1-5 that best match the user's intent.",
  system: async ({ network }) => {
    const events = network?.state.data.eventTypes || [];
    const sample = events.slice(0, 50); // avoid overly long prompts

    return [
      "You are an event selection specialist.",
      "Your job is to analyze the user's request and the list of available event names, then choose the 1-5 most relevant events.",
      "",
      "Instructions:",
      "- Review the list of available events provided below.",
      "- Based on the user's query, decide which 1-5 events are the best match.",
      "- Call the `select_events` tool and pass your final choice in the `events` parameter.",
      "- Do not guess event names; only use names from the provided list.",
      "",
      sample.length
        ? `Available events (${
            events.length
          } total, showing up to 50):\n${sample.join("\n")}`
        : "No event list is available. Ask the user to clarify which events they are interested in.",
    ].join("\n");
  },
  model: openai({ model: "gpt-5-nano-2025-08-07" }),
  tools: [selectEventsTool],
  tool_choice: "select_events", // Force this tool to be called
});
```

Once you have your agent defined, you can define your server-side state type and use `createToolManifest` to create a type which will be used on the client-side to ensure end-to-end type safety.

```tsx theme={"system"}
import { createToolManifest, type StateData } from "@inngest/agent-kit";
import { selectEventsTool } from "./event-matcher";
import { generateSqlTool } from "./query-writer";

// server-side state used by networks, routers and agents
export type AgentState = StateData & {
  userId?: string;
  eventTypes?: string[];
  schemas?: Record<string, unknown>;
  selectedEvents?: { event_name: string; reason: string }[];
  currentQuery?: string;
  sql?: string;
};

// a typed manifest of all available tools
const manifest = createToolManifest([
  generateSqlTool,
  selectEventsTool,
] as const);
export type ToolManifest = typeof manifest;
```

With server-side state and a ToolManifest now defined, you can strongly type your own agent hook and define client-side state that you may want sent in each message:

```tsx theme={"system"}
import {
  useAgent,
  type AgentKitEvent,
  type UseAgentsConfig,
  type UseAgentsReturn,
} from "@inngest/use-agent";

import type { ToolManifest } from "@/app/api/inngest/functions/agents/types";

export type ClientState = {
  sqlQuery: string;
  eventTypes: string[];
  schemas: Record<string, unknown> | null;
  currentQuery: string;
};

export type AgentConfig = { tools: ToolManifest; state: ClientState };

export type AgentEvent = AgentKitEvent<ToolManifest>;

export function useInsightsAgent(
  config: UseAgentsConfig<ToolManifest, ClientState>
): UseAgentsReturn<ToolManifest, ClientState> {
  return useAgent<{ tools: ToolManifest; state: ClientState }>(config);
}
```

Before we move onto implementing the agent hook into your UI components, let's create a summarizer agent and an agent network with a code-based router to orchestrate everything:

```tsx theme={"system"}
// Define the summarizer agent - this agent has no tools and just provides a summary
export const summarizerAgent = createAgent<AgentState>({
  name: "Insights Summarizer",
  description:
    "Writes a concise summary describing what the generated SQL does and why.",
  system: async ({ network }) => {
    const events =
      network?.state.data.selectedEvents?.map((e) => e.event_name) ?? [];
    const sql = network?.state.data.sql;

    return [
      "You are a helpful assistant summarizing the result of a SQL generation process.",
      "Write a one sentence short summary that explains:",
      "- What events were just analyzed (if known).",
      "- What the query returns and how it helps the user.",
      "Avoid restating the full SQL. Be clear and non-technical when possible.",
      events.length ? `Selected events: ${events.join(", ")}` : "",
      sql
        ? "A SQL statement has been prepared; summarize its intent, not its exact text."
        : "",
    ]
      .filter(Boolean)
      .join("\n");
  },
  model: openai({ model: "gpt-5-nano-2025-08-07" }),
});
```

```tsx theme={"system"}
// app/api/inngest/functions/agents/network.ts

import { createNetwork, openai, type Network } from "@inngest/agent-kit";
import { eventMatcherAgent } from "./event-matcher";
import { queryWriterAgent } from "./query-writer";
import { summarizerAgent } from "./summarizer";
import type { InsightsAgentState } from "./types";

// A simple router that executes agents in a fixed order
const sequenceRouter: Network.Router<InsightsAgentState> = async ({
  callCount,
}) => {
  if (callCount === 0) return eventMatcherAgent;
  if (callCount === 1) return queryWriterAgent;
  if (callCount === 2) return summarizerAgent;
  return undefined; // ends the network run
};

// Define the network directly - no factory function needed
export const insightsNetwork = createNetwork<InsightsAgentState>({
  name: "Insights SQL Generation Network",
  description:
    "Selects relevant events, proposes a SQL query, and summarizes the result.",
  agents: [eventMatcherAgent, queryWriterAgent, summarizerAgent],
  defaultModel: openai({ model: "gpt-5-nano-2025-08-07" }),
  maxIter: 6,
  router: sequenceRouter,
});
```

Now let’s create an Inngest function which we’ll use to run our agent network and configure event streaming:

```tsx theme={"system"}
// app/api/inngest/functions/run-network.ts
import {
  createState,
  type AgentMessageChunk,
  type Message,
} from "@inngest/agent-kit";
import type { ChatRequestEvent } from "@inngest/use-agent";
import { v4 as uuidv4 } from "uuid";

import { inngest } from "../client";
import { createChannel } from "../realtime";
import type { InsightsAgentState } from "./agents/types";
import { insightsNetwork } from "./agents/network";

export const runAgentNetwork = inngest.createFunction(
  {
    id: "run-insights-agent",
    name: "Insights SQL Agent",
  },
  { event: "insights-agent/chat.requested" },
  async ({ event, publish, step }) => {
    const {
      threadId: providedThreadId,
      userMessage, // new user message
      userId,
      channelKey, // channel to stream on
      history, // previous messages
    } = event.data as ChatRequestEvent;

    // Validate required userId
    if (!userId) {
      throw new Error("userId is required for agent chat execution");
    }

    // Generate a threadId
    const threadId = await step.run("generate-thread-id", async () => {
      return providedThreadId || uuidv4();
    });

    // Determine the target channel for publishing (channelKey takes priority)
    const targetChannel = await step.run(
      "generate-target-channel",
      async () => {
        return channelKey || userId;
      }
    );

    try {
      const clientState = userMessage.state || {};

      // Create state for the network
      const networkState = createState<InsightsAgentState>(
        {
          userId,
          ...clientState, // passing in client-side managed state into our network
        },
        {
          messages: history,
          threadId,
        }
      );

      // Run the network with streaming enabled
      await insightsNetwork.run(userMessage, {
        state: networkState,
        streaming: {
          publish: async (chunk: AgentMessageChunk) => {
            // you can inspect and add metadata to chunks here
            await publish(createChannel(targetChannel).agent_stream(chunk));
          },
        },
      });

      return {
        success: true,
        threadId,
        message: "Agent network completed successfully",
      };
    } catch (error) {
      // emit an error chunk here
    }
  }
);
```

With all that wired up now, you can now render tool calls and messages in your UI like so:

```tsx theme={"system"}
"use client";

import { useState } from "react";
import { useInsightsAgent, type ClientState } from "@/lib/use-insights-agent";
import type { ToolCallUIPart } from "@inngest/use-agent";
import type { ToolManifest } from "@/app/api/inngest/functions/agents/types";

export default function ChatTestPage() {
  return (
    <div>
      <p>Minimal example using a single-threaded conversation.</p>
      <Chat />
    </div>
  );
}

function Chat() {
  const [input, setInput] = useState("");
  const { messages, status, sendMessage } = useInsightsAgent({
    channelKey: "chat_test",
    state: (): ClientState => ({
      eventTypes: [
        "app/user.created",
        "order.created",
        "payment.failed",
        "email.sent",
      ],
      schemas: null,
      currentQuery: "",
      tabTitle: "Chat Test",
      mode: "demo",
      timestamp: Date.now(),
    }),
  });

  async function onSubmit(e: React.FormEvent) {
    e.preventDefault();
    const value = input.trim();
    if (!value || status !== "ready") return;
    setInput("");
    await sendMessage(value);
  }

  return (
    <div>
      <div>
        {messages.map(({ id, role, parts }) => (
          <div key={id}>
            <div>{role}</div>
            {parts.map((part) => {
              if (part.type === "text") {
                return <div key={part.id}>{part.content}</div>;
              }
              if (part.type === "tool-call") {
                return <ToolCallRenderer key={part.toolCallId} part={part} />;
              }
              return null;
            })}
          </div>
        ))}

        {status !== "ready" && <p>AI is thinking...</p>}
      </div>

      <form onSubmit={onSubmit}>
        <input
          value={input}
          onChange={(e) => setInput(e.target.value)}
          placeholder={status === "ready" ? "Ask me anything" : "Thinking..."}
          disabled={status !== "ready"}
        />
        <button type="submit" disabled={status !== "ready"}>
          Send
        </button>
      </form>
    </div>
  );
}

function ToolCallRenderer({ part }: { part: ToolCallUIPart<ToolManifest> }) {
  if (part.state !== "output-available") return null;

  if (part.toolName === "select_events") {
    const { data } = part.output;
    return (
      <div>
        <div>Selected Events:</div>
        <ul>
          {data.selected.map((e) => (
            <li key={e.event_name}>
              <p>{e.event_name}</p>
              <p>{e.reason}</p>
            </li>
          ))}
        </ul>
      </div>
    );
  }

  if (part.toolName === "generate_sql") {
    const { data } = part.output;
    return (
      <div>
        <div>SQL Query:</div>
        <p>{data.title}</p>
        <p>{data.reasoning}</p>
        <pre>{data.sql}</pre>
      </div>
    );
  }

  return null;
}
```

With all that done, you should now have a fully functional SQL generation agent network with realtime streaming!

By following this guide and using the `useAgent` hook, you now have:

1. **Type Safety**: Tool names, inputs, and outputs are fully typed based on your `ToolManifest`
2. **Real-time Streaming**: See tools execute in real-time with different states (`input-streaming`, `input-available`, `executing`, `output-available`)
3. **Generative UI**: Each tool can have its own custom rendering logic while maintaining type safety
4. **State Management**: The hook automatically manages conversation state, message ordering, and streaming events
5. **Error Handling**: Built-in error states and recovery mechanisms