# 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
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
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
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}
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
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
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"
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"
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"
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"
"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 path="messages" 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 path="status" 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 path="error" 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 path="threads" 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 path="currentThreadId" type="string">
  The ID of the currently active/displayed thread.
</ParamField>

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

<ParamField path="connectionError" 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 path="sendMessage" 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 path="sendMessageToThread" 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 path="setCurrentThread" 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 path="createThread" type="(threadId: string) => void">
  Creates a new, empty thread in the local state.
</ParamField>

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

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

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

<ParamField path="clearConnectionError" 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
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
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
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
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
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
  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
  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 path="mcpServers" type="MCP.Server[]">
  An array of MCP server configurations.
</ParamField>

### MCP.Server

<ParamField path="name" type="string" required>
  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 path="transport" type="TransportSSE | TransportWebsocket" required>
  The transport configuration for connecting to the MCP server.
</ParamField>

### TransportSSE

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

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

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

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

### TransportWebsocket

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

<ParamField path="url" type="string" required>
  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 className="mr-2 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">
    Agents
  </span>

  <span className="mr-2 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">
    Tools
  </span>

  <span className="mr-2 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">
    Network
  </span>

  <span className="mr-2 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">
    Integrations
  </span>

  <br />

  <span className="mr-2 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">
    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
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}
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}
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
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}
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}
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
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}
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}
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
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
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
// 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
// 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
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
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>

{/* TODO - Compare to OpenAI sdk call */}

{/* TODO - When combined with Inngest's step.ai...expand */}

## 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
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">
    {/* TODO - Update this when Inngest isn't a requirement */}

    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
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
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
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
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
  npm install inngest
  ```

  ```shell pnpm
  pnpm install inngest
  ```

  ```shell yarn
  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}
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 caption="Create and copy an Event Key, and copy your Signing Key">
    <img src="https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/concepts/deployment/inngest-event-and-signing-keys.png?fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=d998d6db34ab4ad3b7dbc213a950ec9e" alt="Inngest Event Key and Signing Key" data-og-width="402" width="402" data-og-height="192" height="192" data-path="graphics/concepts/deployment/inngest-event-and-signing-keys.png" data-optimize="true" data-opv="2" srcset="https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/concepts/deployment/inngest-event-and-signing-keys.png?w=280&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=3ae0f7ccd3be42e2438e531db863e8b8 280w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/concepts/deployment/inngest-event-and-signing-keys.png?w=560&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=0a0af839c86cd1ff9fcf0da5dbeae453 560w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/concepts/deployment/inngest-event-and-signing-keys.png?w=840&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=062401d7d94dcb0f7074c64084efdfc5 840w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/concepts/deployment/inngest-event-and-signing-keys.png?w=1100&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=13639d4738e2c87520a469f9db47a2a8 1100w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/concepts/deployment/inngest-event-and-signing-keys.png?w=1650&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=87d368228130abb41c331715a82769d2 1650w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/concepts/deployment/inngest-event-and-signing-keys.png?w=2500&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=5899ef73fea258e2bb4a5ae53bba42cc 2500w" />
</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 caption="Sync your AgentKit network deployment with the Inngest Platform">
    <img src="https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/concepts/deployment/inngest-sync-app.png?fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=b50d407bcd544544a972cbd0e5ebd554" alt="Inngest Event Key and Signing Key" data-og-width="852" width="852" data-og-height="717" height="717" data-path="graphics/concepts/deployment/inngest-sync-app.png" data-optimize="true" data-opv="2" srcset="https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/concepts/deployment/inngest-sync-app.png?w=280&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=5686e99d58fc58c5c5e45613a3213b6c 280w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/concepts/deployment/inngest-sync-app.png?w=560&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=eb53287b21b14bc7104ca3acdd35c15d 560w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/concepts/deployment/inngest-sync-app.png?w=840&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=99ac22119d981da61cc13d3b3f60ca6e 840w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/concepts/deployment/inngest-sync-app.png?w=1100&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=f7d225069edbf5eca75fb6ec61fcff83 1100w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/concepts/deployment/inngest-sync-app.png?w=1650&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=ea58fb8f0440c5e4d1dad33f660eed04 1650w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/concepts/deployment/inngest-sync-app.png?w=2500&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=dc81b5c67253c5c50aea93a72426c3b2 2500w" />
