Two-Step Visualize Pattern

This guide demonstrates how to integrate C1 Visualize API with your existing agentic application using a two-step architecture. This pattern allows you to leverage any LLM provider (OpenAI, Anthropic, etc.) for tool-calling and business logic, while using C1 exclusively for generating beautiful, interactive UI components.

Overview

The two-step Visualize pattern separates concerns between your primary LLM and the UI generation layer:

Step 1 - Business Logic: Your primary LLM handles user requests, executes tool calls, and generates a final text/markdown response
Step 2 - UI Generation: C1 Visualize API converts the text response into interactive, generative UI components

This approach is ideal when:

You want to use your existing LLM infrastructure for tool-calling
You need to maintain complete conversation history with your primary LLM
You want to add beautiful UI generation without refactoring your agent logic

For most applications, we recommend using C1 as the Gateway LLM instead, which provides lower latency and better context awareness.

Architecture

Key Concepts

Message Types

The pattern uses two distinct message storage strategies: AIMessage: Complete conversation history with your primary LLM

Includes user prompts, assistant responses, tool calls and their results
Essential for maintaining context in subsequent LLM calls

UIMessage: Display-optimized messages for the frontend

User prompts and final generative UI responses from C1
Used for rendering the chat interface

The Two-Step Flow

Step 1: Call your primary LLM with full conversation context, allowing it to use tools and generate a complete response
Step 2: Send the final LLM response to C1 Visualize API, which transforms it into rich UI components without needing tool access

Setup

1. Install Dependencies

npm

npm install openai @thesysai/genui-sdk @crayonai/react-core @crayonai/react-ui @crayonai/stream

pip install openai fastapi uvicorn thesys-genui-sdk

2. Environment Variables

Create a .env file with your API keys:

OPENAI_API_KEY=your_openai_api_key
THESYS_API_KEY=your_thesys_api_key

You can create a new API key from Developer Console

3. Configure OpenAI Clients

Create two OpenAI client instances - one for your standard LLM calls and one for C1 Visualize:

TypeScript/Next.js

import OpenAI from "openai";

// Standard OpenAI client for business logic and tool-calling
const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

// C1 Visualize client for UI generation
const thesysClient = new OpenAI({
  baseURL: "https://api.thesys.dev/v1/visualize",
  apiKey: process.env.THESYS_API_KEY,
});

import os
from openai import OpenAI

# Standard OpenAI client for business logic and tool-calling
openai = OpenAI(
    api_key=os.environ["OPENAI_API_KEY"]
)

# C1 Visualize client for UI generation
thesys_client = OpenAI(
    base_url="https://api.thesys.dev/v1/visualize",
    api_key=os.environ["THESYS_API_KEY"],
)

Implementation

Backend API Route

Create an API route that orchestrates the two-step process:

app/api/chat/route.ts

import { NextRequest } from "next/server";
import OpenAI from "openai";
import { transformStream } from "@crayonai/stream";
import { tools } from "./tools";

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

const thesysClient = new OpenAI({
  baseURL: "https://api.thesys.dev/v1/visualize",
  apiKey: process.env.THESYS_API_KEY,
});

const SYSTEM_PROMPT = `You are a helpful assistant.

Your outputs will be processed by a downstream visualizer agent to generate a user interface.
The visualizer agent is responsible for generating a user interface based on your output but it does not have access to the tool calls or the database.
In your response, you should provide enough information with possible actions like buttons, forms, links, etc. that the user can take to interact with the UI.

If user asks for output in a specific component (e.g., graph, table, chart), generate the output in the requested format so the visualizer can render it properly. Give hints in your output so that the downstream agent can use those hints to generate UI properly.`;

