DEV Community: Bonnie

Implementing Automatic LLM Provider Fallback In AI Agents Using an LLM Gateway (OpenAI, Anthropic, Gemini & Bifrost)

Bonnie — Thu, 02 Apr 2026 14:22:18 +0000

Every major LLM provider such as OpenAI, Anthropic, Gemini e.t.c, has experienced outages or rate-limiting incidents in the last twelve months.

As a developer, shipping AI-powered applications or AI agents depending on a single LLM provider is a production risk you cannot afford.

For that reason, you need to implement automatic LLM provider fallback in your app where AI requests are routed to backup LLM providers ( e.g, Anthropic or Gemini) the moment your primary provider (e.g, OpenAI) hits a rate limit, outage, or network error.

In this guide, you will learn how to implement automatic LLM provider fallback using the Bifrost LLM Gateway

Before we jump in, here is what we will be covering:

What is LLM provider fallback (and why it matters in production)?
How to set up Bifrost LLM gateway with multiple providers
How to configure automatic LLM provider failover
Testing LLM fallback with the Bifrost Mocker plugin

What is automatic LLM provider fallback?

LLM provider fallback (also called LLM provider failover) is the practice of automatically routing AI requests to backup providers when your primary provider encounters issues such as rate limiting, network errors, or outages.

Without a fallback strategy, a single provider incident can bring down your entire AI app hence frustrating users and eroding trust. With it, your application continues working transparently, as if nothing went wrong.

To implement automatic LLM provider failover, you can use an LLM gateway such as Bifrost. When your primary AI provider fails, Bifrost automatically tries backup providers in the order you specify using this process:

Primary attempt — Bifrost tries your configured primary provider and model first.
Automatic detection — If the primary fails, Bifrost detects the failure immediately.
Sequential fallbacks — Bifrost tries each fallback provider in order until one succeeds.
Success response — The response from the first successful provider is returned.
Complete failure — If all providers fail, Bifrost returns the original error from the primary provider.

You can read more about how fallbacks work in the Bifrost docs.

Prerequisites

Before we start, make sure you have the following:

Node.js 18+ (for running Bifrost via npx) or Docker (for containerized deployment)
API keys for the providers you want to use:
- OpenAI: platform.openai.com
- Anthropic: console.anthropic.com
- Google (Gemini): aistudio.google.com or Google Cloud (for Vertex)
Python 3.9+ or Node.js for writing the agent code
Go 1.21+ for automatic LLM provider failover demo using Bifrost Mocker plugin

Setting up and configuring LLM providers with Bifrost

In this section, you will how to set up Bifrost LLM gateway with multiple AI model providers that you can use with Claude Code.

Let’s get started.

Step 1: Install Bifrost using NPX binary

To install Bifrost, first, create your project folder named automatic-failover-demo and open it using your preferred code editor such as VS Code or Cursor.

Then run the command below with the **-app-dir** flag that determines where Bifrost stores all its data:

npx -y @maximhq/bifrost -app-dir ./my-bifrost-data

Step 2: Create a config.json file

Once you have installed Bifrost in your project, create a config.json file in the ./my-bifrost-data folder. Then add the code below that defines multiple LLM providers and database persistence.

{
  "$schema": "https://www.getbifrost.ai/schema",
  "client": {
    "enable_logging": true,
    "disable_content_logging": false,
    "drop_excess_requests": false,
    "initial_pool_size": 300,
    "allow_direct_keys": false
  },
  "providers": {
    "openai": {
      "keys": [
        {
          "name": "openai-primary",
          "value": "env.OPENAI_API_KEY",
          "models": [],
          "weight": 1.0
        }
      ]
    },
    "anthropic": {
      "keys": [
        {
          "name": "anthropic-primary",
          "value": "env.ANTHROPIC_API_KEY",
          "models": [],
          "weight": 1.0
        }
      ]
    },
    "gemini": {
      "keys": [
        {
          "name": "gemini-primary",
          "value": "env.GEMINI_API_KEY",
          "models": [],
          "weight": 1.0
        }
      ]
    }
  },
  "config_store": {
    "enabled": true,
    "type": "sqlite",
    "config": {
      "path": "./config.db"
    }
  },
  "logs_store": {
    "enabled": true,
    "type": "sqlite",
    "config": {
      "path": "./logs.db"
    }
  }
}

Step 3: Set up your API keys

After creating the config.json file, set your API keys as environment variables so they're never hardcoded using the commands below in the terminal.

export OPENAI_API_KEY="your-openai-api-key"
export ANTHROPIC_API_KEY="your-anthropic-api-key"
export GEMINI_API_KEY="your-gemini-api-key"

Step 4: Start Bifrost Gateway server

Once you have set up your API keys, start the Bifrost LLM gateway server by running the command below again (Make sure to stop the initial running server instance).

npx -y @maximhq/bifrost -app-dir ./my-bifrost-data

Then Bifrost will listen on port 8080, as shown below.

Finally, navigate to the gateway dashboard at http://localhost:8080 as shown below

Step 5: Verify the Setup

After installing and starting Bifrost, you can verify if it's working by running the curl command below in the terminal.

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Then you should get a response from the Bifrost LLM gateway, as shown below.

How to configure automatic LLM provider failover

To implement automatic LLM provider failover, add fallbacks array to the request payload, as shown below:

curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [
      {
        "role": "user",
        "content": "Explain what is an LLM gateway in simple terms"
      }
    ],
    "fallbacks": [
      "anthropic/claude-3-5-sonnet-20241022",
      "openrouter/anthropic.claude-3-sonnet-20240229-v1:0"
    ],
    "max_tokens": 1000,
    "temperature": 0.7
  }'

Bifrost will attempt OpenAI first. If that fails, it will try Anthropic. If Anthropic also fails, it will try Openrouter. The first successful response is returned.

After sending the request, the response format returned is a standard OpenAI-compatible JSON with an extra_fields object that tells you which provider actually handled the request, a shown below.

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "An LLM gateway is a proxy layer that sits between your application and multiple AI providers..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 18,
    "completion_tokens": 42,
    "total_tokens": 60
  },
  "extra_fields": {
    "provider": "anthropic",
    "latency": 1.34
  }
}

If extra_fields.provider is "anthropic" and you sent to "openai/gpt-4o-mini", you know a fallback was triggered.

Implementing automatic LLM provider fallback using Bifrost Mocker plugin

Bifrost triggers LLM provider fallback when it detects any of the following:

Network connectivity issues
Provider API errors (HTTP 500, 502, 503, 504)
Rate limiting (HTTP 429 errors)
Model unavailability
Request timeouts
Authentication failures

Rather than waiting for a real outage, you can use the Bifrost Mocker plugin to simulate these failure conditions and verify that your fallback chain works as expected.

In this section, we will mock a rate-limiting error to confirm that Bifrost automatically falls back from OpenAI to Anthropic.

Let’s get started!

Step 1: Initialize the Go Project

Start by creating a new directory for your project and initializing a Go module:

mkdir bifrost-fallback-demo
cd bifrost-fallback-demo
go mod init bifrost-fallback-demo

Step 2: Install Dependencies

After initializing the Go project, install the core Bifrost SDK and the Mocker plugin using the commands below:

go get github.com/maximhq/bifrost/core
go get github.com/maximhq/bifrost/plugins/mocker

Step 3: Set your API keys

Once you have installed the dependencies, set your LLM provider API keys as environment variables:

export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."

Step 4: Configure the Bifrost Account Interface

After setting your API keys, create a file named account.go that implements the schemas.Account interface required by Bifrost to know which providers are available and how to authenticate them, as shown below.

package main

import (
    "context"
    "fmt"
    "os"

    "github.com/maximhq/bifrost/core/schemas"
)

// MyAccount implements the schemas.Account interface with support
// for OpenAI (primary) and Anthropic (fallback) providers.
type MyAccount struct{}

// GetConfiguredProviders returns the list of AI providers this account supports.
// Step 1: Define the providers we want to configure for fallback logic.
func (a *MyAccount) GetConfiguredProviders() ([]schemas.ModelProvider, error) {
    // The order doesn't dictate fallback order here, but it lists all available providers.
    return []schemas.ModelProvider{
        schemas.OpenAI,
        schemas.Anthropic,
    }, nil
}

// GetKeysForProvider returns API keys for the given provider from env vars.
// Step 2: Implement key retrieval for each configured provider.
func (a *MyAccount) GetKeysForProvider(ctx context.Context, provider schemas.ModelProvider) ([]schemas.Key, error) {
    // Step 2a: Setup routing based on the requested provider.
    switch provider {
    case schemas.OpenAI:
        // Step 2b: Retrieve the OpenAI key from the environment.
        key := os.Getenv("OPENAI_API_KEY")
        if key == "" {
            return nil, fmt.Errorf("OPENAI_API_KEY environment variable is not set")
        }
        // Step 2c: Return the configured key.
        // The Weight controls how traffic is routed if multiple keys are present.
        return []schemas.Key{{
            Value:  *schemas.NewEnvVar(key),
            Models: []string{}, // Empty = all models
            Weight: 1.0,
        }}, nil

    case schemas.Anthropic:
        // Step 2d: Retrieve the Anthropic key from the environment.
        key := os.Getenv("ANTHROPIC_API_KEY")
        if key == "" {
            return nil, fmt.Errorf("ANTHROPIC_API_KEY environment variable is not set")
        }
        // Step 2e: Return the Anthropic key with identical configuration format.
        return []schemas.Key{{
            Value:  *schemas.NewEnvVar(key),
            Models: []string{}, // Empty = all models
            Weight: 1.0,
        }}, nil

    default:
        // Step 2f: Handle unconfigured providers gracefully with an error.
        return nil, fmt.Errorf("provider %s not supported", provider)
    }
}

// GetConfigForProvider returns provider-specific network and concurrency config.
// Step 3: Define connection parameters (like rate limits and timeouts) for each provider.
func (a *MyAccount) GetConfigForProvider(provider schemas.ModelProvider) (*schemas.ProviderConfig, error) {
    // Step 3a: Apply configuration to supported providers.
    switch provider {
    case schemas.OpenAI, schemas.Anthropic:
        // Step 3b: Return the default Bifrost network and concurrency settings 
        // for both OpenAI and Anthropic to simplify the setup.
        return &schemas.ProviderConfig{
            NetworkConfig:            schemas.DefaultNetworkConfig,
            ConcurrencyAndBufferSize: schemas.DefaultConcurrencyAndBufferSize,
        }, nil
    default:
        // Step 3c: Reject unsupported providers.
        return nil, fmt.Errorf("provider %s not supported", provider)
    }
}

Step 5: Configure Bifrost Chat Request

Once you have configured the Bifrost account interface, create a main.go file with a helper function that builds a schemas.BifrostChatRequest. The chat request configures the request to target your primary provider (OpenAI) and explicitly define the fallback chain (Anthropic), as shown below:

package main

import (
    "context"
    "fmt"
    "log"
    "time"

    bifrost "github.com/maximhq/bifrost/core"
    "github.com/maximhq/bifrost/core/schemas"
    mocker "github.com/maximhq/bifrost/plugins/mocker"
)

// --- Pointer helpers ---

func stringPtr(s string) *string { return &s }
func boolPtr(b bool) *bool       { return &b }
func intPtr(i int) *int           { return &i }

// buildChatRequest creates a standard chat request targeting OpenAI
// with Anthropic as the fallback provider.
// Step 1: Define the chat request with OpenAI as primary and Anthropic as a fallback.
func buildChatRequest(message string) *schemas.BifrostChatRequest {
    return &schemas.BifrostChatRequest{
        Provider: schemas.OpenAI,
        Model:    "gpt-4o-mini",
        Input: []schemas.ChatMessage{
            {
                Role: schemas.ChatMessageRoleUser,
                Content: &schemas.ChatMessageContent{
                    ContentStr: schemas.Ptr(message),
                },
            },
        },
        // Fallback chain: OpenAI → Anthropic
        Fallbacks: []schemas.Fallback{
            {
                Provider: schemas.Anthropic,
                Model:    "claude-sonnet-4-5-20250929",
            },
        },
        Params: &schemas.ChatParameters{
            MaxCompletionTokens: bifrost.Ptr(200),
            Temperature:         bifrost.Ptr(0.7),
        },
    }
}

Step 6: Configure the Mocker Plugin and Initialize the Bifrost Client

After configuring Bifrost chat interface, configure the Mocker Plugin and initialize the Bifrost Client by mocking rate limiting fallback trigger in the main.go file, as shown below:

package main

import (
    "context"
    "fmt"
    "log"
    "time"

    bifrost "github.com/maximhq/bifrost/core"
    "github.com/maximhq/bifrost/core/schemas"
    mocker "github.com/maximhq/bifrost/plugins/mocker"
)

// --- Pointer helpers ---

func stringPtr(s string) *string { return &s }
func boolPtr(b bool) *bool       { return &b }
func intPtr(i int) *int           { return &i }

// ...

// =====================================================================
// Scenario 1: Mock Error → Fallback Succeeds
// =====================================================================
// Mocker always returns a 429 rate-limit error for OpenAI,
// but AllowFallbacks=true lets Bifrost try Anthropic.

func runScenario1() {
    fmt.Println("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━")
    fmt.Println("SCENARIO 1: Mock Error → Fallback Succeeds")
    fmt.Println("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━")
    fmt.Println("  Primary:  OpenAI   (will be mocked with 429 error)")
    fmt.Println("  Fallback: Anthropic (real provider)")
    fmt.Println("  AllowFallbacks: true")
    fmt.Println()

    // Step 2: Configure the Mocker plugin. We will set up a rule that always
    // triggers a 429 rate limit error for OpenAI requests.
    plugin, err := mocker.Init(mocker.MockerConfig{
        Enabled: true,
        Rules: []mocker.MockRule{
            {
                Name:        "openai-rate-limit",
                Enabled:     true,
                Priority:    100,
                Probability: 1.0, // Always trigger
                Conditions: mocker.Conditions{
                    Providers: []string{"openai"},
                },
                Responses: []mocker.Response{
                    {
                        Type:           mocker.ResponseTypeError,
                        AllowFallbacks: boolPtr(true), // ← KEY: allow Bifrost to try fallbacks
                        Error: &mocker.ErrorResponse{
                            Message:    "Rate limit exceeded",
                            Type:       stringPtr("rate_limit"),
                            Code:       stringPtr("429"),
                            StatusCode: intPtr(429),
                        },
                    },
                },
                Latency: &mocker.Latency{
                    Type: mocker.LatencyTypeFixed,
                    Min:  100 * time.Millisecond, // Simulate slight network delay
                },
            },
        },
    })
    if err != nil {
        log.Fatalf("Scenario 1 — plugin creation failed: %v", err)
    }

    // Step 3: Initialize the Bifrost client, attaching our Account definition and the plugin.
    client, initErr := bifrost.Init(context.Background(), schemas.BifrostConfig{
        Account:    &MyAccount{},
        LLMPlugins: []schemas.LLMPlugin{plugin},
        Logger:     bifrost.NewDefaultLogger(schemas.LogLevelInfo),
    })
    if initErr != nil {
        log.Fatalf("Scenario 1 — Bifrost init failed: %v", initErr)
    }
    defer client.Shutdown()

    // Step 4: Execute the ChatCompletionRequest. Bifrost will attempt OpenAI first,
    // encounter the rate limit error from the mocker, and automatically fallback to Anthropic.
    response, bifrostErr := client.ChatCompletionRequest(
        schemas.NewBifrostContext(context.Background(), schemas.NoDeadline),
        buildChatRequest("What is the capital of France? Reply in one sentence."),
    )
    if bifrostErr != nil {
        // Step 5: Handle the final error (if both primary and fallback fail).
        fmt.Printf("  ❌ Request failed: %v\n\n", bifrostErr.Error.Message)
        return
    }

    // Step 6: Process the successful response.
    fmt.Printf("  ✅ Fallback succeeded!\n")
    fmt.Printf("  Provider: %s\n", response.ExtraFields.Provider)
    fmt.Printf("  Response: %s\n\n", *response.Choices[0].Message.Content.ContentStr)
}

// =====================================================================
// Main
// =====================================================================

func main() {
    fmt.Println()
    fmt.Println("╔══════════════════════════════════════════════════╗")
    fmt.Println("║  Bifrost Mocker Plugin — Fallback Demo           ║")
    fmt.Println("╚══════════════════════════════════════════════════╝")
    fmt.Println()

    runScenario1()

    fmt.Println("Done!")
}

Step 7: Run the demo

Once you have configured the Mocker Plugin and initialized the Bifrost Client by mocking rate limiting fallback trigger, run the demo using the command below:

go run .

After running the demo, you should see that a rate limiting error by OpenAI provider triggered an automatic fallback to Anthropic provider as shown below:

Step 8: Mock other fallback triggers

If you want to mock other fallback triggers such as Network connectivity issues, Provider API errors (500, 502, 503, 504), Request timeouts and Authentication failures, clone the demo repo from GitHub using the command below,

git clone https://github.com/TheGreatBonnie/automatic-llm-provider-fallback-demo.git

Then set your LLM provider API keys as environment variables:

export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."

Finally run the demos

go run .

Congratulations! You have successfully implemented automatic LLM provider failover or fall back.

Conclusion

Automatic LLM provider fallback is one of the most effective ways to harden your AI agents against the outages, rate limits, and network issues that are an inevitable part of production.

In this guide, you:

Set up Bifrost as an OpenAI-compatible LLM gateway
Configured multiple AI providers (OpenAI, Anthropic, Gemini)
Implemented a fallback chain so requests automatically move from a failing primary model to backup providers
Tested fallback behavior locally using the Bifrost Mocker plugin without waiting for a real outage

As a next step, explore Bifrost's other reliability features to build an even more resilient AI stack.

Explore Bifrost:

🌐 Website: https://getmax.im/bifrost-home
📦 GitHub: https://git.new/bifrostrepo
📘 Docs (Quickstart): https://getmax.im/bifrostdocs

How To Use Claude Code With Any AI Model Using an LLM Gateway (Bifrost)

Bonnie — Sat, 07 Mar 2026 15:49:40 +0000

Unless you live under a rock, vibe coding has been the talk of the town in software development for a while now since AI coding tools became a thing.

And one of the most popular and capable AI coding tool developers can use today is Claude Code by Anthropic.

Claude Code can read your repository, run commands, modify files, and help implement features directly from the terminal using only Anthropic’s own AI models.

But what if you want to use Claude Code with different LLM providers instead of being tied to a single one?

Maybe you want to:

Switch between Anthropic, OpenAI, or Gemini
Use a cheaper model for simple tasks
Fall back to another provider during outages
Route requests for performance or cost optimization

This is where an LLM gateway becomes incredibly useful.

In this guide, you will learn how to connect Claude Code to any LLM using the Bifrost LLM gateway.

Before we jump in, here is what we will cover:

Why Bifrost LLM gateway?
Setting up and configuring LLM providers with Bifrost LLM gateway
Integrating Claude Code with Bifrost LLM gateway
Running Claude Code with any AI model.
Enabling built-in observability and monitoring
Integrating MCP tools

Let’s dive in.

Why Bifrost LLM gateway?

Bifrost is an open-source LLM gateway built by Maxim AI to route, manage, and optimize requests between your AI application and multiple large language model providers.

The LLM gateway is built using Go (Golang) for performance and below is what makes it stand out:

Blazing fast overhead: At 5,000 requests per second, Bifrost adds less than 15 microseconds of internal overhead per request which is very important at production scale.
Zero-config startup: You can launch Bifrost with a single npx command and configure everything through a web UI.
Built-in fallbacks and load balancing: If a provider fails or rate-limits you, Bifrost automatically routes to a backup. Traffic can be distributed across multiple keys or providers using weighted rules.
Semantic caching: Repeated or similar queries can be served from cache, which helps in cutting costs and reducing latency.
**Observability: **Bifrost offers Prometheus metrics, request tracing, and a built-in web dashboard out of the box.

Bifrost supports 15+ providers including OpenAI, Anthropic, Google Gemini (via Vertex or GenAI), AWS Bedrock, Azure, Mistral, Cohere, Groq, and more.

You can learn more about Bifrost LLM gateway here on there website.

Prerequisites

Before we start, make sure you have the following:

Node.js 18+ (for running Bifrost via npx) or Docker (for containerized deployment)
API keys for the providers you want to use:
- OpenAI: platform.openai.com
- Anthropic: console.anthropic.com
- Google (Gemini): aistudio.google.com or Google Cloud (for Vertex)

Let’s get started!

Setting up and configuring LLM providers with Bifrost

In this section, you will how to set up Bifrost LLM gateway with multiple AI model providers that you can use with Claude Code.

Let’s get started.

Step 1: Install Bifrost using NPX binary

To install Bifrost, first, create your project folder named claude-code-demo and open it using your preferred code editor such as VS Code or Cursor.

Then run the command below with the **-app-dir** flag that determines where Bifrost stores all its data:

npx -y @maximhq/bifrost -app-dir ./my-bifrost-data

Step 2: Create a config.json file

Once you have installed Bifrost in your project, create a config.json file in the ./my-bifrost-data folder. Then add the code below that defines multiple LLM providers and database persistence.

{
  "$schema": "https://www.getbifrost.ai/schema",
  "client": {
    "enable_logging": true,
    "disable_content_logging": false,
    "drop_excess_requests": false,
    "initial_pool_size": 300,
    "allow_direct_keys": false
  },
  "providers": {
    "openai": {
      "keys": [
        {
          "name": "openai-primary",
          "value": "env.OPENAI_API_KEY",
          "models": [],
          "weight": 1.0
        }
      ]
    },
    "anthropic": {
      "keys": [
        {
          "name": "anthropic-primary",
          "value": "env.ANTHROPIC_API_KEY",
          "models": [],
          "weight": 1.0
        }
      ]
    },
    "gemini": {
      "keys": [
        {
          "name": "gemini-primary",
          "value": "env.GEMINI_API_KEY",
          "models": [],
          "weight": 1.0
        }
      ]
    }
  },
  "config_store": {
    "enabled": true,
    "type": "sqlite",
    "config": {
      "path": "./config.db"
    }
  },
  "logs_store": {
    "enabled": true,
    "type": "sqlite",
    "config": {
      "path": "./logs.db"
    }
  }
}

Step 3: Set up your API keys

After creating the config.json file, set your API keys as environment variables so they're never hardcoded using the commands below in the terminal.

export OPENAI_API_KEY="your-openai-api-key"
export ANTHROPIC_API_KEY="your-anthropic-api-key"
export GEMINI_API_KEY="your-gemini-api-key"

Step 4: Start Bifrost Gateway server

Once you have set up your API keys, start the Bifrost LLM gateway server by running the command below again (Make sure to stop the initial running server instance).

npx -y @maximhq/bifrost -app-dir ./my-bifrost-data

Then Bifrost will listen on port 8080, as shown below.

Finally, navigate to the gateway dashboard at http://localhost:8080 as shown below

Integrating Claude Code with Bifrost LLM gateway

In this section, you will learn how to integrate Claude Code with Bifrost LLM gateway in order to use it with any AI model.

Let’s get started.

Step 1: Install Claude Code

To install Claude Code, run the command below in the command line:

npm install -g @anthropic-ai/claude-code

Step 2: Point Claude Code at Bifrost

Once you have installed Claude Code, point it at Bifrost LLM gateway by setting the environment variables below in the terminal where ANTHROPIC_BASE_URL tells Claude Code to send its API requests to Bifrost instead of Anthropic's servers:

export ANTHROPIC_BASE_URL="http://localhost:8080/anthropic"
export ANTHROPIC_API_KEY="dummy-key"

Step 3: Run Claude Code with Any Model

After pointing Claude Code at Bifrost, start and run Claude Code with with any model such OpenAI GPT 5.2-codex model using the command below.

claude --model openai/gpt-5.2-codex

Then you should see Claude Code running, as shown below:

Step 4: Verify the setup

Once Claude Code is running, verify it setup with Bifrost using a simple query such as, “Hello there.” You should see the response in Claude Code, as shown below:

Integrating MCP tools

In this section, you will learn how to integrate MCP tools with Bifrost to allow Claude Code to connect directly and access the tools.

Let’s get started!

Step 1: Connect Bifrost to MCP server

To connect Bifrost to MCP server for let’s say filesystem, update the config.json file with the code below:

{
  "$schema": "https://www.getbifrost.ai/schema",
  "client": {
    "enable_logging": true,
    "disable_content_logging": true,
    "drop_excess_requests": false,
    "initial_pool_size": 300,
    "allow_direct_keys": false
  },

 // ...

  "mcp": {
    "client_configs": [
      {
        "name": "filesystem",
        "connection_type": "stdio",
        "stdio_config": {
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
        },
        "tools_to_execute": ["*"],
        "tools_to_auto_execute": [
          "read_file",
          "list_directory",
          "create_file",
          "delete_file"
        ]
      }
    ],
    "tool_manager_config": {
      "max_agent_depth": 10,
      "tool_execution_timeout": 300000000000,
      "code_mode_binding_level": "server"
    }
  }
}

Then restart Bifrost server and navigate to the MCP catalog page in the web UI. You should see the filesystem MCP server connected, as shown below:

Step 2: Connect Claude Code to Bifrost MCP

Once you have connected MCP server to Bifrost, add Bifrost as an MCP server to Claude Code using the command below:

claude mcp add --transport http bifrost http://localhost:8080/mcp

Step 3: Execute a coding task

After connecting Claude Code to Bifrost MCP, restart it and execute a simple coding task using the prompt below:

Create a simple calculator program in Python.

It should support:
- addition
- subtraction
- multiplication
- division

The user should input two numbers and an operation, and the program should print the result.

Claude Code should create a python file with the calculator code. Then run the prompt below that analyzes your codebase and creates a Readme file.

Analyze this repository and create a README.md explaining how the project works.

Include the project architecture and instructions for running it locally.

Once Claude Code completes the run, the Readme file should be created, as shown below:

Built-in observability and monitoring

Bifrost provides built-in observability and monitoring by logging all traffic passing through the gateway.

The web interface at http://localhost:8080/logs provides:

Real-time streaming of requests and responses
Token usage tracking per request
Latency measurements
Filtering by provider, model, or conversation content
Full request/response inspection

You can also monitor LLM logs with requests, latency, tokens and cost, a shown below:

Conclusion

In conclusion, Claude Code is already one of the most powerful AI development assistants available today.

By combining it with an LLM gateway like Bifrost unlocks even more flexibility where you can:

Use any AI provider
Dynamically switch models
Integrate MCP tools
Monitor responses, tokens, latency and usage cost

Finally, feel free to explore Bifrost and try it yourself using the links below:

🌐 Website: https://getmax.im/bifrost-home
📦 GitHub: https://git.new/bifrostrepo
📘 Docs (Quickstart): https://getmax.im/bifrostdocs

Building AI Agent With Multiple AI Model Providers Using an LLM Gateway (OpenAI, Anthropic, Gemini & Bifrost)

Bonnie — Tue, 24 Feb 2026 15:11:21 +0000

Imagine building an AI agent that uses only one LLM provider such as OpenAI, Gemini or Anthropic through their specific APIs.

While in production, your AI agent LLM provider hits a rate limit during a traffic spike or has a partial outage or you realize that different tasks in your agent’s workflow are better suited for different AI models entirely.

To avoid such issues, you need to integrate a multi AI model provider system using an LLM gateway.

The LLM gateway handles AI model selection, authentication, failover, load balancing, routing and observability without changing your AI agent code.

In this guide, you will learn how build an AI agent with multi AI model provider consisting of OpenAI, Gemini and Anthropic using Bifrost.

Before we jump in, here is what we will cover:

What is an LLM Gateway (and why Bifrost)?
Setting up Bifrost with multiple AI providers
Building the AI agent
Implementing Load balancing
Implementing Routing Rules

Let’s jump in!

What is an LLM Gateway (and Why Bifrost)?

An LLM gateway is a middleware layer that sits between your AI agent and one or more AI model providers.

Instead of writing code for OpenAI's API format, Anthropic's authentication scheme, and Gemini's endpoint structure, your AI agent simply sends requests to the gateway in a standard format, and the gateway takes care of the rest.

In simple terms, an LLM gateway routes model requests without your agent needing to know how each LLM provider handles requests and responses.

But why will we be using Bifrost in this guide?

Bifrost is an open-source LLM gateway built by Maxim AI to route, manage, and optimize requests between your AI application and multiple large language model providers.

The LLM gateway is built using Go (Golang) for performance and below is what makes it stand out:

Blazing fast overhead: At 5,000 requests per second, Bifrost adds less than 15 microseconds of internal overhead per request which is very important at production scale.
Zero-config startup: You can launch Bifrost with a single npx command and configure everything through a web UI.
Built-in fallbacks and load balancing: If a provider fails or rate-limits you, Bifrost automatically routes to a backup. Traffic can be distributed across multiple keys or providers using weighted rules.
Semantic caching: Repeated or similar queries can be served from cache, which helps in cutting costs and reducing latency.
Observability: Bifrost offers Prometheus metrics, request tracing, and a built-in web dashboard out of the box.

Bifrost supports 15+ providers including OpenAI, Anthropic, Google Gemini (via Vertex or GenAI), AWS Bedrock, Azure, Mistral, Cohere, Groq, and more.

You can learn more about Bifrost LLM gateway here on there website.