</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 caption="Your AgentKit network is now live and ready to use">
    <img src="https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/concepts/deployment/inngest-functions-tab.png?fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=cf503f7caa80f92ae076015b85f96fe7" alt="Inngest Event Key and Signing Key" data-og-width="1548" width="1548" data-og-height="456" height="456" data-path="graphics/concepts/deployment/inngest-functions-tab.png" data-optimize="true" data-opv="2" srcset="https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/concepts/deployment/inngest-functions-tab.png?w=280&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=eb8c2058aca1e546d5cc0278c23d2695 280w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/concepts/deployment/inngest-functions-tab.png?w=560&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=f6ccdc0df2906f785a6f1910c6bc2ac8 560w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/concepts/deployment/inngest-functions-tab.png?w=840&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=8da3e5a46386277483ceedba5f16c9b0 840w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/concepts/deployment/inngest-functions-tab.png?w=1100&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=38c9df04ba6afe778211ab87fe103541 1100w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/concepts/deployment/inngest-functions-tab.png?w=1650&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=994640b7f431098b87e84d9799fbd37f 1650w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/concepts/deployment/inngest-functions-tab.png?w=2500&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=a345b5f8f5c962bab89d7f26c5ca4149 2500w" />
</Frame>

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

{/* ## Configuring Parallel tool calls, Multitenancy and Retries */}

## Configuring Multitenancy and Retries

<CardGroup cols={1}>
  {/* <Card title="Parallel tool calls" icon="arrows-turn-right" href="/advanced-patterns/multi-steps-tools">
          Learn how to run multiple tools in parallel.
      </Card> */}

  <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 cols={2}>
  <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
// 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
// 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
// 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
// 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
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
// 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
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
// 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
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
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
  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
  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
  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
  import { openai, createAgent } from "@inngest/agent-kit";

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

  ```ts Anthropic
  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
  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
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
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
  "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
  "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
  "gemini-1.5-flash"
  "gemini-1.5-flash-8b"
  "gemini-1.5-pro"
  "gemini-1.0-pro"
  "text-embedding-004"
  "aqa"
  ```

  ```plaintext Grok
  "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
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
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
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
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
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
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).
  {/* TODO - The "stack" of agents isn't clear how this stack is created and when they are executed in relation to the router */}
* 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
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
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
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
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
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
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

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
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;
  },
});
```

{// TODO
  // - Using state in routers (why, how, example)
  // - Using state in agent prompts (why, how, example)
}


# 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
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}
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 cols={1}>
  <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>

{/* TODO - Talk about the handler arguments and what you can do */}

{/* TODO - Typing with zod */}

{/* TODO - Showing how tools can be used for structured output */}

{/* TODO - Leveraging state within tools */}

{/* TODO - Using tool output from agent.run */}

{/* TODO - Using Inngest steps with tools, human in the middle, etc. */}


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



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

## Tutorials

<CardGroup cols={2}>
  <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 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">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 className="mr-2 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">Agents</span>
    <span className="mr-2 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">Tools</span>
    <span className="mr-2 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">Network</span>
    <span className="mr-2 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">State</span>

    <br />

    <span className="mr-2 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">Code-based Router</span>
  </Card>
</CardGroup>

<br />

## MCP as tools examples

<CardGroup cols={2}>
  <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 className="mr-2 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">Agents</span>
    <span className="mr-2 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">Tools</span>
    <span className="mr-2 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">Network</span>
    <span className="mr-2 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">Integrations</span>

    <br />

    <span className="mr-2 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">Code-based Router</span>
  </Card>
</CardGroup>

<br />

## Code Examples

<CardGroup cols={2}>
  <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 className="mr-2 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">Agents</span>
    <span className="mr-2 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">Tools</span>
    <span className="mr-2 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">Network</span>

    <br />

    <span className="mr-2 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">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 className="mr-2 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">Agents</span>
    <span className="mr-2 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">Tools</span>
    <span className="mr-2 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">Network</span>

    <br />

    <span className="mr-2 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">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 className="mr-2 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">Agents</span>
    <span className="mr-2 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">Tools</span>
    <span className="mr-2 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">Network</span>
    <span className="mr-2 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">Integrations</span>

    <br />

    <span className="mr-2 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">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
  npm install @inngest/agent-kit inngest
  ```

  ```shell pnpm
  pnpm install @inngest/agent-kit inngest
  ```

  ```shell yarn
  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 autoPlay muted loop playsInline className="w-full rounded" src="https://cdn.inngest.com/agent-kit/agentkit-with-inngest-dev-server.mp4" />

## 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
  npm install inngest
  ```

  ```shell pnpm
  pnpm install inngest
  ```

  ```shell yarn
  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}
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
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 src="https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-agent.png?fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=1dbefde2fb346e67760db3de677bcc54" alt="Inngest Dev Server function list" data-og-width="2630" width="2630" data-og-height="1642" height="1642" data-path="graphics/quick-start/dev-server-agent.png" data-optimize="true" data-opv="2" srcset="https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-agent.png?w=280&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=814e4277ded9e3e0dd347fbb85efd086 280w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-agent.png?w=560&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=a3a41de9d639760d4000e1290246c7bc 560w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-agent.png?w=840&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=469fb1f121f7ba8d39ee2d5df30b6cd8 840w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-agent.png?w=1100&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=1ae4f30b0c1efd47abf8871f3214597a 1100w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-agent.png?w=1650&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=455b092d6a62ebbde73edb69e3f9e444 1650w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-agent.png?w=2500&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=21915562b10910fb22e84deabdb0103f 2500w" />

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

