Backend Actions & Agents

Find your CopilotRuntime

The starting point for backend actions is the CopilotRuntime you setup during quickstart (the CopilotKit backend endpoint). For a refresher, see Self-Hosting (or alternatively, revisit the quickstart).

Backend actions can return (and stream) values -- which will be piped back to the Copilot system and which may result in additional agentic action.

Integrate your backend actions

Choose any of the methods below to integrate backend actions into your Copilot system.
They can be mixed-and-matched as desired.

When you initialize the CopilotRuntime, you can provide backend actions in the same format as frontend Copilot actions.

Note that actions is not merely an array of actions, but rather a generator of actions. This generator takes properties and url as input -- which means you can customize which backend actions are made available according to the current frontend URL, as well as custom properties you can pass from the frontend.

/api/copilotkit/route.ts

const runtime = new CopilotRuntime({
  actions: ({properties, url}) => {
    // You can use the input parameters to the actions generator to expose different backend actions to the Copilot at different times: 
    // `url` is the current URL on the frontend application.
    // `properties` contains custom properties you can pass from the frontend application.
    
    return [
      {
        name: "fetchNameForUserId",
        description: "Fetches user name from the database for a given ID.",
        parameters: [
          {
            name: "userId",
            type: "string",
            description: "The ID of the user to fetch data for.",
            required: true,
          },
        ],
        handler: async ({userId}: {userId: string}) => {
          // do something with the userId
          // return the user data
          return {
            name: "Darth Doe",
          };
        },
      },
    ]
  }
});
 
// ... define the route using the CopilotRuntime.

Test it out!

After defining the action, ask the copilot to perform the task. Watch it select the correct task, execute it, and stream back relevant responses.

Backend Actions & Agents

Find your CopilotRuntime

Integrate your backend actions

Test it out!

On this page