> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thesys.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Integration Patterns

> How to integrate Generative UI with your existing applications.

## Definitions

* **Gateway LLM**: The gateway LLM is the first LLM that is invoked when the user interacts with your application.
  Like traditional API Gateways, the gateway LLM is responsible for planning how to process the user's request and invoke
  other LLMs, tools or sub-agents to generate the final response.
* **Presentation Layer LLM**: The presentation layer LLM is the LLM that is used to generate the UI response.
  It may or may not be the same as the gateway LLM.

## C1 as the Gateway LLM (Preferred)

In this pattern, C1 is used as a gateway LLM that can be used to generate responses to user queries which can
then call other tools, LLMs or sub-agents to generate the final response. This is the recommended pattern for most
applications as it allows you to use the full power of C1 and results in no additional latency over your existing
LLM.

```mermaid theme={null}
sequenceDiagram
    participant User
    participant C1Gateway as C1
    participant Tools
    participant SubAgents as Sub-agents/Other LLMs

    User->>C1Gateway: User Query

    alt Tool Calling Required
        C1Gateway->>Tools: Execute Tool Calls
        Tools-->>C1Gateway: Tool Results
    end

    alt Sub-agent Required
        C1Gateway->>SubAgents: Invoke Sub-agent/LLM
        SubAgents-->>C1Gateway: Sub-agent Response
    end

    C1Gateway->>User: Generate UI Components<br/>& Stream Response
```

In a practical example, let's say you are currently using OpenAI GPT 4.1 as your gateway LLM.
Rather than calling the OpenAI API directly, you can use C1 endpoint with a model version that is built on top of GPT 4.1.
All your system prompts, tools, etc. would remain the same and the only change needed would be to use the `<C1Component>` component
to render the response.

<Note>
  This is the preferred pattern for integrating Generative UI into your existing applications.
</Note>

## C1 as a Presentation Layer LLM

In some cases, you might not want to replace your gateway LLM with C1 due to a variety of reasons (for example if you are
using a custom-model). In such cases, you can use the presentation layer LLM pattern where your existing LLM first generates a text-only
response and then C1 is used to generate a UI response based on the text response.

```mermaid theme={null}
sequenceDiagram
    participant User
    participant Gateway as Gateway LLM
    participant C1Presentation as C1 (Presentation Layer LLM)
    participant Tools as Tools / Sub-agents

    User->>Gateway: User Query

    alt Tool Calling Required
        Gateway->>Tools: Execute Tool Calls
        Tools-->>Gateway: Tool Results
    end

    Gateway->>Gateway: Generate Complete<br/>Text Response
    Gateway->>C1Presentation: Text Response<br/>(for UI generation)
    C1Presentation->>User: Generate UI Components<br/>& Stream Response
```

**Pros:**

* Can support any LLM since now the business logic layer LLM is separate from the presentation layer LLM.

**Cons:**

* Introduces additional latency since now you'll have to wait for the entire text response to be generated before you C1 can start streaming
* Generally speaking, the UI generation works better when C1 has more context of the current state and available functionality.
  Since the text response is generated by a different LLM, C1 will not have access to these details which it could have used to
  generate a more accurate UI response.

<Warning>
  This pattern is not recommended for most applications as it results in additional latency and is not as flexible as the
  gateway LLM pattern.
</Warning>

## C1 as a Tool

In this pattern your gateway LLM decides when to invoke C1 which is exposed to it as a tool call.
When the gateway LLM invokes C1, it will pass the current state of the application to C1 as context which it
can use to generate a more accurate UI response.

This has to be the final tool call in the chain of tool calls and the response returned by C1 should be directly
streamed back to the UI without any additional processing.

```mermaid theme={null}
sequenceDiagram
    participant User
    participant Gateway as Gateway LLM
    participant Tools as Tools / Sub-agents
    participant C1Tool as C1 (Tool)

    User->>Gateway: User Query

    alt Other Tool Calls Required
        Gateway->>Tools: Execute Other Tool Calls
        Tools-->>Gateway: Tool Results
    end

    alt If Decided to Call C1
        Gateway->>C1Tool: Tool Call with Context<br/>& Current State
        C1Tool->>User: Generate UI Components<br/>& Stream Response
    else If Not
        Gateway->>User: Return Text Response
    end
```

**Examples:**

* The user asks to generate a report on the sales of the last 30 days which invokes C1 as a tool call.
* Your agent needs input from the user to execute its task so it generates a live form via C1 to collect the required information.

**Pros:**

* Can support any LLM since now the business logic layer LLM is separate from the presentation layer LLM.

**Cons:**

* Introduces additional latency since now you'll have to wait for the entire text response to be generated before you C1 can start streaming
* Since the decision to invoke C1 is made by the gateway LLM, it is more error prone and requires more maintenance.