<img src="https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-invoke.png?fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=c1f99bf2f192ab6f3a06171e2a324d2d" alt="Inngest Dev Server invoke function modal" data-og-width="1588" width="1588" data-og-height="914" height="914" data-path="graphics/quick-start/dev-server-invoke.png" data-optimize="true" data-opv="2" srcset="https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-invoke.png?w=280&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=3c5db677aae33ec1c0bc0db9f730b122 280w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-invoke.png?w=560&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=aebe6c95a5b85e09d6dba4db5a9dea20 560w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-invoke.png?w=840&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=af6f523a97d600051f43be220887bbaf 840w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-invoke.png?w=1100&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=20af2a42355a5af9099948efe1c1de1c 1100w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-invoke.png?w=1650&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=81e1414ca7fd684c35dcd503280fad17 1650w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-invoke.png?w=2500&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=d0395a064165b5ca2a3a6497bbd5c87b 2500w" />

### 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 src="https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-agent-step-details.png?fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=bc1292a771a14eeb528e498c2a2ffa29" alt="Inngest Dev Server agent run" data-og-width="1255" width="1255" data-og-height="726" height="726" data-path="graphics/quick-start/dev-server-agent-step-details.png" data-optimize="true" data-opv="2" srcset="https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-agent-step-details.png?w=280&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=1bb9c8a14121da572f303377da413fad 280w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-agent-step-details.png?w=560&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=8bcb15ee84a124aca0f1d0c634e71d03 560w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-agent-step-details.png?w=840&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=19ad6a60867928d3e8d5d60b7110cb6c 840w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-agent-step-details.png?w=1100&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=9946deeb99cdb3af059ce43f44726ad7 1100w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-agent-step-details.png?w=1650&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=8de14b22d41d1c0852bf5f0ee619493e 1650w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-agent-step-details.png?w=2500&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=a0d26798fdd023590ef7c83399307073 2500w" />

<Info>
  **Tips**

  You can force line breaks to **make the input and output more readable** using the following button:   <img src="https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-network-run-linebreak-btn.png?fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=16a9227f0750fdd4b7d79c4bd7197b0a" alt="Inngest Dev Server agent run" data-og-width="36" width="36" data-og-height="31" height="31" data-path="graphics/quick-start/dev-server-network-run-linebreak-btn.png" data-optimize="true" data-opv="2" srcset="https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-network-run-linebreak-btn.png?w=280&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=faf0d0740d4e20c7e83ce7cba95a6a03 280w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-network-run-linebreak-btn.png?w=560&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=e529becd2272022e300bca3271238d66 560w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-network-run-linebreak-btn.png?w=840&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=7aae343c8f3e6274a7836b93f9d377db 840w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-network-run-linebreak-btn.png?w=1100&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=7bd51bbc6ffedcc847be806a1e11a9e8 1100w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-network-run-linebreak-btn.png?w=1650&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=30bfdef114893af55e1e2af01db6019e 1650w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-network-run-linebreak-btn.png?w=2500&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=6580c2f61040407200d9eb6cdf3e6a87 2500w" />

  You can **expand the input and output view to show its full content** using the following button:   <img src="https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-network-run-expand-btn.png?fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=57a35cb5fd67b118ac855076af533b99" alt="Inngest Dev Server agent run" data-og-width="35" width="35" data-og-height="28" height="28" data-path="graphics/quick-start/dev-server-network-run-expand-btn.png" data-optimize="true" data-opv="2" srcset="https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-network-run-expand-btn.png?w=280&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=0a0a8b329323c8722336c4a1e5b159ac 280w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-network-run-expand-btn.png?w=560&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=437c1d25d27828e65453133ae75b226c 560w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-network-run-expand-btn.png?w=840&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=b578aa897517345fbb80b5c6a4cbc055 840w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-network-run-expand-btn.png?w=1100&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=7b1712ee268592971fb54f489fac66f8 1100w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-network-run-expand-btn.png?w=1650&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=f41a290ed4fab6f7d19fbd67f33a625d 1650w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-network-run-expand-btn.png?w=2500&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=1fbd82605403efe667fbede698c4b089 2500w" />

  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 src="https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-agent-step-rerun-modal.png?fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=7fe561a83dcfb70b3001ea3ee2a19e4f" alt="Inngest Dev Server agent run" data-og-width="1248" width="1248" data-og-height="611" height="611" data-path="graphics/quick-start/dev-server-agent-step-rerun-modal.png" data-optimize="true" data-opv="2" srcset="https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-agent-step-rerun-modal.png?w=280&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=63d1a1c1d9aef75fee160cd4fb5fdddf 280w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-agent-step-rerun-modal.png?w=560&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=279a52c6b4b288eac525a63740232dbb 560w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-agent-step-rerun-modal.png?w=840&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=9b318b33b3e242bc5db9c0f0ab84e43d 840w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-agent-step-rerun-modal.png?w=1100&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=4675355b8ee710d993488cefcee48a19 1100w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-agent-step-rerun-modal.png?w=1650&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=0b7914902e4cfca6416acaf5dee248e6 1650w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-agent-step-rerun-modal.png?w=2500&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=8694a2e2dbce0690dd8d6126955fddfa 2500w" />


