# Quickstart

> Turn your Strands agent into an agent-native application in 10 minutes.

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

Use this prompt to connect your AWS Strands agent to CopilotKit and verify a working conversation. Your coding agent will follow this guide in your project, or you can work through the manual steps below.

<PageAgentPrompt />

## Prerequisites [#prerequisites]

Before you begin, you'll need the following:

- An OpenAI or Anthropic API key
- Node.js 20+
- Python 3.12+ (Python agents only)
- [uv](https://docs.astral.sh/uv/) (Python agents only)
- Your favorite package manager

## Getting started [#getting-started]

<Steps>
    <Step>
        ### Set up CopilotKit Intelligence [#set-up-copilotkit-intelligence]

        <SignupLink surface="docs_aws_strands_quickstart_step1">Sign in to cloud-hosted Intelligence</SignupLink>. Cloud-hosted setup uses a server-side project API key and does not issue `COPILOTKIT_LICENSE_TOKEN`. You will connect the app after you create it below.
    </Step>

    <Step>
        ### Choose your starting point [#choose-your-starting-point]

        You can either start fresh with our starter template or integrate CopilotKit into your existing Strands agent.

        <TailoredContent
            className="step"
            id="agent"
        >
        <TailoredContentOption
            id="starter"
            title="Start from scratch"
            description="Get started quickly with our ready-to-go starter application."
        >
            <Step>
                ### Run our CLI [#run-our-cli]

                <Tabs groupId="language_strands_agent" items={['Python', 'TypeScript']} persist>
                    <Tab value="Python">
                        ```bash
                        npx copilotkit@latest create --framework aws-strands-py
                        ```
                    </Tab>
                    <Tab value="TypeScript">
                        ```bash
                        npx copilotkit@latest create --framework aws-strands-ts
                        ```
                    </Tab>
                </Tabs>

                The CLI walks you through:

                - **Project name**
                - **CopilotKit Intelligence**: persistent threads and the inspector. Choose **Yes** to scaffold a project pre-wired for the platform (the CLI walks you through sign-up, or you can [create an account](https://dashboard.operations.copilotkit.ai/?utm_source=docs&utm_medium=cta&utm_campaign=intelligence&utm_content=docs_cli_prompt) first), or **No** for a standard AWS Strands setup.
                - **Framework**: the command selects the AWS Strands template for this page.
            </Step>
            <Step>
                ### Install dependencies [#install-dependencies]

                ```npm
                npm install
                ```
            </Step>
            <Step>
                ### Configure your environment [#configure-your-environment]

                Create a `.env` file in your agent directory and add your OpenAI API key:

                ```plaintext title="agent/.env"
                OPENAI_API_KEY=your_openai_api_key
                ```

                <ApiKeyHint provider="openai" />

                <Callout type="info" title="Using Anthropic instead">
                  The starter reads its model from `COPILOTKIT_AGENT_MODEL`. Add these lines to `agent/.env`:

                  ```plaintext title="agent/.env"
                  ANTHROPIC_API_KEY=your_anthropic_api_key
                  COPILOTKIT_AGENT_MODEL=anthropic:claude-sonnet-4-6
                  ```

                  Every model call in the agent then uses Claude. This includes the A2UI tool.
                </Callout>
            </Step>
            <Step>
                ### Start the development server [#start-the-development-server]

                <Tabs groupId="package-manager" items={['npm', 'pnpm', 'yarn', 'bun']}>
                    <Tab value="npm">
                        ```bash
                        npm run dev
                        ```
                    </Tab>
                    <Tab value="pnpm">
                        ```bash
                        pnpm dev
                        ```
                    </Tab>
                    <Tab value="yarn">
                        ```bash
                        yarn dev
                        ```
                    </Tab>
                    <Tab value="bun">
                        ```bash
                        bun dev
                        ```
                    </Tab>
                </Tabs>

                This will start both the UI and agent servers concurrently.
            </Step>
        </TailoredContentOption>
        <TailoredContentOption
            id="bring-your-own"
            title="Use an existing agent"
            description="I already have a Strands agent and want to add CopilotKit."
        >
            <Step>
                ### Initialize your agent project [#initialize-your-agent-project]

                <Tabs groupId="language_strands_agent" items={['Python', 'TypeScript']} persist>
                    <Tab value="Python">
                        If you don't already have a Python project set up, create one using `uv`:

                        ```bash
                        uv init my-agent
                        cd my-agent
                        ```
                    </Tab>
                    <Tab value="TypeScript">
                        If you don't already have a Node project set up, create one:

                        ```bash
                        mkdir my-agent && cd my-agent
                        npm init -y
                        npm pkg set type=module
                        npm install -D typescript @types/node tsx
                        npx tsc --init
                        ```
                    </Tab>
                </Tabs>
            </Step>
            <Step>
                ### Install Strands with AG-UI [#install-strands-with-ag-ui]

                <Tabs groupId="language_strands_agent" items={['Python', 'TypeScript']} persist>
                    <Tab value="Python">
                        Add Strands and the required packages to your project:

                        ```bash
                        uv add ag-ui-strands "strands-agents[OpenAI]" fastapi uvicorn
                        ```
                    </Tab>
                    <Tab value="TypeScript">
                        Add the Strands SDK, the AG-UI integration, and the Express helpers:

                        ```bash
                        npm install @ag-ui/aws-strands @strands-agents/sdk express
                        npm install -D @types/express
                        # `@modelcontextprotocol/sdk` is loaded unconditionally by `@strands-agents/sdk`
                        # and is required at runtime even when your agent doesn't use MCP.
                        npm install @modelcontextprotocol/sdk
                        ```
                    </Tab>
                </Tabs>
            </Step>
            <Step>
                ### Configure your environment [#configure-your-environment-1]

                Set your OpenAI API key as an environment variable:

                ```bash
                export OPENAI_API_KEY=your_openai_api_key
                ```

                <ApiKeyHint provider="openai" />

                <Callout type="info" title="Using Anthropic instead">
                  Set `ANTHROPIC_API_KEY`, then use this model in the next step:

                  <Tabs groupId="language_strands_agent" items={['Python', 'TypeScript']} persist>
                      <Tab value="Python">
                          ```bash
                          uv add "strands-agents[anthropic]"
                          ```

                          ```python title="main.py"
                          from strands.models.anthropic import AnthropicModel

                          model = AnthropicModel(
                              client_args={"api_key": os.getenv("ANTHROPIC_API_KEY", "")},
                              model_id="claude-sonnet-4-6",
                              max_tokens=8192,  # required
                          )
                          ```
                      </Tab>
                      <Tab value="TypeScript">
                          ```bash
                          npm install @anthropic-ai/sdk
                          ```

                          ```typescript title="main.ts"
                          import { AnthropicModel } from "@strands-agents/sdk/models/anthropic";

                          const model = new AnthropicModel({
                            apiKey: process.env.ANTHROPIC_API_KEY,
                            modelId: "claude-sonnet-4-6",
                            maxTokens: 8192,
                          });
                          ```
                      </Tab>
                  </Tabs>
                </Callout>
            </Step>
            <Step>
                ### Expose your agent via AG-UI [#expose-your-agent-via-ag-ui]

                <Tabs groupId="language_strands_agent" items={['Python', 'TypeScript']} persist>
                    <Tab value="Python">
                        Update your agent file to expose it as an AG-UI ASGI application:

                        ```python title="main.py"
                        import os

                        from ag_ui_strands import StrandsAgent, create_strands_app
                        from strands import Agent
                        from strands.models.openai import OpenAIModel

                        # Setup your Strands agent
                        api_key = os.getenv("OPENAI_API_KEY", "")
                        model = OpenAIModel(
                            client_args={"api_key": api_key},
                            model_id="gpt-6-luna",
                        )

                        agent = Agent(
                            model=model,
                            system_prompt="You are a helpful AI assistant.",
                        )

                        # Wrap with AG-UI integration
                        agui_agent = StrandsAgent(
                            agent=agent,
                            name="strands_agent",
                        )

                        # Create the FastAPI app
                        app = create_strands_app(agui_agent, "/")

                        if __name__ == "__main__":
                            import uvicorn

                            uvicorn.run("main:app", host="0.0.0.0", port=8000, reload=True)

                        ```

                        <Callout type="info" title="What is AG-UI?">
                          AG-UI is an open protocol for frontend-agent communication. The `create_strands_app` function creates an ASGI app that CopilotKit can connect to.
                        </Callout>
                    </Tab>
                    <Tab value="TypeScript">
                        Update your agent file to expose it as an AG-UI Express application:

                        ```typescript title="main.ts"
                        import { Agent } from "@strands-agents/sdk";
                        import { OpenAIModel } from "@strands-agents/sdk/models/openai";
                        import { StrandsAgent } from "@ag-ui/aws-strands";
                        import { createStrandsApp } from "@ag-ui/aws-strands/server";

                        // Setup your Strands agent
                        const model = new OpenAIModel({
                          apiKey: process.env.OPENAI_API_KEY ?? "",
                          modelId: "gpt-6-luna",
                        });

                        const agent = new Agent({
                          model,
                          systemPrompt: "You are a helpful AI assistant.",
                        });

                        await agent.initialize();

                        // Wrap with AG-UI integration
                        const aguiAgent = new StrandsAgent({
                          agent,
                          name: "strands_agent",
                        });

                        // Create the Express app
                        const app = await createStrandsApp(aguiAgent, { path: "/" });

                        app.listen(8000, () => {
                          console.log("Agent listening on http://localhost:8000");
                        });
                        ```

                        <Callout type="info" title="What is AG-UI?">
                          AG-UI is an open protocol for frontend-agent communication. The `createStrandsApp` function returns an Express app that CopilotKit can connect to.
                        </Callout>
                    </Tab>
                </Tabs>
            </Step>
            <Step>
                ### Create your frontend [#create-your-frontend]

                CopilotKit works with any React-based frontend. We'll use Next.js for this example.

                ```bash
                npx create-next-app@latest frontend
                cd frontend
                ```
            </Step>
            <Step>
                ### Install CopilotKit packages [#install-copilotkit-packages]

                ```npm
                npm install @copilotkit/react-ui @copilotkit/react-core @copilotkit/runtime @ag-ui/client@1.0.2
                ```
            </Step>
            <Step>
                ### Setup Copilot Runtime [#setup-copilot-runtime]

                Create an API route to connect CopilotKit to your Strands agent:

                ```tsx title="app/api/copilotkit/[[...slug]]/route.ts" doctest="component"
                import {
                  CopilotKitIntelligence,
                  CopilotRuntime,
                  createCopilotRuntimeHandler,
                } from "@copilotkit/runtime/v2";
                import { HttpAgent } from "@ag-ui/client";

                const runtime = new CopilotRuntime({
                  agents: {
                    strands_agent: new HttpAgent({ url: "http://localhost:8000" }),
                  },
                  // [!code highlight:8]
                  intelligence: new CopilotKitIntelligence({
                    apiKey: process.env.CPK_INTELLIGENCE_API_KEY!,
                  }),
                  // Threads are per-user. Without this, every visitor shares one history.
                  identifyUser: (request) => ({
                    id: request.headers.get("x-user-id") ?? "anonymous",
                    name: request.headers.get("x-user-name") ?? "Anonymous",
                  }),
                });

                const handler = createCopilotRuntimeHandler({
                  runtime,
                  basePath: "/api/copilotkit",
                });

                export const GET = handler;
                export const POST = handler;
               ```

                From this frontend app directory, connect the runtime to an Intelligence project:

                ```bash title="Terminal"
                npx copilotkit@latest project select
                ```

                The command writes the server-side project API key to `.env`. The runtime reads it here:

                ```plaintext title=".env"
                CPK_INTELLIGENCE_API_KEY=cpk-...
                ```

                <Callout type="info" title="Running without the Intelligence Platform?">
                  Drop the `intelligence` and `identifyUser` options and the runtime falls back
                  to SSE mode with an in-memory runner. Chat and the Inspector still work, but
                  Rich Threads stay locked and the key is never read. See
                  [Connect your runtime to Intelligence](/strands-typescript/intelligence/quickstart) for the
                  full constructor and how to confirm the key is in use.
                </Callout>
            </Step>
            <Step>
                ### Configure CopilotKit Provider [#configure-copilotkit-provider]

                Wrap your application with the CopilotKit provider:

                ```tsx title="app/providers.tsx"
                "use client";

                import { CopilotKit } from "@copilotkit/react-core/v2";

                export function Providers({ children }: { children: React.ReactNode }) {
                  return (
                    <CopilotKit runtimeUrl="/api/copilotkit" agent="strands_agent" useSingleEndpoint={false}>
                      {children}
                    </CopilotKit>
                  );
                }
                ```

                Render `Providers` in `app/layout.tsx`:

                ```tsx title="app/layout.tsx"
                import { Providers } from "./providers"; // [!code highlight]
                import "@copilotkit/react-core/v2/styles.css";
                import './globals.css';

                // ...

                export default function RootLayout({ children }: {children: React.ReactNode}) {
                  return (
                    <html lang="en">
                      <body>
                        {/* [!code highlight:3] */}
                        <Providers>
                          {children}
                        </Providers>
                      </body>
                    </html>
                  );
                }
                ```
            </Step>
            <Step>
              ### Add the chat interface [#add-the-chat-interface]

              Add the CopilotSidebar component to your page:

              ```tsx title="app/page.tsx"
              "use client"; // [!code highlight]

              import { CopilotSidebar } from "@copilotkit/react-core/v2"; // [!code highlight:1]

              export default function Page() {
                return (
                  <main>
                    <h1>Your App</h1>
                    {/* [!code highlight:1] */}
                    <CopilotSidebar />
                  </main>
                );
              }
              ```
            </Step>
            <Step>
                ### Start your agent [#start-your-agent]

                From the `frontend` directory, go back to the agent directory and start the agent server:

                <Tabs groupId="language_strands_agent" items={['Python', 'TypeScript']} persist>
                    <Tab value="Python">
                        ```bash
                        cd ..
                        uv run main.py
                        ```
                    </Tab>
                    <Tab value="TypeScript">
                        ```bash
                        cd ..
                        npx tsx main.ts
                        ```
                    </Tab>
                </Tabs>

                Your agent will be available at `http://localhost:8000`.
            </Step>
            <Step>
                ### Start your UI [#start-your-ui]

                In a separate terminal, navigate to your frontend directory and start the development server:

                <Tabs groupId="package-manager" items={['npm', 'pnpm', 'yarn', 'bun']}>
                    <Tab value="npm">
                        ```bash
                        cd frontend
                        npm run dev
                        ```
                    </Tab>
                    <Tab value="pnpm">
                        ```bash
                        cd frontend
                        pnpm dev
                        ```
                    </Tab>
                    <Tab value="yarn">
                        ```bash
                        cd frontend
                        yarn dev
                        ```
                    </Tab>
                    <Tab value="bun">
                        ```bash
                        cd frontend
                        bun dev
                        ```
                    </Tab>
                </Tabs>
            </Step>
        </TailoredContentOption>
    </TailoredContent>
    </Step>
    <Step>
        ### Start chatting [#start-chatting]

        Your AI agent is now ready to use. Navigate to `localhost:3000` and try asking it some questions:

        ```
        What can you do?
        ```

        ```
        Please tell me a joke.
        ```

        ```
        What do you think about React?
        ```

        <Accordions className="mb-4">
            <Accordion title="Troubleshooting">
                - If you're having connection issues, try using `0.0.0.0` or `127.0.0.1` instead of `localhost`
                - Make sure your agent is running on port 8000
                - Check that your OpenAI API key is correctly set
                - Verify that the `@ag-ui/client` package is installed in your frontend
            </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](/strands-typescript/inspector).
    </Step>

</Steps>

## Deploying to AWS? [#deploying-to-aws]

If you're planning to deploy your Strands agent to AWS Bedrock AgentCore, see the [AgentCore deploy guide](/strands-typescript/deploy/agentcore).

## What's next? [#whats-next]

Now that you have your basic agent setup, explore these advanced features:

<Cards>
  <Card
    title="Add some generative UI"
    description="Render your agent's progress and output in the UI."
    href="/strands-typescript/generative-ui/tool-rendering"
    icon={<PaintbrushIcon />}
  />
  <Card
    title="Setup frontend tools"
    description="Give your agent the ability to call frontend tools, directly updating your application."
    href="/strands-typescript/frontend-tools"
    icon={<WrenchIcon />}
  />
</Cards>