export async function POST(req: NextRequest) {
  const { prompt, threadId, responseId } = await req.json();

  // Step 1: Call Standard OpenAI API
  const previousAiMessages = await getAIThreadMessages(threadId);

  // Use runTools helper to handle tool execution automatically
  const runner = openai.beta.chat.completions.runTools({
    model: "gpt-4",
    messages: [
      { role: "system", content: SYSTEM_PROMPT },
      ...previousAiMessages,
      { role: "user", content: prompt.content },
    ],
    temperature: 0.1,
    stream: false,
    tools: tools,
  });

  // Wait for OpenAI to complete (including tool calls)
  await runner.done();
  const finalMessages = runner.messages;

  // Step 2: Store AI Interaction History
  const newAiMessagesToStore = [];

  // Add the user prompt
  newAiMessagesToStore.push(prompt);

  // Track messages and extract final assistant message
  let finalAssistantMessageForUI;
  runner.on("message", (message) => {
    newAiMessagesToStore.push({ ...message, id: crypto.randomUUID() });
    if (typeof message.content === "string") {
      finalAssistantMessageForUI = message;
    }
  });

  // Step 3: Validate Final Assistant Content

  if (!finalAssistantMessageForUI ||
      typeof finalAssistantMessageForUI.content !== "string") {
    console.error("No final assistant message found");
    return new Response("", { status: 200 });
  }

  // Step 4: Call C1 Visualize API
  const thesysStreamRunner = thesysClient.beta.chat.completions.runTools({
    model: "c1/anthropic/claude-sonnet-4/v-20251230",
    messages: [
      ...previousAiMessages,
      { role: "user", content: prompt.content },
      { role: "assistant", content: finalAssistantMessageForUI.content },
    ],
    stream: true,
    tools: [], // No tools needed for Visualize API
  });

  // Visualize API returns only one assistant message
  thesysStreamRunner.on("message", async (message) => {
    // Step 5: Store messages after streaming completes
    await addMessages(
      threadId,
      newAiMessagesToStore,
      [prompt, { ...message, id: responseId }]
    );
  });

  const llmStream = await thesysStreamRunner;

  // Step 6: Stream Response to Client
  const responseStream = transformStream(llmStream, (chunk) => {
    return chunk.choices[0]?.delta?.content || "";
  });

  return new Response(responseStream, {
    headers: {
      "Content-Type": "text/event-stream",
      "Cache-Control": "no-cache, no-transform",
      Connection: "keep-alive",
    },
  });
}

For tool definitions, see the Tool Calling guide for complete examples of how to define and implement tools for your application.

import os
import json
from typing import List, Dict, Any, Optional
from fastapi import FastAPI
from pydantic import BaseModel
from openai import OpenAI
from thesys_genui_sdk.fast_api import with_c1_response
from thesys_genui_sdk.context import write_content
from tools import tools, tool_impls

app = FastAPI()

# Standard OpenAI client for business logic and tool-calling
openai = OpenAI(
    api_key=os.environ["OPENAI_API_KEY"]
)

# C1 Visualize client for UI generation
thesys_client = OpenAI(
    base_url="https://api.thesys.dev/v1/visualize",
    api_key=os.environ["THESYS_API_KEY"],
)

SYSTEM_PROMPT = """You are a helpful assistant.

Your outputs will be processed by a downstream visualizer agent to generate a user interface.
The visualizer agent is responsible for generating a user interface based on your output but it does not have access to the tool calls or the database.
In your response, you should provide enough information with possible actions like buttons, forms, links, etc. that the user can take to interact with the UI.

If user asks for output in a specific component (e.g., graph, table, chart), generate the output in the requested format so the visualizer can render it properly. Give hints in your output so that the downstream agent can use those hints to generate UI properly."""


class ChatMessage(BaseModel):
    role: str
    content: str
    id: Optional[str] = None


class ChatRequest(BaseModel):
    prompt: ChatMessage
    threadId: str
    responseId: str


def run_chat_with_tools(
    messages: List[Dict[str, Any]]
) -> str:
    """Step 1: Call Standard OpenAI API with tool execution"""
    completion = openai.chat.completions.create(
        model="gpt-4",
        messages=messages,
        temperature=0.1,
        tools=tools,
    )

    while True:
        choice = completion.choices[0]
        message = choice.message
        tool_calls = message.tool_calls or []

        # If there are no tool calls, return the assistant's answer
        if not tool_calls:
            return message.content or ""

        # Record the assistant message that requested tools
        messages.append(
            {
                "role": "assistant",
                "content": message.content or "",
                "tool_calls": [
                    {
                        "id": tc.id,
                        "type": "function",
                        "function": {
                            "name": tc.function.name,
                            "arguments": tc.function.arguments,
                        },
                    }
                    for tc in tool_calls
                ],
            }
        )

        # Execute tools and append results
        for tool_call in tool_calls:
            name = tool_call.function.name
            args = json.loads(tool_call.function.arguments or "{}")
            result = tool_impls[name](**args)
            messages.append(
                {
                    "role": "tool",
                    "tool_call_id": tool_call.id,
                    "content": result,
                }
            )

        # Ask the model again with tool results
        completion = openai.chat.completions.create(
            model="gpt-4",
            messages=messages,
            temperature=0.1,
            tools=tools,
        )