# 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
  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
      npm install @inngest/agent-kit inngest
      ```

      ```shell pnpm
      pnpm install @inngest/agent-kit inngest
      ```

      ```shell yarn
      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
        mkdir my-agent-kit-project && npm init
        ```

        ```shell pnpm
        mkdir my-agent-kit-project && pnpm init
        ```

        ```shell yarn
        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
    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
    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
    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
    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
    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 src="https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-agent.png?fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=1dbefde2fb346e67760db3de677bcc54" alt="Inngest Dev Server function list" data-og-width="2630" width="2630" data-og-height="1642" height="1642" data-path="graphics/quick-start/dev-server-agent.png" data-optimize="true" data-opv="2" srcset="https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-agent.png?w=280&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=814e4277ded9e3e0dd347fbb85efd086 280w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-agent.png?w=560&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=a3a41de9d639760d4000e1290246c7bc 560w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-agent.png?w=840&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=469fb1f121f7ba8d39ee2d5df30b6cd8 840w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-agent.png?w=1100&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=1ae4f30b0c1efd47abf8871f3214597a 1100w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-agent.png?w=1650&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=455b092d6a62ebbde73edb69e3f9e444 1650w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-agent.png?w=2500&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=21915562b10910fb22e84deabdb0103f 2500w" />

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

        <img src="https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-invoke.png?fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=c1f99bf2f192ab6f3a06171e2a324d2d" alt="Inngest Dev Server invoke function modal" data-og-width="1588" width="1588" data-og-height="914" height="914" data-path="graphics/quick-start/dev-server-invoke.png" data-optimize="true" data-opv="2" srcset="https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-invoke.png?w=280&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=3c5db677aae33ec1c0bc0db9f730b122 280w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-invoke.png?w=560&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=aebe6c95a5b85e09d6dba4db5a9dea20 560w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-invoke.png?w=840&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=af6f523a97d600051f43be220887bbaf 840w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-invoke.png?w=1100&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=20af2a42355a5af9099948efe1c1de1c 1100w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-invoke.png?w=1650&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=81e1414ca7fd684c35dcd503280fad17 1650w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-invoke.png?w=2500&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=d0395a064165b5ca2a3a6497bbd5c87b 2500w" />

    ```json Invoke payload
    {
      "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 src="https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-agent-run.png?fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=7a350418b0bb2026ccb4c941d55f7aee" alt="Inngest Dev Server agent run" data-og-width="3122" width="3122" data-og-height="2336" height="2336" data-path="graphics/quick-start/dev-server-agent-run.png" data-optimize="true" data-opv="2" srcset="https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-agent-run.png?w=280&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=d2e4bab2e9296f09c7aaa7e684548364 280w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-agent-run.png?w=560&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=0a5559f2e1f9f9b5f129832a7abad339 560w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-agent-run.png?w=840&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=dc67f18a57b0f831aa1efbe7e6e4451d 840w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-agent-run.png?w=1100&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=46b4fc7fd933f3e472148e4a05f653da 1100w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-agent-run.png?w=1650&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=144999a5897fed01cbf453c1bc46eacd 1650w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-agent-run.png?w=2500&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=04dd19965d6a61454e51082db64b6f71 2500w" />
  </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}
    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}
    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}
    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
    {
      "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 src="https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-network-run.png?fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=b64e39ff4fe1dc5efc69aea2fa4f63fd" alt="Inngest Dev Server agent run" data-og-width="1399" width="1399" data-og-height="574" height="574" data-path="graphics/quick-start/dev-server-network-run.png" data-optimize="true" data-opv="2" srcset="https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-network-run.png?w=280&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=13fea77c3d9f6587845470c1c8618e5f 280w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-network-run.png?w=560&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=46365a97397dc3b94b1af96a440952f5 560w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-network-run.png?w=840&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=8475616bce276fa313eb8ec97309427e 840w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-network-run.png?w=1100&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=2f264528c4bc360cefdbb30b26fdfb02 1100w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-network-run.png?w=1650&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=d21597922c191be5cfda6dfedee4d3a1 1650w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-network-run.png?w=2500&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=4641463ee42e02bbe6ae25f71cf65ca6 2500w" />

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

        <img src="https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-network-run-result.png?fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=3ba968d0c0d73fc681dbc8d026b0bccc" alt="Inngest Dev Server agent run" data-og-width="1399" width="1399" data-og-height="627" height="627" data-path="graphics/quick-start/dev-server-network-run-result.png" data-optimize="true" data-opv="2" srcset="https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-network-run-result.png?w=280&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=a846ecc117bdc2012454dea14e0367a4 280w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-network-run-result.png?w=560&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=b862f068608960ad00572da6c7f8697c 560w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-network-run-result.png?w=840&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=32f1a5765baad06fea328544e4b01c20 840w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-network-run-result.png?w=1100&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=008fc50127965e78484450ea7ab7e20e 1100w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-network-run-result.png?w=1650&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=b513f1384489cc74a8246147b0c05154 1650w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/quick-start/dev-server-network-run-result.png?w=2500&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=a3f90b36d7ba485150e7326722c72c29 2500w" />
  </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 cols={2}>
  <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
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" defaultOpen="true">
    <CodeGroup>
      ```bash npm
      npm init
      ```

      ```bash pnpm
      pnpm init
      ```

      ```bash yarn
      yarn init
      ```
    </CodeGroup>
  </Accordion>

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

      ```bash pnpm
      pnpm install @inngest/agent-kit inngest zod
      ```

      ```bash yarn
      yarn add @inngest/agent-kit zod
      ```
    </CodeGroup>
  </Accordion>

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

      ```bash npm
      npm install -D tsx @types/node
      ```

      ```bash pnpm
      pnpm install -D tsx @types/node
      ```

      ```bash yarn
      yarn add -D tsx @types/node
      ```
    </CodeGroup>

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

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

  <Accordion title="4. Download the example code file">
    <CodeGroup>
      ```bash
      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

