Quickstart

    <SignupLink surface="docs_aws_strands_quickstart_step1">Sign up for a free developer account</SignupLink> on our Enterprise Intelligence Platform to get a license key. You'll use it later to enable persistent threads, observability, and the inspector.
</Step>

<Step>
    ### 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

            ```bash
            npx copilotkit@latest create
            ```

            The CLI walks you through:

            - **Project name**
            - **Enterprise Intelligence Platform** — persistent threads, observability, 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** — pick **AWS Strands (Python)** when prompted.
        </Step>
        <Step>
            ### Install dependencies

            ```npm
            npm install
            ```
        </Step>
        <Step>
            ### 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
            ```

            <Callout type="info" title="What about other models?">
              The starter template is configured to use OpenAI's GPT-4o by default, but you can modify it to use any language model supported by Strands.
            </Callout>
        </Step>
        <Step>
            ### 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

            <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 install -D typescript @types/node tsx
                    npx tsc --init
                    ```
                </Tab>
            </Tabs>
        </Step>
        <Step>
            ### 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 cors
                    npm install -D @types/express @types/cors
                    # `@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

            Set your OpenAI API key as an environment variable:

            ```bash
            export OPENAI_API_KEY=your_openai_api_key
            ```

            <Callout type="info" title="What about other models?">
              This example uses OpenAI's GPT-4o, but you can modify it to use any language model supported by Strands.
            </Callout>
        </Step>
        <Step>
            ### 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-5.4",
                    )

                    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-5.4",
                    });

                    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

            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

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

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

            ```tsx title="app/api/copilotkit/route.ts"
            import {
              CopilotRuntime,
              ExperimentalEmptyAdapter,
              copilotRuntimeNextJSAppRouterEndpoint,
            } from "@copilotkit/runtime";
            import { HttpAgent } from "@ag-ui/client";
            import { NextRequest } from "next/server";

            const serviceAdapter = new ExperimentalEmptyAdapter();

            const runtime = new CopilotRuntime({
              agents: {
                strands_agent: new HttpAgent({ url: "http://localhost:8000" }),
              }
            });

            export const POST = async (req: NextRequest) => {
              const { handleRequest } = copilotRuntimeNextJSAppRouterEndpoint({
                runtime,
                serviceAdapter,
                endpoint: "/api/copilotkit",
              });

              return handleRequest(req);
            };
           ```
        </Step>
        <Step>
            ### Configure CopilotKit Provider

            Wrap your application with the CopilotKit provider:

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

            // ...

            export default function RootLayout({ children }: {children: React.ReactNode}) {
              return (
                <html lang="en">
                  <body>
                    <CopilotKit runtimeUrl="/api/copilotkit" agent="strands_agent">
                      {children}
                    </CopilotKit>
                  </body>
                </html>
              );
            }
            ```
        </Step>
        <Step>
          ### Add the chat interface

          Add the CopilotSidebar component to your page:

          ```tsx title="app/page.tsx"
          import { CopilotSidebar } from "@copilotkit/react-core/v2"; // [!code highlight:1]

          export default function Page() {
            return (
              <main>
                <h1>Your App</h1>
                <CopilotSidebar />
              </main>
            );
          }
          ```
        </Step>
        <Step>
            ### Start your agent

            From your agent directory, 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

            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!

    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>