@app.post("/api/chat")
@with_c1_response()
async def chat(request: ChatRequest):
    # Step 1: Get AI thread messages
    previous_ai_messages = await get_ai_thread_messages(request.threadId)

    # Prepare messages for OpenAI
    messages = [
        {"role": "system", "content": SYSTEM_PROMPT},
        *previous_ai_messages,
        {"role": "user", "content": request.prompt.content},
    ]

    # Step 2: Call OpenAI with tools and get final response
    final_assistant_message = run_chat_with_tools(messages.copy())

    # Step 3: Store AI interaction history
    new_ai_messages = [
        {"role": "user", "content": request.prompt.content, "id": request.prompt.id},
        {"role": "assistant", "content": final_assistant_message, "id": request.responseId},
    ]
    await add_ai_messages(request.threadId, new_ai_messages)

    # Step 4: Call C1 Visualize API
    visualize_messages = [
        *previous_ai_messages,
        {"role": "user", "content": request.prompt.content},
        {"role": "assistant", "content": final_assistant_message},
    ]

    stream = thesys_client.chat.completions.create(
        model="c1/anthropic/claude-sonnet-4/v-20251230",
        messages=visualize_messages,
        stream=True,
    )

    # Step 5: Stream response to client
    for chunk in stream:
        content = chunk.choices[0].delta.content
        if content:
            await write_content(content)

    # Step 6: Store UI messages
    await add_ui_messages(
        request.threadId,
        [
            {"role": "user", "content": request.prompt.content, "id": request.prompt.id},
            {"role": "assistant", "content": final_assistant_message, "id": request.responseId},
        ]
    )


# Helper functions for message storage (implement based on your database)
async def get_ai_thread_messages(thread_id: str) -> List[Dict[str, Any]]:
    # Implement fetching AI messages from your database
    pass


async def add_ai_messages(thread_id: str, messages: List[Dict[str, Any]]):
    # Implement storing AI messages to your database
    pass


async def add_ui_messages(thread_id: str, messages: List[Dict[str, Any]]):
    # Implement storing UI messages to your database
    pass

Frontend Component

Use the GenUI SDK to render the chat interface:

app/page.tsx

"use client";

import "@crayonai/react-ui/styles/index.css";
import {
  C1Chat,
  useThreadListManager,
  useThreadManager,
} from "@thesysai/genui-sdk";
import * as apiClient from "@/src/apiClient";

export default function Home() {
  const threadListManager = useThreadListManager({
    fetchThreadList: () => apiClient.getThreadList(),
    deleteThread: (threadId) => apiClient.deleteThread(threadId),
    updateThread: (t) => apiClient.updateThread(t),
    createThread: (message) => apiClient.createThread(message.message),
  });

  const threadManager = useThreadManager({
    threadListManager,
    loadThread: (threadId) => apiClient.getMessages(threadId),
    onUpdateMessage: ({ message }) => {
      apiClient.updateMessage(
        threadListManager.selectedThreadId,
        message
      );
    },
    apiUrl: "/api/chat",
  });

  return (
    <C1Chat
      threadManager={threadManager}
      threadListManager={threadListManager}
    />
  );
}

System Prompt Best Practices

When crafting your system prompt for the primary LLM, include guidance for the downstream visualizer:

Mention the Visualizer: Inform the LLM that its output will be processed by a UI generator
Provide Context: Explain that the visualizer doesn’t have access to tools or database
Request Structure: Ask for actionable elements like buttons, forms, and links
Format Hints: Suggest specific UI components when appropriate (tables, charts, etc.)

Example System Prompt