{/* _TODO: Add a diagram here_ */}

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
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}
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}
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}
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}
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}
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}
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}
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
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
  ANTHROPIC_API_KEY=<your-api-key> npm run start
  ```

  ```bash pnpm
  ANTHROPIC_API_KEY=<your-api-key> pnpm run start
  ```

  ```bash yarn
  ANTHROPIC_API_KEY=<your-api-key> yarn run start
  ```
</CodeGroup>

The following output should be displayed in your terminal:

```txt
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
/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
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" defaultOpen="true">
    <CodeGroup>
      ```bash npm
      npm init
      ```

      ```bash pnpm
      pnpm init
      ```

      ```bash yarn
      yarn init
      ```
    </CodeGroup>
  </Accordion>

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

      ```bash pnpm
      pnpm install @inngest/agent-kit inngest zod
      ```

      ```bash yarn
      yarn add @inngest/agent-kit zod
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="3. Add TypeScript support">
    <CodeGroup>
      ```bash npm
      npm install -D tsx @types/node
      ```

      ```bash pnpm
      pnpm install -D tsx @types/node
      ```

      ```bash yarn
      yarn add -D tsx @types/node
      ```
    </CodeGroup>

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

    ```json
    "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}
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
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}
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
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
  ANTHROPIC_API_KEY=<your-api-key> npm run start
  ```

  ```bash pnpm
  ANTHROPIC_API_KEY=<your-api-key> pnpm run start
  ```

  ```bash yarn
  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
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" defaultOpen="true">
    <CodeGroup>
      ```bash npm
      npm init
      ```

      ```bash pnpm
      pnpm init
      ```

      ```bash yarn
      yarn init
      ```
    </CodeGroup>
  </Accordion>

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

      ```bash pnpm
      pnpm install @inngest/agent-kit inngest
      ```

      ```bash yarn
      yarn add @inngest/agent-kit inngest
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="3. Add TypeScript support">
    <CodeGroup>
      ```bash npm
      npm install -D tsx @types/node
      ```

      ```bash pnpm
      pnpm install -D tsx @types/node
      ```

      ```bash yarn
      yarn add -D tsx @types/node
      ```

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

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

  <Accordion title="4. Download the example code file">
    <CodeGroup>
      ```bash
      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}
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}
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}
/* 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
  ANTHROPIC_API_KEY=<your-api-key> npm run start
  ```

  ```bash pnpm
  ANTHROPIC_API_KEY=<your-api-key> pnpm run start
  ```

  ```bash yarn
  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
      npm install @inngest/agent-kit inngest @browserbasehq/sdk playwright-core
      ```

      ```shell pnpm
      pnpm install @inngest/agent-kit inngest @browserbasehq/sdk playwright-core
      ```

      ```shell yarn
      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
        mkdir my-agent-kit-project && npm init
        ```

        ```shell pnpm
        mkdir my-agent-kit-project && pnpm init
        ```

        ```shell yarn
        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
    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}
    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 className="mr-2 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">
    Agents
  </span>

  <span className="mr-2 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">
    Tools
  </span>

  <span className="mr-2 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">
    Network
  </span>

  <span className="mr-2 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">
    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}
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 className="mr-2 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">
    Agents
  </span>

  <span className="mr-2 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">
    Tools
  </span>

  <span className="mr-2 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">
    Network
  </span>

  <span className="mr-2 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">
    Integrations
  </span>
</Card>


# 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
      npm install @inngest/agent-kit inngest @e2b/code-interpreter
      ```

      ```shell pnpm
      pnpm install @inngest/agent-kit inngest @e2b/code-interpreter
      ```

      ```shell yarn
      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
        mkdir my-agent-kit-project && npm init
        ```

        ```shell pnpm
        mkdir my-agent-kit-project && pnpm init
        ```

        ```shell yarn
        mkdir my-agent-kit-project && yarn init
        ```
      </CodeGroup>
    </Accordion>
  </Step>

  <Step title="Setup your Coding Agent">
    Create a Agent and its associated Network:

    ```typescript
    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}
    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 cols={2}>
  <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 className="mr-2 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">Agents</span>
    <span className="mr-2 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">Tools</span>
    <span className="mr-2 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">Network</span>
    <span className="mr-2 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">Integrations</span>

    <br />

    <span className="mr-2 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">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 className="mr-2 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">Agents</span>
    <span className="mr-2 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">Tools</span>
    <span className="mr-2 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">Network</span>
    <span className="mr-2 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">Integrations</span>

    <br />

    <span className="mr-2 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">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
      npm install @inngest/agent-kit inngest @smithery/sdk
      ```

      ```shell pnpm
      pnpm install @inngest/agent-kit inngest @smithery/sdk
      ```

      ```shell yarn
      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
        mkdir my-agent-kit-project && npm init
        ```

        ```shell pnpm
        mkdir my-agent-kit-project && pnpm init
        ```

        ```shell yarn
        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
    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}
    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 className="mr-2 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">
    Agents
  </span>

  <span className="mr-2 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">
    Tools
  </span>

  <span className="mr-2 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">
    Network
  </span>

  <span className="mr-2 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">
    Integrations
  </span>

  <br />

  <span className="mr-2 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">
    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)).

⚡ **Stream live updates** to your UI with [UI Streaming](/advanced-patterns/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 className="flex gap-4">
  <div className="flex-1 py-8 mr-5">
    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 className="flex-1">
    <Frame>
            <img
              src="https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/system.svg?fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=a9f150f3746240513b94372e0eeb7111"
              alt="A diagram with the components of AgentKit in an AgentKit
      Network"
              data-og-width="832"
              width="832"
              data-og-height="643"
              height="643"
              data-path="graphics/system.svg"
              data-optimize="true"
              data-opv="2"
              srcset="https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/system.svg?w=280&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=d448a0a61f646fffe5407f96449c29b0 280w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/system.svg?w=560&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=1792ec241bc114ff74003a4a5d17ebeb 560w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/system.svg?w=840&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=91f5aa6c2e5ca4c7e45b87d32850288e 840w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/system.svg?w=1100&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=bda48c34babd154e5ba29455fb29482e 1100w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/system.svg?w=1650&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=a06242140ed9367dc4c87043f0656976 1650w, https://mintcdn.com/inngest/UgDIu2BDE2TbH2t8/graphics/system.svg?w=2500&fit=max&auto=format&n=UgDIu2BDE2TbH2t8&q=85&s=5d49a28e4542c7c9542feb0a3be594f7 2500w"
            />
    </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
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
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 path="name" type="string" required>
  The name of the agent. Displayed in tracing.
</ParamField>

<ParamField path="description" type="string">
  Optional description for the agent, used for LLM-based routing to help the
  network pick which agent to run next.
</ParamField>

<ParamField path="model" type="string" required>
  The provider model to use for inference calls.
</ParamField>

<ParamField path="system" type="string | function" required>
  The system prompt, as a string or function. Functions let you change prompts
  based off of state and memory.
</ParamField>

<ParamField path="tools" type="array<TypedTool>">
  Defined tools that an agent can call.

  Tools are created via [`createTool`](/reference/createTool).
</ParamField>

<ParamField path="lifecycle" 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 path="onStart" 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 path="onResponse" 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 path="onFinish" 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
  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
  function onResponse() {}
  ```
</CodeGroup>

{/* TODO - Add docs for run, withModel, etc. */}


