# 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/claude-sdk-typescript/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](/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>
      ### Connect the selected agent backend [#connect-the-selected-agent-backend]

      <Steps>
        <Step>
          ### Install the Claude Agent SDK packages

          ```bash
          npm install @ag-ui/core @ag-ui/encoder @ag-ui/claude-agent-sdk @anthropic-ai/claude-agent-sdk@^0.2.58 @anthropic-ai/sdk zod
          ```
        </Step>

        <Step>
          ### Bridge Claude Agent SDK to AG-UI

          Use `ClaudeAgentAdapter` from `@ag-ui/claude-agent-sdk`. The adapter
          receives the AG-UI run input, emits AG-UI events back to CopilotKit, and can
          expose backend tools through an in-process Claude SDK MCP server.

      ~~~~typescript title="claude-agent-sdk-adapter.ts"
      function createClaudeAgentAdapter({
        toolSchemas,
        emit,
        getState,
        setState,
        executeTool,
        model,
        systemPrompt,
      }: {
        toolSchemas: Anthropic.Tool[];
        emit: Emit;
        getState: () => Record<string, unknown>;
        setState: (state: Record<string, unknown>) => void;
        executeTool: ExecuteTool;
        model: string;
        systemPrompt: string;
      }) {
        const backendToolServer = buildBackendToolServer({
          toolSchemas,
          emit,
          getState,
          setState,
          executeTool,
        });

        return new ClaudeAgentAdapter({
          agentId: "claude-sdk-typescript",
          model: normalizeClaudeAgentSdkModel(model),
          systemPrompt,
          tools: [],
          mcpServers: backendToolServer.mcpServers,
          allowedTools: backendToolServer.allowedTools,
          permissionMode: "dontAsk",
          maxTurns: 10,
        });
      }
      ~~~~

      ~~~~typescript title="claude-agent-sdk-adapter.ts"
      export async function runWithClaudeAgentSdk({
        input,
        emit,
        runId,
        threadId,
        systemPrompt,
        toolSchemas,
        initialState,
        model,
        executeTool,
        forwardedHeaders,
      }: {
        input: RunAgentInput;
        emit: Emit;
        runId: string;
        threadId: string;
        systemPrompt: string;
        toolSchemas: Anthropic.Tool[];
        initialState: Record<string, unknown>;
        model: string;
        executeTool: ExecuteTool;
        forwardedHeaders?: Record<string, string>;
      }): Promise<void> {
        let state = { ...initialState };
        const pendingStateSnapshots: Record<string, unknown>[] = [];
        const adapter = createClaudeAgentAdapter({
          toolSchemas,
          emit,
          getState: () => state,
          setState: (nextState) => {
            state = nextState;
            pendingStateSnapshots.push(state);
          },
          executeTool,
          systemPrompt,
          model,
        });

        if (forwardedHeaders && Object.keys(forwardedHeaders).length > 0) {
          adapter.headers = forwardedHeaders;
        }

        const runInput: RunAgentInput = {
          ...input,
          runId,
          threadId,
          state: input.state ?? initialState,
        };

        await new Promise<void>((resolve) => {
          adapter.run(runInput).subscribe({
            next: (event) => {
              if (event.type === EventType.TOOL_CALL_RESULT) {
                const snapshot = pendingStateSnapshots.shift();
                if (snapshot) {
                  emit({ type: EventType.STATE_SNAPSHOT, snapshot });
                }
              }
              emit(event);
            },
            error: (error) => {
              const message =
                error instanceof Error ? error.stack || error.message : String(error);
              emit({ type: EventType.RUN_ERROR, runId, threadId, message });
              resolve();
            },
            complete: () => resolve(),
          });
        });
      }
      ~~~~

        </Step>
      </Steps>

      <Callout type="info" title="Expose the selected backend through Copilot Runtime">
        Configure Copilot Runtime to register this backend as the `default`
        agent at `/api/copilotkit`. Continue with the selected backend's
        [Copilot Runtime guide](/angular/claude-sdk-typescript/backend/copilot-runtime) for its runtime
        adapter, credentials, and server command. Do not replace it with the
        `BuiltInAgent` server from the standalone Angular path.
      </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 backend, runtime, and Angular app [#run-the-backend-runtime-and-angular-app]

      Start the selected agent backend and Copilot Runtime with the commands
      from its runtime guide. Confirm
      `http://localhost:8200/api/copilotkit/info` reports the `default`
      agent, then start Angular:

      ```bash
      npm start
      ```

      Open the Angular CLI URL (usually `http://localhost:4200`) and send a
      message. The request now follows the selected path end to end:
      Angular → Copilot Runtime → your selected agent backend.
    </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/claude-sdk-typescript/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/claude-sdk-typescript/backend/copilot-runtime): configure the server, secure requests, and deploy without leaving the selected Angular surface.

Later:

- [CopilotKit Intelligence](/angular/claude-sdk-typescript/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.