Prerequisites

Before we start, make sure you have the following:

Node.js 18+ (for running Bifrost via npx) or Docker (for containerized deployment)
API keys for the providers you want to use:
- OpenAI: platform.openai.com
- Anthropic: console.anthropic.com
- Google (Gemini): aistudio.google.com or Google Cloud (for Vertex)
Python 3.9+ or Node.js for writing the agent code

Setting up Bifrost with Multiple LLM providers

In this section, you will how to set up Bifrost LLM gateway with multiple AI model providers for your AI agent or application.

Let’s get started.

Step 1: Install Bifrost using NPX binary

To install Bifrost, first, create your project folder named multi-provider-agent and open it using your preferred code editor such as VS Code or Cursor.

Then run the command below with the -app-dir flag that determines where Bifrost stores all its data:

npx -y @maximhq/bifrost -app-dir ./my-bifrost-data

Step 2: Create a config.json file

Once you have installed Bifrost in your project, create a config.json file in the ./my-bifrost-data folder. Then add the code below that defines multiple LLM providers and database persistence.

{
  "$schema": "https://www.getbifrost.ai/schema",
  "client": {
    "drop_excess_requests": false
  },
  "providers": {
    "openai": {
      "keys": [
        {
          "name": "openai-primary",
          "value": "env.OPENAI_API_KEY",
          "models": [],
          "weight": 1.0
        }
      ]
    },
    "anthropic": {
      "keys": [
        {
          "name": "anthropic-primary",
          "value": "env.ANTHROPIC_API_KEY",
          "models": [

          ],
          "weight": 1.0
        }
      ]
    },
    "gemini": {
      "keys": [
        {
          "name": "gemini-primary",
          "value": "env.GEMINI_API_KEY",
          "models": [],
          "weight": 1.0
        }
      ]
    }
  },
  "config_store": {
    "enabled": true,
    "type": "sqlite",
    "config": {
      "path": "./config.db"
    }
  }
}

Step 3: Set up your API keys

After creating the config.json file, set your API keys as environment variables so they're never hardcoded using the commands below in the terminal.

export OPENAI_API_KEY="your-openai-api-key"
export ANTHROPIC_API_KEY="your-anthropic-api-key"
export GEMINI_API_KEY="your-gemini-api-key"

Step 4: Start Bifrost Gateway server

Once you have set up your API keys, start the Bifrost LLM gateway server by running the command below again (Make sure to stop the initial running server instance).

npx -y @maximhq/bifrost -app-dir ./my-bifrost-data

Then Bifrost will listen on port 8080, as shown below.

Finally, navigate to the gateway dashboard at http://localhost:8080 as shown below

Step 5: Verify the Setup

After installing and starting Bifrost, you can verify if it's working by running the curl command below in the terminal.

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Then you should get a response from the Bifrost LLM gateway, as shown below.

Building an AI agent with multiple AI models using Bifrost and LangChain (LangGraph)

In this section, you will learn how to build an AI agent with multiple AI models using Bifrost and LangGraph.

You can learn how to set up Bifrost with LangGraph using LangChain SDK here on Bifrost docs.

Let’s get started.

Step 1: Set up a Python virtual environment

To set up a Python virtual environment for your project, run the commands below in the terminal to create and activate a virtual environment.

# Create a virtual environment
python3 -m venv venv

# Activate it
source venv/bin/activate

Step 2: Install LangGraph dependencies

After setting up a Python virtual environment, install LangGraph dependencies in your project by running the command below in the terminal.

pip install langgraph langchain-openai

Step 3: Configure your AI agent

Once you have installed LangGraph dependencies, create an agent.py file in your project folder and add the following code that sets up a Multi-Provider Research Agent with LangGraph.

import os
from typing import TypedDict, Annotated
from langchain_openai import ChatOpenAI
from langchain_core.messages import HumanMessage, AIMessage, SystemMessage
from langchain_core.tools import tool
from langgraph.graph import StateGraph, END
from langgraph.prebuilt import ToolNode
import operator

BIFROST_URL = "http://localhost:8080"

# ─────────────────────────────────────────────
# Model definitions — all pointing at Bifrost
# ─────────────────────────────────────────────

# Deep reasoning: complex planning and analysis
planner_llm = ChatOpenAI(
    model="openrouter/claude-3.7-sonnet",
    base_url=f"{BIFROST_URL}/v1",
    api_key="dummy",
    max_tokens=2048
)

# General purpose: tool use and synthesis
executor_llm = ChatOpenAI(
    model="openai/gpt-4o",
    base_url=f"{BIFROST_URL}/v1",
    api_key="dummy",
    max_tokens=2048
)

# Fast and cheap: lightweight formatting and summaries
summarizer_llm = ChatOpenAI(
    model="gemini/gemini-2.0-flash",
    base_url=f"{BIFROST_URL}/v1",
    api_key="dummy",
    max_tokens=1024
)

# ─────────────────────────────────────────────
# Tools
# ─────────────────────────────────────────────

@tool
def search_web(query: str) -> str:
    """Search the web for information on a given topic."""
    # Replace with a real search implementation (e.g. Tavily, SerpAPI)
    return f"[Search results for '{query}': Sample results would appear here]"

@tool
def calculate(expression: str) -> str:
    """Evaluate a mathematical expression."""
    try:
        result = eval(expression, {"__builtins__": {}})
        return str(result)
    except Exception as e:
        return f"Calculation error: {e}"

tools = [search_web, calculate]
tool_node = ToolNode(tools)
executor_with_tools = executor_llm.bind_tools(tools)

# ─────────────────────────────────────────────
# State
# ─────────────────────────────────────────────

class AgentState(TypedDict):
    messages: Annotated[list, operator.add]
    research_plan: str
    final_summary: str

# ─────────────────────────────────────────────
# Nodes
# ─────────────────────────────────────────────

def planner_node(state: AgentState) -> dict:
    """
    Uses Claude Opus via Bifrost.
    Analyses the user's request and produces a structured research plan.
    """
    messages = [
        SystemMessage(content="""You are a strategic research planner. 
        Given a user's question, create a clear, step-by-step research plan 
        that identifies: what information is needed, what tools to use, 
        and what the final answer should look like."""),
    ] + state["messages"]

    response = planner_llm.invoke(messages)

    return {
        "messages": [response],
        "research_plan": response.content
    }

def executor_node(state: AgentState) -> dict:
    """
    Uses GPT-4o via Bifrost with tool access.
    Executes the research plan by calling tools and gathering information.
    """
    messages = [
        SystemMessage(content=f"""You are a research executor. 
        Follow this plan carefully and use the available tools to gather 
        the required information:

        {state.get('research_plan', 'Gather information to answer the user question.')}"""),
    ] + state["messages"]

    response = executor_with_tools.invoke(messages)
    return {"messages": [response]}

def summarizer_node(state: AgentState) -> dict:
    """
    Uses Gemini Flash via Bifrost.
    Takes the gathered research and produces a clean, concise final answer.
    """
    # Collect all content from the conversation
    research_content = "\n\n".join([
        msg.content for msg in state["messages"] 
        if hasattr(msg, "content") and msg.content
    ])

    messages = [
        SystemMessage(content="""You are a concise summarizer. 
        Given research findings, produce a clear, well-structured final answer. 
        Be direct and helpful. Remove redundancy."""),
        HumanMessage(content=f"Research gathered:\n\n{research_content}\n\nProvide the final answer.")
    ]

    response = summarizer_llm.invoke(messages)

    return {
        "messages": [response],
        "final_summary": response.content
    }

def should_use_tools(state: AgentState) -> str:
    """Conditional edge: if the executor requested tool calls, run them."""
    last_message = state["messages"][-1]
    if hasattr(last_message, "tool_calls") and last_message.tool_calls:
        return "tools"
    return "summarizer"

# ─────────────────────────────────────────────
# Graph assembly
# ─────────────────────────────────────────────

def build_research_agent() -> StateGraph:
    graph = StateGraph(AgentState)

    graph.add_node("planner", planner_node)
    graph.add_node("executor", executor_node)
    graph.add_node("tools", tool_node)
    graph.add_node("summarizer", summarizer_node)

    graph.set_entry_point("planner")
    graph.add_edge("planner", "executor")
    graph.add_conditional_edges(
        "executor",
        should_use_tools,
        {"tools": "tools", "summarizer": "summarizer"}
    )
    graph.add_edge("tools", "executor")   # Loop back after tool use
    graph.add_edge("summarizer", END)

    return graph.compile()

# ─────────────────────────────────────────────
# Run it
# ─────────────────────────────────────────────

if __name__ == "__main__":
    agent = build_research_agent()

    questions = [
        "What are the key differences between transformer and mamba architectures for language models?",
        "If a company grows revenue 23% YoY from $4.2M, what is the new revenue?",
    ]

    for question in questions:
        print(f"\n{'='*60}")
        print(f"Question: {question}")

        result = agent.invoke({
            "messages": [HumanMessage(content=question)],
            "research_plan": "",
            "final_summary": ""
        })

        print(f"\nFinal Answer:\n{result['final_summary']}")

Step 4: Run your agent

After setting up your AI agent, run it by executing the following command in the terminal.

python agent.py

Once the AI agent runs and completes its workflow, you should see the response on the terminal, as shown below.

Implementing Load balancing

In this section, you will learn how to implement load balancing in your AI agent using Bifrost. But before we get started, let’s understand what is load balancing.

What is load balancing in Bifrost?

In Bifrost, Load balancing means distributing AI requests across multiple API keys and AI models instead of sending all traffic to a single key.

Sending all your AI agent traffic to a single API key can lead to the following issues:

You can hit rate limits
Requests can fail when traffic spikes
One key outage breaks everything
Performance becomes unstable

However, if you implement load balancing using Bifrost, your AI agent can:

Share traffic across several keys
Automatically switch if one key fails
Avoid overloading a single provider

Load balancing in Bifrost is implemented using two methods which are weighted load balancing and Model Whitelisting & Filtering.

In weighted load balancing, you assign a weight to each API key where openai-primary handles ~70% of requests and openai-secondary handles ~30%, as shown below.

"providers": {
    "openai": {
      "keys": [
        {
          "name": "openai-primary",
          "value": "env.OPENAI_API_KEY_PRIMARY",
          "models": ["gpt-4o", "gpt-4o-mini",],
          "weight": 0.7
        },
        {
          "name": "openai-secondary",
          "value": "env.OPENAI_API_KEY_SECONDARY",
          "models": [],
          "weight": 0.3
        }
      ]
    }, 
 }

In Model Whitelisting & Filtering, keys can be restricted to specific models for access control and cost management, a shown below. A request for gpt-4o will only be routed to premium-key while a request to gpt-4o-mini will only use standard-key

"providers": {
    "openai": {
      "keys": [
        {
          "name": "premium-key",
          "value": "env.OPENAI_API_KEY_PREMIUM",
          "models": ["gpt-4o", "o1-preview"],
          "weight": 1.0
        },
        {
          "name": "standard-key",
          "value": "env.OPENAI_API_KEY_STANDARD",
          "models": [],
          "weight": 1.0
        }
      ]
    }, 
 }

You can learn more about about load balancing here on Bifrost docs.

Implementing Routing Rules

In this section, you will learn how to implement routing rules in your AI agent. Before we get started, let’s understand what are routing rules in Bifrost.

What are routing rules in Bifrost?

Routing rules in Bifrost are like traffic signs for your AI requests. They tell Bifrost where to send each request based on conditions you define.

Instead of always using the same AI model or provider, routing rules let you say things like, “If the request looks like this, send it to that provider.”

For example:

If a request is for summarization, use a cheaper model
If the user is a premium customer, use a more powerful model
If one provider is too busy, send the request to another provider

Everytime your AI agent sends a request, Bifrost checks these rules. The first rule that matches the request is sent to the chosen provider and model.

If no rule matches the request, Bifrost simply falls back to its default behavior, such as load balancing between providers.

To implement routing rules, define them in the config.json file, as shown below.

"governance": {
    "routing_rules": [
      {
        "id": "rule-uuid-123",
        "name": "Premium Tier Route",
        "description": "Route premium users to fast provider",
        "enabled": true,
        "cel_expression": "headers[\"x-tier\"] == \"premium\"",
        "provider": "openrouter",
        "model": "claude-3.7-sonnet",
        "fallbacks": ["openrouter/gpt-4o", "openrouter/gpt-3.5-turbo"],
        "scope": "global",
        "scope_id": null,
        "priority": 10
      },
      {
        "id": "rule-uuid-456",
        "name": "Budget Overflow Route",
        "description": "Route to cheaper provider when budget is high",
        "enabled": true,
        "cel_expression": "budget_used > 85",
        "provider": "groq",
        "model": "llama-2-70b",
        "fallbacks": [],
        "scope": "team",
        "scope_id": "team-ml-ops",
        "priority": 5
      },
      {
        "id": "team-preference",
        "name": "ML Team Anthropic Route",
        "enabled": true,
        "cel_expression": "team_name == \"ml-research\"",
        "provider": "anthropic",
        "model": "claude-3-opus-20240229",
        "fallbacks": ["bedrock/claude-3-opus"],
        "scope": "team",
        "scope_id": "team-ml-research",
        "priority": 0
      }
    ]
  },

After defining the routing rules, you can pass the routing rules in your AI agent request, as shown below.

# Deep reasoning: complex planning and analysis
planner_llm = ChatOpenAI(
    model="openrouter/claude-3.7-sonnet",
    base_url=f"{BIFROST_URL}/v1",
    api_key="dummy",
    default_headers={
        'x-tier': 'premium',
    },
    max_tokens=2048
)

You can learn more about about routing rules here on Bifrost docs.

Conclusion

In conclusion, building AI agents that rely on a single LLM provider is risky and limits flexibility. By using an LLM gateway like Bifrost, you can create a multi-provider AI agent that is resilient, scalable, and future-proof.

Finally, If you’re building or scaling an AI application and performance is becoming a bottleneck, explore Bifrost and try it yourself:

🌐 Website: https://getmax.im/bifrost-home
📦 GitHub: https://git.new/bifrostrepo
📘 Docs (Quickstart): https://getmax.im/bifrostdocs

How a Go-Based LLM Gateway Achieves Extreme Performance Gains (Bifrost vs LiteLLM)

Bonnie — Wed, 11 Feb 2026 14:29:39 +0000

Unless you live under a rock, AI has been the talk of the town since 2022 when ChatGPT was announced to the world powered by a Large Language Model (LLM).

Since then, the Large Language Models (LLMs) such as OpenAI’s GPT series, Anthropic’s Claude, and Google’s Gemini, have become the back bone of AI-powered applications.

However, as these AI-powered applications scale, they encounter the following issues:

If performance drops or prices rise when using one LLM provider, migrating to another LLM requires changing code frequently.
Using different LLM providers becomes a bottleneck since each LLM provider defines their API requests and responses differently.
Monitoring usage, optimizing cost, and debugging issues across different LLMs becomes a nightmare when everything is scattered across direct LLM provider APIs.

That’s where LLM Gateways comes in.

Understanding what is an LLM gateway?

In simple terms, an LLM gateway can be described as a middle man who routes, manages, optimizes and monitors requests together with responses from your AI-powered app to different LLM providers.

Below is an illustration of an LLM gateway.

In this guide, we will cover how a Go-based LLM gateway named Bifrost achieves extreme performance gains over LiteLLM, a python-based LLM gateway.

Before we get started, here is what we will cover:

Understanding what is an LLM gateway
What is Bifrost and why was it built?
Bifrost vs LiteLLM performance comparison
Advantages of Go-based design architecture over Python-based design architecture.
Bifrost key features that improve performance gains
How to get started with Bifrost

Let’s jump in!

What is Bifrost?

Bifrost is a high-performance LLM gateway designed to route, manage, and optimize requests between your AI application and multiple large language model providers such as OpenAI, Anthropic, Gemini and others.

It acts as a single entry point for all LLM traffic, providing a unified API, built-in observability, and performance optimizations that make it suitable for production AI systems.

You can learn more about Bifrost LLM gateway here on there website.

Why Was Bifrost Built?

As LLM-powered applications moved from experimentation to production, teams began facing several challenges:

**Extreme Latency & Speed: **Existing LLM gateways became performance bottlenecks under high traffic
**Reliability at Scale: **Under heavy load (500+ requests per second), other gateways started failing requests or consuming excessive memory.
Unified Control: Standardizing the fragmented API landscape so developers don't have to rewrite code when switching models.

Instead of being another LLM proxy, Bifrost was built to be the fastest, and most scalable LLM gateway where it is:

Blazing fast: Built in Go, Bifrost introduces <15µs* internal overhead per request at 5000 RPS.
First-class observability: Native Prometheus metrics built-in - no wrappers, no sidecars, just drop it in and scrape.
Flexible transport: Supports HTTP and* gRPC *(planned) *out of the box, so you don’t have to contort your infra to fit the tool. Bifrost bends to *your system, not the other way around.

Feel free to explore Bifrost docs here.

Bifrost vs LiteLLM performance comparison

To compare Bifrost and LiteLLM, some benchmark tests were ran at 500 RPS to compare performance of Bifrost and LiteLLM. Below are the results

Based on the benchmarking data, throughput comparison results between Bifrost and LiteLLM where the number of requests a gateway can successfully process per second (RPS) shows Bifrost performing better than LiteLLM, as shown below.

In Latency Comparison between Bifrost and LiteLLM, Bifrost was ~9.5x faster, with ~54x lower P99 latency, and used 68% less memory than LiteLLM — on t3.medium instance (2 vCPUs) with tier 5 OpenAI Key, as shown below.

When a like-for-like benchmark based on the LiteLLM proxy’s own benchmarking setup was ran with the same load, same mocking behaviour, and same hardware profile to get a clean, apples-to-apples comparison of real-world overheads from the gateway layer itself, Bifrost performed better than LiteLLM, as shown below.

Advantages of Bifrost Go-based design architecture over LiteLLM Python-based design architecture

The performance gap between Bifrost (Go) and LiteLLM (Python) is a good example of why architecture design choice for an LLM gateway is critical for infrastructure tools.

While Python is the undisputed king of AI research and data science, Go (Golang) is widely considered superior for building the infrastructure (gateways, proxies, and cloud-native tools) that serves those models.

Here are the advantages of a Go-based architecture design for an LLM gateway over a Python-based one:

a). Higher Performance and Lower Latency

Go is a compiled language that produces native binaries, while Python is interpreted. This means:

Go executes faster at runtime.
It adds less overhead per request.
It provides more predictable response times under load.

For systems handling thousands of concurrent requests, this leads to lower latency and higher throughput.

b). Efficient Concurrency Model

Go was built with concurrency as a core feature using goroutines and channels. This means:

Goroutines are lightweight and cheap to create.
Go can handle many concurrent requests with minimal memory usage.
Context switching is faster and simpler than Python threads or async tasks.

Python, on the other hand is limited by the Global Interpreter Lock (GIL) and requires complex async frameworks to scale concurrency.

c). Predictable Memory Management

Go’s garbage collector is optimized for low-latency server workloads. This means:

More stable memory usage.
Fewer unpredictable pauses.
Better performance consistency under load.

Python’s memory management can cause higher overhead and less predictable pauses in long-running services.

You can learn more about Bifrost Go-based architecture here on the docs.

Bifrost key features that improve performance gains

Bifrost is designed as a production-grade infrastructure layer rather than just a developer utility. Its core features work in harmony with its Go-based architecture to eliminate the bottlenecks typically found in Python-based proxies like LiteLLM.

Here is a breakdown of how its key features drive significant performance and reliability gains:

a). Adaptive Load Balancing

The Adaptive Load Balancing feature in Bifrost enables the LLM gateway to:

Continuously monitor performance metrics like latency, error rates, and throughput for each provider and API key.
Dynamically adjusts where traffic goes so faster, healthier providers or keys get more requests.
Reduce an endpoint traffic or temporarily removes it when it slows down or starts failing until it recovers.

Bifrost’s adaptive load balancing feature improves performance by reducing slow or failed calls, keeping responses fast, and preventing bottlenecks that hurt overall throughput and reliability.

You can learn more about the Bifrost’s adaptive load balancing feature here on the Bifrost docs.

b). Semantic Caching

The semantic caching feature in Bifrost enables the LLM gateway to:

Not only cache exact matches, but use semantic similarity to detect when requests mean the same thing even if the text is phrased differently.
Return the stored response in milliseconds on a cache hit which is much faster than making a full LLM request.
Reduce repeated external API calls when similar queries occur frequently.

Bifrost’s semantic caching feature improves performance by providing instant responses for many requests and fewer expensive model calls, which cuts both latency and cost.

You can learn more about the Bifrost’s semantic caching feature here on the Bifrost docs.

c). Unified Interfaces

The unified interfaces feature in Bifrost enables the LLM gateway to:

Provide one consistent OpenAI-compatible API no matter which provider (OpenAI, Anthropic, AWS, etc.) is used.
Internally handle provider-specific quirks (input/output formats, errors, rate limits).

Bifrost’s unified interfaces feature improves performance by simplifying your application code and removing overhead by letting requests flow efficiently and reduce expensive error handling or conversions.

You can learn more about the unified interfaces feature here on the Bifrost docs.

d). Built-In Metrics and Observability

The Built-In Metrics and Observability feature enables you to monitor and analyze every AI request and response in real-time where:

Native Prometheus-based metrics is supported without requiring external sidecars or wrappers.
It tracks key performance signals like latency, success rates, cache hit/miss rates, and throughput.
It help teams identify slow paths, provider degradation, and optimization opportunities.

Bifrost’s Built-In Metrics and Observability feature improves performance by helping teams fine-tune configurations and prevent issues before they slow down systems.

You can learn more about the Built-In Metrics and Observability feature feature here on the Bifrost docs.

How to get started with Bifrost LLM gateway

Getting started with Bifrost is designed to be straightforward, especially if you are already using the OpenAI API.

There are two primary ways to integrate it: as a standalone HTTP server (easiest for most) or as a Go package directly in your code.

Let’s get started

Prerequisites

Go 1.23 or higher (not needed if using Docker)
Access to at least one AI model provider (OpenAI, Anthropic, etc.)
API keys for the providers you wish to use

Option A: Using Bifrost as an HTTP Server

This is the most common method. You run Bifrost as a proxy and simply point your application to it.

To use Bifrost as an HTTP server, follow the steps below,

Step 1: Configuration:

Create a file named config.json which tells Bifrost which keys and models to use, as shown below

{
 "openai": {
 "keys": [{
     "value": "env.OPENAI_API_KEY",
     "models": ["gpt-4o-mini"],
     "weight": 1.0
   }]
 }
}

Step 2. Set Environment Variables:

Add your API key to your environment so the config file can read it securely

export OPENAI_API_KEY=your_openai_api_key;

Step 3: Start the Bifrost HTTP Server:

You have two options to run the server, either using Go Binary or a Docker setup if go is not installed.

a. Using Go Binary

To use Go Binary, first, install the transport package:

go install github.com/maximhq/bifrost/transports/bifrost-http@latest

Then run the server (make sure Go is present in the PATH):

bifrost-http -config config.json -port 8080

b. Using Docker

To use Docker, first download the Dockerfile:

curl -L -o Dockerfile https://raw.githubusercontent.com/maximhq/bifrost/main/transports/Dockerfile

Then build the Docker image:

docker build \
--build-arg CONFIG_PATH=./config.json \
--build-arg PORT=8080 \
-t bifrost-transports .

Finally, run the Docker container:

docker run -p 8080:8080 -e OPENAI_API_KEY bifrost-transports

Step 4: Using the API:

Once the server is running, you can send requests to the HTTP endpoints.

curl -X POST http://localhost:8080/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
  "model": "openai/gpt-4o-mini",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Tell me about Bifrost in Norse mythology."}
  ]
}'

Note: For additional configurations in HTTP server setup, please read this.

Option B: Using Bifrost as a Go Package

If you are building a Go application and want to avoid the network hop of an external proxy, you can embed Bifrost directly.

To use Bifrost as a Go Package, follow the steps below,

Step 1: Go Get Bifrost:

To get Bitfrost, run the following command to install Bifrost as a golang package in your project.

go get github.com/maximhq/bifrost/core@latest

Step 2: Implement Your Account Interface:

To implement your account interface, you first need to create your account which follows Bifrost's account interface.

type BaseAccount struct{}

func (baseAccount *BaseAccount) GetConfiguredProviders() ([]schemas.ModelProvider, error) {
  return []schemas.ModelProvider{schemas.OpenAI}, nil
}

func (baseAccount *BaseAccount) GetKeysForProvider(providerKey schemas.ModelProvider) ([]schemas.Key, error) {
    return []schemas.Key{
      {
        Value:  os.Getenv("OPENAI_API_KEY"),
        Models: []string{"gpt-4o-mini"},
      },
    }, nil
}

func (baseAccount *BaseAccount) GetConfigForProvider(providerKey schemas.ModelProvider) (*schemas.ProviderConfig, error) {
    return &schemas.ProviderConfig{
                NetworkConfig:            schemas.DefaultNetworkConfig,
                ConcurrencyAndBufferSize: schemas.DefaultConcurrencyAndBufferSize,
    }, nil
}

Bifrost uses these methods to get all the keys and configurations it needs to call the providers. You can check Additional Configurations for further customisations.

Step 3: Initialize Bifrost:

To initialize Bifrost, set up the Bifrost instance by providing your account implementation.

account := BaseAccount{}

client, err := bifrost.Init(schemas.BifrostConfig{
  Account: &account,
})

Step 4: Use Bifrost:

Make your First LLM Call!

bifrostResult, bifrostErr := client.ChatCompletionRequest(
     context.Background(),
     &schemas.BifrostRequest{
         Provider: schemas.OpenAI,
         Model: "gpt-4o-mini", // make sure you have configured gpt-4o-mini in your account interface
         Input: schemas.RequestInput{
         ChatCompletionInput: bifrost.Ptr([]schemas.Message{{
                 Role:    schemas.RoleUser,
                 Content: schemas.MessageContent{
                     ContentStr: bifrost.Ptr("What is a LLM gateway?"),
             },
             }}),
          },
       },
  )

  // you can add model parameters by passing them in Params: &schemas.ModelParameters{...yourParams} in ChatCompletionRequest.

For more settings and configurations, check out the Documentation.