# createNetwork
Source: https://agentkit.inngest.com/reference/create-network

Define a network

Networks are defined using the `createNetwork` function.

```ts
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 path="agents" type="array<Agent>" required>
  Agents that can be called from within the `Network`.
</ParamField>

<ParamField path="defaultModel" type="string">
  The provider model to use for routing inference calls.
</ParamField>

<ParamField path="system" type="string" required>
  The system prompt, as a string or function. Functions let you change prompts
  based off of state and memory
</ParamField>

<ParamField path="tools" 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
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 path="name" type="string" required>
  The name of the tool. Used by the model to identify which tool to call.
</ParamField>

<ParamField path="description" type="string" required>
  A clear description of what the tool does. This helps the model understand when and how to use the tool.
</ParamField>

<ParamField path="parameters" type="JSONSchema | ZodType" required>
  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 path="handler" type="function" required>
  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 path="strict" type="boolean" default={true}>
  Option to disable strict validation of the tool parameters.
</ParamField>

<ParamField path="lifecycle" 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
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 path="onStart" 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 path="onFinish" 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
  const tool = createTool({
    name: 'write-file',
    lifecycle: {
      onStart: ({ parameters }) => {
        // Validate or modify parameters before execution
        return parameters;
      },
    },
  });
  ```

  ```ts onFinish
  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
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
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 path="model" type="string" required>
  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 path="max_tokens" type="number" deprecated>
  **This option has been moved to the `defaultParameters` option.**

  <br />

  The maximum number of tokens to generate before stopping.
</ParamField>

<ParamField path="apiKey" 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 path="betaHeaders" type="string[]">
  The beta headers to enable, eg. for computer use, prompt caching, and so on.
</ParamField>

<ParamField path="baseUrl" type="string" default="https://api.anthropic.com/v1/">
  The base URL for the Anthropic API.
</ParamField>

<ParamField path="defaultParameters" type="object" required>
  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
"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
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
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 path="model" type="string" required>
  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 path="apiKey" 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 path="baseUrl" type="string" default="https://generativelanguage.googleapis.com/v1/">
  The base URL for the Gemini API.
</ParamField>

<ParamField path="defaultParameters" 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
"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
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
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 path="model" type="string" required>
  ID of the model to use.

  See the [xAI models list](https://docs.x.ai/docs/models).
</ParamField>

<ParamField path="apiKey" 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 path="baseUrl" type="string" default="https://api.x.ai/v1">
  The base URL for the xAI API.
</ParamField>

<ParamField path="defaultParameters" type="object">
  The default parameters to use for the model (ex: `temperature`, `max_tokens`,
  etc).
</ParamField>

### Available Models

```plaintext Gemini
"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
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
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 path="model" type="string" required>
  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 path="apiKey" 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 path="baseUrl" type="string" default="https://api.openai.com/v1/">
  The base URL for the OpenAI API.
