# Angular

> Connect an Angular app to Copilot Runtime with CopilotKit.

This guide takes an Angular app to a working chat UI backed by [Copilot Runtime](/angular/backend/copilot-runtime). When you select an agent backend in the sidebar, the backend step below changes with it. Without a selection, the guide uses CopilotKit's `BuiltInAgent`.

The runtime runs on your server, keeps model credentials out of the browser, and exposes the `default` agent that `CopilotChat` uses automatically.

<OpsPlatformCTA
  variant="inline"
  title="Take your Angular copilot from local to production"
  body="Add threads, inspection, and cloud-hosted or self-hosted CopilotKit Intelligence without changing the Angular frontend APIs in this guide."
  surface="docs:angular/quickstart:production"
/>

## Start with your coding agent [#start-with-your-coding-agent]

Use this prompt to connect your Angular app to Copilot Runtime with the selected agent backend, then verify a working conversation. You can also follow the manual steps below.

<PageAgentPrompt />

## Prerequisites [#prerequisites]

- An OpenAI API key (or another model provider supported by [Model Selection](/angular/model-selection))
- Angular 22
- Node.js 22

## Getting started [#getting-started]

<Steps>
    <Step>
        ### Create your Angular app [#create-your-angular-app]

        If you don't have one already, pin the CLI to the supported major:

        ```bash
        npx @angular/cli@22 new my-copilot-app
        cd my-copilot-app
        ```
    </Step>
    <Step>
        ### Install CopilotKit [#install-copilotkit]

        `@copilotkit/angular` gives you Angular components, directives, and services for CopilotKit. It supports zoneless applications. Install it with `@angular/cdk`, and install `@copilotkit/runtime` for your local Copilot Runtime server:

        <Tabs groupId="package-manager" items={['npm', 'pnpm', 'yarn']}>
            <Tab value="npm">
                ```bash
                npm install @copilotkit/angular @angular/cdk @copilotkit/runtime
                npm install -D tsx typescript @types/node
                ```
            </Tab>
            <Tab value="pnpm">
                ```bash
                pnpm add @copilotkit/angular @angular/cdk @copilotkit/runtime
                pnpm add -D tsx typescript @types/node
                ```
            </Tab>
            <Tab value="yarn">
                ```bash
                yarn add @copilotkit/angular @angular/cdk @copilotkit/runtime
                yarn add -D tsx typescript @types/node
                ```
            </Tab>
        </Tabs>

        <Callout type="info" title="Match @angular/cdk to your Angular version">
          `@angular/cdk` must share your Angular major version. Most package managers resolve this for you, but if you hit a peer-dependency error, pin it explicitly (for example `@angular/cdk@^22`).
        </Callout>
    </Step>
    <Step>
      ### Create the Copilot Runtime [#create-the-copilot-runtime]

      Add a small Node server that hosts Copilot Runtime at `/api/copilotkit` and registers a `default` built-in agent:

      ```ts title="server.ts"
      import { createServer } from "node:http";
      import { BuiltInAgent, CopilotRuntime } from "@copilotkit/runtime/v2";
      import { createCopilotNodeListener } from "@copilotkit/runtime/v2/node";

      const runtime = new CopilotRuntime({
        agents: {
          default: new BuiltInAgent({
            model: "openai:gpt-6-luna",
            prompt: "You are a helpful assistant for an Angular app.",
          }),
        },
      });

      const port = Number(process.env['PORT'] ?? 8200);

      createServer(
        createCopilotNodeListener({
          runtime,
          basePath: "/api/copilotkit",
          cors: true,
        }),
      ).listen(port, () => {
        console.log(
          `Copilot Runtime listening at http://localhost:${port}/api/copilotkit`,
        );
      });
      ```

      <Callout type="info" title="Angular runs the runtime as its own process">
        Copilot Runtime runs as its own process, so `runtimeUrl` is an absolute URL. To use another port, run `PORT=8250 npx tsx server.ts` and set `runtimeUrl` to match.
      </Callout>
    </Step>
    <Step>
        ### Import the styles [#import-the-styles]

        Add the package stylesheet to your global styles. It's self-contained, so the chat renders without any other CSS.

        ```css title="src/styles.css"
        @import "@copilotkit/angular/styles.css"; /* [!code highlight] */
        ```
    </Step>
    <Step>
        ### Connect to Copilot Runtime [#connect-to-copilot-runtime]

        Point `provideCopilotKit` at the runtime endpoint. The chat uses the agent that your runtime registers as `default`.

        ```ts title="src/app/app.config.ts"
        import { ApplicationConfig } from "@angular/core";
        import { provideCopilotKit } from "@copilotkit/angular"; // [!code highlight]

        export const appConfig: ApplicationConfig = {
          providers: [
            // [!code highlight:3]
            provideCopilotKit({
              runtimeUrl: "http://localhost:8200/api/copilotkit",
            }),
          ],
        };
        ```
    </Step>
    <Step>
        ### Add the chat UI [#add-the-chat-ui]

        Import the `CopilotChat` component into your root component and drop it into the template.

        ```ts title="src/app/app.ts"
        import { Component } from "@angular/core";
        import { CopilotChat } from "@copilotkit/angular"; // [!code highlight]

        @Component({
          selector: "app-root",
          imports: [CopilotChat], // [!code highlight]
          template: `
            <!-- [!code highlight:3] -->
            <div style="height: 100vh">
              <copilot-chat />
            </div>
          `,
        })
        export class App {}
        ```

    </Step>
    <Step>
      ### Run the runtime and app [#run-the-runtime-and-app]

      Start Copilot Runtime in one terminal:

      ```bash
      export OPENAI_API_KEY=sk-...
      npx tsx server.ts
      ```

      Start the Angular app in another terminal:

      ```bash
      npm start
      ```

      Open the dev server URL (the Angular CLI prints it, usually `http://localhost:4200`), send a message, and you'll see it stream back through Copilot Runtime.

      <Accordions className="mb-4">
          <Accordion title="Troubleshooting">
              - **Chat renders unstyled**: Make sure you imported `@copilotkit/angular/styles.css` in `src/styles.css`.
              - **No response from the agent**: Confirm the runtime server is running and `http://localhost:8200/api/copilotkit/info` returns agent information.
              - **CORS errors**: Keep `cors: true` in `createCopilotNodeListener` for local development, or configure CORS to allow your Angular app's origin in production.
              - **Model auth errors**: Confirm `OPENAI_API_KEY` is set in the terminal running `npx tsx server.ts`.
              - **Peer-dependency error on install**: `@angular/cdk` must match your Angular major version. Install the matching major, for example `@angular/cdk@^22` on Angular 22.
              - **Production build exceeds the bundle budget**: CopilotKit pulls in markdown and syntax-highlighting dependencies, so a fresh app can exceed Angular's default 1 MB budget. Raise `budgets` in `angular.json` if your production build fails on size.
          </Accordion>
      </Accordions>
    </Step>
    <Step>
        ### Open Inspector and confirm setup [#open-inspector-and-confirm-setup]

        On localhost, click the Inspector button in the corner of the app.

        1. Open **Inspect**, then **Agent**. Your agent is listed.
        2. Send a chat message. Open **Inspect**, then **AG-UI Events**. Events are moving.
        3. Open **Rich Threads**. The list is unlocked (Intelligence is on), or locked with **Copy setup prompt** (Intelligence is off).

        More detail: [Inspector](/angular/inspector).
    </Step>

</Steps>

## Next steps [#next-steps]

1. [Prebuilt Components](/angular/prebuilt-components): choose a chat surface, then follow the sidebar to frontend tools, generative UI, human-in-the-loop, shared state, threads, attachments, and headless UI.
2. [Runtime and backend docs](/angular/backend/copilot-runtime): configure the server, secure requests, and deploy without leaving the selected Angular surface.

Later:

- [CopilotKit Intelligence](/angular/intelligence/overview): add threads, inspection, and cloud-hosted or self-hosted operations.
- [Angular API reference](/reference/angular): use components, signals, tools, context, and runtime services.
- [Production and lifecycle](/reference/angular/production-lifecycle): handle cleanup, errors, server rendering, hydration, zoneless Angular, and browser-only features.
