Get started with agents

Build your first agent

In this guide, we will be using Next.js. If you’re working with a different framework, you can find more examples in the primers.

Installation

First, create a new Next.js project with:

npx create-next-app@latest [project-name] [options]

bash

Then cd into the project and install the following packages:

npm i @chatbotkit/sdk @chatbotkit/next @chatbotkit/react

bash

Set Environment Variables

Create a .env.local file in your project root and add the following environment variables:

CHATBOTKIT_API_KEY=your_api_key_here

plain

Make sure to replace your_api_key_here with your actual ChatBotKit API key. You can get your API key from the ChatBotKit dashboard.

💡 Remember to add .env.local to your .gitignore file to keep your API key secure.

Define an endpoint

Next, we will define the endpoint to run the agent:

In app/api/chat/route.ts:

import { getSession } from '@/lib/session'

import { stream } from '@chatbotkit/next/edge'

export async function POST(
  req: Request,
  { params }: { params: { id: string } }
) {
  const { messages } = await req.json()

  const cbk = await getSession()

  return stream(
    cbk.conversation.complete(null {
    model:'gpt-4o'
    backstory:
    'You are an AI assistant with the ability to fetch and analyze web content. Your primary function is to help users by retrieving and understanding information from web pages. When users ask questions or request information, you should:'+
    '1. Determine if the query requires fetching web content' +
    '2. Use the Fetch Webpage ability to retrieve relevant information' +
    '3. Process and summarize the fetched content in a clear, concise manner' +
    '4. Provide accurate, helpful responses based on the retrieved information' +
    'Always maintain a professional and helpful tone. If you cannot access a webpage or if the content is unavailable, clearly communicate this to the user and suggest alternative approaches. Respect user privacy and data security guidelines at all times.',
      inlineSkillset: {
        abilities: [
          {
            name: 'Fetch Webpage',
            description: 'Fetch a webpage',
            instruction: `template: fetch/text/get`,
          },
          {
            name: 'Search Web',
            description: 'Search the web for knowledge related to the task.',
            instruction: `template: search/web`,
          },
        ],
      },
      messages,
    })
  )
}

javascript

The code defines an API endpoint that uses ChatBotKit's capabilities with an inline skillset. Specifically, it includes:

  • An ability called "Fetch Webpage" that uses a pre-built template 'fetch/text/get' to retrieve webpage content
  • An ability called "Search Web" that enables searching for knowledge using the 'search/web' template to enhance the agent's information gathering capabilities.

When this endpoint is called:

  • It accepts a POST request with the messages
  • Creates a stateless conversation session
  • Streams the conversation completion with the configured abilities

Calling the Endpoint

To run the endpoint, first let’s create a client component called ChatArea.tsx:

'use client'

import { ChatInput, useConversationManager } from '@chatbotkit/react'

export default function ChatArea() {
  const {
    thinking,
    text,
    setText,
    message,
    messages,
    submit,
  } = useConversationManager({ endpoint: '/api/chat' })

  // Our renderer is quite basic. We simply iterate over the messages and render
  // them accordingly. We also use our own AutoTextarea for the user input.

  return (
    <div>
      <div>
        {messages.map(({ id, type, text }) => {
          switch (type) {
            case 'user':
              return (
                <div key={id}>
                  <strong>user:</strong> {text}
                </div>
              )

            case 'bot':
              return (
                <div key={id}>
                  <strong>bot:</strong> {text}
                </div>
              )
          }
        })}
        {message ? (
          <div key={message.id}>
            <strong>bot:</strong> {message.text}
          </div>
        ) : null}
        {thinking ? (
          <div key="thinking">
            <strong>bot:</strong> thinking...
          </div>
        ) : null}
      </div>
      <ChatInput
        value={text}
        onChange={(e) => setText(e.target.value)}
        onSubmit={submit}
        placeholder="Type something..."
        style={{
          border: 0,
          outline: 'none',
          resize: 'none',
          width: '100%',
          marginTop: '10px',
        }}
      />
    </div>
  )
}


typescript

This component uses the useConversationManager hook from the React SDK to manage the chat state and handle communications with our API endpoint. It maintains a list of messages and provides a way to submit new messages to the agent.

Now that we have our chat component set up, we can integrate it into our main page. The component provides a simple but functional chat interface that allows users to interact with our agent and leverage its web-fetching capabilities.

Using the Chat Component

To use the ChatArea component in your application, simply import and add it to your page:

import ChatArea from '@/components/ChatArea'

export default function Page() {
  return (
    <div>
      <h1>My Chat Agent</h1>
      <ChatArea />
    </div>
  )
}

typescript

With this setup complete, your agent is now ready to fetch and analyze web content. You can test it by sending messages through the chat interface, asking questions about web pages, or requesting information that requires web searches. The agent will handle these requests using its configured abilities.

Try asking the agent something like "What's the latest news about artificial intelligence?" or "Can you fetch and summarize the content from a specific webpage?" to see it in action.

Conclusion

This completes our guide on building your first agent with web-fetching capabilities. Remember to handle API keys securely and follow best practices when deploying your application.

Go to cbk.ai