</ParamField>

<ParamField path="defaultParameters" type="object">
  The default parameters to use for the model (ex: `temperature`, `max_tokens`,
  etc).
</ParamField>

### Available Models

```plaintext OpenAI
"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
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 path="input" type="string">
  The original input provided to the network.
</ParamField>

<ParamField path="network" type="Network">
  The network instance, including its state and history.

  See [`Network.State`](/reference/state) for more details.
</ParamField>

<ParamField path="stack" type="Agent[]">
  The list of future agents to be called. (*internal read-only value*)
</ParamField>

<ParamField path="callCount" type="number">
  The number of agent calls that have been made.
</ParamField>

<ParamField path="lastResult" 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
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 path="name" type="string" required>
  The name of the routing agent.
</ParamField>

<ParamField path="description" type="string">
  Optional description of the routing agent's purpose.
</ParamField>

<ParamField path="lifecycle" type="object" required>
  <Expandable title="properties">
    <ParamField path="onRoute" type="function" required>
      Called after each inference to determine the next agent(s) to call.

      **Arguments:**

      ```ts
      {
        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 path="model" 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
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 path="data" 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 path="agent" type="Agent">
  The agent responsible for this inference call.
</ParamField>

<ParamField path="input" type="string">
  The input passed into the agent's run method.
</ParamField>

<ParamField path="prompt" type="Message[]">
  The input instructions without additional history, including the system prompt, user input, and initial agent assistant message.
</ParamField>

<ParamField path="history" type="Message[]">
  The history sent to the inference call, appended to the prompt to form a complete conversation log.
</ParamField>

<ParamField path="output" type="Message[]">
  The parsed output from the inference call.
</ParamField>

<ParamField path="toolCalls" type="ToolResultMessage[]">
  Output from any tools called by the agent.
</ParamField>

<ParamField path="raw" 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
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 path="userId" 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 path="channelKey" type="string">
  A key for targeting subscriptions, enabling collaborative sessions. If not provided, it defaults to the `userId`.
</ParamField>

<ParamField path="transport" 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 path="initialThreadId" type="string">
  The ID of the conversation thread to load when the hook is first mounted.
</ParamField>

<ParamField path="state" 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 path="fetchThreads" 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 path="fetchHistory" 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 path="threadsPageSize" type="number" default="20">
  The number of threads to fetch per page in pagination requests.
</ParamField>

### Callbacks

<ParamField path="onEvent" 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 path="onStreamEnded" 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 path="onToolResult" 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 path="onStateRehydrate" 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 path="onThreadNotFound" type="(threadId) => void">
  A callback that is triggered if `switchToThread` is called with a `threadId` that cannot be found.
</ParamField>

### Behavior

<ParamField path="debug" type="boolean" default="false">
  Enables detailed logging to the console for debugging the hook's internal state and event flow.
</ParamField>

<ParamField path="requireProvider" type="boolean" default="false">
  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 path="enableThreadValidation" type="boolean" default="true">
  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 path="messages" 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 path="status" type="AgentStatus">
  The current activity status of the agent for the active thread. Possible values are: `"ready"`, `"submitted"`, `"streaming"`, or `"error"`.
</ParamField>

<ParamField path="error" type="AgentError">
  An object containing details about the last error that occurred. It's `undefined` if there is no error.
</ParamField>

<ParamField path="clearError" type="() => void">
  A function to clear the current error state.
</ParamField>

<ParamField path="isConnected" type="boolean">
  Returns `true` if the client is currently connected to the real-time event stream.
</ParamField>

### Core Actions

<ParamField path="sendMessage" type="(message, options) => Promise<void>">
  Sends a message to the currently active thread.
</ParamField>

<ParamField path="cancel" type="() => Promise<void>">
  Sends a request to the backend to cancel the current agent run for the active thread.
</ParamField>

<ParamField path="approveToolCall" type="(toolCallId, reason) => Promise<void>">
  Approves a tool call that is awaiting human-in-the-loop (HITL) confirmation.
</ParamField>

<ParamField path="denyToolCall" type="(toolCallId, reason) => Promise<void>">
  Denies a tool call that is awaiting human-in-the-loop (HITL) confirmation.
</ParamField>

### Thread Management State

<ParamField path="threads" type="Thread[]">
  An array of all conversation threads loaded for the user.
</ParamField>

<ParamField path="currentThreadId" type="string | null">
  The ID of the currently active thread.
</ParamField>

<ParamField path="threadsLoading" type="boolean">
  `true` while the initial list of threads is being fetched.
</ParamField>

<ParamField path="threadsHasMore" type="boolean">
  `true` if there are more pages of threads to be loaded.
</ParamField>

<ParamField path="threadsError" type="string | null">
  Contains an error message if fetching threads failed.
</ParamField>

<ParamField path="isLoadingInitialThread" type="boolean">
  `true` only while the selected thread's history has not yet been loaded.
</ParamField>

### Thread Management Actions

<ParamField path="switchToThread" type="(threadId) => Promise<void>">
  Switches the active conversation to a different thread, loading its history.
</ParamField>

<ParamField path="setCurrentThreadId" type="(threadId) => void">
  Immediately changes the `currentThreadId` without fetching history. Useful for optimistic UI updates before `switchToThread` completes.
</ParamField>

<ParamField path="createNewThread" type="() => string">
  Creates a new, empty thread locally and returns its generated UUID.
</ParamField>

<ParamField path="deleteThread" type="(threadId) => Promise<void>">
  Deletes a thread from the backend and removes it from the local state.
</ParamField>

<ParamField path="loadMoreThreads" type="() => Promise<void>">
  Fetches the next page of threads.
</ParamField>

<ParamField path="refreshThreads" type="() => Promise<void>">
  Refetches the first page of threads to get the latest list.
</ParamField>

### Advanced Actions

<ParamField path="sendMessageToThread" type="(threadId, message, options) => Promise<void>">
  Sends a message to a specific thread, which may not be the currently active one.
</ParamField>

<ParamField path="loadThreadHistory" type="(threadId) => Promise<ConversationMessage[]>">
  Manually fetches the message history for a specific thread.
</ParamField>

<ParamField path="clearThreadMessages" type="(threadId) => void">
  Clears all messages from a specific thread's local state.
</ParamField>

<ParamField path="replaceThreadMessages" type="(threadId, messages) => void">
  Replaces all messages in a specific thread's local state. Useful for manually populating history.
</ParamField>

<ParamField path="rehydrateMessageState" 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
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
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
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
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
    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
    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
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
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
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
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
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
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
    // 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
    // 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
    // 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
    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
    // 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
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
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
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
// 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
// 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
// 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
"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