agentic-shell-python: Skill for Claude Code

AG-UI Integration

This skill helps you integrate the AG-UI (Agent-UI) protocol to connect a frontend application with an AI agent backend using CopilotKit.

When to Use

• Connecting a React/Next.js frontend to an AI agent backend
• Adding a chat sidebar or conversational UI to your application
• Implementing the AG-UI protocol for agent-frontend communication
• Building a BFF (Backend-for-Frontend) pattern with AI agents

Architecture

Browser → Next.js (/api/copilotkit) → Python Backend (/) → Azure OpenAI
          └─ CopilotKit Runtime         └─ Agent Framework

The AG-UI protocol enables:

• Streaming responses from the agent
• Tool call visualization
• Message history management
• State synchronization

Step-by-Step Instructions

Backend Setup

First, ensure your backend implements the AG-UI protocol. See the ms-agent-framework skill for Python/FastAPI setup.

The backend should expose an endpoint (e.g., POST /) that:

• Accepts AG-UI protocol requests
• Returns Server-Sent Events (SSE) for streaming

Frontend Setup

1. Install Dependencies

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

Or add to package.json:

{
  "dependencies": {
    "@ag-ui/client": "^0.0.41",
    "@copilotkit/react-core": "^1.10.6",
    "@copilotkit/react-ui": "^1.10.6",
    "@copilotkit/runtime": "^1.10.6",
    "next": "16.0.3",
    "react": "19.2.0",
    "react-dom": "19.2.0"
  }
}

2. Create the API Route (BFF)

Create app/api/copilotkit/route.ts:

import {
  CopilotRuntime,
  ExperimentalEmptyAdapter,
  copilotRuntimeNextJSAppRouterEndpoint,
} from "@copilotkit/runtime";
import { HttpAgent } from "@ag-ui/client";
import { NextRequest } from "next/server";

// Use the empty adapter since we're routing to a single agent
const serviceAdapter = new ExperimentalEmptyAdapter();

// Create the CopilotRuntime with AG-UI HttpAgent
const runtime = new CopilotRuntime({
  agents: {
    my_agent: new HttpAgent({ 
      url: process.env.AGENT_API_URL || "http://localhost:8080" 
    }),
  },
});

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