const SYSTEM_PROMPT = `You are a [domain-specific] assistant.

**Your Workflow:**
1. [Describe your agent's workflow]
2. [List key actions and tools]
3. [Specify behavior patterns]

**Visualizer Agent:**
Your outputs will be processed by a downstream visualizer agent to generate a user interface.
The visualizer agent is responsible for generating a user interface based on your output but it does not have access to the tool calls or the database.
In your response, you should provide enough information with possible actions like buttons to select items, forms to submit data, links to navigate, etc. that the user can take to interact with the UI.

If user asks for output in a specific component (e.g., graph, table, chart), generate the output in the requested format so the visualizer can render it properly. Give hints in your output so that the downstream agent can use those hints to generate UI properly.`;

Message Persistence

Store two types of messages with distinct purposes: AIMessage Table

Stores complete LLM conversation history including tool calls and results
Used for context in subsequent LLM calls

UIMessage Table

Stores user-facing messages with generative UI responses
Used for rendering chat interface

Example Prisma Schema

schema.prisma

model Thread {
  id          String      @id @default(uuid())
  title       String?
  createdAt   DateTime    @default(now())
  updatedAt   DateTime    @updatedAt
  aiMessages  AIMessage[]
  uiMessages  UIMessage[]
}

model AIMessage {
  id        String   @id @default(uuid())
  threadId  String
  thread    Thread   @relation(fields: [threadId], references: [id], onDelete: Cascade)
  role      String
  content   String?
  toolCalls Json?
  toolCallId String?
  name      String?
  createdAt DateTime @default(now())
}

model UIMessage {
  id        String   @id @default(uuid())
  threadId  String
  thread    Thread   @relation(fields: [threadId], references: [id], onDelete: Cascade)
  role      String
  content   String?
  createdAt DateTime @default(now())
}

Troubleshooting

C1 generates generic UI instead of domain-specific components

Enhance your system prompt to provide more context about expected UI patterns and include relevant metadata in the assistant’s final message.

const SYSTEM_PROMPT = `You are a ${domainName} assistant.
...
Include specific details about ${relevantContext} in your responses.`;

Message history growing too large

For development, you can truncate to recent messages. For production, use prompt caching with conversation compaction:

// Development: Keep only the last N messages
const recentMessages = conversationHistory.slice(-10);

// Production: Use prompt caching and compaction
// Compact older messages into summaries while keeping recent context

Best Practices

Separate Concerns: Keep business logic in your primary LLM and UI generation in C1
Rich Context: Provide detailed information in the final assistant message for better UI generation
Actionable Elements: Always include next-step actions (buttons, forms) in your responses
Message Storage: Store both AI and UI message histories for optimal context management
Error Recovery: Implement graceful fallbacks if either API call fails
Testing: Test the full two-step flow with various query types and edge cases

This pattern introduces additional latency since you must wait for the primary LLM to complete before C1 can start streaming. For most applications, consider using C1 as the Gateway LLM instead.

Full Example on GitHub

See a complete working implementation of this pattern in our e-commerce agent example with tools, database integration, and production-ready code.

Getting Started

Basics

Interactivity

Styling

Conversational UI

Artifacts

Advanced

Ecosystem

Overview

Architecture

Key Concepts

Message Types

The Two-Step Flow

Setup

1. Install Dependencies

2. Environment Variables

3. Configure OpenAI Clients

Implementation

Backend API Route

Frontend Component

System Prompt Best Practices

Example System Prompt

Message Persistence

Example Prisma Schema

Troubleshooting

Best Practices

Full Example on GitHub

​Overview

​Architecture

​Key Concepts

​Message Types

​The Two-Step Flow

​Setup

​1. Install Dependencies

​2. Environment Variables

​3. Configure OpenAI Clients

​Implementation

​Backend API Route

​Frontend Component

​System Prompt Best Practices

​Example System Prompt

​Message Persistence

​Example Prisma Schema

​Troubleshooting

​Best Practices

Full Example on GitHub

Overview

Architecture

Key Concepts

Message Types

The Two-Step Flow

Setup

1. Install Dependencies

2. Environment Variables

3. Configure OpenAI Clients

Implementation

Backend API Route

Frontend Component

System Prompt Best Practices

Example System Prompt

Message Persistence

Example Prisma Schema

Troubleshooting

Best Practices