Bonus: You can use Maxim’s pre-made plugin from [github.com/maximhq/bifrost/plugins](https://github.com/maximhq/bifrost/tree/main/plugins) to add observability to Bifrost in just a single line by installing the package using the command below,

go get github.com/maximhq/bifrost/plugins/maxim

Then add observability as shown below.

maximPlugin, err := maxim.NewMaximLoggerPlugin(os.Getenv("MAXIM_API_KEY"), os.Getenv("MAXIM_LOG_REPO_ID"))

client, err := bifrost.Init(schemas.BifrostConfig{
  Account: &account,
  Plugins: []schemas.Plugin{maximPlugin},
})

Remember to get your Maxim API Key and Log Repo ID from here.

Conclusion

In conclusion, scaling your AI-powered app from a proof-of-concept to a production-grade AI application can be a headache if you don’t use a fast and scalable LLM gateway*.*

While Python-based proxies like LiteLLM are excellent for early development, they eventually become the bottleneck in high-throughput environments.
Bifrost eliminates this hurdle by moving the gateway logic to a high-performance Go-based architecture.

By choosing Bifrost, you gain:

Infrastructure Efficiency that handle 10x more traffic with 68% less memory compared to LiteLLM gateway
Zero-Latency Overhead with internal processing in microseconds ($<15\mu s$), not milliseconds.
**Production Stability with **100% success rates even under heavy concurrency.

Finally, If you’re building or scaling an AI application and performance is becoming a bottleneck, explore Bifrost and try it yourself:

🌐 Website: https://getmax.im/bifrost-home
📦 GitHub: https://git.new/bifrostrepo
📘 Docs (Quickstart): https://getmax.im/bifrostdocs
📊 Benchmark vs LiteLLM: https://www.getmaxim.ai/blog/bifrost-a-drop-in-llm-proxy-40x-faster-than-litellm/

Test it in your own workload and see how a performance-first LLM gateway can change your system’s behavior at scale.

Build with Google's new A2UI Spec: Agent User Interfaces with A2UI + AG-UI

Bonnie — Tue, 16 Dec 2025 15:24:45 +0000

TL;DR

In this guide, you will learn how to build full-stack agent-to-user interface (A2UI) agents using the agent-to-agent (A2A) protocol, the AG-UI protocol, and CopilotKit.

Before we jump in, I would also like to cover how A2UI & AG-UI fit together. You can read about it here

For this build, we'll cover:

What is A2UI?
Building A2UI + A2A agent backend
Building A2UI + A2A agent frontend using AG-UI and CopilotKit

Here is a preview of what we will be building:

What is A2UI?

A2UI is a new open-source UI Toolkit to facilitate LLM-generated UIs that allows AI agents to create and present dynamic, interactive user interfaces (UIs) on the fly, rather than relying on a fixed, pre-built interface.

A2UI is built with the A2A protocol and allows an A2A agent to send interactive components instead of just text, using a high-level framework-agnostic format that can be rendered natively on any surface

In simpler terms, instead of the AI agent only responding with text in a chat window, it can respond by generating a complete UI component like:

An interactive chart or graph.
A fully populated form or table.
Specific buttons (like "Approve" or "Reject") relevant only to the task at hand.

You can learn more about A2UI here.

Now that you have learned what the A2UI protocol is, let us see how to use it together with A2A, AG-UI, and CopilotKit to build full-stack A2UI AI agents.

Prerequisites

To fully understand this tutorial, you need to have a basic understanding of React or Next.js

We'll also make use of the following:

Python - a popular programming language for building AI agents with AI agent frameworks; make sure it is installed on your computer.
AG-UI Protocol - The Agent User Interaction Protocol (AG-UI), developed by CopilotKit, is an open-source, lightweight, event-based protocol that facilitates rich, real-time interactions between the frontend and your AI agent backend.
Google ADK - an open-source framework designed by Google to simplify the process of building complex and production-ready AI agents.
Gemini API Key - an API key to enable you to perform various tasks using the Gemini models for ADK agents.
CopilotKit - an open-source copilot framework for building custom AI chatbots, in-app AI agents, and text areas.

Building A2UI + A2A agent backend

In this section, you will learn how to configure your agent to use A2UI using the A2A protocol in the backend.

Let’s get started.

To get started, clone the A2A starter template using the command below:

git clone https://github.com/copilotkit/with-a2a-a2ui.git

After that, create an environment file with your API key:

echo "GEMINI_API_KEY=your_api_key_here" > .env

Then run the command below to install the dependencies:

pnpm install

Finally, run and connect your agent using the following command:

pnpm dev

Let us now see how to configure your agent to use A2UI using the A2A protocol.

Step 1: Define your agent A2UI Response Components

To define your agent A2UI response components, first, define a schema that contains the complete JSON Schema that defines a valid A2UI message, as shown in the agent/restaurant_finder/prompt_builder.py file.

A2UI_SCHEMA = r'''
{
  "title": "A2UI Message Schema",
  "description": "Describes a JSON payload for an A2UI (Agent to UI) message, which is used to construct and update user interfaces dynamically. A message MUST contain exactly ONE of the action properties: 'beginRendering', 'surfaceUpdate', 'dataModelUpdate', or 'deleteSurface'.",
  "type": "object",
  "properties": {
    "beginRendering": {
      "type": "object",
      "description": "Signals the client to begin rendering a surface with a root component and specific styles.",
      "properties": {
        "surfaceId": {
          "type": "string",
          "description": "The unique identifier for the UI surface to be rendered."
        },
        "root": {
          "type": "string",
          "description": "The ID of the root component to render."
        },
        "styles": {
          "type": "object",
          "description": "Styling information for the UI.",
          "properties": {
            "font": {
              "type": "string",
              "description": "The primary font for the UI."
            },
            "primaryColor": {
              "type": "string",
              "description": "The primary UI color as a hexadecimal code (e.g., '#00BFFF').",
              "pattern": "^#[0-9a-fA-F]{6}$"
            }
          }
        }
      },
      "required": ["root", "surfaceId"]
    },

   // ...

  }

Then define A2UI response components that your agent uses to format its responses, as shown in the agent/restaurant_finder/prompt_builder.py file.

RESTAURANT_UI_EXAMPLES = """
---BEGIN SINGLE_COLUMN_LIST_EXAMPLE---
[
  {{ "beginRendering": {{ "surfaceId": "default", "root": "root-column", "styles": {{ "primaryColor": "#FF0000", "font": "Roboto" }} }} }},
  {{ "surfaceUpdate": {{
    "surfaceId": "default",
    "components": [
      {{ "id": "root-column", "component": {{ "Column": {{ "children": {{ "explicitList": ["title-heading", "item-list"] }} }} }} }},
      {{ "id": "title-heading", "component": {{ "Text": {{ "usageHint": "h1", "text": {{ "literalString": "Top Restaurants" }} }} }} }},
      {{ "id": "item-list", "component": {{ "List": {{ "direction": "vertical", "children": {{ "template": {{ "componentId": "item-card-template", "dataBinding": "/items" }} }} }} }} }},
      {{ "id": "item-card-template", "component": {{ "Card": {{ "child": "card-layout" }} }} }},
      {{ "id": "card-layout", "component": {{ "Row": {{ "children": {{ "explicitList": ["template-image", "card-details"] }} }} }} }},
      {{ "id": "template-image", weight: 1, "component": {{ "Image": {{ "url": {{ "path": "imageUrl" }} }} }} }},
      {{ "id": "card-details", weight: 2, "component": {{ "Column": {{ "children": {{ "explicitList": ["template-name", "template-rating", "template-detail", "template-link", "template-book-button"] }} }} }} }},
      {{ "id": "template-name", "component": {{ "Text": {{ "usageHint": "h3", "text": {{ "path": "name" }} }} }} }},
      {{ "id": "template-rating", "component": {{ "Text": {{ "text": {{ "path": "rating" }} }} }} }},
      {{ "id": "template-detail", "component": {{ "Text": {{ "text": {{ "path": "detail" }} }} }} }},
      {{ "id": "template-link", "component": {{ "Text": {{ "text": {{ "path": "infoLink" }} }} }} }},
      {{ "id": "template-book-button", "component": {{ "Button": {{ "child": "book-now-text", "primary": true, "action": {{ "name": "book_restaurant", "context": [ {{ "key": "restaurantName", "value": {{ "path": "name" }} }}, {{ "key": "imageUrl", "value": {{ "path": "imageUrl" }} }}, {{ "key": "address", "value": {{ "path": "address" }} }} ] }} }} }} }},
      {{ "id": "book-now-text", "component": {{ "Text": {{ "text": {{ "literalString": "Book Now" }} }} }} }}
    ]
  }} }},
  {{ "dataModelUpdate": {{
    "surfaceId": "default",
    "path": "/",
    "contents": [
      {{ "key": "items", "valueMap": [
        {{ "key": "item1", "valueMap": [
          {{ "key": "name", "valueString": "The Fancy Place" }},
          {{ "key": "rating", "valueNumber": 4.8 }},
          {{ "key": "detail", "valueString": "Fine dining experience" }},
          {{ "key": "infoLink", "valueString": "https://example.com/fancy" }},
          {{ "key": "imageUrl", "valueString": "https://example.com/fancy.jpg" }},
          {{ "key": "address", "valueString": "123 Main St" }}
        ] }},
        {{ "key": "item2", "valueMap": [
          {{ "key": "name", "valueString": "Quick Bites" }},
          {{ "key": "rating", "valueNumber": 4.2 }},
          {{ "key": "detail", "valueString": "Casual and fast" }},
          {{ "key": "infoLink", "valueString": "https://example.com/quick" }},
          {{ "key": "imageUrl", "valueString": "https://example.com/quick.jpg" }},
          {{ "key": "address", "valueString": "456 Oak Ave" }}
        ] }}
      ] }} // Populate this with restaurant data
    ]
  }} }}
]
---END SINGLE_COLUMN_LIST_EXAMPLE---

// ...

After that, define a function that constructs the full prompt with instructions, A2UI response components and A2UI message JSON Schema, as shown in the agent/restaurant_finder/prompt_builder.py file.

def get_ui_prompt(base_url: str, examples: str) -> str:
    """
    Constructs the full prompt with UI instructions, rules, examples, and schema.

    Args:
        base_url: The base URL for resolving static assets like logos.
        examples: A string containing the specific UI examples for the agent's task.

    Returns:
        A formatted string to be used as the system prompt for the LLM.
    """
    # The f-string substitution for base_url happens here, at runtime.
    formatted_examples = examples.format(base_url=base_url)

    return f"""
    You are a helpful restaurant finding assistant. Your final output MUST be a A2UI UI JSON response.

    To generate the response, you MUST follow these rules:
    1.  Your response MUST be in two parts, separated by the delimiter: `---a2ui_JSON---`.
    2.  The first part is your conversational text response.
    3.  The second part is a single, raw JSON object that is a list of A2UI messages.
    4.  The JSON part MUST validate against the A2UI JSON SCHEMA provided below.

    --- UI TEMPLATE RULES ---
    -   If the query is for a list of restaurants, use the restaurant data you have already received from the `get_restaurants` tool to populate the `dataModelUpdate.contents` array (e.g., as a `valueMap` for the "items" key).
    -   If the number of restaurants is 5 or fewer, you MUST use the `SINGLE_COLUMN_LIST_EXAMPLE` template.
    -   If the number of restaurants is more than 5, you MUST use the `TWO_COLUMN_LIST_EXAMPLE` template.
    -   If the query is to book a restaurant (e.g., "USER_WANTS_TO_BOOK..."), you MUST use the `BOOKING_FORM_EXAMPLE` template.
    -   If the query is a booking submission (e.g., "User submitted a booking..."), you MUST use the `CONFIRMATION_EXAMPLE` template.

    {formatted_examples}

    ---BEGIN A2UI JSON SCHEMA---
    {A2UI_SCHEMA}
    ---END A2UI JSON SCHEMA---
    """

Step 2: Generating A2UI components with A2UI Composer

If you want an easy way to generate components, you can use the A2UI Composer, which enables you to generate A2UI components.

To create a component using the A2UI composer, go to https://a2ui-editor.ag-ui.com/ and describe your A2UI widget, as shown below.

Then click the create button, and the composer will generate your A2UI widget, as shown below.

After that, copy the generated JSON spec and paste it into your agent's prompt as we discussed in step one above.

Step 3: Configure your A2UI agent

Once you have set up your A2A components and assembled your agent prompt, configure your agent, as shown in the agent/restaurant_finder/agent.py file.

// ...

# Local imports from sibling modules
from prompt_builder import (
    A2UI_SCHEMA,  # JSON Schema for A2UI validation
    RESTAURANT_UI_EXAMPLES,  # Example A2UI responses for few-shot learning
    get_text_prompt,  # Prompt for text-only mode
    get_ui_prompt,  # Prompt for UI mode (with schema and examples)
)
from tools import get_restaurants  # Tool function for fetching restaurant data

logger = logging.getLogger(__name__)

AGENT_INSTRUCTION = """
    You are a helpful restaurant finding assistant. Your goal is....
"""

class RestaurantAgent:
    """
    An agent that finds restaurants based on user criteria.

    """

    # Supported content types for A2A protocol
    SUPPORTED_CONTENT_TYPES = ["text", "text/plain"]

    def __init__(self, base_url: str, use_ui: bool = False):
        """
        Initialize the RestaurantAgent.

        Args:
            base_url: The server's base URL (used for resolving image URLs)
            use_ui: If True, generate A2UI JSON responses; if False, generate text
        """
        self.base_url = base_url
        self.use_ui = use_ui

        # Build the underlying LlmAgent with appropriate instructions
        self._agent = self._build_agent(use_ui)

        # User ID for session management (constant for this simple example)
        self._user_id = "remote_agent"

        // ...

        # =====================================================================
        # LOAD AND WRAP A2UI SCHEMA
        # =====================================================================
        # We need to validate LLM responses against the A2UI schema.
        # The schema defines a SINGLE message, but the LLM returns a LIST of messages.
        # So we wrap the schema in an array validator.
        try:
            # Parse the schema for a single A2UI message
            single_message_schema = json.loads(A2UI_SCHEMA)

            # Wrap it: the LLM must return an ARRAY of valid messages
            self.a2ui_schema_object = {"type": "array", "items": single_message_schema}
            logger.info(
                "A2UI_SCHEMA successfully loaded and wrapped in an array validator."
            )
        except json.JSONDecodeError as e:
            logger.error(f"CRITICAL: Failed to parse A2UI_SCHEMA: {e}")
            self.a2ui_schema_object = None  # Validation will be skipped

   // ...

    # =========================================================================
    # STEP 3c: BUILD THE LLM AGENT
    # =========================================================================
    def _build_agent(self, use_ui: bool) -> LlmAgent:
        """
        Builds the LLM agent with appropriate instructions and tools.

        Args:
            use_ui: Whether to include UI instructions and schema in the prompt

        Returns:
            A configured LlmAgent instance
        """
        # Get the model name from the environment variable, with a sensible default
        LITELLM_MODEL = os.getenv("LITELLM_MODEL", "gemini/gemini-2.5-flash")

        if use_ui:
            # UI mode: Include instructions for generating A2UI JSON
            # This adds:
            # - Detailed formatting rules (delimiter, JSON structure)
            # - Template examples for different scenarios
            # - The complete A2UI JSON schema
            instruction = AGENT_INSTRUCTION + get_ui_prompt(
                self.base_url, RESTAURANT_UI_EXAMPLES
            )
        else:
            # Text mode: Simple instructions for text-only responses
            instruction = get_text_prompt()

        # Create the LlmAgent with:
        # - A LiteLLM wrapper (allows using different LLM providers)
        # - Name and description for identification
        # - The instruction (system prompt)
        # - Available tools (get_restaurants function)
        return LlmAgent(
            model=LiteLlm(model=LITELLM_MODEL),
            name="restaurant_agent",
            description="An agent that finds restaurants and helps book tables.",
            instruction=instruction,
            tools=[get_restaurants],  # The agent can call this function
        )

      // ...

Step 4: Configure your A2UI agent executor using A2A protocol

After configuring your A2UI agent, configure the agent with an A2A agent executor that handles A2A requests and responses, as shown in the agent/restaurant_finder/agent_executer.py file.

// ...

# =============================================================================
# STEP 2: AGENT EXECUTOR CLASS
# =============================================================================
class RestaurantAgentExecutor(AgentExecutor):
    """
    Restaurant AgentExecutor - Bridges A2A Protocol and RestaurantAgent.


    """

    # =========================================================================
    # STEP 2a: INITIALIZATION
    # =========================================================================
    def __init__(self, base_url: str):
        """
        Initialize the executor with two agent instances.


        """
        # UI agent: Generates rich A2UI responses with components and data models
        self.ui_agent = RestaurantAgent(base_url=base_url, use_ui=True)

        # Text agent: Generates plain text responses (for clients without A2UI support)
        self.text_agent = RestaurantAgent(base_url=base_url, use_ui=False)

    # =========================================================================
    # STEP 2b: MAIN EXECUTION METHOD
    # =========================================================================
    async def execute(
        self,
        context: RequestContext,
        event_queue: EventQueue,
    ) -> None:
        """
        Main entry point for handling A2A requests.

        This method orchestrates the entire request-response cycle:
        1. Detects whether the client supports A2UI
        2. Parses incoming message parts (text or UI events)
        3. Transforms UI events into natural language queries
        4. Invokes the appropriate agent
        5. Formats and sends the response

        Args:
            context: Contains the incoming message, task state, and client info
            event_queue: Queue for sending events (status updates, responses) to client
        """
        # Initialize variables for tracking the query and UI events
        query = ""  # The final query string to send to the LLM
        ui_event_part = None  # Will hold A2UI event data if present
        action = None  # The action name from UI events (e.g., "book_restaurant")

        # =====================================================================
        # STEP 2b-i: DETECT A2UI SUPPORT
        # =====================================================================
        # Check which protocol extensions the client requested
        logger.info(
            f"--- Client requested extensions: {context.requested_extensions} ---"
        )

        # try_activate_a2ui_extension checks if A2UI is in the requested extensions
        # and marks it as active in the context if so
        use_ui = try_activate_a2ui_extension(context)

        # =====================================================================
        # STEP 2b-ii: SELECT APPROPRIATE AGENT
        # =====================================================================
        # Based on A2UI support, choose which agent to use
        if use_ui:
            agent = self.ui_agent
            logger.info(
                "--- AGENT_EXECUTOR: A2UI extension is active. Using UI agent. ---"
            )
        else:
            agent = self.text_agent
            logger.info(
                "--- AGENT_EXECUTOR: A2UI extension is not active. Using text agent. ---"
            )

        # =====================================================================
        # STEP 2b-iii: PARSE INCOMING MESSAGE PARTS
        # =====================================================================
        # A2A messages can contain multiple "parts" - these can be:
        # - TextPart: Plain text from the user
        # - DataPart: Structured data (like A2UI events from button clicks)
        if context.message and context.message.parts:
            logger.info(
                f"--- AGENT_EXECUTOR: Processing {len(context.message.parts)} message parts ---"
            )

            # Iterate through all parts to find relevant data
            for i, part in enumerate(context.message.parts):
                if isinstance(part.root, DataPart):
                    # DataPart contains structured JSON data
                    if "userAction" in part.root.data:
                        # This is an A2UI ClientEvent - a button was clicked!
                        logger.info(f"  Part {i}: Found a2ui UI ClientEvent payload.")
                        ui_event_part = part.root.data["userAction"]
                    else:
                        # Some other structured data
                        logger.info(f"  Part {i}: DataPart (data: {part.root.data})")
                elif isinstance(part.root, TextPart):
                    # Plain text from the user
                    logger.info(f"  Part {i}: TextPart (text: {part.root.text})")
                else:
                    logger.info(f"  Part {i}: Unknown part type ({type(part.root)})")

        # =====================================================================
        # STEP 2b-iv: TRANSFORM UI EVENTS INTO LLM QUERIES
        # =====================================================================
        # If we received a UI event (button click), we need to transform it
        # into a natural language query that the LLM can understand.
        # This is a key part of the A2UI pattern - UI events become LLM inputs.
        if ui_event_part:
            logger.info(f"Received a2ui ClientEvent: {ui_event_part}")

            # Extract the action name and context data from the event
            action = ui_event_part.get("actionName")
            ctx = ui_event_part.get("context", {})

            # Handle "Book Now" button click
            if action == "book_restaurant":
                # User clicked "Book Now" on a restaurant card
                # Extract restaurant details from the button's context
                restaurant_name = ctx.get("restaurantName", "Unknown Restaurant")
                address = ctx.get("address", "Address not provided")
                image_url = ctx.get("imageUrl", "")

                # Create a structured query that tells the LLM what the user wants
                # The LLM is trained to recognize this pattern and show a booking form
                query = f"USER_WANTS_TO_BOOK: {restaurant_name}, Address: {address}, ImageURL: {image_url}"

            # Handle "Submit Reservation" button click
            elif action == "submit_booking":
                # User filled out the booking form and submitted it
                # Extract all the form data from the button's context
                restaurant_name = ctx.get("restaurantName", "Unknown Restaurant")
                party_size = ctx.get("partySize", "Unknown Size")
                reservation_time = ctx.get("reservationTime", "Unknown Time")
                dietary_reqs = ctx.get("dietary", "None")
                image_url = ctx.get("imageUrl", "")

                # Create a query that tells the LLM to confirm the booking
                query = f"User submitted a booking for {restaurant_name} for {party_size} people at {reservation_time} with dietary requirements: {dietary_reqs}. The image URL is {image_url}"

            else:
                # Unknown action - pass it through as-is
                query = f"User submitted an event: {action} with data: {ctx}"
        else:
            # No UI event - this is a regular text message
            logger.info("No a2ui UI event part found. Falling back to text input.")
            query = context.get_user_input()  # Extract text from the message parts

        logger.info(f"--- AGENT_EXECUTOR: Final query for LLM: '{query}' ---")

        // ...

    # =========================================================================
    # STEP 2c: CANCEL METHOD (NOT IMPLEMENTED)
    # =========================================================================
    async def cancel(
        self, request: RequestContext, event_queue: EventQueue
    ) -> Task | None:
        """
        Handle task cancellation requests.

        This agent does not support cancellation, so we raise an error.
        A more sophisticated agent might gracefully stop ongoing work.

        Raises:
            ServerError: With UnsupportedOperationError
        """
        raise ServerError(error=UnsupportedOperationError())

Step 5: Configure your A2UI agent server using A2A protocol

Once you have configured the agent executor, set up a main entry for your agent that sets up and starts an A2A-compliant server that can:

Respond to agent discovery requests (via AgentCard)
Handle user queries about restaurants
Serve static files (restaurant images)
Support both text-only and A2UI (rich UI) responses

You can configure the server, as shown in the agent/restaurant_finder/__main__.py file.

// ...

@click.command()  # Decorates this function as a CLI command
@click.option("--host", default="localhost")  # Optional --host argument
@click.option("--port", default=10002)  # Optional --port argument
def main(host, port):
    """
    Main entry point for the Restaurant Finder Agent server.


    """
    try:
        # =====================================================================
        # VALIDATE API CREDENTIALS
        # =====================================================================
        # The agent needs either:
        # - GEMINI_API_KEY for direct Gemini API access, OR
        # - GOOGLE_GENAI_USE_VERTEXAI=TRUE for Vertex AI authentication
        if not os.getenv("GOOGLE_GENAI_USE_VERTEXAI") == "TRUE":
            if not os.getenv("GEMINI_API_KEY"):
                raise MissingAPIKeyError(
                    "GEMINI_API_KEY environment variable not set and GOOGLE_GENAI_USE_VERTEXAI is not TRUE."
                )

        # =====================================================================
        # DEFINE AGENT CAPABILITIES
        # =====================================================================
        # AgentCapabilities tells clients what this agent supports:
        # - streaming=True: Agent can stream responses progressively
        # - extensions: List of protocol extensions (here, A2UI for rich UIs)
        capabilities = AgentCapabilities(
            streaming=True,
            extensions=[get_a2ui_agent_extension()],  # Enable A2UI rich UI support
        )

        # =====================================================================
        # DEFINE AGENT SKILLS
        # =====================================================================
        # AgentSkill describes what this agent can do. This metadata is used
        # for agent discovery and helps clients understand the agent's purpose.
        skill = AgentSkill(
            id="find_restaurants",  # Unique identifier for this skill
            name="Find Restaurants Tool",  # Human-readable name
            description="Helps find restaurants based on user criteria (e.g., cuisine, location).",
            tags=["restaurant", "finder"],  # Searchable tags
            examples=["Find me the top 10 chinese restaurants in the US"],  # Example queries
        )

        # =====================================================================
        # CONSTRUCT BASE URL
        # =====================================================================
        # The base URL is used for:
        # - Agent discovery (clients connect to this URL)
        # - Resolving static asset URLs (e.g., restaurant images)
        base_url = f"http://{host}:{port}"

        # =====================================================================
        # CREATE AGENT CARD
        # =====================================================================
        # The AgentCard is the "identity card" for this agent in the A2A protocol.
        # Clients use this to discover and understand the agent.
        agent_card = AgentCard(
            name="Restaurant Agent",  # Display name
            description="This agent helps find restaurants based on user criteria.",
            url=base_url,  # Where to reach this agent
            version="1.0.0",  # Semantic version
            default_input_modes=RestaurantAgent.SUPPORTED_CONTENT_TYPES,  # ["text", "text/plain"]
            default_output_modes=RestaurantAgent.SUPPORTED_CONTENT_TYPES,
            capabilities=capabilities,  # What the agent supports
            skills=[skill],  # What the agent can do
        )

        # =====================================================================
        # CREATE AGENT EXECUTOR
        # =====================================================================
        # The AgentExecutor is the bridge between the A2A protocol and our
        # RestaurantAgent. It handles:
        # - Parsing A2A requests
        # - Invoking the appropriate agent (UI or text)
        # - Formatting A2A responses
        agent_executor = RestaurantAgentExecutor(base_url=base_url)

        # =====================================================================
        # CREATE REQUEST HANDLER
        # =====================================================================
        # DefaultRequestHandler processes incoming A2A requests and delegates
        # to our agent_executor. The InMemoryTaskStore keeps track of ongoing
        # tasks (useful for multi-turn conversations).
        request_handler = DefaultRequestHandler(
            agent_executor=agent_executor,
            task_store=InMemoryTaskStore(),
        )

        # =====================================================================
        # BUILD THE A2A APPLICATION
        # =====================================================================
        # A2AStarletteApplication creates an ASGI web application that:
        # - Exposes the /.well-known/agent.json endpoint (agent discovery)
        # - Handles A2A protocol messages
        server = A2AStarletteApplication(
            agent_card=agent_card, http_handler=request_handler
        )
        import uvicorn

        # Build the Starlette app from our A2A configuration
        app = server.build()

          // ...

        # =====================================================================
        # MOUNT STATIC FILES
        # =====================================================================
        # Serve restaurant images from the ./images directory at /static
        # Example: http://localhost:10002/static/restaurant1.jpg
        app.mount("/static", StaticFiles(directory="images"), name="static")

        # =====================================================================
        # START THE SERVER
        # =====================================================================
        # uvicorn is an ASGI server that will run our application.
        # It handles HTTP connections and routes them to our app.
        uvicorn.run(app, host=host, port=port)

      // ...

Congrats! You've successfully built your A2UI backend using the A2A protocol. Let’s see how to add a frontend to it using AG-UI and CopilotKit.

Building A2UI + A2A agent frontend using AG-UI and CopilotKit

In this section, you will learn how to configure your A2UI + A2A agent with the frontend using AG-UI protocol that handles communicating with your A2UI + A2A agent, and passes the A2UI messages back and forth as ActivityMessage objects.

Let’s get started.

Step 1: Configure the CopilotKit API Route with AG-UI and A2A Client

To connect your A2UI + A2A agent to the frontend, configure a CopilotKit API route handler that connects the frontend to your A2UI + A2A agent backend using AG-UI and A2A client, as shown below.

// CopilotKit Runtime - Core server-side components
import {
  CopilotRuntime,         // Main runtime that orchestrates agents and handles requests
  createCopilotEndpoint,  // Factory function to create an HTTP endpoint
  InMemoryAgentRunner,    // Runs agents with in-memory state (no persistence)
} from "@copilotkitnext/runtime";

// Hono adapter for Vercel/Next.js - Converts Hono app to Next.js route handlers
import { handle } from "hono/vercel";

// A2A (Agent-to-Agent) Integration
import { A2AAgent } from "@ag-ui/a2a";     // CopilotKit wrapper for A2A protocol
import { A2AClient } from "@a2a-js/sdk/client"; // Client to communicate with A2A servers

// =============================================================================
// STEP 2: CREATE A2A, CLIENT
// =============================================================================
/**
 * A2AClient connects to an A2A-compliant agent server.
 */
const a2aClient = new A2AClient("http://localhost:10002");

// =============================================================================
// STEP 3: CREATE A2A AGENT WRAPPER
// =============================================================================
/**
 * A2AAgent wraps the A2AClient to make it compatible with CopilotKit.
 */
const agent = new A2AAgent({ a2aClient, debug: true });

// =============================================================================
// STEP 4: CREATE COPILOTKIT RUNTIME
// =============================================================================
/**
 * CopilotRuntime is the central orchestrator that:
 * - Manages registered agents
 * - Routes requests to the appropriate agent
 * - Handles streaming responses
 * - Manages conversation state
 */
const runtime = new CopilotRuntime({
  agents: {
    default: agent, // Our A2A Restaurant Agent is the default agent
  },
  runner: new InMemoryAgentRunner(),
});

// =============================================================================
// STEP 5: CREATE THE HTTP ENDPOINT
// =============================================================================
/**
 * createCopilotEndpoint creates a Hono web application that handles
 * CopilotKit API requests.
 *
 * The endpoint handles:
 * - POST /api/copilotkit - Main chat endpoint for sending messages
 * - GET /api/copilotkit - Health check and capability discovery
 * - Various sub-routes for streaming, actions, etc.
 */
const app = createCopilotEndpoint({
  runtime,
  basePath: "/api/copilotkit",
});

export const GET = handle(app as any);
export const POST = handle(app as any);

Step 2: Create A2UI Message Renderer

After configuring the API route, create an A2UI message renderer provided by CopilotKit to render A2UI messages and instantiate it with a theme, as shown below.

"use client";

// A2UI Renderer Factory - Creates a message renderer for A2UI protocol responses
import { createA2UIMessageRenderer } from "@copilotkitnext/a2ui-renderer";

// Custom theme configuration for styling A2UI components
import { theme } from "./theme";

// =============================================================================
// CREATE A2UI MESSAGE RENDERER
// =============================================================================
/**
 * A2UIMessageRenderer is a custom message renderer that knows how to
 * display A2UI protocol messages as rich, interactive UI components.
 *
 * When the A2A agent sends back A2UI JSON (with beginRendering, surfaceUpdate,
 * dataModelUpdate messages), this renderer:
 * 1. Parses the A2UI JSON
 * 2. Builds a component tree from the surfaceUpdate
 * 3. Binds data from dataModelUpdate to components
 * 4. Renders native React components (cards, buttons, forms, etc.)
 * 5. Handles user interactions and sends events back to the agent
 *
 * The `theme` option allows customizing colors, fonts, and spacing of
 * The rendered A2UI components to match your app's design.
 */
const A2UIMessageRenderer = createA2UIMessageRenderer({ theme });

// ....

Step 3: Set up the CopilotKit provider and Chat Component

Once you have created the A2UI message renderer, set up the CopilotKit provider together with the chat component.

Then pass the A2UI message renderer to the CopilotKit provider, as shown below.

"use client";

import { CopilotChat, CopilotKitProvider } from "@copilotkitnext/react";

// ...

export default function Home() {
  return (
    // =========================================================================
    // CopilotKitProvider - The Context Provider
    // =========================================================================
    /**
     * CopilotKitProvider wraps the app and provides:
     * - Connection to the backend API
     * - Shared state for all CopilotKit components
     * - Message history management
     * - Action/tool registration
     *
     * Props:
     * - runtimeUrl: The backend API endpoint (our Next.js API route)
     * - showDevConsole: "auto" shows dev tools in development mode only
     * - renderActivityMessages: Custom renderers for agent messages
     *   - A2UIMessageRenderer handles A2UI protocol messages
     *   - Multiple renderers can be provided for different message types
     */
    <CopilotKitProvider
      runtimeUrl="/api/copilotkit"
      showDevConsole="auto"
      renderActivityMessages={[A2UIMessageRenderer]}
    >
      {/* Main container - full viewport height with flex layout */}
      <main
        className="flex min-h-screen flex-1 flex-col overflow-hidden"
        style={{ minHeight: "100dvh" }} // Use dynamic viewport height for mobile
      >
        <Chat />
      </main>
    </CopilotKitProvider>
  );
}

// =============================================================================
// CHAT COMPONENT
// =============================================================================
/**
 * Chat is a wrapper component that contains the CopilotChat interface.
 */
function Chat() {
  return (
    // Flex container that fills available space
    <div className="flex flex-1 flex-col overflow-hidden">
      <CopilotChat style={{ flex: 1, minHeight: "100%" }} />
    </div>
  );
}

Step 4: Running your A2UI + A2A + AG-UI agent

After setting up the CopilotKit provider alongside the chat component, run your agent backend server alongside the frontend server. Then navigate to the frontend localhost URL, and you should see the A2UI agent running with the chat component, as shown below.

After that, ask the agent to find you restaurants in New York with Chinese cuisine. Then you should see the A2UI components and messages rendering with the top restaurants in New York that you can book and reserve, as shown.

Conclusion

In this guide, we have walked through the steps of building a full-stack A2UI agent using A2A + AG-UI protocols and CopilotKit.

While we’ve explored a couple of features, we have barely scratched the surface of the countless use cases for CopilotKit, ranging from building interactive AI chatbots to building agentic solutions—in essence, CopilotKit lets you add a ton of functional AI capabilities to your products in minutes.

Hopefully, this guide makes it easier for you to integrate AI-powered Copilots into your existing application.

Follow CopilotKit on Twitter and say hi. If you'd like to build something cool, join the Discord community.

Easily Build a Frontend for your AWS Strands Agents using AG-UI in 30 minutes

Bonnie — Mon, 08 Dec 2025 14:13:05 +0000

TL;DR

In this guide, you will learn how to build a frontend for your AWS Strands Agents using AG-UI Protocol and CopilotKit. AWS Strands will power the AI agents backend, while CopilotKit powers the frontend, and then AG-UI creates a bridge that enables the frontend to communicate with the backend.

By the way, it's worth mentioning that this integration was built by Umar Majeed from the CopilotKit / AG-UI community, with AWS adding the finishing touches.

Check out AG-UI's GitHub ⭐️

Before we jump in, here is what we will cover:

What is AWS Strands?
Setting up a AWS Strands + AG-UI + CopilotKit agent using CLI
Integrating your AWS Strands agent with AG-UI protocol in the backend
Building a frontend for your AWS Strands + AG-UI agent using CopilotKit

Here is a preview of what you can build using AWS Strands + AG-UI + CopilotKit.

What is AWS Strands?

AWS Strands, also known as Strands Agents, is an open-source agent development framework developed by the AWS team for building and deploying AI agents.

The framework adopts a model-driven approach where it leverages model reasoning to plan, orchestrate tasks, and reflect on goals.

Moreover, Strands is model-agnostic and supports various LLM providers, including Amazon Bedrock, Anthropic, OpenAI, Meta Llama, and local models via Ollama or LiteLLM.

Below are the key features and capabilities of AWS Strands:

Tool Integration: It provides straightforward mechanisms for integrating custom tools and comes with native support for the Model Context Protocol (MCP), which allows agents to access a vast ecosystem of third-party tools.
Multi-Agent Systems: Strands simplifies the creation of complex systems where multiple specialized agents collaborate on complex tasks.
Observability: It includes native features for observability, such as traces, metrics, and logs, which are essential for debugging and monitoring agent performance.

You can learn more about AWS Strands if you visit the Strands Agents docs.

Prerequisites

Node.js 20+
Python 3.12+
OpenAI API Key (for the strands agent)
Any of the following package managers:
- pnpm (recommended)
- npm
- yarn
- bun

Setting up a AWS Strands + AG-UI + CopilotKit agent using CLI

In this section, you will learn how to set up a full-stack AWS Strands agent using a CLI command that sets up the backend using AG-UI protocol and the frontend using CopilotKit.

Let’s get started.

Step 1: Run CLI command

If you don’t already have an AWS Strands agent, you can set up one quickly by running the CLI command below in your terminal.

npx copilotkit@latest create -f aws-strands-py

Then give your project a name as shown below.

Step 2: Install dependencies

Once your project has been created successfully, install dependencies using your preferred package manager:

# Using pnpm (recommended)
pnpm install

# Using npm
npm install

# Using yarn
yarn install

# Using bun
bun install

Step 3: Set up your OpenAI key

After installing the dependencies, create a .env file in the root folder and add your OpenAI API key.

OPENAI_API_KEY="your-open-api-key-here”

Step 4: Run development server

Then start the development server using your preferred package manager:

# Using pnpm
pnpm dev

# Using npm
npm run dev

# Using yarn
yarn dev

# Using bun
bun run dev

Once the development server is running, navigate to http://localhost:3000/, and you should see your AWS Strands + AG-UI + CopilotKit agent up and running.

Congrats! You've successfully set up a full-stack AWS Strands agent. Your AI agent is now ready to use! Try playing around with the suggestions in the chat to test the integration.

Integrating your AWS Strands agent with AG-UI protocol in the backend

In this section, you will learn how to integrate your AWS Strands agent with AG-UI protocol, to expose it to the frontend.

Let’s jump in.

Step 1: Install AWS Strands + AG-UI packages

To get started, install the AWS Strands + AG-UI packages, along with other necessary dependencies, using the commands below.

uv pip install ag-ui-protocol strands-agents[OpenAI] strands-agents-tools ag_ui_strands

Step 2: Import required packages

Once you have installed the required packages, import them as shown below in a main.py file.

# AG-UI / Strands integration helpers:
# - StrandsAgent: Wrapper that makes a Strands Agent compatible with AG-UI protocol
# - StrandsAgentConfig: Configuration for shared state and tool behaviors
# - ToolBehavior: Defines how specific tools interact with the AG-UI state system
# - create_strands_app: Factory function that creates a FastAPI application
from ag_ui_strands import (
    StrandsAgent,
    StrandsAgentConfig,
    ToolBehavior,
    create_strands_app,
)

# dotenv: Loads environment variables from a .env file for local development
from dotenv import load_dotenv

# Pydantic: Used for data validation and schema definition
from pydantic import BaseModel, Field

# Strands SDK:
# - Agent: The core agent class that orchestrates LLM interactions
# - tool: Decorator to mark functions as tools the agent can call
from strands import Agent, tool

# OpenAI model wrapper from Strands for using GPT models
from strands.models.openai import OpenAIModel

// ...

Step 3: Define your AWS Strands Agent Data Models

After importing required packages, define Pydantic models for structured data validation to ensure that tool inputs are validated adequately before processing, as shown below.

# Pydantic: Used for data validation and schema definition
from pydantic import BaseModel, Field

// ...

class ProverbsList(BaseModel):
    """Pydantic model representing the entire proverbs list.

    We use a dedicated model to validate tool inputs for `update_proverbs`.
    The `proverbs` field is a list of strings describing the stored proverbs.
    """

    # The proverbs field is a list of strings with a description for the LLM
    proverbs: List[str] = Field(description="The complete list of proverbs")

 // ...

Step 4: Define your AWS Strands Agent Tools

Once you have defined your agent data models, define your agent tools decorated with @tool to register them with the Strands framework, as shown below.

// ...

@tool
def get_weather(location: str):
    """Backend tool example: returns weather information for a location.

    This is a simple synchronous tool demonstrating a backend operation. In a
    real app this would call an external weather API. Here it returns a JSON
    string for simplicity so agents and UI can display structured data.

    Args:
        location: The location to get weather for (e.g., "Seattle, WA")

    Returns:
        A JSON string containing weather information.
    """
    # Return a JSON-encoded placeholder response
    # In production, this would call an actual weather API like OpenWeatherMap
    return json.dumps({"location": "70 degrees"})

@tool
def set_theme_color(theme_color: str):
    """Frontend-only tool example: request a UI theme color change.

    Frontend tools are declared on the backend so the agent can request UI
    actions, but actual execution happens in the browser via a frontend
    integration (e.g., `useFrontendTool`). Because the frontend performs the
    action, this backend implementation returns `None`.

    Args:
        theme_color: CSS color (hex, name, or rgb) that the UI should apply
    """
    # Return None because the actual implementation is in the frontend
    # The frontend will intercept this tool call and apply the theme change
    return None

@tool
def update_proverbs(proverbs_list: ProverbsList):
    """Backend tool: replace the entire proverbs list.

    IMPORTANT: This tool expects the complete list of proverbs, not just
    additions. When the UI or user wants to modify the list, always send the
    full array so the backend can store a canonical snapshot.

    Args:
        proverbs_list: A validated `ProverbsList` instance containing the
                        complete array of proverbs.

    Returns:
        A success message string on completion.
    """
    # In a real app, this would persist to a DB. Here we return success.
    # The state synchronization happens via the ToolBehavior config below.
    return "Proverbs updated successfully."

 // ...

Step 5: Define State Management Functions

After defining your agent tools, configure state management functions to handle state synchronization between the agent and the UI, as shown below.

// ...

def build_proverbs_prompt(input_data, user_message: str) -> str:
    """Build a model prompt that includes the current proverbs state.

    When the agent composes messages for the model, we inject the current
    `proverbs` array into the prompt so the model can reference or modify it.

    This function acts as a "state context builder" - it takes the current
    shared state and incorporates it into the prompt sent to the LLM.

    Args:
        input_data: The shared state container (may include a `state` key)
        user_message: The user's raw request/message

    Returns:
        The combined prompt string includes proverbs when available.
    """
    # Step 5a: Try to extract the state dictionary from input_data
    state_dict = getattr(input_data, "state", None)

    # Step 5b: Check if we have a valid state with proverbs
    if isinstance(state_dict, dict) and "proverbs" in state_dict:
        # Step 5c: Pretty-print the proverbs array for the model to read easily
        # Using indent=2 makes the JSON human-readable in the prompt
        proverbs_json = json.dumps(state_dict["proverbs"], indent=2)

        # Step 5d: Combine the proverbs context with the user message
        return (
            f"Current proverbs list:\n{proverbs_json}\n\nUser request: {user_message}"
        )

    # Step 5e: Fall back to the plain user message if no proverbs state is available
    return user_message

async def proverbs_state_from_args(context):
    """Extract a `{'proverbs': [...]}` snapshot from tool arguments.

    This function is used by the shared state system when the `update_proverbs`
    tool runs. It inspects the tool input and returns a small dictionary
    containing only the `proverbs` array so AG-UI can update its local state.

    This is an async function because AG-UI's state handling may involve
    async operations in more complex scenarios.

    Args:
        context: ToolResultContext containing `tool_input` (string or dict)

    Returns:
        A dictionary like `{"proverbs": [...]}` or `None` on error.
    """
    try:
        # Step 5f: Get the raw tool input from the context
        tool_input = context.tool_input

        # Step 5g: If the tool input was serialized to a string, parse it back
        # This handles cases where the LLM sends the input as a JSON string
        if isinstance(tool_input, str):
            tool_input = json.loads(tool_input)

        # Step 5h: Some call sites may package the list under `proverbs_list` key
        # This provides flexibility in how the data is structured
        proverbs_data = tool_input.get("proverbs_list", tool_input)

        # Step 5i: Ensure we extract the array safely with proper type checking
        if isinstance(proverbs_data, dict):
            proverbs_array = proverbs_data.get("proverbs", [])
        else:
            proverbs_array = []

        # Step 5j: Return the state snapshot in the expected format
        return {"proverbs": proverbs_array}
    except Exception:
        # Step 5k: Return None to indicate we couldn't build a valid state snapshot
        # AG-UI will handle this gracefully and not update the state
        return None

    // ...

Step 6: Configure Shared State between your Agent and UI

Once you have defined state management functions, configure how your AWS Strands agent and the UI share state and behave for specific tools using AG-UI’s StrandsAgentConfig class and state management functions you defined earlier, as shown below.

// ...

shared_state_config = StrandsAgentConfig(
    # Step 6a: Inject proverbs into the prompt using the builder function above
    # This ensures the LLM always has context about the current proverbs list
    state_context_builder=build_proverbs_prompt,

    # Step 6b: Define tool-specific behaviors for AG-UI integration
    # This dictionary maps tool names to their ToolBehavior configurations
    tool_behaviors={
        "update_proverbs": ToolBehavior(
            # Step 6c: Skip messages snapshot to avoid redundant state updates
            # When this is True, the tool result won't trigger a full message sync
            skip_messages_snapshot=True,

            # Step 6d: Use our custom state extractor function
            # This tells AG-UI how to extract state changes from tool arguments
            state_from_args=proverbs_state_from_args,
        )
    },
)

// ...

Step 7: Configure your AWS Strands Agent

After configuring shared state, configure your AWS Strands agent by first initializing the OpenAI model using your OpenAI API key, as shown below.

// ...

# Step 7a: Retrieve the OpenAI API key from environment variables
# Default to empty string if not set (will cause authentication errors)
api_key = os.getenv("OPENAI_API_KEY", "")

# Step 7b: Create the OpenAI model instance with configuration
model = OpenAIModel(
    # Pass API key through client_args for the underlying OpenAI client
    client_args={"api_key": api_key},
    # Use GPT-4o (the optimized version); change as appropriate for your account
    model_id="gpt-4o",
)

// ...

Then define the system prompt that sets the agent's persona and behavior, as shown below.

// ...

system_prompt = (
    "You are a helpful and wise assistant who helps manage a collection of proverbs."
)

// ...

Finally, create a Strands Agent with the model and declared tools, as shown below.

// ...

strands_agent = Agent(
    model=model,                                          # The LLM to use
    system_prompt=system_prompt,                          # Agent's persona
    tools=[update_proverbs, get_weather, set_theme_color],  # Available tools
)

// ...

Step 8: Integrate your AWS Strands Agent with AG-UI Protocol

Once you have configured your AWS Strands agent, integrate it with AG-UI protocol using AG-UI’s StrandsAgent wrapper, as shown below.

// ...

# Step 9a: Create a StrandsAgent wrapper that adds AG-UI capabilities
agui_agent = StrandsAgent(
    agent=strands_agent,       # The underlying Strands agent
    name="proverbs_agent",     # Unique identifier for this agent
    description="A proverbs assistant that collaborates with you to manage proverbs",
    config=shared_state_config,  # Shared state and tool behavior configuration
)

// ...

Step 9: Create a FastAPI Server

After integrating your AWS Strands agent with AG-UI protocol, create a FastAPI server using the AG-UI factory function to expose your Strands + AG-UI agent to the frontend, as shown below.

// ...

app = create_strands_app(agui_agent, "/")

if __name__ == "__main__":
    # Step 11a: Import uvicorn ASGI server (only needed when running directly)
    import uvicorn

    # Step 11b: Start the development server with auto-reload enabled
    # - "main:app": Module and app variable reference for uvicorn
    # - host="0.0.0.0": Listen on all network interfaces
    # - port=8000: Default HTTP port for development
    # - reload=True: Auto-restart on code changes (development mode)
    uvicorn.run("main:app", host="0.0.0.0", port=8000, reload=True)

Congrats! You've successfully integrated your Python AWS Strands Agent with AG-UI protocol and it is available at http://localhost:8000 (or specified port) endpoint.

Let’s now see how to add a frontend to your AG-UI wrapped AWS Strands agent.

Building a frontend for your AWS Strands + AG-UI agent using CopilotKit

In this section, you will learn how to add a frontend to your AWS Strands + AG-UI agent using CopilotKit, which runs anywhere that React runs.

Let’s get started.

Step 1: Install CopilotKit packages

To get started, install the latest CopilotKit packages in your frontend.

npm install @copilotkit/react-ui @copilotkit/react-core @copilotkit/runtime @ag-ui/client

Step 2: Set up the Copilot Runtime instance

Once you have installed the CopilotKit packages, set up the Copilot runtime instance with an HttpAgent example in the /api/copilotkit API route to enable your frontend to make HTTP requests to the backend.

import {
  CopilotRuntime,
  ExperimentalEmptyAdapter,
  copilotRuntimeNextJSAppRouterEndpoint,
} from "@copilotkit/runtime";

import { HttpAgent } from "@ag-ui/client";
import { NextRequest } from "next/server";

// 1. You can use any service adapter here for multi-agent support. We use
//    the empty adapter since we're only using one agent.
const serviceAdapter = new ExperimentalEmptyAdapter();

// 2. Create the CopilotRuntime instance and utilize the Strands AG-UI
//    integration to set up the connection.
const runtime = new CopilotRuntime({
  agents: {
    // Our FastAPI endpoint URL
    strands_agent: new HttpAgent({ url: "http://localhost:8000" }),
  },
});

// 3. Build a Next.js API route to handle CopilotKit runtime requests.
export const POST = async (req: NextRequest) => {
  const { handleRequest } = copilotRuntimeNextJSAppRouterEndpoint({
    runtime,
    serviceAdapter,
    endpoint: "/api/copilotkit",
  });

  return handleRequest(req);
};

Step 3: Set up CopilotKit provider

After setting up a Copilot Runtime instance, set up the CopilotKit provider component that manages your ADK agent sessions.

To set up the CopilotKit Provider, the component must wrap the Copilot-aware parts of your application.

For most use cases, it's appropriate to wrap the CopilotKit provider around the entire app, e.g., in your layout.tsx file.

// Step 1: Import necessary types and components from Next.js and CopilotKit
import type { Metadata } from "next";

import { CopilotKit } from "@copilotkit/react-core";
import "./globals.css";
import "@copilotkit/react-ui/styles.css";

// Step 2: Define metadata for the application, used by Next.js for SEO and page headers
export const metadata: Metadata = {
  title: "Create Next App",
  description: "Generated by create next app",
};

// Step 3: Define the RootLayout component, which wraps the entire application
export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  // Step 4: Return the JSX structure for the layout
  return (
    <html lang="en">
      <body className={"antialiased"}>
        {/* Step 5: Wrap the children components with CopilotKit provider to enable CopilotKit functionality */}
        <CopilotKit runtimeUrl="/api/copilotkit" agent="strands_agent">
          {children}
        </CopilotKit>
      </body>
    </html>
  );
}

Step 4: Set up a Copilot UI component

Once you have set up the CopilotKit Provider, add a Copilot UI component to enable interaction with your ADK agent. CopilotKit ships with several built-in chat components, which include CopilotPopup, CopilotSidebar, and CopilotChat.

To set up a Copilot UI component, define it alongside your core page components, e.g., in your page.tsx file.

"use client";

import { CopilotKitCSSProperties, CopilotSidebar } from "@copilotkit/react-ui";
import { useState } from "react";

export default function CopilotKitPage() {

  // ...

  return (
    <main
      // Step 2d-i: Apply theme color as a CSS custom property
      // CopilotKit components read this variable to style their elements
      style={
        { "--copilot-kit-primary-color": themeColor } as CopilotKitCSSProperties
      }
    >
      {/* Step 2d-ii: CopilotSidebar provides the chat interface */}
      <CopilotSidebar
        // Step 2d-iii: Configuration options for the sidebar behavior
        clickOutsideToClose={false}  // Keep sidebar open when clicking outside
        defaultOpen={true}            // Start with sidebar visible

        // Step 2d-iv: Labels customize the sidebar header and welcome message
        labels={{
          title: "Popup Assistant",
          initial: "👋 Hi, there! You're chatting with a Strands agent.",
        }}

        // Step 2d-v: Suggestions provide quick-action buttons for users
        // Each suggestion sends a predefined message when clicked
        suggestions={[
          {
            title: "Generative UI",
            message: "What's the weather in San Francisco?",
          },
          {
            title: "Frontend Tools",
            message: "Set the theme to green.",
          },
          {
            title: "Writing Agent State",
            message: "Add a proverb about AI.",
          },
        ]}
      >
        {/* Step 2d-vi: Child content is pushed to the side by the sidebar */}
        <YourMainContent themeColor={themeColor} />
      </CopilotSidebar>
    </main>
  );
}

Step 5: Sync your AWS Strands + AG-UI agent state with the Frontend

After setting up a Copilot UI component, sync your AWS Strands + AG-UI agent state with the frontend using CopilotKit hooks.

To sync your AWS Strands + AG-UI agent state with the frontend, use the CopilotKit useCoAgent hook that allows you to share state bidirectionally between your application and the agent.

"use client";

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

function YourMainContent({ themeColor }: { themeColor: string }) {

  // 🪁 Shared State: https://docs.copilotkit.ai/coagents/shared-state
  const { state, setState } = useCoAgent({

      // Agent name must match the CopilotKit Provider StrandsAgent name
    name: "strands_agent",
    initialState: {
      proverbs: [
        "CopilotKit may be new, but it's the best thing since sliced bread.",
      ],
    },
  })

     // ...
  return (

  // ...
  )

Step 6: Rendering your AWS Strands + AG-UI Agent Tool Calls

Once you have synced your agent state with the frontend, render your agent's tool calls with custom UI components using the CopilotKit’s [useRenderToolCall](https://docs.copilotkit.ai/reference/hooks/useRenderToolCall) hook to provide the user with feedback about what your agent is doing, specifically when your agent is calling tools, as shown below.

"use client";

import {
  useDefaultTool,
  useRenderToolCall,
} from "@copilotkit/react-core";

// ...

function YourMainContent({ themeColor }: { themeColor: string }) {

  // -------------------------------------------------------------------------
  // Step 3c: Generative UI for Weather Tool
  // -------------------------------------------------------------------------
  // 🪁 Generative UI: https://docs.copilotkit.ai/strands/generative-ui/backend-tools
  //
  // This hook tells CopilotKit how to render the "get_weather" tool call.
  // Instead of showing raw JSON, it displays a custom WeatherCard component.
  useRenderToolCall(
    {
      // Step 3c-i: Tool name to intercept for custom rendering
      name: "get_weather",

      // Step 3c-ii: Parameter schema (for documentation/type checking)
      parameters: [
        {
          name: "location",
          description: "The location to get the weather for.",
          required: true,
        },
      ],

      // Step 3c-iii: Render function called when this tool is executed
      // Returns a React component that displays the tool result visually
      render: (props) => (
        <WeatherCard themeColor={themeColor} location={props.args.location} />
      ),
    },
    // Step 3c-iv: Dependency array - re-creates the render when themeColor changes
    [themeColor],
  );

  // -------------------------------------------------------------------------
  // Step 3d: Default Generative UI (Fallback Renderer)
  // -------------------------------------------------------------------------
  // 🪁 Default Generative UI: https://docs.copilotkit.ai/strands/generative-ui/backend-tools
  //
  // This hook provides a fallback UI for any tool that doesn't have a
  // specific useRenderToolCall defined. It ensures all tools have some
  // visual representation in the chat.
  useDefaultTool(
    {
      // Step 3d-i: Default render function receives all tool props
      render: (props) => (
        <DefaultToolComponent themeColor={themeColor} {...props} />
      ),
    },
    // Step 3d-ii: Dependency array for re-render on theme changes
    [themeColor],
  );

  return (

    // ...

  );
}

Then try asking the agent for the weather in a location. You should see the custom UI component that we added, which renders the get weather tool call and displays the arguments that were passed to the tool.

Step 7: Declaring Frontend Tools

After rendering your agent's tool calls, you can declare frontend tools using the CopilotKit’s [useFrontendTool](https://docs.copilotkit.ai/reference/hooks/useFrontendTool) hook that your agent can call to interact with client-side primitives such as:

Reading or modifying React component state
Accessing browser APIs like localStorage, sessionStorage, or cookies
Triggering UI updates or animations
Interacting with third-party frontend libraries
Performing actions that require the user's immediate browser context

You can declare frontend tools and use them within your AWS Strands agent, as shown below.

"use client";

import {

  useFrontendTool,

  } from "@copilotkit/react-core";

export default function CopilotKitPage() {
  // -------------------------------------------------------------------------
  // Step 2a: Local State for Theme Color
  // -------------------------------------------------------------------------
  // Initialize with a default indigo color. This state will be updated
  // when the agent calls the "set_theme_color" frontend tool.
  const [themeColor, setThemeColor] = useState("#6366f1");

  // Step 2b: Debug Effect - logs theme color changes to console
  useEffect(() => {
    console.log(themeColor);
  }, [themeColor]);

  // -------------------------------------------------------------------------
  // Step 2c: Frontend Tool Declaration
  // -------------------------------------------------------------------------
  // 🪁 Frontend Actions: https://docs.copilotkit.ai/guides/frontend-actions
  //
  // This hook declares a tool that the agent can call, but the execution
  // happens here in the browser (not on the backend server).
  //
  // When the backend agent calls "set_theme_color", CopilotKit intercepts
  // the call and runs the handler function defined here instead.
  useFrontendTool({
    // Step 2c-i: Tool name must match the backend tool declaration
    name: "set_theme_color",

    // Step 2c-ii: Parameter schema for the LLM to understand the tool
    parameters: [
      {
        name: "theme_color",
        description: "The theme color to set. Make sure to pick nice colors.",
        required: true,
      },
    ],

    // Step 2c-iii: Handler function executed when the tool is called
    // Destructures the theme_color from the tool arguments and updates the state
    handler({ theme_color }) {
      setThemeColor(theme_color);
    },
  });

  // -------------------------------------------------------------------------
  // Step 2d: Render the Page Layout
  // -------------------------------------------------------------------------
  return (
    <main
      // Step 2d-i: Apply theme color as a CSS custom property
      // CopilotKit components read this variable to style their elements
      style={
        { "--copilot-kit-primary-color": themeColor } as CopilotKitCSSProperties
      }
    >
      {/* Step 2d-ii: CopilotSidebar provides the chat interface */}
      <CopilotSidebar
        // Step 2d-iii: Configuration options for the sidebar behavior
        clickOutsideToClose={false}  // Keep sidebar open when clicking outside
        defaultOpen={true}            // Start with sidebar visible

        // Step 2d-iv: Labels customize the sidebar header and welcome message
        labels={{
          title: "Popup Assistant",
          initial: "👋 Hi, there! You're chatting with a Strands agent.",
        }}

        // Step 2d-v: Suggestions provide quick-action buttons for users
        // Each suggestion sends a predefined message when clicked
        suggestions={[
          {
            title: "Generative UI",
            message: "What's the weather in San Francisco?",
          },
          {
            title: "Frontend Tools",
            message: "Set the theme to green.",
          },
          {
            title: "Writing Agent State",
            message: "Add a proverb about AI.",
          },
        ]}
      >
        {/* Step 2d-vi: Child content is pushed to the side by the sidebar */}
        <YourMainContent themeColor={themeColor} />
      </CopilotSidebar>
    </main>
  );
}

Then try asking the agent to set the UI theme to green. You should see the theme change to green, as shown below.

Step 8: Stream your AWS Strands + AG-UI agent responses in the frontend

To stream your AWS Strands + AG-UI agent responses or results in the frontend, pass the agent’s state field values to the frontend components, as shown below.

"use client";

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

function YourMainContent({ themeColor }: { themeColor: string }) {
  // 🪁 Shared State: https://docs.copilotkit.ai/coagents/shared-state
  const { state, setState } = useCoAgent<AgentState>({
    name: "strands_agent",
    initialState: {
      proverbs: [
        "CopilotKit may be new, but it's the best thing since sliced bread.",
      ],
    },
  })

  // ...

  return (
    <div
      // Step 3e-i: Dynamic background color from theme state
      style={{ backgroundColor: themeColor }}
      className="h-screen flex justify-center items-center flex-col transition-colors duration-300"
    >
      {/* Step 3e-ii: Glass-morphism card container for proverbs */}
      <div className="bg-white/20 backdrop-blur-md p-8 rounded-2xl shadow-xl max-w-2xl w-full">
        {/* Step 3e-iii: Page header */}
        <h1 className="text-4xl font-bold text-white mb-2 text-center">
          Proverbs
        </h1>
        <p className="text-gray-200 text-center italic mb-6">
          This is a demonstrative page, but it could be anything you want! 🪁
        </p>
        <hr className="border-white/20 my-6" />

        {/* Step 3e-iv: Proverbs list - maps over shared state array */}
        <div className="flex flex-col gap-3">
          {state.proverbs?.map((proverb, index) => (
            <div
              key={index}
              className="bg-white/15 p-4 rounded-xl text-white relative group hover:bg-white/20 transition-all"
            >
              {/* Step 3e-v: Proverb text content */}
              <p className="pr-8">{proverb}</p>

              {/* Step 3e-vi: Delete button - appears on hover */}
              <button
                onClick={() =>
                  // Step 3e-vii: Update shared state by filtering out this proverb
                  // This change will sync back to the backend agent
                  setState({
                    ...state,
                    proverbs: state.proverbs?.filter((_, i) => i !== index),
                  })
                }
                className="absolute right-3 top-3 opacity-0 group-hover:opacity-100 transition-opacity
                  bg-red-500 hover:bg-red-600 text-white rounded-full h-6 w-6 flex items-center justify-center"
              >
                ✕
              </button>
            </div>
          ))}
        </div>

        {/* Step 3e-viii: Empty state message when no proverbs exist */}
        {state.proverbs?.length === 0 && (
          <p className="text-center text-white/80 italic my-8">
            No proverbs yet. Ask the assistant to add some!
          </p>
        )}
      </div>
    </div>
    );
}

If you query your AWS Strands + AG-UI agent, you should see the agent’s response or results streaming in the UI, as shown below.

Conclusion

In this guide, we have walked through the steps to build a frontend for your AWS Strands agent using the AG-UI protocol and CopilotKit.

Hopefully, this guide makes it easier for you to integrate AI-powered Copilots into your existing application.

Follow CopilotKit on Twitter and say hi. If you'd like to build something cool, join the Discord community.

Converting Figma Design To Next.js Code In Minutes

Bonnie — Tue, 02 Dec 2025 15:24:03 +0000

In this guide, you will learn how to convert Figma designs into production-ready Next.js code code in minutes using Kombai, a specialized frontend AI agent that's about to become your new best friend.

Before we jump in, here is what we will cover:

Understanding what Kombai AI agent is
Configuring your Tech stack
Generating and reviewing a code plan
Generating, running and previewing code
Analyzing output results

Here is a preview of the final results.

Understanding what is Kombai AI Agent

Kombai is a highly specialized AI agent built for frontend developme*nt,* designed to automate the conversion of Figma designs into clean, production-ready code.

It is a domain-specific agent, meaning its AI models are fine-tuned for the nuances of UI (User Interface) creation, making it more effective at this task than general-purpose coding assistants.

Here is a breakdown of Kombai key capabilities:

Multi-input support: Works with Figma designs, text instructions, images, or existing code
Tech stack aware: Supports 30+ frontend libraries including React, Next.js, Material UI, Tailwind, and more
Smart planning: Generates editable development plans before complex tasks using plan mode.
Codebase integration: Scans and reuses existing components and theme variables in your codebase.
Auto-fixing: Automatically fixes TypeScript and linting errors after generating code from Figma designs or images.
Sandbox preview: Run and test generated code in a local environment
Three modes: Plan Mode for code plan generation, Code Mode for code generation, and Ask Mode for codebase understanding.
Preview browser: Kombai browser lets you preview your app’s local deployment in the browser with built-in listeners so you can iterate fast by sending elements and errors back to Kombai as context.

You can learn more about Kombai AI agent here on Kombai docs.

Prerequisites

To fully understand this tutorial, you need to have a basic understanding of Next.js

A Kombai AI account (they have a free tier).
A Figma account with a design file you want to convert.
Visual Studio Code (or a supported IDE like Cursor).
The Kombai AI VS Code extension.
A new or existing Next.js project.

Step 1: Setting Up Your Project and the Kombai Agent

In this section, you will learn how to set up your Next.js project and Kombai AI agent in your IDE (VS Code, Cursor, WindSurf, etc).

Let’s get started.

First, open your Next.js project in your IDE or set up one using the command below.

npx create-next-app@15.5.6 kombai-nextjs-app --yes

Then Install the Kombai AI extension from the marketplace, as shown below.

Once the Kombai extension is installed, click Sign In button in Kombai. Then you will be redirected to the Kombai website to Sign up or log in to your Kombai account.

After signing in, you will be redirected back to the IDE.

Step 2: Scan and Configure your tech stack

Once you have set up your project and the Kombai extension in your IDE, configure your tech stack.

The Kombai agent offers a wide range of tech stacks which lets you generate code that aligns with your workspace’s requirements.

In this case, our Tech stack will be Next.js, and TypeScript. To configure your tech stack, follow the steps as shown below and then save the configuration.

Step 3: Define Code Generation Rules

After scanning and configuring your tech stack, set persistent instructions for Kombai using rules and Agents.md files. The rules provide project level instructions to Kombai in order to enforce specific coding standards, architectural patterns, and output formats

To set the rules or instructions, create a AGENTS.md file in your project and add the project rules or instructions.

You can generate the project instructions by first taking screen shots of your Figma design, as shown below.

Then navigate to Google Gemini, add the screenshot to the chat and generate the instructions using the prompt below.

Give me a prompt for generating a Next.js + TypeScript + Tailwind css web app 
from the provided Figma designs. Describe structure of each page section in 
detail

Once the instructions have been generated, add them to your AGENTS.md file, as shown below.

After that, Kombai automatically picks up the **AGENTS.md** file stored, as shown below.

Step 4: Connect Figma and add your Figma design to Kombai

Once you have defined code generation rules, connect your Figma account with Kombai in order to access your Figma design and generate code based on them, as shown below.

Once you have connected your Figma account, copy your Figma design link, and add it to Kombai, as shown below.

Step 5: Generate, and review code plan

After connecting your Figma account and adding your Figma designs to Kombai, use Kombai plan mode to generate a detailed code plan for the given input before starting the code generation, as shown below.

You can learn more about Kombai plan mode here on Kombai docs.

Step 6: Generate, Run and Fix Code Errors

Once the coding plan is approved or updated, Kombai will generate the code based on the plan, and auto-fix any TS or linting errors found in the generated code, as shown below.

After that, Kombai will run the development server and you can fix any build errors, as shown below.

Step 7: Preview your App using Kombai Browser

After generating code and fixing errors, run the code in Kombai Browser to preview the generated code.

If you find any visual mismatches in the preview, you can tag DOM elements and suggest Kombai to make the necessary changes. Kombai will regenerate the code accordingly, as shown below.

Step 8: Analyzing Kombai Figma Design to Next.js Code Output Results

Once you have run and previewed your app, analyze the generated code and the UI to make sure it is close to what you wanted.

From the output results, Kombai gives you clean, semantic JSX that a human would write since the agent understands layout and structure, not just layers.

Kombai gets you 80-90% of the way where it builds the perfect UI scaffolding, which is the most laborious part. You, the developer, are still needed for the last 10-20% and that's the fun part.

Also, as you can see from the preview results below, Kombai was able to generate frontend UI that is pixel perfect with the Figma design. The code only requires minimal tweaks to match the desired UI design.

What Differentiates Kombai from other Figma Design to Code tools

After using general coding agents, MCPs and Kombai to convert Figma designs into Next.js Code, Kombai significantly outperforms these other AI tools in building UX & UI from Figma, images, or text based prompts as shown below in benchmarks for real-world frontend tasks.

Here are the key reasons for its high-quality output:

"Human-Like" UX Interpretation:
- Unlike older tools that required strict layer naming or auto-layout in Figma, Kombai uses deep learning models to understand the design visually, similar to how an experienced human developer would.
- It intelligently infers structure, component boundaries, spacing, and layout hierarchies even from messy or non-ideal design files.
Workflow Integration and Safety:
- Kombai integrates directly into developer IDEs (like VS Code).
- Planning: For complex tasks, it generates an editable development plan (often in Markdown) before writing code.
- Sandbox Preview: It can spin up a local development server to preview the generated UI in isolation to validate the output before it touches your main codebase.
- Error Correction: It automatically attempts to fix linting and TypeScript errors, and you can feed runtime errors back to the agent for correction.
Codebase Awareness:
- It can analyze your existing repository to detect your current tech stack, styling frameworks, and component libraries. This allows it to generate code that is consistent and integrates seamlessly into your project's architecture.

In essence, Kombai acts as a highly specialized AI partner for frontend teams, taking on the task of building the user interface shell so human developers can focus on complex application logic and unique user experiences.

Conclusion

In conclusion, Kombai AI agent changes the developer's role where it eliminates the most time-consuming, least creative part of frontend development.

Note that this isn't about replacing developers but upgrading their frontend developement workflow.

You are no longer a translator for a designer but a reviewer and integrator of high-quality code, which allows you to move 10x faster and focus on what actually matters: your app's logic, state, and data flow.

Stop hand-coding your UI boilerplate. Grab a free Kombai account, install the VS Code extension, and try converting one of your own Figma frames.

You won't just be surprised by how much time you get back, you will change how you approach frontend development.

Build a Frontend for your Microsoft Agent Framework (Python) Agents with AG-UI

Bonnie — Fri, 21 Nov 2025 14:24:21 +0000

TL;DR

In this guide, you will learn how to build a frontend for your Microsoft Agent Framework (Python) Agents using AG-UI Protocol and CopilotKit. Microsoft Agent Framework (Python) will power the AI agents backend, while CopilotKit powers the frontend, and then AG-UI creates a bridge that enables the frontend to communicate with the backend.

Check out AG-UI's GitHub ⭐️

Before we jump in, here is what we will cover:

Understanding the Microsoft Agent Framework?
Setting up a Microsoft Agent Framework + AG-UI + CopilotKit agent using CLI
Integrating your Microsoft Agent Framework agent with AG-UI protocol in the backend
Building a frontend for your Microsoft Agent Framework + AG-UI agent using CopilotKit

Here is a preview of what you can build using Microsoft Agent Framework (Python) + AG-UI + CopilotKit.

What is the Microsoft Agent Framework?

The Microsoft Agent Framework (MAF) is an open-source development kit (SDK) and runtime for building and deploying AI agents and multi-agent workflows in both Python and NET.

MAF is considered the next generation of Microsoft's previous agent-related projects, unifying the strengths of AutoGen (for innovative multi-agent orchestration) and Semantic Kernel (for enterprise-grade features and production readiness).

The core purpose of the framework is to allow developers to create sophisticated AI applications that involve:

Individual AI agents that use Large Language Models (LLMs) to reason, make decisions, and use tools.
Complex multi-agent systems where multiple agents collaborate to solve complex, multi-step tasks.

The Python implementation offers a developer-friendly experience that is highly suitable for building and testing agentic systems quickly.

If you want to dive deeper into how Microsoft Agent Framework works and its setup, check out the docs here: Microsoft Agent Framework docs.

Prerequisites

Before you begin, you'll need the following:

OpenAI or Azure OpenAI credentials (for the Microsoft Agent Framework agent)
Python 3.12+
uv
Node.js 20+
Any of the following package managers:
- pnpm (recommended)
- npm
- yarn
- bun

Setting up a Microsoft Agent Framework + AG-UI + CopilotKit agent using CLI

In this section, you will learn how to set up a full-stack Microsoft Agent Framework (Python) agent using a CLI command that sets up the backend using AG-UI protocol and the frontend using CopilotKit.

Let’s get started.

Step 1: Run CLI command

If you don’t already have a Microsoft Agent Framework agent, you can set up one quickly by running the CLI command below in your terminal.

npx copilotkit@latest init -m microsoft-agent-framework-py

Then give your project a name as shown below.

Step 2: Install dependencies

Once your project has been created successfully, install dependencies using your preferred package manager:

# Using pnpm (recommended)
pnpm install

# Using npm
npm install

# Using yarn
yarn install

# Using bun
bun install

Step 3: Set up your agent credentials

After installing the dependencies, set up your agent credentials. The backend automatically uses Azure when the Azure env vars below are present; otherwise, it falls back to OpenAI.

To set up your agent credentials, create a .env file inside the agent folder with one of the following configurations:

OpenAI:

OPENAI_API_KEY=sk-...your-openai-key-here...
OPENAI_CHAT_MODEL_ID=gpt-4o-mini

Azure OpenAI:

AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
AZURE_OPENAI_CHAT_DEPLOYMENT_NAME=gpt-4o-mini
# If you are not relying on az login:
# AZURE_OPENAI_API_KEY=...

Step 4: Run development server

Then start the development server using your preferred package manager:

# Using pnpm
pnpm dev

# Using npm
npm run dev

# Using yarn
yarn dev

# Using bun
bun run dev

Once the development server is running, navigate to http://localhost:3000/ and you should see your Microsoft Agent Framework (Python) + AG-UI + CopilotKit agent up and running.

Congrats! You've successfully set up a full-stack Microsoft Agent Framework agent. Your AI agent is now ready to use! Try playing around with the suggestions in the chat to test the integration.

Integrating your Microsoft Agent Framework agent with AG-UI protocol in the backend

In this section, you will learn how to integrate your Microsoft Agent Framework agent with AG-UI protocol to expose it to the frontend.

Let’s jump in.

Step 1: Install Microsoft Agent Framework + AG-UI packages

To get started, install the Microsoft Agent Framework + AG-UI packages together with other necessary dependencies using the commands below.

uv pip install agent-framework, agent-framework-ag-ui, azure-identity

Step 2: Define your agent state

Once you have installed the required packages, use a JSON schema to define the structure of the agent state that will be synchronised between the backend and the frontend UI, as shown below.

from __future__ import annotations

from textwrap import dedent
from typing import Annotated

# Import core agent framework components for building conversational AI agents
from agent_framework import ChatAgent, ChatClientProtocol, ai_function
# Import CopilotKit integration layer that bridges Agent Framework with the frontend
from agent_framework_ag_ui import AgentFrameworkAgent
from pydantic import Field

# STATE_SCHEMA: Defines the structure of agent state 
STATE_SCHEMA: dict[str, object] = {
    "proverbs": {
        "type": "array",  # Proverbs is a list/array of items
        "items": {"type": "string"},  # Each item in the array is a string
        "description": "Ordered list of the user's saved proverbs.",  # Human-readable description
    }
}

// ...

After that, use a state config JSON schema to tell the agent which tool function to call when it needs to update state, as shown below.

from __future__ import annotations

from textwrap import dedent
from typing import Annotated

# Import core agent framework components for building conversational AI agents
from agent_framework import ChatAgent, ChatClientProtocol, ai_function
# Import CopilotKit integration layer that bridges Agent Framework with the frontend
from agent_framework_ag_ui import AgentFrameworkAgent
from pydantic import Field

// ...

# PREDICT_STATE_CONFIG: Maps state fields to the tools that modify them.
# This tells your agent which tool function to call when the agent needs to update
# a particular piece of state, and which argument of that tool contains the new state value.
PREDICT_STATE_CONFIG: dict[str, dict[str, str]] = {
    "proverbs": {
        "tool": "update_proverbs",  # The name of the tool function that updates proverbs
        "tool_argument": "proverbs",  # The parameter name in that tool that receives the new proverb list
    }
}

// ...

Step 3: Define your agent tools

After defining your agent state, configure your agent tools using the @ai_function decorator to mark them as tools that your AI agent can call, as shown below. The name and description help the agent to understand when and how to use these tools.

from __future__ import annotations

from textwrap import dedent
from typing import Annotated

# Import core agent framework components for building conversational AI agents
from agent_framework import ChatAgent, ChatClientProtocol, ai_function
# Import CopilotKit integration layer that bridges Agent Framework with the frontend
from agent_framework_ag_ui import AgentFrameworkAgent
from pydantic import Field

// ...

# @ai_function decorator: Marks this as a tool that the AI agent can call.
# The name and description help the LLM understand when and how to use this tool.
@ai_function(
    name="update_proverbs",
    description=(
        "Replace the entire list of proverbs with the provided values. "
        "Always include every proverb you want to keep."
    ),
)
def update_proverbs(
    proverbs: Annotated[
        list[str],  # The function accepts a list of strings
        Field(
            description=(
                # This description guides the LLM on how to use this parameter correctly.
                # Emphasises that this should be the COMPLETE list, not a partial update.
                "The complete source of truth for the user's proverbs. "
                "Maintain ordering and include the full list on each call."
            )
        ),
    ],
) -> str:
    """
    Persist the provided set of proverbs.

    Returns:
        A confirmation message indicating how many proverbs are now tracked.
    """
    return f"Proverbs updated. Tracking {len(proverbs)} item(s)."

# Weather tool: Demonstrates frontend UI integration through tool calls.
# When the agent calls this function, CopilotKit can render a weather card in the UI.
@ai_function(
    name="get_weather",
    description="Share a quick weather update for a location. Use this to render the frontend weather card.",
)
def get_weather(
    location: Annotated[str, Field(description="The city or region to describe. Use fully spelled out names.")],
) -> str:
    """
    Return a short natural language weather summary.

    Args:
        location: The city or region name to get the weather for.

    Returns:
        A friendly weather description string that can be displayed to the user.
    """
    # Normalise the location string: remove whitespace, capitalise words
    normalized = location.strip().title() or "the requested location"

    # Return a mock weather response (in production, this would query a real API)
    return (
        f"The weather in {normalised} is mild with a light breeze. "
        "Skies are mostly clear—perfect for planning something fun."
    )

# Human-in-the-loop tool: Demonstrates requiring explicit user approval before executing.
# The approval_mode="always_require" parameter ensures this function will pause execution
# and wait for the user to explicitly approve or reject the action via the UI.
@ai_function(
    name="go_to_moon",
    description="Request a playful human-in-the-loop confirmation before launching a mission to the moon.",
    approval_mode="always_require",  # CRITICAL: Forces user approval before this tool executes
)
def go_to_moon() -> str:
    """
    Request human approval before continuing.


    Returns:
        A message confirming the approval request has been initiated.
    """
    return "Mission control requested. Awaiting human approval for the lunar launch."

Step 4: Create, configure and integrate your agent with AG-UI protocol

Once you have defined your agent tools, create your agent with Microsoft Agent Framework. Then configure the agent with instructions, chat client, and tools, as shown below.

from __future__ import annotations

from textwrap import dedent
from typing import Annotated

# Import core agent framework components for building conversational AI agents
from agent_framework import ChatAgent, ChatClientProtocol, ai_function
# Import CopilotKit integration layer that bridges Agent Framework with the frontend
from agent_framework_ag_ui import AgentFrameworkAgent
from pydantic import Field

// ...

def create_agent(chat_client: ChatClientProtocol) -> AgentFrameworkAgent:
    """
    Instantiate the Microsoft Agent Framework with AG-UI.

    This is the main entry point for creating the agent. It configures the base ChatAgent
    with instructions and tools, then wraps it in an AgentFrameworkAgent for AG-UI integration.

    Args:
        chat_client: The chat client protocol implementation that handles LLM communication.

    Returns:
        A fully configured AgentFrameworkAgent ready to handle user interactions.
    """
    # Step 1: Create the base ChatAgent with Microsoft Agent Framework
    # This agent handles the core conversational logic and tool execution
    base_agent = ChatAgent(
        name="proverbs_agent",  # Internal identifier for this agent

        # System instructions: These guide the agent's behaviour throughout the conversation.
        # The instructions are carefully crafted to ensure proper state management,
        # tool usage, and user experience.
        instructions=dedent(
            """
            You help users brainstorm, organize, and refine proverbs while coordinating UI updates.

            // ...

            """.strip()
        ),

        # The chat client handles actual LLM API calls (e.g., to OpenAI, Azure OpenAI, etc.)
        chat_client=chat_client,

        # Tools: These are the functions the agent can call to perform actions
        tools=[update_proverbs, get_weather, go_to_moon],
    )

    // ...

After that, wrap your agent with AgentFrameworkAgent middleware for frontend communication using AG-UI, as shown below.

from __future__ import annotations

from textwrap import dedent
from typing import Annotated

# Import core agent framework components for building conversational AI agents
from agent_framework import ChatAgent, ChatClientProtocol, ai_function
# Import CopilotKit integration layer that bridges Agent Framework with the frontend
from agent_framework_ag_ui import AgentFrameworkAgent
from pydantic import Field

// ...

def create_agent(chat_client: ChatClientProtocol) -> AgentFrameworkAgent:
    """
    Instantiate the Microsoft Agent Framework with AG-UI.

    This is the main entry point for creating the agent. It configures the base ChatAgent
    with instructions and tools, then wraps it in an AgentFrameworkAgent for CopilotKit integration.

    Args:
        chat_client: The chat client protocol implementation that handles LLM communication.

    Returns:
        A fully configured AgentFrameworkAgent ready to handle user interactions.
    """
    # Step 1: Create the base ChatAgent with Microsoft Agent Framework
    # This agent handles the core conversational logic and tool execution

    // ...

    # Step 2: Wrap the base agent in an AgentFrameworkAgent for AG-UI integration
    # This wrapper adds CopilotKit-specific features like state sync and frontend coordination
    return AgentFrameworkAgent(
        agent=base_agent,  # The underlying ChatAgent we just configured

        name="CopilotKitMicrosoftAgentFrameworkAgent",  # Display name for the agent
        description="Manages proverbs, weather snippets, and human-in-the-loop moon launches.",

        # STATE_SCHEMA tells CopilotKit what state this agent manages
        state_schema=STATE_SCHEMA,

        # PREDICT_STATE_CONFIG maps state fields to the tools that update them
        predict_state_config=PREDICT_STATE_CONFIG,

        # require_confirmation=False means the agent can update the state and continue
        # without waiting for explicit user confirmation after each state change.
        # This allows for smoother conversational flow.
        require_confirmation=False,
    )

Step 5: Build and configure chat client

Once you have wrapped your agent with AgentFrameworkAgent middleware, build and configure a chat client with Azure OpenAI or OpenAI credentials using their respective clients, as shown below in the ./main.py file.

from __future__ import annotations

import os

# Uvicorn: ASGI server for running FastAPI applications
import uvicorn
# ChatClientProtocol: Interface that all chat clients must implement
from agent_framework._clients import ChatClientProtocol

// ...

# Load environment variables from .env file (must be done before accessing os.getenv)
# This allows developers to configure API keys and endpoints without hardcoding them
load_dotenv()

def _build_chat_client() -> ChatClientProtocol:
    """
    Build and configure the appropriate chat client based on environment variables.

    Returns:
        ChatClientProtocol: A configured chat client ready to communicate with an LLM.

    Raises:
        RuntimeError: If credentials are missing or invalid.
    """
    try:
        # Option 1: Azure OpenAI Service
        # Check if Azure OpenAI endpoint is configured
        if bool(os.getenv("AZURE_OPENAI_ENDPOINT")):
            # Azure OpenAI uses deployment names instead of model IDs
            # Deployments are custom instances of models you create in Azure
            deployment_name = os.getenv("AZURE_OPENAI_CHAT_DEPLOYMENT_NAME", "gpt-4o-mini")

            return AzureOpenAIChatClient(
                # DefaultAzureCredential tries multiple authentication methods:
                # 1. Environment variables (AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, etc.)
                # 2. Managed Identity (if running on Azure infrastructure)
                # 3. Azure CLI credentials (for local development)
                credential=DefaultAzureCredential(),

                # The name of your deployed model in Azure OpenAI Studio
                deployment_name=deployment_name,

                # Your Azure OpenAI resource endpoint (e.g., https://my-resource.openai.azure.com/)
                endpoint=os.getenv("AZURE_OPENAI_ENDPOINT"),
            )

        # Option 2: OpenAI API (public service)
        # Check if OpenAI API key is configured
        if bool(os.getenv("OPENAI_API_KEY")):
            return OpenAIChatClient(
                # Model identifier from OpenAI's catalogue (e.g., gpt-4o-mini, gpt-4, etc.)
                model_id=os.getenv("OPENAI_CHAT_MODEL_ID", "gpt-4o-mini"),

                # Your OpenAI API key from platform.openai.com
                api_key=os.getenv("OPENAI_API_KEY"),
            )

        # If neither Azure nor OpenAI credentials are found, raise an error
        raise ValueError("Either AZURE_OPENAI_ENDPOINT or OPENAI_API_KEY environment variable is required")

    except Exception as exc:  # pragma: no cover
        # Catch any initialization errors and provide a helpful message
        raise RuntimeError(
            "Unable to initialize the chat client. Double-check your API credentials as documented in README.md."
        ) from exc

Then configure your Microsoft Agent Framework + AG-UI agent with the chat client, as shown below.

from __future__ import annotations

import os

# Uvicorn: ASGI server for running FastAPI applications
import uvicorn
# ChatClientProtocol: Interface that all chat clients must implement
from agent_framework._clients import ChatClientProtocol

// ...

# Step 1: Initialize the chat client
# This creates the connection to either Azure OpenAI or OpenAI API
chat_client = _build_chat_client()

# Step 2: Create the agent with the configured chat client
# This instantiates our MAF + AG-UI agent with all its tools and instructions
my_agent = create_agent(chat_client)

// ...

Step 6: Add a FastAPI server and configure your agent endpoint

Once you have built the chat client with credentials, add a FastAPI server that exposes your Microsoft Agent Framework agent over AG-UI, as shown below.

from __future__ import annotations

import os

# Uvicorn: ASGI server for running FastAPI applications
import uvicorn
# add_agent_framework_fastapi_endpoint: CopilotKit integration that registers agent endpoints
from agent_framework_ag_ui import add_agent_framework_fastapi_endpoint
# dotenv: Loads environment variables from .env file
from dotenv import load_dotenv
# FastAPI: Modern web framework for building APIs
from fastapi import FastAPI
# CORSMiddleware: Handles Cross-Origin Resource Sharing for frontend communication
from fastapi.middleware.cors import CORSMiddleware

// ...

# Step 3: Create the FastAPI application
# FastAPI will handle HTTP requests from the frontend and route them to our agent
app = FastAPI(title="CopilotKit + Microsoft Agent Framework (Python)")

# Step 4: Configure CORS (Cross-Origin Resource Sharing)
# This is essential for allowing the frontend (running on a different port/domain)
# to communicate with this backend API
app.add_middleware(
    CORSMiddleware,
    # allow_origins=["*"] means accept requests from any domain
    # In production, you should restrict this to your specific frontend domain(s)
    # e.g., allow_origins=["https://myapp.com", "https://www.myapp.com"]
    allow_origins=["*"],

    # Allow cookies and authentication headers to be included in requests
    allow_credentials=True,

    # Allow all HTTP methods (GET, POST, PUT, DELETE, etc.)
    allow_methods=["*"],

    # Allow all headers (Content-Type, Authorization, etc.)
    allow_headers=["*"],
)

# Step 5: Register the CopilotKit endpoint
# This function adds the necessary routes to handle CopilotKit's communication protocol
# It creates endpoints for:
# - Agent chat interactions
# - State synchronization
# - Tool execution
# - Streaming responses
add_agent_framework_fastapi_endpoint(
    app=app,  # The FastAPI application to add routes to
    agent=my_agent,  # Our configured agent instance
    path="/",  # Base path for CopilotKit endpoints (frontend will connect here)
)

# ============================================================================
# Main Entry Point
# ============================================================================

if __name__ == "__main__":
    # This block runs only when executing this file directly (not when imported)
    # It starts the web server that listens for requests from the frontend

    # Read server configuration from environment variables with sensible defaults
    host = os.getenv("AGENT_HOST", "0.0.0.0")  # 0.0.0.0 means listen on all network interfaces
    port = int(os.getenv("AGENT_PORT", "8000"))  # Default to port 8000

    # Start the Uvicorn ASGI server
    # - "main:app" references the 'app' variable in the 'main' module
    # - host and port determine where the server listens
    # - reload=True enables auto-restart when code changes (great for development)
    #   NOTE: In production, set reload=False for better performance and stability
    uvicorn.run("main:app", host=host, port=port, reload=True)

Congrats! You've successfully integrated your Python Microsoft Agent Framework Agent with AG-UI protocol, and it is available at http://localhost:8000 (or specified port) endpoint.

Let’s now see how to add a frontend to your AG-UI wrapped Microsoft Agent Framework agent.

Building a frontend for your Microsoft Agent Framework + AG-UI agent using CopilotKit

In this section, you will learn how to add a frontend to your Microsoft Agent Framework + AG-UI agent using CopilotKit, which runs anywhere that React runs.

Let’s get started.

Step 1: Install CopilotKit packages

To get started, install the latest packages for CopilotKit into your frontend.

npm install @copilotkit/react-ui @copilotkit/react-core @copilotkit/runtime

Step 2: Set up the Copilot Runtime instance

Once you have installed CopilotKit packages, set up the copilot runtime instance with an HttpAgent instance in the /api/copilotkit API route that enables your frontend to make HTTP requests to the backend.

import {
  CopilotRuntime, // Main runtime that manages agent communication
  ExperimentalEmptyAdapter, // Service adapter for single-agent setups
  copilotRuntimeNextJSAppRouterEndpoint, // Next.js App Router endpoint handler
} from "@copilotkit/runtime";

// Import AG-UI client for connecting to Microsoft Agent Framework agents
import { HttpAgent } from "@ag-ui/client";

// Import Next.js types for request handling
import { NextRequest } from "next/server";

// Create a service adapter for the CopilotKit runtime
const serviceAdapter = new ExperimentalEmptyAdapter();

// Create the main CopilotRuntime instance that manages communication between the frontend and backend agents
const runtime = new CopilotRuntime({

  // Define the agents that will be available to the frontend
    agents: {

    // Configure the ADK agent connection
    my_agent: new HttpAgent({

      // Specify the URL where the Microsoft Agent Framework agent is running
      url: "http://localhost:8000/",
    }),
  },
});

// Export the POST handler for the API route
export const POST = async (req: NextRequest) => {

  // Create the request handler using CopilotKit's Next.js helper
  const { handleRequest } = copilotRuntimeNextJSAppRouterEndpoint({
    runtime, // The CopilotRuntime instance we configured
    serviceAdapter, // The service adapter for agent coordination
    endpoint: "/api/copilotkit", // The endpoint path (matches this file's location)
  });


  return handleRequest(req);
};

Step 3: Set up CopilotKit provider

After setting up a Copilot Runtime instance, set up the CopilotKit provider component that manages your ADK agent sessions.

To set up the CopilotKit Provider, the [<CopilotKit>](https://docs.copilotkit.ai/reference/components/CopilotKit) component must wrap the Copilot-aware parts of your application.

For most use cases, it's appropriate to wrap the CopilotKit provider around the entire app, e.g., in your layout.tsx file.

// Step 1: Import necessary types and components from Next.js and CopilotKit
import type { Metadata } from "next";

import { CopilotKit } from "@copilotkit/react-core";
import "./globals.css";
import "@copilotkit/react-ui/styles.css";

// Step 2: Define metadata for the application, used by Next.js for SEO and page headers
export const metadata: Metadata = {
  title: "Create Next App",
  description: "Generated by create next app",
};

// Step 3: Define the RootLayout component, which wraps the entire application
export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  // Step 4: Return the JSX structure for the layout
  return (
    <html lang="en">
      <body className={"antialiased"}>
        {/* Step 5: Wrap the children components with CopilotKit provider to enable CopilotKit functionality */}
        <CopilotKit runtimeUrl="/api/copilotkit" agent="my_agent">
          {children}
        </CopilotKit>
      </body>
    </html>
  );
}

Step 4: Set up a Copilot UI component

Once you have set up the CopilotKit Provider, set up a Copilot UI component that enables you to interact with your ADK agent. CopilotKit ships with a number of built-in chat components, which include CopilotPopup, CopilotSidebar, and CopilotChat.

To set up a Copilot UI component, define it alongside your core page components, e.g. in your page.tsx file.

"use client";

import { CopilotKitCSSProperties, CopilotSidebar } from "@copilotkit/react-ui";
import { useState } from "react";

export default function CopilotKitPage() {
  const [themeColor, setThemeColor] = useState("#6366f1");

  // ...

  return (
    <main style={{ "--copilot-kit-primary-color": themeColor } as CopilotKitCSSProperties}>
      <CopilotSidebar
        disableSystemMessage={true}
        clickOutsideToClose={false}
        labels={{
          title: "Popup Assistant",
          initial: "👋 Hi, there! You're chatting with an agent.",
        }}
        suggestions={[
          {
            title: "Generative UI",
            message: "Get the weather in San Francisco.",
          },
          {
            title: "Frontend Tools",
            message: "Set the theme to green.",
          },
          {
            title: "Human in the Loop",
            message: "Please go to the moon.",
          },
          {
            title: "Write Agent State",
            message: "Add a proverb about AI.",
          },
          {
            title: "Update Agent State",
            message: "Please remove 1 random proverb from the list if there are any.",
          },
          {
            title: "Read Agent State",
            message: "What are the proverbs?",
          },
        ]}
      >
        <YourMainContent themeColor={themeColor} />
      </CopilotSidebar>
    </main>
   );
}

Step 5: Sync your Microsoft Agent Framework agent state with the frontend

After setting up a Copilot UI component, sync your Microsoft Agent Framework agent state with the frontend using CopilotKit hooks.

To sync your Microsoft Agent Framework agent state with the frontend, use the CopilotKit useCoAgent hook that allows you to share state bidirectionally between your application and the agent.

"use client";

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

// State of the agent, make sure this aligns with your agent's state.
type AgentState = {
  proverbs: string[];
}

function YourMainContent({ themeColor }: { themeColor: string }) {

  // 🪁 Shared State: https://docs.copilotkit.ai/coagents/shared-state
  const { state, setState } = useCoAgent<AgentState>({
    name: "my_agent",
    initialState: {
      proverbs: [
        "CopilotKit may be new, but it's the best thing since sliced bread.",
      ],
    },
  })

     // ...
  return (

  // ...
  )

To render your agent's state, progress, outputs, or tool calls with custom UI components in real-time, you can use tool-based Generative UI.

"use client";

import { useCoAgent, useCopilotAction } from "@copilotkit/react-core";

// ...

function YourMainContent({ themeColor }: { themeColor: string }) {
  // ...

  //🪁 Generative UI: https://docs.copilotkit.ai/coagents/generative-ui
  useCopilotAction({
    name: "get_weather",
    description: "Get the weather for a given location.",
    available: "disabled",
    parameters: [
      { name: "location", type: "string", required: true },
    ],
    render: ({ args }) => {
      return <WeatherCard location={args.location} themeColor={themeColor} />
    },
  });

  return ( ... )

Then try asking the agent to get the weather for a location. You should see the custom UI component that we added renders the get weather tool call and displays the arguments that were passed to the tool.

Step 6: Implementing Human-in-the-Loop (HITL) in the frontend

Human-in-the-loop (HITL) allows agents to request human input or approval during execution, making AI systems more reliable and trustworthy. This pattern is essential when building AI applications that need to handle complex decisions or actions that require human judgment.

You can learn more about Human in the Loop here on CopilotKit docs.

To implement Human-in-the-Loop (HITL) in the frontend, you need to use the CopilotKit useCopilotKitAction hook with the renderAndWaitForResponse method, which allows returning values asynchronously from the render function, as shown in the src/app/page.tsx file.

import { MoonCard } from "@/components/moon";
import { useCopilotAction } from "@copilotkit/react-core";

// ...

function YourMainContent({ themeColor }: { themeColor: string }) {

  // ...

  // 🪁 Human In the Loop: https://docs.copilotkit.ai/pydantic-ai/human-in-the-loop
  useCopilotAction(
    {
      name: "go_to_moon",
      description: "Go to the moon on request.",
      renderAndWaitForResponse: ({ respond, status }) => {
        return <MoonCard themeColor={themeColor} status={status} respond={respond} />;
      },
    },
    [themeColor],
  );

  return (

    // ...

  );
}

Then try asking the agent to go to the moon. Then the agent will trigger frontend actions by tool/action name to request human input or feedback during execution, and you are prompted with a choice (rendered inside the chat UI). Then you can choose by pressing a button in the chat UI, as shown below.

Step 7: Stream your Microsoft Agent Framework agent responses in the frontend

Once you have synced your Microsoft Agent Framework agent state with the frontend, stream your MAF agent responses or results in the frontend.

To stream your Microsoft Agent Framework agent responses or results in the frontend, pass the agent’s state field values to the frontend components, as shown below.

"use client";

import { useCoAgent } from "@copilotkit/react-core";
import { ProverbsCard } from "@/components/proverbs";

// State of the agent, make sure this aligns with your agent's state.
type AgentState = {
  proverbs: string[];
}

function YourMainContent({ themeColor }: { themeColor: string }) {
  // 🪁 Shared State: https://docs.copilotkit.ai/coagents/shared-state
  const { state, setState } = useCoAgent<AgentState>({
    name: "my_agent",
    initialState: {
      proverbs: [
        "CopilotKit may be new, but it's the best thing since sliced bread.",
      ],
    },
  })

  // ...

  return (
    <div
      style={{ backgroundColor: themeColor }}
      className="h-screen flex justify-center items-center flex-col transition-colors duration-300"
    >
      <ProverbsCard state={state} setState={setState} />
    </div>
    );
}

If you query your Microsoft Agent Framework agent, you should see the agent’s response or results streaming in the UI, as shown below.

Conclusion

In this guide, we have walked through the steps of building a frontend for your Microsoft Agent Framework agent using AG-UI protocol and CopilotKit.

While we’ve explored a couple of features, we have barely scratched the surface of the countless use cases for CopilotKit, ranging from building interactive AI chatbots to building agentic solutions—in essence, CopilotKit lets you add a ton of useful AI capabilities to your products in minutes.

Hopefully, this guide makes it easier for you to integrate AI-powered Copilots into your existing application.

Follow CopilotKit on Twitter and say hi, and if you'd like to build something cool, join the Discord community.

Converting Figma Design To React + Material UI Code In Minutes

Bonnie — Wed, 19 Nov 2025 16:17:06 +0000

TL;DR

Imagine if you could convert your Figma designs into production-ready React + Material UI code faster than you can grab a coffee.

In this guide, you will learn how to convert Figma designs into production-ready React code in minutes using Kombai, a specialized frontend AI agent that's about to become your new best friend.

Before we jump in, here is what we will cover:

What is Kombai?
Setting up the Kombai AI Agent in your IDE (VS Code, Cursor, etc.)
Connecting Figma with Kombai
Adding Figma design to Kombai
Configuring your tech stack
Reviewing code generation plan
Running & previewing your app using Kombai browser

Here is a preview of the final results.

What is Kombai?

Kombai is an AI agent purpose-built for frontend development. It generates beautiful, functional frontends from Figma, text, images, or code, understanding your codebase and best practices of 30+ frontend libraries.

Key features:

Multi-input support: Works with Figma designs, text instructions, images, or existing code
Tech stack aware: Supports 30+ frontend libraries including React, Next.js, Material UI, Tailwind, and more
Smart planning: Generates editable development plans before complex tasks
Codebase integration: Scans and reuses existing components and theme variables
Auto-fixing: Automatically fixes TypeScript and linting errors
Sandbox preview: Run and test generated code in a local environment
Three modes: Plan Mode for code plan generation, Code Mode for code generation, and Ask Mode for codebase understanding.
Preview browser: Kombai browser lets you preview your app’s local deployment in the browser with built-in listeners so you can iterate fast by sending elements and errors back to Kombai as context.

You can learn more about Kombai AI agent here on Kombai docs.

Prerequisites

To fully understand this tutorial, you need to have a basic understanding of React

A Kombai AI account (they have a free tier).
A Figma account with a design file you want to convert.
Visual Studio Code (or a supported IDE like Cursor).
The Kombai AI VS Code extension.
A new or existing React project (e.g., created with create-react-app or Vite).

Step 1: Set Up Your Project and the Kombai Agent

In this section, you will learn how to set up your React project and Kombai AI agent in your IDE (VS Code, Cursor, WindSurf, etc).

Let’s get started.

First, open your React project in your IDE or set up one using the command below.

npx create-react-app figma-kombai-demo

Then Install the Kombai AI extension from the marketplace, as shown below.

Once the Kombai extension is installed, click Sign In button in Kombai. Then you will be redirected to the Kombai website to Sign up or log in to your Kombai account.

After signing in, you will be redirected back to the IDE.

Step 2: Connecting Figma and adding your Figma design to Kombai

In this section, you will learn how to connect your Figma account to Kombai and add your Figma design to convert it into React code.

Let’s get started.

First, connect your Figma account with Kombai in order to access your Figma design and generate code based on them, as shown below.

Once you have connected your Figma account, copy your Figma design link, and add it to Kombai, as shown below.

Step 3: Define Code Generation Rules

After adding your Figma design URL, set persistent instructions for Kombai using rules and Agents.md files. The rules provide project level instructions to Kombai in order to enforce specific coding standards, architectural patterns, and output formats

To set the rules or instructions, create a AGENTS.md file in your project and add the project rules or instructions.

You can generate the project instructions by first taking screen shots of your Figma design, as shown below.

Then navigate to Google Gemini, add the screenshot to the chat and generate the instructions using the prompt below.

Give me a prompt for generating a React + Material UI web app 
from the provided Figma designs. Describe structure of each page section in 
detail

Once the instructions have been generated, add them to your AGENTS.md file, as shown below.

After that, Kombai automatically picks up the AGENTS.md file stored, as shown below.

Step 4: Scan and Configure your tech stack

Once you have managed project rules, configure your tech stack. Kombai offers a wide range of tech stack. This lets you generate code that aligns with your workspace’s requirements.

In this case, our Tech stack will be React, TypeScript and Material UI. To configure your tech stack, follow the steps as shown below and then save the configuration.

Step 5: Generate, and Review Code Plan

After configuring your tech stack, use Kombai plan mode to generate a detailed code plan for the given input before starting the code generation, as shown below.

You can learn more about Kombai plan mode here on Kombai docs.

Step 6: Generating code

Once the plan is approved or updated, Kombai starts the code generation process in the workset. Working set refers to the set of files generated by Kombai during the code generation process, as shown below.

Step 7: Running & previewing your app using Kombai browser

After generating the code, Kombai will run the development server and fix any errors.

Also, Kombai browser lets you preview your app’s local deployment in the browser, with built-in listeners so you can iterate fast by sending elements and errors back to Kombai as context.

To open the preview, click the Start Preview button below the Kombai input box. Kombai will start the dev server.

Once the server is runnning, click the Kombai Browser button to open the browser preview, as shown below.

Step 8: Analyzing Kombai output results

Once you have run and previewed your app, analyze the generated code and the UI to make sure it is close to what you wanted.

With other tools, you'll see an endless nesting of divs, often with no semantic meaning, because the tool is just tracing layer groups.

However, with Kombai, you'll get clean, semantic JSX that a human would write. Kombai understands layout and structure, not just layers, as shown below in the App.tsx file.

import { useState } from 'react';
import type { FC } from 'react';
import { Box, Toolbar, Typography } from '@mui/material';
import Sidebar from './components/Sidebar';
import TopBar from './components/TopBar';
import StatCard from './components/StatCard';
import RevenueChart from './components/RevenueChart';
import YearlyBackupChart from './components/YearlyBackupChart';
import FinancialSummaryChart from './components/FinancialSummaryChart';
import ProjectsOverviewCard from './components/ProjectsOverviewCard';
import WeeklyEarningChart from './components/WeeklyEarningChart';
import EmployeeTaskTable from './components/EmployeeTaskTable';
import BestSellingProducts from './components/BestSellingProducts';
import { mockQuery } from './data/dashboardMockData';

const App: FC = () => {
  const [mobileOpen, setMobileOpen] = useState(false);

  const handleDrawerToggle = () => {
    setMobileOpen(!mobileOpen);
  };

  return (
    <Box sx={{ display: 'flex', minHeight: '100vh' }}>
      <Sidebar mobileOpen={mobileOpen} onDrawerToggle={handleDrawerToggle} />

      <Box sx={{ flexGrow: 1, display: 'flex', flexDirection: 'column' }}>
        <TopBar onMenuClick={handleDrawerToggle} />

        <Box
          component="main"
          sx={{
            flexGrow: 1,
            p: { xs: 2, sm: 3 },
            bgcolor: 'background.default',
            overflowY: 'auto'
          }}
        >
          <Toolbar />

          {/* Statistics Cards */}
          <Box
            sx={{
              display: 'grid',
              gridTemplateColumns: {
                xs: '1fr',
                sm: 'repeat(2, 1fr)',
                md: 'repeat(3, 1fr)',
                lg: 'repeat(6, 1fr)'
              },
              gap: 3,
              mb: 3
            }}
          >
            {mockQuery.statistics.map((stat) => (
              <StatCard key={stat.id} {...stat} />
            ))}
          </Box>

          {/* Charts Row 1 */}
          <Box
            sx={{
              display: 'grid',
              gridTemplateColumns: { xs: '1fr', lg: '2fr 1fr' },
              gap: 3,
              mb: 3
            }}
          >
            <RevenueChart
              data={mockQuery.revenueData}
              stats={mockQuery.revenueStats}
            />
            <YearlyBackupChart {...mockQuery.yearlyBackup} />
          </Box>

          {/* Charts Row 2 */}
          <Box
            sx={{
              display: 'grid',
              gridTemplateColumns: { xs: '1fr', md: 'repeat(3, 1fr)' },
              gap: 3,
              mb: 3
            }}
          >
            <FinancialSummaryChart {...mockQuery.financialSummary} />
            <ProjectsOverviewCard {...mockQuery.projectsOverview} />
            <WeeklyEarningChart {...mockQuery.weeklyEarning} />
          </Box>

          {/* Tables Row */}
          <Box
            sx={{
              display: 'grid',
              gridTemplateColumns: { xs: '1fr', lg: '2fr 1fr' },
              gap: 3,
              mb: 3
            }}
          >
            <EmployeeTaskTable tasks={mockQuery.employeeTasks} />
            <BestSellingProducts products={mockQuery.bestSellingProducts} />
          </Box>

          {/* Footer */}
          <Box sx={{ textAlign: 'center', py: 2 }}>
            <Typography variant="body1" sx={{ color: 'text.secondary' }}>
              Design and Developed by{' '}
              <Typography
                component="a"
                href="https://getnextjs.com"
                target="_blank"
                rel="noopener noreferrer"
                sx={{ color: 'secondary.main', textDecoration: 'underline' }}
              >
                GetNextJs Templates
              </Typography>
            </Typography>
          </Box>
        </Box>
      </Box>
    </Box>
  );
};

export default App;

From the output results, Kombai gets you 80-90% of the way where it builds the perfect UI scaffolding, which is the most laborious part. You, the developer, are still needed for the last 10-20% and that's the fun part.

So, is Kombai the Best Choice for converting Figma Design to React code in minutes?

After using general coding agents, MCPs and Kombai to convert Figma designs into React Code, Kombai significantly outperforms these other AI tools in building UX & UI from Figma, images, or text based prompts as shown below in benchmarks for real-world frontend tasks.

Here are the key reasons for its high-quality output:

Understands Design Intent: Unlike other AI tools that require perfect Figma designs (like strict auto-layouts and layer naming), Kombai's AI agent is trained to interpret the visual design. It understands logical groupings, spacing, and layout intentions, even from "messy" Figma files.
Codebase & Tech Stack Aware: You can configure Kombai for your specific tech stack. It can scan your existing codebase to reuse your own components and styles and even integrate with popular libraries like Tailwind CSS, MUI, **and **Shadcn UI.
**Generates Readable & Maintainable Code: **Kombai analyzes the entire design, identifies repeating UI elements, and automatically generates them as reusable React components. This promotes a modular, DRY (Don't Repeat Yourself) codebase from the start.
Agentic & Iterative Workflow: Kombai is built for frontend teams and the "Plan, Code, Preview" loop is a game-changer. You review a plan, preview the component in a sandbox, and ask for changes before any code is written to your files. This gives you full control and trust in the process.
Focuses on the 80%: Kombai intelligently handles the 80% of UI work that is tedious (layout, styling, component boilerplate) so you can focus on the 20% that matters (logic, data fetching, and state management).

If your goal is to ship React UIs that look exactly like the Figma file, respect your repo conventions, and compile error-free on the first try, Kombai is currently the only AI agent purposely built to do exactly that—nothing more, nothing less.

Conclusion

In conclusion, Kombai AI agent changes the developer's role where it eliminates the most time-consuming, least creative part of frontend development.

Note that this isn't about replacing developers but upgrading their frontend developement workflow.

Stop hand-coding your UI boilerplate. Grab a free Kombai account, install the VS Code extension, and try converting one of your own Figma frames.

You won't just be surprised by how much time you get back, you will change how you approach frontend development.

Build a Frontend for your Microsoft Agent Framework (.NET) Agents with AG-UI

Bonnie — Thu, 13 Nov 2025 15:13:17 +0000

In this guide, you will learn how to build a frontend for your Microsoft Agent Framework Agents using AG-UI Protocol and CopilotKit. Microsoft Agent Framework will power the AI agents backend while CopilotKit powers the frontend and then AG-UI creates a bridge that enables the frontend to communicate with the backend.

Before we jump in, here is what we will cover:

What is the Microsoft Agent Framework?
Setting up a Microsoft Agent Framework + AG-UI + CopilotKit agent using CLI
Integrating your Microsoft Agent Framework agent with AG-UI protocol in the backend
Building a frontend for your Microsoft Agent Framework + AG-UI agent using CopilotKit

Here is a preview of what you can build using Microsoft Agent Framework + AG-UI + CopilotKit.

Check out AG-UI's GitHub ⭐️

What is the Microsoft Agent Framework?

The Microsoft Agent Framework is an open-source software development kit (SDK) and runtime designed for building, orchestrating, and deploying AI agents and multi-agent workflows.

It supports both Python and .NET languages, allowing developers to create everything from simple chat-based agents to complex systems where multiple agents collaborate on tasks

Microsoft Agent Framework key features include:

Agents: Modular AI entities powered by large language models (LLMs) like Azure OpenAI, OpenAI, or others. Agents can reason, use tools, and maintain conversation history via built-in threading.
**Workflows: **Graph-based orchestration for explicit control over multi-agent execution (e.g., sequential, parallel, nested, or human-in-the-loop). Supports checkpointing, type-based routing, and debugging.
**Tools and Integrations: **OpenAPI-first design for calling APIs; Model Context Protocol (MCP) for dynamic tools; Agent2Agent (A2A) protocol for cross-runtime collaboration.

If you want to dive deeper into how Microsoft Agent Framework works and its setup, check out the docs here: Microsoft Agent Framework docs.

Prerequisites

Before you begin, you'll need the following:

.NET 9.0 SDK
Node.js 20+
GitHub Personal Access Token (for GitHub Models API)
Optional: Azure OpenAI endpoint and deployment (if using Azure OpenAI instead of GitHub Models)

Setting up a Microsoft Agent Framework + AG-UI + CopilotKit agent using CLI

In this section, you will learn how to set up a full-stack Microsoft Agent Framework agent using a CLI command that setups the backend using AG-UI protocol and the frontend using CopilotKit.

Let’s get started.

Step 1: Run CLI command

If you don’t already have a Microsoft Agent Framework agent, you can set up one quickly by running the CLI command below in your terminal.

npx copilotkit@latest init -m microsoft-agent-framework

Then give your project a name as shown below.

Step 2: Install dependencies

Once your project has been created successfully, install dependencies using your preferred package manager:

# Using pnpm (recommended)
pnpm install

# Using npm
npm install

# Using yarn
yarn install

# Using bun
bun install

Step 3: Set up your GitHub token for GitHub Models

After installing the dependencies, first, get your GitHub token:

gh auth token

Then, navigate to the agent directory and set it as a user secret:

cd agent
dotnet user-secrets set GitHubToken "<your-token>"
cd ..

Step 4: Run development server

Then start the development server using your preferred package manager:

# Using pnpm
pnpm dev

# Using npm
npm run dev

# Using yarn
yarn dev

# Using bun
bun run dev

Once the development server is running, navigate to http://localhost:3000/ and you should see your Microsoft Agent Framework + AG-UI + CopilotKit agent up and running.

Congrats! You've successfully integrated a ADK Agent chatbot to your application. To start, try the provided tools to set the web page theme, write proverbs or get the weather, as shown below.

Integrating your Microsoft Agent Framework agent with AG-UI protocol in the backend

In this section, you will learn how to integrate your Microsoft Agent Framework agent with AG-UI protocol, in order to expose it to the frontend.

Let’s jump in.

Step 1: Install Microsoft Agent Framework + AG-UI packages

To get started, install the Microsoft Agent Framework + AG-UI packages together with other necessary dependencies using the commands below.

dotnet new web -n AGUIServer
cd AGUIServer
dotnet add package Microsoft.Agents.AI.Hosting.AGUI.AspNetCore
dotnet add package Microsoft.Extensions.AI.OpenAI
dotnet add package OpenAI

Step 2: Import required packages

Once you have installed the required packages, import them as shown below in a Program.cs file.

using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Hosting.AGUI.AspNetCore;
using Microsoft.AspNetCore.Http.Json;
using Microsoft.Extensions.AI;
using Microsoft.Extensions.Options;
using OpenAI;
using System.ComponentModel;
using System.Text.Json.Serialization;

Step 3: Create and Configure Web Application Builder

After importing the required packages, create a new WebApplicationBuilder instance with command-line arguments, configure JSON Serialization Options and register AG-UI Services, as shown below.

// ...

// Create a new WebApplicationBuilder instance with command-line arguments
WebApplicationBuilder builder = WebApplication.CreateBuilder(args);

// Configure JSON Serialization Options
builder.Services.ConfigureHttpJsonOptions(options => options.SerializerOptions.TypeInfoResolverChain.Add(ProverbsAgentSerializerContext.Default));

// Register AG-UI Services
builder.Services.AddAGUI();

// Build the WebApplication instance from the builder
// This compiles all registered services and configurations
WebApplication app = builder.Build();

// ...

Step 4: Set Up Agent Factory and Map Endpoints

Once you have configured the web application builder, set up the agent factory and map endpoints, as shown below.

// ...

// Get Required Services from Dependency Injection Container
// Retrieve the logger factory for creating loggers
var loggerFactory = app.Services.GetRequiredService<ILoggerFactory>();
// Retrieve JSON options for serialization configuration
var jsonOptions = app.Services.GetRequiredService<IOptions<JsonOptions>>();

// Create Agent Factory Instance
// Instantiate the ProverbsAgentFactory with:
// - Application configuration (for accessing appsettings, environment variables, etc.)
// - Logger factory (for creating loggers within the factory)
// - JSON serializer options (for serializing agent data)
var agentFactory = new ProverbsAgentFactory(builder.Configuration, loggerFactory, jsonOptions.Value.SerializerOptions);

// Map AG-UI Endpoint
// Map the root path ("/") to the AG-UI agent endpoint
// The CreateProverbsAgent() method returns a configured AI agent instance
// This allows the agent to handle requests at the root URL
app.MapAGUI("/", agentFactory.CreateProverbsAgent());

// Start the web application and begin listening for HTTP requests
// This is an async operation that will run until the application is stopped
await app.RunAsync();

// ...

Step 5: Define your agent state

After setting up the agent factory and mapping endpoints, define your agent state class that maintains the application's state. The agent state class is registered as a singleton in the dependency injection container, meaning there's one instance shared across the entire application lifetime.

// ...

public class ProverbsState
{
    // Initialize the Proverbs list as an empty list to avoid null reference issues
    public List<string> Proverbs { get; set; } = new List<string>();
}

// ...

Step 6: Configure your Agent factory

Once you have defined your agent state, configure your agent factory class responsible for creating and configuring AI agents.

// ...

public class ProverbsAgentFactory
{
    // Store configuration for accessing settings (like API tokens)
    private readonly IConfiguration _configuration;
    // Reference to the shared state instance
    private readonly ProverbsState _state;
    // OpenAI client instance for making API calls
    private readonly OpenAIClient _openAiClient;
    // Logger instance for logging agent activities
    private readonly ILogger _logger;
    // JSON serializer options for serializing/deserializing agent data
    private readonly System.Text.Json.JsonSerializerOptions _jsonSerializerOptions;

    // ...
 }

 // ...

Step 7: Initialize the Agent factory

Inside the agent factory class, define a constructor that initializes the agent factory by using a GitHub token to authenticate with the Azure OpenAI endpoint and configure the OpenAI client.

// ...

public class ProverbsAgentFactory
{
    // Store configuration for accessing settings (like API tokens)
    private readonly IConfiguration _configuration;
    // Reference to the shared state instance
    private readonly ProverbsState _state;
    // OpenAI client instance for making API calls
    private readonly OpenAIClient _openAiClient;
    // Logger instance for logging agent activities
    private readonly ILogger _logger;
    // JSON serializer options for serializing/deserializing agent data
    private readonly System.Text.Json.JsonSerializerOptions _jsonSerializerOptions;

    // Step 3.1: Constructor - Initialize the factory with dependencies
    // This constructor is called by the dependency injection container
    public ProverbsAgentFactory(IConfiguration configuration, ProverbsState state)
    {
        // Store injected dependencies
        _configuration = configuration;
        _state = new();

        // Step 3.2: Retrieve the GitHub token from configuration
        // The token is used to authenticate with the Azure OpenAI endpoint
        // If the token is not found, throw an exception with helpful instructions
        var githubToken = _configuration["GitHubToken"]
            ?? throw new InvalidOperationException(
                "GitHubToken not found in configuration. " +
                "Please set it using: dotnet user-secrets set GitHubToken \"<your-token>\" " +
                "or get it using: gh auth token");

        // Step 3.3: Create and configure the OpenAI client
        // - Use the GitHub token as the API key credential
        // - Set the endpoint to Azure's inference API endpoint
        _openAiClient = new OpenAIClient(
            new System.ClientModel.ApiKeyCredential(githubToken),
            new OpenAIClientOptions
            {
                Endpoint = new Uri("https://models.inference.ai.azure.com")
            });
    }

    // ...

 }

Step 8: Create and configure your AI agent

Once you have initialized the agent factory, define a method inside the agent factory class that sets up the chat client, defines the agent's behavior, and registers the available tools

// ...

public class ProverbsAgentFactory
{
    // Store configuration for accessing settings (like API tokens)
    private readonly IConfiguration _configuration;
    // Reference to the shared state instance
    private readonly ProverbsState _state;
    // OpenAI client instance for making API calls
    private readonly OpenAIClient _openAiClient;
    // Logger instance for logging agent activities
    private readonly ILogger _logger;
    // JSON serializer options for serializing/deserializing agent data
    private readonly System.Text.Json.JsonSerializerOptions _jsonSerializerOptions;

    // ...

    // Create Proverbs Agent
    // This method creates and configures the AI agent with its tools and capabilities
    public AIAgent CreateProverbsAgent()
    {
        // Get Chat Client
        // Retrieve a chat client for the "gpt-4o-mini" model
        // Convert it to the IChatClient interface required by the agent framework
        var chatClient = _openAiClient.GetChatClient("gpt-4o-mini").AsIChatClient();

        // Create Chat Client Agent
        // Create a ChatClientAgent that wraps the chat client with agent capabilities
        // - name: Identifier for the agent
        // - description: System prompt that describes the agent's role and behavior
        //   This instructs the agent to always check the current proverbs list before discussing them
        // - tools: Array of functions the agent can call to perform actions
        var chatClientAgent = new ChatClientAgent(
            chatClient,
            name: "ProverbsAgent",
            description: @"A helpful assistant that helps manage and discuss proverbs.
            You have tools available to add, set, or retrieve proverbs from the list.
            When discussing proverbs, ALWAYS use the get_proverbs tool to see the current list before mentioning, updating, or discussing proverbs with the user.",
            tools: [
                // Tool 1: Get the current list of proverbs
                AIFunctionFactory.Create(GetProverbs, options: new() { Name = "get_proverbs", SerializerOptions = _jsonSerializerOptions }),
                // Tool 2: Add new proverbs to the existing list
                AIFunctionFactory.Create(AddProverbs, options: new() { Name = "add_proverbs", SerializerOptions = _jsonSerializerOptions }),
                // Tool 3: Replace the entire list of proverbs
                AIFunctionFactory.Create(SetProverbs, options: new() { Name = "set_proverbs", SerializerOptions = _jsonSerializerOptions }),
                // Tool 4: Get weather information for a location
                AIFunctionFactory.Create(GetWeather, options: new() { Name = "get_weather", SerializerOptions = _jsonSerializerOptions })
            ]);

        // Wrap with Shared State Agent
        // Wrap the chat client agent with SharedStateAgent to enable state persistence
        // This allows the agent to maintain state across multiple interactions
        // The JSON serializer options are used for state serialization
        return new SharedStateAgent(chatClientAgent, _jsonSerializerOptions);
    }    
    // ...

 }

Step 9: Define agent tools

After configuring your agent, define agent tool methods inside the agent factory class that your AI agent can call as tools.

// ...

public class ProverbsAgentFactory
{
    // Store configuration for accessing settings (like API tokens)
    private readonly IConfiguration _configuration;
    // Reference to the shared state instance
    private readonly ProverbsState _state;
    // OpenAI client instance for making API calls
    private readonly OpenAIClient _openAiClient;


    // ...

    // Tool 1: Get Proverbs
    // Retrieves the current list of proverbs from the shared state
    [Description("Get the current list of proverbs.")]
    private List<string> GetProverbs()
    {
        // Log the operation for debugging and monitoring
        _logger.LogInformation("📖 Getting proverbs: {Proverbs}", string.Join(", ", _state.Proverbs));
        // Return the current list of proverbs from the shared state
        return _state.Proverbs;
    }

    // Tool 2: Add Proverbs
    // Adds new proverbs to the existing list without removing existing ones
    [Description("Add new proverbs to the list.")]
    private void AddProverbs([Description("The proverbs to add")] List<string> proverbs)
    {
        // Log the operation with the proverbs being added
        _logger.LogInformation("➕ Adding proverbs: {Proverbs}", string.Join(", ", proverbs));
        // Add the new proverbs to the end of the existing list
        // AddRange appends all items from the input list to the state's Proverbs list
        _state.Proverbs.AddRange(proverbs);
    }

    // Tool 3: Set Proverbs
    // Replaces the entire list of proverbs with a new list
    [Description("Replace the entire list of proverbs.")]
    private void SetProverbs([Description("The new list of proverbs")] List<string> proverbs)
    {
        // Log the operation with the new list of proverbs
        _logger.LogInformation("📝 Setting proverbs: {Proverbs}", string.Join(", ", proverbs));
        // Replace the entire list using collection expression syntax
        // The [.. proverbs] syntax creates a new list with a copy of all items from proverbs
        _state.Proverbs = [.. proverbs];
    }

    // Tool 4: Get Weather
    // Retrieves weather information for a specified location
    // Note: This is a mock implementation that returns hardcoded values
    // In a real application, this would call a weather API
    [Description("Get the weather for a given location. Ensure location is fully spelled out.")]
    private WeatherInfo GetWeather([Description("The location to get the weather for")] string location)
    {
        // Log the operation with the requested location
        _logger.LogInformation("🌤️  Getting weather for: {Location}", location);
        // Return a mock WeatherInfo object with sample data
        // In production, this would make an API call to a weather service
        return new()
        {
            Temperature = 20,
            Conditions = "sunny",
            Humidity = 50,
            WindSpeed = 10,
            FeelsLike = 25
        };
    }

 }

// ...

Step 10: Define data model classes

Once your agent factory class is configured, configure the data model classes that define the structure of the data returned by the tools.

// ...

// Step 5.1: Model for returning proverbs state snapshots
// Used by tools that modify proverbs to return the updated state
public class ProverbsStateSnapshot
{
    // Map the C# property name "Proverbs" to JSON property name "proverbs"
    // This follows JSON naming conventions (camelCase)
    [JsonPropertyName("proverbs")]
    public List<string> Proverbs { get; set; } = new();
}

// Step 5.2: Model for weather information
// Used by the GetWeather tool to return structured weather data
public class WeatherInfo
{
    // Temperature in degrees (example uses Celsius)
    [JsonPropertyName("temperature")]
    public int Temperature { get; init; }

    // Weather conditions description (e.g., "sunny", "cloudy", "rainy")
    [JsonPropertyName("conditions")]
    public string Conditions { get; init; } = string.Empty;

    // Humidity percentage (0-100)
    [JsonPropertyName("humidity")]
    public int Humidity { get; init; }

    // Wind speed (units depend on implementation)
    [JsonPropertyName("wind_speed")]
    public int WindSpeed { get; init; }

    // "Feels like" temperature (accounts for wind, humidity, etc.)
    [JsonPropertyName("feelsLike")]
    public int FeelsLike { get; init; }
}

// Step 5.3: Partial class declaration
// This allows the Program class to be extended with the top-level statements below
// (C# 9+ top-level statements are compiled into a Program class)
public partial class Program { }

// ...

Step 11: Configure Serializer context

After defining data model classes, configure the serializer context, as shown below.

// ...

// Register ProverbsStateSnapshot for JSON serialization
[JsonSerializable(typeof(ProverbsStateSnapshot))]
// Register WeatherInfo for JSON serialization
[JsonSerializable(typeof(WeatherInfo))]
// Sealed partial class that provides type information for JSON serialization
// The JsonSerializerContext base class enables source generation
internal sealed partial class ProverbsAgentSerializerContext : JsonSerializerContext;

Then use the command below to run your agent.

dotnet run

Congrats! You've successfully integrated your Microsoft Agent Framework Agent with AG-UI protocol, and it is available at http://localhost:8000 (or specified port) endpoint.

Let’s now see how to add a frontend to your AG-UI wrapped Microsoft Agent Framework agent.

Building a frontend for your Microsoft Agent Framework + AG-UI agent using CopilotKit

In this section, you will learn how to add a frontend to your Microsoft Agent Framework + AG-UI agent using CopilotKit, which runs anywhere that React runs.

Let’s get started.

Step 1: Install CopilotKit packages

To get started, install the latest packages for CopilotKit into your frontend.

npm install @copilotkit/react-ui @copilotkit/react-core @copilotkit/runtime

Step 2: Setup the Copilot Runtime instance

import {
  CopilotRuntime, // Main runtime that manages agent communication
  ExperimentalEmptyAdapter, // Service adapter for single-agent setups
  copilotRuntimeNextJSAppRouterEndpoint, // Next.js App Router endpoint handler
} from "@copilotkit/runtime";

// Import AG-UI client for connecting to Microsoft Agent Framework agents
import { HttpAgent } from "@ag-ui/client";

// Import Next.js types for request handling
import { NextRequest } from "next/server";

// Create a service adapter for the CopilotKit runtime
const serviceAdapter = new ExperimentalEmptyAdapter();

// Create the main CopilotRuntime instance that manages communication between the frontend and backend agents
const runtime = new CopilotRuntime({

  // Define the agents that will be available to the frontend
    agents: {

    // Configure the ADK agent connection
    my_agent: new HttpAgent({

      // Specify the URL where the Microsoft Agent Framework agent is running
      url: "http://localhost:8000/",
    }),
  },
});

// Export the POST handler for the API route
export const POST = async (req: NextRequest) => {

  // Create the request handler using CopilotKit's Next.js helper
  const { handleRequest } = copilotRuntimeNextJSAppRouterEndpoint({
    runtime, // The CopilotRuntime instance we configured
    serviceAdapter, // The service adapter for agent coordination
    endpoint: "/api/copilotkit", // The endpoint path (matches this file's location)
  });


  return handleRequest(req);
};

Step 3: Set up CopilotKit provider

After setting up a Copilot Runtime instance, set up the CopilotKit provider component that manages your ADK agent sessions.

To set up the CopilotKit Provider, the [<CopilotKit>](https://docs.copilotkit.ai/reference/components/CopilotKit) component must wrap the Copilot-aware parts of your application.

For most use cases, it's appropriate to wrap the CopilotKit provider around the entire app, e.g., in your layout.tsx file.

// Step 1: Import necessary types and components from Next.js and CopilotKit
import type { Metadata } from "next";

import { CopilotKit } from "@copilotkit/react-core";
import "./globals.css";
import "@copilotkit/react-ui/styles.css";

// Step 2: Define metadata for the application, used by Next.js for SEO and page headers
export const metadata: Metadata = {
  title: "Create Next App",
  description: "Generated by create next app",
};

// Step 3: Define the RootLayout component, which wraps the entire application
export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  // Step 4: Return the JSX structure for the layout
  return (
    <html lang="en">
      <body className={"antialiased"}>
        {/* Step 5: Wrap the children components with CopilotKit provider to enable CopilotKit functionality */}
        <CopilotKit runtimeUrl="/api/copilotkit" agent="my_agent">
          {children}
        </CopilotKit>
      </body>
    </html>
  );
}

Step 4: Set up a Copilot UI component

Once you have set up the CopilotKit Provider, set up a Copilot UI component that enables you to interact with your ADK agent. CopilotKit ships with several built-in chat components, which include CopilotPopup, CopilotSidebar, and CopilotChat.

To set up a Copilot UI component, define it alongside your core page components, e.g., in your page.tsx file.

"use client";

import { CopilotKitCSSProperties, CopilotSidebar } from "@copilotkit/react-ui";
import { useState } from "react";

export default function CopilotKitPage() {
  const [themeColor, setThemeColor] = useState("#6366f1");

  // ...

  return (
    <main style={{ "--copilot-kit-primary-color": themeColor } as CopilotKitCSSProperties}>
      <CopilotSidebar
        disableSystemMessage={true}
        clickOutsideToClose={false}
        labels={{
          title: "Popup Assistant",
          initial: "👋 Hi, there! You're chatting with an agent.",
        }}
        suggestions={[
          {
            title: "Generative UI",
            message: "Get the weather in San Francisco.",
          },
          {
            title: "Frontend Tools",
            message: "Set the theme to green.",
          },
          {
            title: "Human In the Loop",
            message: "Please go to the moon.",
          },
          {
            title: "Write Agent State",
            message: "Add a proverb about AI.",
          },
          {
            title: "Update Agent State",
            message: "Please remove 1 random proverb from the list if there are any.",
          },
          {
            title: "Read Agent State",
            message: "What are the proverbs?",
          },
        ]}
      >
        <YourMainContent themeColor={themeColor} />
      </CopilotSidebar>
    </main>
   );
}

Step 5: Sync your Microsoft Agent Framework agent state with the frontend

After setting up a Copilot UI component, sync your Microsoft Agent Framework agent state with the frontend using CopilotKit hooks.

To sync your Microsoft Agent Framework agent state with the frontend, use the CopilotKit useCoAgent hook that allows you to share state bidirectionally between your application and the agent.

"use client";

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

// State of the agent, make sure this aligns with your agent's state.
type AgentState = {
  proverbs: string[];
}

function YourMainContent({ themeColor }: { themeColor: string }) {

  // 🪁 Shared State: https://docs.copilotkit.ai/coagents/shared-state
  const { state, setState } = useCoAgent<AgentState>({
    name: "my_agent",
    initialState: {
      proverbs: [
        "CopilotKit may be new, but it's the best thing since sliced bread.",
      ],
    },
  })

     // ...
  return (

  // ...
  )

To render your agent's state, progress, outputs, or tool calls with custom UI components in real-time, you can use tool-based Generative UI.

"use client";

import { useCoAgent, useCopilotAction } from "@copilotkit/react-core";

// ...

function YourMainContent({ themeColor }: { themeColor: string }) {
  // ...

  //🪁 Generative UI: https://docs.copilotkit.ai/coagents/generative-ui
  useCopilotAction({
    name: "get_weather",
    description: "Get the weather for a given location.",
    available: "disabled",
    parameters: [
      { name: "location", type: "string", required: true },
    ],
    render: ({ args }) => {
      return <WeatherCard location={args.location} themeColor={themeColor} />
    },
  });

  return ( ... )

Step 6: Implementing Human-in-the-Loop (HITL) in the frontend

You can learn more about Human in the Loop here on CopilotKit docs.

import { MoonCard } from "@/components/moon";
import { useCopilotAction } from "@copilotkit/react-core";

// ...

function YourMainContent({ themeColor }: { themeColor: string }) {

  // ...

  // 🪁 Human In the Loop: https://docs.copilotkit.ai/pydantic-ai/human-in-the-loop
  useCopilotAction(
    {
      name: "go_to_moon",
      description: "Go to the moon on request.",
      renderAndWaitForResponse: ({ respond, status }) => {
        return <MoonCard themeColor={themeColor} status={status} respond={respond} />;
      },
    },
    [themeColor],
  );

  return (

    // ...

  );
}

Step 7: Stream your Microsoft Agent Framework agent responses in the frontend

Once you have synced your Microsoft Agent Framework agent state with the frontend, stream your ADK agent responses or results in the frontend.

To stream your Microsoft Agent Framework agent responses or results in the frontend, pass the agent’s state field values to the frontend components, as shown below.

"use client";

import { useCoAgent } from "@copilotkit/react-core";
import { ProverbsCard } from "@/components/proverbs";

// State of the agent, make sure this aligns with your agent's state.
type AgentState = {
  proverbs: string[];
}

function YourMainContent({ themeColor }: { themeColor: string }) {
  // 🪁 Shared State: https://docs.copilotkit.ai/coagents/shared-state
  const { state, setState } = useCoAgent<AgentState>({
    name: "my_agent",
    initialState: {
      proverbs: [
        "CopilotKit may be new, but it's the best thing since sliced bread.",
      ],
    },
  })

  // ...

  return (
    <div
      style={{ backgroundColor: themeColor }}
      className="h-screen flex justify-center items-center flex-col transition-colors duration-300"
    >
      <ProverbsCard state={state} setState={setState} />
    </div>
    );
}

If you query your Microsoft Agent Framework agent, you should see the agent’s response or results streaming in the UI, as shown below.

Conclusion

In this guide, we have walked through the steps of building a frontend for your Microsoft Agent Framework agent using AG-UI protocol and CopilotKit.

While we’ve explored a couple of features, we have barely scratched the surface of the countless use cases for CopilotKit, ranging from building interactive AI chatbots to building agentic solutions—in essence, CopilotKit lets you add a ton of useful AI capabilities to your products in minutes.

Hopefully, this guide makes it easier for you to integrate AI-powered Copilots into your existing application.

Follow CopilotKit on Twitter and say hi, and if you'd like to build something cool, join the Discord community.

Comparison of the Best Figma To Code AI Tools

Bonnie — Tue, 04 Nov 2025 15:12:27 +0000

TL;DR

For many professional frontend teams, Figma files are the primary source of design instructions.

Developers currently use image exports or Figma MCPs with existing agents, which often struggle with complex, real-world designs. These MCPs can also be context-inefficient, leading to model hallucinations.

In this guide, we will compare the best two AI tools for converting Figma design to code in minutes. These two AI tools are:

Kombai: a specialized AI agent which is purpose-built to "think" like a frontend developer, and convert Figma designs into high-quality UI code across a configurable, robust tech stack.
Framelink MCP: a protocol-based server that acts as a "universal translator," and gives design context from Figma directly into your general-purpose AI coding assistant (e.g., Cursor, Claude, or VS Code).

Before we get started, here is what we will cover:

What is Kombai?
What is Framelink MCP?
Head-to-Head comparison of Kombai vs Framelink MCP
Testing workflows and code outputs of Kombai vs Framelink MCP
The final verdict on which tool is right for you

Here is a preview of the final results between Kombai and Framelink MCP.

What is Kombai?

Key features:

Multi-input support: Works with Figma designs, text instructions, images, or existing code
Tech stack aware: Supports 30+ frontend libraries including React, Next.js, Material UI, Tailwind, and more
Smart planning: Generates editable development plans before complex tasks
Codebase integration: Scans and reuses existing components and theme variables
Auto-fixing: Automatically fixes TypeScript and linting errors
Sandbox preview: Run and test generated code in a local environment
Two modes: Code mode for generation, Ask mode for codebase understanding

You can learn more about Kombai AI agent here on Kombai docs.

What is Framelink MCP?

Framelink MCP (Model Context Protocol) is a server that bridges Figma design files with AI-powered coding tools, such as Claude Code, Cursor or GitHub Copilot on VS Code.

Key Features:

Context-Rich Generation: Moves beyond "screenshot-to-code" guesswork.
IDE Integration: Designed to live inside your AI-powered editor (Cursor, VS Code, Windsurf, etc.).
Developer-in-Control: The developer still drives the process via prompts, using the MCP as their "Figma expert."

You can learn more about Framelink MCP here.

Now that you have learned what Kombai agent and Framelink MCP are, let us see how they compare in a head-to-head comparison.

Head-to-Head comparison of Kombai vs Framelink MCP

The difference between Kombai and Framelink MCP boils down to specialization versus flexibility and workflow integration.

Kombai significantly outperforms generic coding agents + Frontier models + MCPs in building UX from Figma, image, or text based prompts as shown below in benchmarks for real-world frontend tasks.

Here is the head-to-head comparison of the Kombai agent and the Framelink MCP.

Feature	Kombai Agent	Framelink MCP
Functionality	Generates code directly.	Provides context to another AI tool (which then generates code).
Code Output	Highly Configurable (React, Next.js, support for multiple UI libraries (MUI, Shadcn, etc.), and advanced styling options).	Depends entirely on your AI assistant (React, Vue, Svelte, Angular, etc.)—if the LLM knows it, the MCP can enable it.
Figma Reliance	Highly flexible; performs well with "messy" designs.	Benefits greatly from well-structured files (Dev Mode, variables, components).
Workflow	Generate in a sandbox, then copy/paste into the project.	Prompt in editor, AI writes code directly into the file.
Code Quality	Production-ready code with high compilation success but may need tweaks.	Depends on the quality of the connected LLM in your IDE and prompt quality.
Context Awareness	Can scan the local codebase to adhere to local styling conventions and theme files.	Can be instructed via prompt to use existing components and architecture.
Flexibility	Limited to Kombai's comprehensive but defined supported tech stack.	Can be used for virtually any framework or language the connected LLM supports.

Testing workflows and code outputs of Kombai vs Framelink MCP

In this section, we will convert a Figma design into frontend code in two scenarios. In the first scenario, we will use Kombai extension on a code editor of your choice to convert a Figma design into frontend code.

Then in scenario two, we will use Framelink MCP on a code editor of your choice to provide a Figma design as context to an AI coding tool to generate frontend code using a stack of your choice.

After that, we will compare the results from both scenarios and determine which tool is better at converting Figma designs into pixel perfect frontend UI.

Here is the Figma design we will be using in both scenarios. You can get it here on the Figma community.

Let us get started.

Scenario 1: The Kombai Figma Design-to-Code Workflow

To get started with Kombai agent, follow the set up guide in the Kombai docs, as shown below.

Once you have set up Kombai, follow the steps below to convert a Figma design into frontend code.

Let us jump in.

Step 1: Connect Figma

To add a Figma design as context, you need to connect your Figma account with Kombai. This lets Kombai access your Figma design and generate code based on them.

Here is how to connect your Figma account to Kombai:

Step 2: Add Figma design URL

Once you have connected your Figma account, copy the Figma design link, as shown below.

Then in the Enter the link to your Figma frame modal, add the Figma URL and click Confirm, as shown below.

Step 3: Configure your tech stack

After adding your Figma design URL, configure your tech stack. Kombai offers a wide range of tech stack. This lets you generate code that aligns with your workspace’s requirements.

To configure your tech stack, follow the steps as shown below and then save the configuration.

Step 4: Plan for complex tasks

After configuring your tech stack, you can plan for complex tasks. Kombai always generates an editable plan for you to approve or update. This ensures that the task and generated code is always in your control.

Complexity of a task is determined by the number of sections, images, icons, global store entities, queries, etc. required in the code.

You can plan for complex tasks, as shown below.

Once the plan is generated, click the Approve Plan & Start Coding button to accept the plan and start the code generation process, as shown below.

Step 5: Generate Code

Step 6: Run and fix code errors

After generating the code, Kombai will run the development server and fix any errors, as shown below.

Once the development server is running, navigate to the localhost URL in the terminal to preview the frontend code UI in the browser, as shown below.

As you can see from the preview results, Kombai was able to generate frontend code that is pixel perfect with the Figma design. The code only requires minimal tweaks to match the desired UI design.

Scenario 2: The Framelink MCP Figma Design-to-Code Workflow

To get started with Framelink MCP, follow the set up guide in the Framelink docs, as shown below.

Once you have set up Framelink MCP, follow the steps below to convert a Figma design into frontend code.

Let us jump in.

Step 1: Copy a link to a Figma frame

The MCP server compresses the data it receives from the Figma API by almost 90%. Even still, complex designs can overwhelm AI agents with too much information.

To do that, right click on the frame or group you'd like to implement, then select Copy/Paste as and choose Copy link to selection, as shown below.

Step 2: Paste the link into your editor

Once you have a link to the Figma frame or group, you can make a request to your editor's AI agent.

A request as simple as "Implement this Figma frame" along with the link should be enough to get the agent to call the MCP's get_figma_data function, but more context is often helpful in getting the best results, as shown below.

Step 3: Generate Code

After submitting your request, your coding agent will get to work. It should call the MCP's get_figma_data function with the link you provided and start the code generation process, as shown below.

Step 4: Run and fix code errors

After generating the code, your coding agent will run the development server and fix any errors, as shown below.

Once the development server is running, navigate to the localhost URL in the terminal to preview the frontend code UI in the browser, as shown below.

As you can see from the preview results, the coding agent was not able to generate frontend code that is pixel perfect with the Figma design. The code requires a lot of tweaks to match the desired UI design.

Conclusion: Which Tool is Right for You?

In conclusion, both Kombai and Framelink MCP offer powerful solutions for converting Figma designs into code, but they cater to different needs and workflows.

Kombai is a specialized AI agent that excels at generating high-quality, production-ready UI code directly from Figma designs.

Its strengths lie in its configurable tech stack, its ability to handle complex and even "messy" designs, and its feature of generating an editable development plan before starting complex tasks.

The Kombai agent is the ideal choice for developers and teams who prioritize a streamlined workflow, desire highly configurable code output, and want a tool that can intelligently interpret and convert intricate designs with minimal manual intervention.

Framelink MCP, on the other hand, acts as a "universal translator" that provides rich design context from Figma directly into your existing AI-powered coding assistant, such as those in Cursor, Claude, or VS Code.

Its primary advantage is its flexibility; it can be used with virtually any framework or language that your connected LLM supports.

The Framelink MCP is best suited for developers who prefer to remain in their familiar coding environment, want to maintain a high degree of control over the code generation process through prompting, and require the adaptability to work with a wide variety of technologies.

Ultimately, the decision between Kombai and Framelink MCP comes down to a choice between a specialized, end-to-end solution and a flexible, integrated tool.

If your priority is to get high-quality, production-ready code with a specialized tool, Kombai is the better option. If you value flexibility and want to enhance your existing AI-powered workflow with rich design context, Framelink MCP is the more suitable choice.

Building a Full-Stack AI Shopping Assistant with CrewAI and Tavily

Bonnie — Thu, 23 Oct 2025 13:29:28 +0000

TL;DR

In this guide, you will learn how to build a full-stack AI shopping assistant using CrewAI Flows, paired with the Tavily Search API in the backend. We'll then walk through adding a frontend to the shopping agent using CopilotKit to interact with it.

The AI shopping assistant will be able to search products on commerce platforms such as Amazon, Target, or eBay- extract structured product data and provide tailored product recommendations.

Before we jump in, here is what we will cover:

What are CrewAI Flows?
Building the AI shopping assistant backend using CrewAI, Tavily, and CopilotKit
Building the AI shopping assistant frontend using CopilotKit.

Here is a preview of what we will be building:

What are CrewAI Flows?

Flows are a flexible building block in CrewAI that lets you control things at a detailed level while keeping it simple overall. You can use them to automate tasks ranging from a basic call to an AI model all the way to a team of smart AI agents that work on their own.

With Flows, it's straightforward to create and set up step-by-step processes that make the most of what CrewAI can do.

Here are some key features:

Easy Workflow Building: Quickly link up different teams of AI agents (called Crews) and individual tasks to make advanced AI systems.
Handling Shared Information: Flows make it really simple to keep track of and share data between various steps in your process.
Event-Based Design: It's built around reacting to events, which helps create workflows that adapt and respond quickly.
Customizable Paths: Add rules like "if this happens, then do that," repeat steps in loops, or split into different branches in your workflows.

You can learn more about CrewAI Flows here on CrewAI docs.

Now that we have learned what the CrewAI Flows are, let us see how to build the CrewAI shopping assistant from the backend to the frontend.

Let’s get started!

Prerequisites

To fully understand this tutorial, you need to have a basic understanding of React or Next.js.

We'll also make use of the following:

Python - a popular programming language for building AI agents with LangGraph; make sure it is installed on your computer.
OpenAI API - to enable us to perform various tasks using the GPT models; for this tutorial, ensure you have access to the GPT-4 model.
CopilotKit - an open-source copilot framework for building custom AI chatbots, in-app AI agents, and text areas.
CrewAI - a Python framework that enables developers to create autonomous AI agents with high-level simplicity and precise low-level control.
Tavily API - a search engine built specifically for AI agents (LLMs), delivering real-time, accurate, and factual results at speed.

Setting up the project

To get started, clone the CrewAI-Shopping-Assistant repo that consists of a Python-based backend (agent) and a Next.js frontend (frontend).

Next, navigate to the backend directory:

cd agent

Then install the dependencies using Poetry:

poetry install

After that, create a .env file with OpenAI API Key and Tavily API Key:

OPENAI_API_KEY=<<your-OpenAI-key-here>>
TAVILY_API_KEY=<<your-tavily-key-here>>

Then run the agent using the command below:

poetry run python main.py

After that, navigate to the frontend directory:

cd frontend

Next, create a .env file with OpenAI API Key API key:

OPENAI_API_KEY=<<your-OpenAI-key-here>>

Then install the dependencies:

pnpm install

After that, start the development server:

pnpm run dev

Navigate to http://localhost:3000, and you should see the AI shopping assistant UI up and running.

Let’s now see how to build the AI shopping assistant backend using CrewAI, Tavily, and CopilotKit.

Building the AI shopping assistant backend using CrewAI, Tavily, and CopilotKit

In this section, you will learn how to build the AI shopping assistant backed using CrewAI for agent flows, Tavily for reliable web search, and CopilotKit for state management + UI updates.

Let’s jump in.

Step 1: Define the agent state

First, define the AgentState class that extends CopilotKitState in order to track the product data, user preferences, logs for UI updates, and more, as shown in the agent/shopping_assistant.py file.

from copilotkit.crewai import CopilotKitState
from typing import List, Dict, Any

class AgentState(CopilotKitState):
    """
    Manages the complete state of the shopping workflow.
    """
    # List of products currently displayed on the canvas
    products: List = []

    # List of users' favorite/saved products
    favorites: List = []

    # Temporary buffer to store products before confirmation
    buffer_products: List = []

    # User's wishlist of products
    wishlist: List = []

    # Activity logs to show processing status to the user
    logs: List = []

    # Generated comparison report for products
    report: Any | None = None

    # Flag to control when to show results in UI
    show_results: bool = False

    # Canvas logging information with title and subtitle for UI updates
    canvas_logs: dict = { "title" : "", "subtitle" : "" }

Step 2: Create the Shopping Agent Workflow

Once you have defined the agent state, define the ShoppingAgentFlow class that extends the Flow[AgentState]. Use the start() method to handle the entire flow, where it initializes state, validates environment variables, processes user queries, and emits state updates via CopilotKit, as shown in the ./agent/shopping_assistant.py file.

class ShoppingAgentFlow(Flow[AgentState]):

    @start()
    async def start(self):
        """
        Main entry point for the shopping assistant workflow.
        This method handles the entire flow from user request to product results.
        """
        try:
            # Step 1: Initialize the workflow
            print("Starting Shopping Agent Flow")

            # Update canvas with initial status
            self.state.canvas_logs = {
                "title" : f"Parsing your request",
                "subtitle" : "Deciding to run product search or not"
            }
            await copilotkit_emit_state(self.state)
            await asyncio.sleep(0)

            # Step 2: Validate required environment variables
            if not os.getenv("TAVILY_API_KEY"):
                raise RuntimeError("Missing TAVILY_API_KEY")
            if not os.getenv("OPENAI_API_KEY"):
                raise RuntimeError("Missing OPENAI_API_KEY")

            # Step 3: Check if this is a report generation request (assistant message)
            if self.state.messages[-1]['role'] == 'assistant':
                # Generate and return product comparison report
                result =await generate_report(self.state.products)
                print(result, "result")
                self.state.report = json.loads(result)
                await copilotkit_emit_state(self.state)
                return

            # Step 4: Add initial processing log
            self.state.logs.append({
                "message" : "Analyzing user query",
                "status" : "processing"
            })
            await copilotkit_emit_state(self.state)

            # Step 5: Mark analysis as completed
            self.state.logs[-1]["status"] = "completed"
            await copilotkit_emit_state(self.state)

            // ...

Step 3: Multi-Retailer Product Search with Tavily API

After creating the shopping agent flow, initialize the Tavily client and prepare for multi-retailer search, as shown below.

class ShoppingAgentFlow(Flow[AgentState]):

    @start()
    async def start(self):
        """
        Main entry point for the shopping assistant workflow.
        This method handles the entire flow from user request to product results.
        """
        try:
            // ...

            # Step 13: Set up Tavily search client and result containers
            tv = TavilyClient(api_key=os.getenv("TAVILY_API_KEY"))
            results_all: List[Dict[str, Any]] = []
            total_mappings_list = []

            # Step 14: Update user with search progress
            self.state.logs.append({
                "message" : "Identifying the sites to search",
                "status" : "processing"
            })
            self.state.canvas_logs={
                "title" : "Identifying the sites to search",
                "subtitle" : "Tavily search in progress...."
            }
            await copilotkit_emit_state(self.state)
            await asyncio.sleep(1)
            self.state.logs[-1]["status"] = "completed"
            await copilotkit_emit_state(self.state)

            // ...

Then search each major retailer using Tavily's domain-specific search capabilities to get relevant product URLs from each major retailer, as shown below.

class ShoppingAgentFlow(Flow[AgentState]):

    @start()
    async def start(self):
        """
        Main entry point for the shopping assistant workflow.
        This method handles the entire flow from user request to product results.
        """
        try:
            // ...

            # Step 15: Search across major retailers for product URLs
                        urls = {}
                        for retailer in RETAILERS:  # RETAILERS = ["target.com", "amazon.com", "ebay.com"]
                            # Search each retailer's domain for products matching the query
                            search = tv.search(
                                query=query,  # User's search query, e.g., "wireless headphones"
                                include_domains=[retailer],  # Limit search to specific retailer
                                include_answer=False,  # Don't include general answers
                                include_images=False,  # Don't include image results
                                include_raw_content=False,  # We'll extract content separately
                                search_depth="advanced",  # Use advanced search for better results
                                max_results=max_search_results,  # Typically 6 results per retailer
                            )

                            # Extract URLs from search results
                            urls[retailer] = [r["url"] for r in search.get("results", []) if r.get("url")]
                            if not urls[retailer]:
                                continue            
            // ...

After gathering URLs, use Tavily's extraction capabilities to get detailed webpage content that includes images and metadata, as shown below.

class ShoppingAgentFlow(Flow[AgentState]):

    @start()
    async def start(self):
        """
        Main entry point for the shopping assistant workflow.
        This method handles the entire flow from user request to product results.
        """
        try:
            // ...

            # Step 17: Define a function for parallel URL content extraction
                        def extract_urls(urls: List[str], retailer: str) -> Dict[str, Any]:
                            """Extract content from URLs for a specific retailer"""
                            try:
                                print(f"Extracting urls for {retailer}. Started at {datetime.now()}")
                                ext1 = tv.extract(urls, extract_depth="advanced", include_images=True, timeout=120)
                                return [ext1, retailer]
                            except Exception as e:
                                print(f"Error extracting urls: {e}")
                                return None

                        # Step 18: Execute parallel extraction for all retailers
                        ext_results = {}
                        with ThreadPoolExecutor(max_workers=3) as executor:
                            # Submit extraction tasks for each retailer
                            futures = {executor.submit(extract_urls, urls[retailer], retailer) : retailer for retailer in RETAILERS}

                            # Collect results as they complete
                            for future in as_completed(futures):
                                result = future.result()
                                ext_results[result[1]] = result[0].get("results", [])
                                if result == None:
                                    print("Condition met! Cancelling remaining tasks...")
                                    # Cancel remaining futures if an error occurs
                                    for f in futures:
                                        f.cancel()
                                    break
            // ...

Finally, process the extracted product data with LLMs to extract product information, as shown below.

class ShoppingAgentFlow(Flow[AgentState]):

    @start()
    async def start(self):
        """
        Main entry point for the shopping assistant workflow.
        This method handles the entire flow from user request to product results.
        """
        try:
            // ...

            # Step 20: Initialize data structures for product processing
            target_listing_pdps: List[str] = []
            done = False
            self.state.logs.append({
                "message" : "Processing the data",
                "status" : "processing"
            })
            await copilotkit_emit_state(self.state)

            # Initialize product containers for each retailer
            products_from_each_site= {
                "target.com" : [],
                "amazon.com" : [],
                "ebay.com" : []
            }

            # Initialize URL replacement counters for each retailer
            retailer_counters = {
                "target.com": {"product": 0, "image": 0},
                "amazon.com": {"product": 0, "image": 0},
                "ebay.com": {"product": 0, "image": 0}
            }

            # Step 21: Define async function for processing extracted data
            async def process_data(ext_results1: Dict[str, Any], retailer: str, retailer_counters: Dict[str, Dict[str, int]]) -> str:
                """Process extracted web content and convert to structured product data"""
                print(f"Processing data for {retailer}. Started at {datetime.now()}")

                for item in ext_results1:
                    url = item["url"]
                    raw = item.get("raw_content") or ""
                    if not raw:
                        return None

                    # Set up URL replacement patterns for each retailer
                    product_base = ""
                    image_base = ""
                    if retailer == "target.com":
                        product_base = "https://tgt.com/url{}"
                        image_base = "https://tgt.com/img/url{}"
                    elif retailer == "amazon.com":
                        product_base = "https://amzn.com/url{}"
                        image_base = "https://amzn.com/img/url{}"
                    elif retailer == "ebay.com":
                        product_base = "https://ebay.com/url{}"
                        image_base = "https://ebay.com/img/url{}"

                    # Replace URLs with standardized product and image links
                    modiefied_text, mappings_list, updated_product_counter, updated_image_counter = replace_urls_with_product_and_image_links(text= raw, product_base= product_base, image_base=image_base, product_counter=retailer_counters[retailer]["product"], image_counter=retailer_counters[retailer]["image"])

                    # Update counters
                    retailer_counters[retailer]["product"] = updated_product_counter
                    retailer_counters[retailer]["image"] = updated_image_counter
                    total_mappings_list.extend(mappings_list)

                    # Determine retailer and page type
                    dom = retailer_of(url)
                    detail_hint = is_pdp(url)

                    # Get structured data assistance for Target specifically
                    assist = parse_target_structured(modified_text) if "target.com" in dom else None

                    # Build prompt for LLM product extraction
                    prompt = build_llm_prompt(modiefied_text, url, assist=assist, detail_hint=detail_hint)

                    try:
                        # Limit products per retailer to avoid overwhelming results
                        if len(products_from_each_site[retailer]) > 2:
                            break
                        print(f"Calling LLM for {url}")
                        data = await call_llm(prompt)
                        print(f"Completed extracting {url}")
                    except Exception as e:
                        # Skip this page if LLM extraction fails
                        print(f"LLM 1st-pass failed for {url}: {e}")
                        continue

                    # Add metadata to extracted data
                    data.setdefault("source_url", url)
                    data.setdefault("retailer", dom)
                    products_from_each_site[retailer] += data["products"]
                return "Completed"
            // ...

Step 4: Configure Human-in-the-Loop functionality

Once the products have been extracted and processed, present them to the user via a tool call to the frontend, as shown below, where the agent pauses to allow the user to review products and make decisions.

class ShoppingAgentFlow(Flow[AgentState]):

    @start()
    async def start(self):
        """
        Main entry point for the shopping assistant workflow.
        This method handles the entire flow from user request to product results.
        """
        try:
            // ...

             # Step 24: Combine and finalize product results
            results_all = combine_products_from_sites(products_from_each_site)
            print(len(results_all), "results_all here")

            # Add unique IDs to each product
            for item in results_all:
                item["id"] = str(uuid.uuid4())

            # Mark data processing as completed
            self.state.logs[-1]["status"] = "completed"
            await copilotkit_emit_state(self.state)

            # Step 25: Apply URL mappings and prepare final results
            updated_products = apply_url_mappings_to_products(results_all, total_mappings_list)
            print(len(updated_products), "updated_products here")
            self.state.buffer_products = updated_products

            print("HERE")
            # Generate a descriptive name for this chat session
            chat_name = await generate_name_for_chat(query)
            print(chat_name, "chat_name here")

            # Step 26: Send product list to user for confirmation
            self.state.messages.append({
                "role" : "assistant",
                "content" : "",
                "tool_calls" : [
                    {
                        "id" : str(uuid.uuid4()),
                        "function" : {
                            "name": "list_products", 
                            "arguments": json.dumps({
                                "products": self.state.buffer_products[:5],  # Show first 5 products
                                "buffer_products" : self.state.buffer_products,  # Keep all products in buffer
                                "chat_name" : chat_name
                            })
                        }
                    }
                ]
            })

            # Step 27: Reset state for user interaction
            self.state.logs = []
            self.state.report = None
            self.state.canvas_logs = {
                "title" : "Awaiting confirmation from the user",
                "subtitle" : "Choose to accept, reject or show all products"
            }
            await copilotkit_emit_state(self.state)
            // ...

After that, when the user responds (via tool calls), handle different scenarios where the user might request more options, accept, or reject the product's recommendations.

class ShoppingAgentFlow(Flow[AgentState]):

    @start()
    async def start(self):
        """
        Main entry point for the shopping assistant workflow.
        This method handles the entire flow from user request to product results.
        """
        try:
            // ...

            # Step 7: Handle tool response messages
                        if(self.state.messages[-1]['role'] == 'tool'):
                            # Handle "Show more products" tool response
                            if(self.state.messages[-1]['content'] == "Show more products"):
                                self.state.messages.append({
                                    "role" : "assistant",
                                    "content" : "Some more products have also been added to be shown in the canvas",
                                    "id" : self.state.messages[-2]['tool_calls'][0]['id']
                                })
                                self.state.logs = []
                                self.state.show_results = True
                                await copilotkit_emit_state(self.state)
                                return self.state

                            # Handle "Rejected" tool response
                            if(self.state.messages[-1]['content'] == "Rejected"):
                                self.state.messages.append({
                                    "role" : "assistant",
                                    "content" : "You have rejected the products. Please try any other product search.",
                                    "id" : self.state.messages[-2]['tool_calls'][0]['id']
                                })
                                self.state.logs = []
                                await copilotkit_emit_state(self.state)
                                return self.state

                            # Handle "Accepted" tool response
                            if(self.state.messages[-1]['content'] == "Accepted"):
                                self.state.messages.append({
                                    "role" : "assistant",
                                    "content" : "The top 5 products have been added to the canvas.",
                                    "id" : self.state.messages[-2]['tool_calls'][0]['id']
                                })
                                self.state.logs = []
                                self.state.show_results = True
                                await copilotkit_emit_state(self.state)
                                return self.state
            // ...

Step 5: Set up a FastAPI endpoint

After creating the ShoppingAgentFlow, set up a FastAPI server that serves as the bridge between our CrewAI shopping agent and the frontend.

To do that, use the CopilotKitRemoteEndpoint to manage the lifecycle of the agent and then use the add_fastapi_endpoint function to mount the CopilotKit's routes to our FastAPI application, as shown in the agent/main.py file.

# Step 1: Import required dependencies
from fastapi import FastAPI  # FastAPI framework for building the API server
import uvicorn  # ASGI server for running FastAPI applications

# Step 2: Import CopilotKit components for agent integration
from copilotkit.integrations.fastapi import add_fastapi_endpoint  # FastAPI integration
from copilotkit import CopilotKitRemoteEndpoint  # Remote endpoint for agent hosting
from copilotkit.crewai.crewai_agent import CrewAIAgent  # CrewAI agent wrapper

# Step 3: Import system dependencies
import os  # Operating system interface for environment variables

# Step 4: Import the shopping assistant flow
from shopping_assistant import ShoppingAgentFlow  # Custom shopping agent implementation

# Step 5: Initialize FastAPI application
app = FastAPI()

# Step 6: Configure CopilotKit Remote Endpoint with Shopping Agent
# This creates a remote endpoint that hosts the shopping assistant agent
sdk = CopilotKitRemoteEndpoint(
    agents=[
        # Step 7: Create CrewAI agent wrapper for the shopping flow
        CrewAIAgent(
            name="shopping_agent_crewai",  # Unique identifier for the agent
            description="A shopping agent that can help you find the best products for your needs by searching various retailers",  # Agent description for CopilotKit
            flow=ShoppingAgentFlow()  # The actual shopping assistant workflow implementation
        )
    ]
)

# Step 8: Add CopilotKit endpoint to FastAPI application
# This mounts the CopilotKit SDK at the "/copilotkit" path
add_fastapi_endpoint(app, sdk, "/copilotkit")

# Step 10: Main server configuration and startup function
def main():
    """
    Configure and run the uvicorn server with development-friendly settings.

    """
    # Step 11: Get server port from environment variable with fallback
    port = int(os.getenv("PORT", "8000"))  # Default to port 8000 if PORT not set

    # Step 12: Start uvicorn server with comprehensive configuration
    uvicorn.run(
        "main:app",  # Application module and instance
        host="0.0.0.0",  # Listen on all network interfaces
        port=port,  # Use configured port
        reload=True,  # Enable hot reload for development
        timeout_keep_alive=900,  # 15 minutes = 900 seconds (for long operations)
        timeout_graceful_shutdown=900,  # 15 minutes graceful shutdown
        reload_dirs=(
            # Step 13: Configure reload directories for development
            ["."] +  # Current directory (always included)
            (["../../../sdk-python/copilotkit"]  # CopilotKit SDK directory if exists
             if os.path.exists("../../../sdk-python/copilotkit")
             else []  # Empty list if SDK directory doesn't exist
             )
        )
    )


# Step 14: Entry point for running the server
if __name__ == "__main__":
    # This ensures the server only starts when the script is run directly
    # (not when imported as a module)
    main()

Congratulations! You have built an AI-powered shopping assistant backend using CrewAI for agent flows, Tavily for web search, and CopilotKit for state management.

Building the CrewAI shopping agent frontend using CopilotKit

In this section, you will learn how to build a frontend for the CrewAI shopping agent using CopilotKit.

Let’s get started!

Step 1: Configure the Copilot Runtime instance

To get started, set up the Copilot runtime instance that serves as the bridge between your frontend and the CrewAI shopping agent backend, as shown below in the frontend/app/api/copilotkit/route.ts file.

/**
 * CopilotKit API Route for Next.js App Router
 *
 * This file sets up the CopilotKit runtime endpoint for the AI Shopping Agent frontend.
 * It handles POST requests to integrate with the CopilotKit service.
 */

import {
  CopilotRuntime,
  copilotRuntimeNextJSAppRouterEndpoint,
  OpenAIAdapter,
} from "@copilotkit/runtime";
import { NextRequest } from "next/server";

// Create an OpenAI adapter for the CopilotKit service
const serviceAdapter = new OpenAIAdapter();

// Initialize the CopilotRuntime with remote endpoints
// This connects to the shopping assistant backend
const runtime = new CopilotRuntime({
  remoteEndpoints: [
    {
      url:
        process.env.NEXT_PUBLIC_SHOPPING_AGENT_URL ||
        "http://localhost:8000/copilotkit",
    },
  ],
});

// POST handler for the CopilotKit API endpoint
// This function processes incoming requests and delegates to the CopilotKit runtime
export const POST = async (req: NextRequest) => {
  const { handleRequest } = copilotRuntimeNextJSAppRouterEndpoint({
    runtime,
    serviceAdapter,
    endpoint: "/api/copilotkit",
  });

  return handleRequest(req);
};

Step 2: Set up CopilotKit provider

After setting up a Copilot Runtime instance, set up the CopilotKit provider component that manages your ADK agent sessions.

To set up the CopilotKit Provider, the CopilotKit component must wrap the Copilot-aware parts of your application.

For most use cases, it's appropriate to wrap the CopilotKit provider around the entire app, e.g., in your layout.tsx file.

/**
 * Root Layout Component for the AI Shopping Agent
 *
 * This is the main layout component for the Next.js application.
 * It sets up the CopilotKit provider and global styles for the entire app.
 */

import type { Metadata } from "next";
import { GeistSans } from "geist/font/sans";
import { GeistMono } from "geist/font/mono";
import "./globals.css";
import "@copilotkit/react-ui/styles.css";
import { CopilotKit } from "@copilotkit/react-core";

// Metadata configuration for the application
export const metadata: Metadata = {
  title: "Shopping Assistant",
  description: "Powered by LangGraph and CopilotKit",
  generator: "v0.app",
};

/**
 * Root Layout Component
 *
 * This component wraps the entire application and provides:
 * - CopilotKit context for AI-powered features
 * - Global font configuration
 * - Base HTML structure
 */
export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang="en">
      <head>
        {/* Custom font configuration using Geist fonts */}
        <style>{`
html {
  font-family: ${GeistSans.style.fontFamily};
  --font-sans: ${GeistSans.variable};
  --font-mono: ${GeistMono.variable};
}
        `}</style>
      </head>
      <body>
        {/* CopilotKit Provider - enables AI chat and agent functionality */}
        <CopilotKit
          runtimeUrl="/api/copilotkit" // Points to our CopilotKit API route
          showDevConsole={false} // Hide development console in production
          agent="shopping_agent_crewai" // Specify which backend agent to use
        >
          {children}
        </CopilotKit>
      </body>
    </html>
  );
}

Step 3: Set up a Copilot chat component

CopilotKit ships with several built-in chat components, which include CopilotPopup, CopilotSidebar, and CopilotChat.

To set up a Copilot chat component, define it as shown in the frontend/components/sidebar.tsx file.

/**
 * Sidebar Component for AI Shopping Assistant
 *
 * This component provides the main navigation and chat interface for the shopping assistant.
 * It includes chat session management, view switching, and integrates with CopilotKit for AI interactions.
 */

"use client";

import type React from "react";
import { Button } from "@/components/ui/button";
import { Input } from "@/components/ui/input";
import { Badge } from "@/components/ui/badge";
import { ScrollArea } from "@/components/ui/scroll-area";
import { CopilotChat } from "@copilotkit/react-ui";
import { useCopilotChat } from "@copilotkit/react-core";

// ...

/**
 * Main Sidebar Component
 *
 * Features:
 * - Chat session management (create, switch, rename, delete)
 * - View switching between products, wishlist, and reports
 * - Integrated CopilotChat for AI interactions
 * - Product comparison analysis generation
 */
export function Sidebar({
  setQuery,
  isLoading,
  clearState,
  onSearch,
  suggestions,
  currentQuery,
  isSearching,
  currentView,
  wishlistCount,
  goToProducts,
  currentChatId,
  chatSessions,
  onSwitchChat,
  onCreateNewChat,
  onRenameChat,
  onDeleteChat,
}: SidebarProps) {

  // ...

  return (
    <div className="flex flex-col min-h-screen w-80 bg-[#FAFCFA] border-r border-[#D8D8E5]">
      {/* Header */}
      <div className="p-4 border-b border-[#D8D8E5] bg-white">
        <div className="flex items-center gap-3 mb-3">
          <div className="text-2xl">🪁</div>
          <div className="flex-1">
            <h1 className="text-lg font-semibold text-[#030507] font-['Roobert']">
              Shopping Assistant
            </h1>
            <Badge
              variant="secondary"
              className="text-xs bg-[#BEC9FF] text-[#030507] font-semibold">
              PRO
            </Badge>
          </div>
        </div>

                // ...

       <div className="flex-1 overflow-auto">
        <CopilotChat
          className="h-full"
          labels={{
            initial:
              "Hi! I'm your AI shopping assistant. I can help you find and compare products across multiple websites. What are you looking for today? Laptops, Phones, Headphones, etc.",
          }}
        />
      </div>
    </div>
  );
}

Step 4: Sync the CrewAI shopping agent state with the frontend using CopilotKit hooks

In CopilotKit, CoAgents maintain a shared state that seamlessly connects your frontend UI with the agent's execution. This shared state system allows you to:

Display the agent's current progress and intermediate results
Update the agent's state through UI interactions
React to state changes in real-time across your application

You can learn more about CoAgents’ shared state here on the CopilotKit docs.

To sync your CrewAI shopping agent state with the frontend, use the CopilotKit useCoAgent hook, as shown in the frontend/components/shopping-assistant.tsx file.

"use client"

import { useCoAgent } from "@copilotkit/react-core"

export function ShoppingAssistant() {

  // ...

  const { state, setState, start, run } = useCoAgent({
    name: "shopping_agent_crewai",
    initialState: conversationHistory.length > 0 ? { ...conversationHistory[0]?.state, show_results: (conversationHistory[0]?.state?.products?.length > 0 ? true : false) } : {
      products: [],
      favorites: typeof window !== 'undefined' && window.localStorage.getItem("wishlist") ? JSON.parse(window.localStorage.getItem("wishlist") || "[]") : [],
      wishlist: typeof window !== 'undefined' && window.localStorage.getItem("wishlist") ? JSON.parse(window.localStorage.getItem("wishlist") || "[]") : [],
      buffer_products: [],
      logs: [] as ToolLog[],
      report: null,
      show_results: false,
      canvas_logs: {
        title: "",
        subtitle: ""
      }
    }
  })


  return (
    <div className="flex h-screen bg-[#FAFCFA] overflow-hidden">

      // ...

      <div className="flex-1 flex flex-col min-w-0">
        {currentView === "report" ? (
          <ReportView isLoading={isLoading} products={state?.products} onExit={exitToProducts} searchQuery={query} report={state?.report} />
        ) : currentView === "wishlist" ? (

          // ...

        ) : (

          // ...

        )}
      </div>
    </div>
  )
}

Then render the CrewAI shopping agent's state in the chat UI, which is useful for informing the user about the agent's state in a more in-context way.

To render the CrewAI shopping agent's state in the chat UI, you can use the useCoAgentStateRender hook in the frontend/components/shopping-assistant.tsx file.

"use client"

import { useCoAgentStateRender} from "@copilotkit/react-core"
import { ToolLog, ToolLogs } from "./tool-logs"

export function ShoppingAssistant() {

  // ...

  useCoAgentStateRender({
    name: "shopping_agent_crewai",
    render: (state1: any) => {
      // useEffect(() => {
      // console.log(state1, "state1")
      // }, [state1])

      return <ToolLogs logs={state1?.state?.logs || []} />
    }
  })  

  return (
    <div className="flex h-screen bg-[#FAFCFA] overflow-hidden">

      // ...

      <div className="flex-1 flex flex-col min-w-0">
        {currentView === "report" ? (
          <ReportView isLoading={isLoading} products={state?.products} onExit={exitToProducts} searchQuery={query} report={state?.report} />
        ) : currentView === "wishlist" ? (

          // ...

        ) : (

          // ...

        )}
      </div>
    </div>
  )
}

If you execute a query in the chat, you should see the CrewAI shopping agent’s state task execution rendered in the chat UI, as shown below.

Step 5: Implementing Human-in-the-Loop (HITL) in the frontend

You can learn more about Human in the Loop here on CopilotKit docs.

"use client"

import { useCopilotAction } from "@copilotkit/react-core"
import DialogBox from "./tool-response"

export function ShoppingAssistant() {

  // ...

  useCopilotAction({
    name: "list_products",
    description: "A list of products that are scraped from the web",
    renderAndWaitForResponse: ({ status, respond, args }) => {
      // console.log(args, "argsargsargsargs")

      return <DialogBox isDisabled={respond == undefined} contentList={args?.products?.map((product: any) => ({ title: product.title, url: product.product_url }))}
        onAccept={() => {
          debugger
          if (respond) {
            respond("Accepted")
            setState({
              ...state,
              products: args?.products,
              buffer_products: args?.buffer_products.slice(5, args?.buffer_products.length),
              logs: []
            })
            let conversations = conversationHistory
            conversations.forEach((conversation: any) => {
              if (conversation.conversationId == currentChatId) {
                conversation.chatName = args?.chat_name
              }
            })
            setConversationHistory(conversations)
            setCurrentChatId(currentChatId)
            console.log(currentChatId, "currentChatId");
            // setConversationHistory((prev: any) => prev.map((conversation: any) => conversation.conversationId === currentChatId ? { ...conversation, chatName: args?.chat_name } : conversation))
            // setProducts(args?.products)
          }
        }}
        onReject={() => {
          if (respond) {
            respond("Rejected")
            setState({
              ...state,
              logs: []
            })
          }
        }}
        onNeedInfo={() => {
          debugger
          if (respond) {
            respond("Show more products")
            setState({
              ...state,
              products: args?.buffer_products?.slice(0, 10),
              buffer_products: args?.buffer_products.slice(10, args?.buffer_products.length),
              logs: []
            })

            let conversations = conversationHistory
            conversations.forEach((conversation: any) => {
              if (conversation.conversationId === currentChatId) {
                conversation.chatName = args?.chat_name
              }
            })
            console.log(currentChatId, "currentChatId");

            setConversationHistory(conversations)
            setCurrentChatId(currentChatId)
            // setConversationHistory((prev: any) => prev.map((conversation: any) => conversation.conversationId === currentChatId ? { ...conversation, chatName: args?.chat_name } : conversation))
            // setProducts(args?.buffer_products?.slice(0, 10))
          }
        }} />
    }

  })  

  return (
    <div className="flex h-screen bg-[#FAFCFA] overflow-hidden">

      // ...

      <div className="flex-1 flex flex-col min-w-0">
        {currentView === "report" ? (
          <ReportView isLoading={isLoading} products={state?.products} onExit={exitToProducts} searchQuery={query} report={state?.report} />
        ) : currentView === "wishlist" ? (

          // ...

        ) : (

          // ...

        )}
      </div>
    </div>
  )
}

When an agent triggers frontend actions by tool/action name to request human input or feedback during execution, the end-user is prompted with a choice (rendered inside the chat UI). Then the user can choose by pressing a button in the chat UI, as shown below.

Step 6: Streaming AG-UI + CrewAI agent responses in the frontend

To stream your CrewAI shopping agent responses or results in the frontend, pass the agent’s state field values to the frontend components, as shown in the frontend/components/shopping-assistant.tsx file.

"use client"

import { useCoAgent } from "@copilotkit/react-core"

export function ShoppingAssistant() {

  // ...

  const { state, setState, start, run } = useCoAgent({
    name: "shopping_agent_crewai",
    initialState: conversationHistory.length > 0 ? { ...conversationHistory[0]?.state, show_results: (conversationHistory[0]?.state?.products?.length > 0 ? true : false) } : {
      products: [],
      favorites: typeof window !== 'undefined' && window.localStorage.getItem("wishlist") ? JSON.parse(window.localStorage.getItem("wishlist") || "[]") : [],
      wishlist: typeof window !== 'undefined' && window.localStorage.getItem("wishlist") ? JSON.parse(window.localStorage.getItem("wishlist") || "[]") : [],
      buffer_products: [],
      logs: [] as ToolLog[],
      report: null,
      show_results: false,
      canvas_logs: {
        title: "",
        subtitle: ""
      }
    }
  })


  return (
    <div className="flex h-screen bg-[#FAFCFA] overflow-hidden">

      // ...

      <div className="flex-1 flex flex-col min-w-0">
        {currentView === "report" ? (
          <ReportView isLoading={isLoading} products={state?.products} onExit={exitToProducts} searchQuery={query} report={state?.report} />
        ) : currentView === "wishlist" ? (

          <WishlistView
            clearAllWishlist={() => {
              debugger
              setState({
                ...state,
                favorites: []
              })
              setConversationHistory((prev: any) => prev.map((conversation: any) => conversation.conversationId === currentChatId ? { ...conversation, state: { ...conversation.state, favorites: [] } } : conversation))
              if (typeof window !== 'undefined') {
                window.localStorage.setItem("wishlist", JSON.stringify([]))
              }
            }}
            products={state?.favorites}
            onExit={exitToProducts}
            onToggleWishlist={toggleWishlist}
            onDeleteProduct={deleteProduct}
          />

        ) : (
          <Canvas
            canvasLogs={state?.canvas_logs}
            start={run}
            show_results={state?.show_results}
            report={state?.report}
            products={state?.products}
            isLoading={isLoading && !state?.show_results}
            query={query}
            wishlistLength={state?.favorites?.length}
            wishlist={state?.favorites}
            onToggleWishlist={toggleWishlist}
            onDeleteProduct={deleteProduct}
            onGoToWishlist={goToWishlist}
            onGoToReport={goToReport}
          />          
        )}
      </div>
    </div>
  )
}

If you query your agent and approve its feedback request, you should see the agent’s response or results streaming in the UI, as shown below.

Conclusion

In this guide, we have walked through the steps of building a full-stack shopping assistant using CrewAI and then adding a frontend to the agents using CopilotKit.

While we’ve explored a couple of features, we have barely scratched the surface of the countless use cases for CopilotKit, ranging from building interactive AI chatbots to building agentic solutions—in essence, CopilotKit lets you add a ton of useful AI capabilities to your products in minutes.

Hopefully, this guide makes it easier for you to integrate AI-powered Copilots into your existing application.

Follow CopilotKit on Twitter and say hi, and if you'd like to build something cool, join the Discord community.