agent-ui

Visão geral

O que é agent-ui?

agent-ui é um componente de Agent completo para React e Next.js fornecido pela ui.inference.sh. Em vez de construir uma interface de chat de IA do zero, você instala uma UI de Agent pronta junto com uma rota de proxy de API simples, baseada em @inferencesh/sdk.

O componente reúne os elementos principais que você normalmente precisa para assistentes de IA modernos:

• Uma interface de chat/agent pronta para uso
• Conexão em tempo de execução com o backend de inferência via rota de proxy
• Suporte a respostas em streaming
• Espaço para ferramentas, aprovações e fluxos de agentes mais avançados (via a infraestrutura da própria ui.inference.sh)

Se você quer lançar assistentes de IA, copilots SaaS ou UIs agentic dentro de um app Next.js, o agent-ui oferece um ponto de partida pronto para produção com pouquíssimo boilerplate.

Para quem é o agent-ui?

agent-ui foi pensado para:

• Desenvolvedores frontend que querem uma UI de agent/chat bem acabada em um app React ou Next.js sem precisar desenhar componentes do zero.
• Times de produto que estão incorporando copilots ou assistentes de IA em dashboards existentes, produtos SaaS ou ferramentas internas.
• Engenheiros focados em API que preferem configurar uma rota de proxy e variáveis de ambiente em vez de codar toda a lógica de requisição no cliente.

Você vai se sentir mais à vontade com esta skill se já:

• Usa Next.js (App Router) ou uma stack React semelhante
• Está familiarizado com variáveis de ambiente e chaves de API
• Sabe configurar rotas e componentes em um codebase TypeScript/React

Que problemas o agent-ui resolve?

agent-ui ajuda você a evitar vários pontos de atrito comuns ao implementar funcionalidades de IA:

• Sem precisar criar UI de chat do zero – você não precisa construir listas de mensagens, campos de entrada e estados de loading na mão.
• Sem “gambiarras” de fetch – a rota de proxy é tratada via @inferencesh/sdk, evitando repetir lógica de streaming e tratamento de erros.
• Configuração mais simples – em vez de espalhar configs pela UI, você passa um objeto agentConfig (referência do modelo, descrição, system prompt).

Isso torna o agent-ui uma ótima opção quando você quer sair rapidamente de “temos uma API key” para “temos uma interface de agent funcionando”.

Quando o agent-ui é uma boa escolha?

agent-ui é uma boa opção quando:

• Você está construindo um app Next.js (especialmente usando a estrutura de diretórios app/).
• Você quer uma agent UI pronta com visual moderno, dentro do ecossistema estilo shadcn.
• Você se sente confortável em configurar uma rota de inference proxy e variáveis de ambiente.

Talvez não seja a melhor escolha se:

• Você não usa React/Next.js como stack de frontend.
• Você precisa de uma UI de chat totalmente customizada, com padrões de interação muito diferentes de uma interface típica de agent.
• Você não pode expor nem gerenciar uma INFERENCE_API_KEY no seu ambiente.

Como usar

1. Instalar a skill no seu workspace de agentes

Para adicionar a skill agent-ui em um workspace compatível com Agent Skills, instale via CLI de skills:

npx skills add https://github.com/inferen-sh/skills --skill agent-ui

Esse comando busca os metadados da skill agent-ui no repositório inferen-sh/skills. Depois da instalação, abra o arquivo SKILL.md na pasta ui/agent-ui para seguir as instruções upstream.

2. Instalar o componente agent-ui em um projeto Next.js

Dentro do seu app Next.js (onde você quer renderizar a UI), instale o componente Agent da ui.inference.sh usando o comando no estilo shadcn mencionado pela skill:

# Instalar o componente de agent
npx shadcn@latest add https://ui.inference.sh/r/agent.json

# Adicionar o SDK para a rota de proxy
npm install @inferencesh/sdk

Isso faz duas coisas:

• Importa o bloco Agent UI (componente React e a lógica de UI relacionada) de ui.inference.sh.
• Instala @inferencesh/sdk, que você vai usar para criar a rota de proxy de inferência no seu app Next.js.

Você pode rodar esses comandos em qualquer projeto Next.js (App Router) existente. Certifique-se de ter Node.js, npm (ou outro gerenciador de pacotes) e um ambiente de desenvolvimento funcionando antes de rodá-los.

3. Configurar a rota de proxy de API no Next.js

O agent-ui espera que o frontend se conecte a uma rota de proxy no backend, em vez de chamar o serviço de inferência diretamente do browser. A documentação da skill fornece uma rota mínima de Next.js baseada em @inferencesh/sdk:

// app/api/inference/proxy/route.ts
import { route } from '@inferencesh/sdk/proxy/nextjs';
export const { GET, POST, PUT } = route;

Observações de implementação:

• Coloque esse arquivo em app/api/inference/proxy/route.ts em um projeto Next.js com App Router.
• O helper route de @inferencesh/sdk/proxy/nextjs expõe para você os handlers HTTP (GET, POST, PUT), então não é necessário criar lógica de roteamento customizada.
• Esse endpoint se torna o proxyUrl que você vai passar para o componente Agent.

Se você usar uma estrutura de diretórios diferente, mantenha o caminho consistente e atualize o proxyUrl de acordo.

4. Definir a variável de ambiente INFERENCE_API_KEY

Em seguida, configure a chave de API de inferência no seu ambiente local. As instruções da skill fazem referência à variável INFERENCE_API_KEY:

# .env.local
INFERENCE_API_KEY=inf_...

Passos:

1. Crie ou abra o arquivo .env.local na raiz do seu projeto Next.js.
2. Coloque a sua chave de API real no lugar de inf_....
3. Reinicie o servidor de desenvolvimento para que as mudanças em .env.local sejam aplicadas.

Certifique-se de manter essa chave em segredo e nunca faça commit de .env.local no version control.

5. Renderizar o componente Agent em uma página

Com o componente e a rota de proxy configurados, você pode renderizar a Agent UI em qualquer página do Next.js. A skill inclui um exemplo simples:

import { Agent } from "@/registry/blocks/agent/agent";

export default function Page() {
  return (
    <Agent
      proxyUrl="/api/inference/proxy"
      agentConfig={{
        core_app: { ref: 'openrouter/claude-haiku-45@0fkg6xwb' },
        description: 'a helpful ai assistant',
        system_prompt: 'you are helpful.',
      }}
    />
  );
}

Pontos principais:

• proxyUrl: Aponta para a rota de proxy de API que você criou (/api/inference/proxy). É por esse caminho que a Agent UI envia e recebe mensagens.
• agentConfig: Objeto que configura o agent por baixo dos panos, incluindo:
  • core_app.ref: Referência ao modelo ou app usado no backend.
  • description: Descrição em linguagem natural do assistente.
  • system_prompt: System prompt curto que orienta o comportamento.

Você pode copiar ou adaptar esse arquivo de página em app/agent/page.tsx ou em qualquer rota existente do seu app.

6. Customizar e estender o agent-ui

O SKILL.md da skill menciona recursos como tools, approvals e widgets (via ui.inference.sh). Para aproveitar essas possibilidades, você pode, de forma incremental:

• Ajustar o agentConfig com diferentes refs de modelo, descrições e system prompts.
• Explorar os arquivos do bloco Agent em @/registry/blocks/agent/agent para entender como a UI foi construída e quais props são suportadas.
• Integrar a Agent UI em fluxos específicos do seu app (por exemplo, um dashboard de suporte, um onboarding copilot ou um assistente para operações internas).

Como o agent-ui é entregue como um componente React, você pode envolvê-lo em layouts, modais ou abas, e usar sua própria navegação e autenticação ao redor dele.

7. Arquivos para revisar depois da instalação

Depois de instalar a skill agent-ui no seu workspace compatível com skills, o principal arquivo para abrir é:

• ui/agent-ui/SKILL.md – guia de início rápido e detalhes de configuração upstream.

A partir daí, você pode aplicar as instruções no seu projeto Next.js real e adaptá-las aos seus modelos e restrições de backend.

FAQ

O agent-ui exige Next.js ou posso usar com React puro?

O passo a passo de setup da skill e o exemplo de rota de proxy foram escritos especificamente para Next.js, usando a convenção de rotas app/api e @inferencesh/sdk/proxy/nextjs. Embora a UI em si seja baseada em React, o caminho documentado e suportado nesta skill é para Next.js com rotas no estilo App Router.

Se você estiver usando React puro ou outro framework, será necessário recriar o comportamento de proxy por conta própria e adaptar o exemplo; esse caminho de integração não está documentado nesta skill.

Em que o agent-ui é diferente de construir uma UI de chat customizada?

Com o agent-ui você:

• Instala um componente Agent pronto da ui.inference.sh.
• Conecta ao backend de inferência via uma única rota de proxy e uma variável de ambiente.

Você não precisa:

• Desenhar e codar lista de mensagens, área de entrada e estados de streaming.
• Escrever manualmente chamadas fetch para envio e recebimento de mensagens.

Você continua tendo controle de configuração via agentConfig, podendo alterar a referência do modelo, descrição e system prompt sem mexer na implementação interna da UI.

Qual é o papel de @inferencesh/sdk nessa configuração?

@inferencesh/sdk é o responsável pela rota de proxy no servidor:

import { route } from '@inferencesh/sdk/proxy/nextjs';
export const { GET, POST, PUT } = route;

Ao usar esse helper, você:

• Expõe um único endpoint (/api/inference/proxy no exemplo) para o qual a sua Agent UI vai enviar as requisições.
• Delega detalhes de protocolo e tratamento dos métodos HTTP (GET, POST, PUT) para o SDK, em vez de escrever código customizado.

Isso facilita manter e evoluir a integração de inferência sem precisar reescrever a UI.

Como eu altero o modelo ou o comportamento do agent?

Você atualiza o agentConfig passado para o componente Agent. Por exemplo:

<Agent
  proxyUrl="/api/inference/proxy"
  agentConfig={{
    core_app: { ref: 'openrouter/claude-haiku-45@0fkg6xwb' },
    description: 'a helpful ai assistant',
    system_prompt: 'you are helpful.',
  }}
/>

Para mudar o comportamento, você pode:

• Trocar o core_app.ref por outro modelo ou app suportado.
• Atualizar a description para refletir o papel do assistente (por exemplo, “customer support copilot”).
• Refinar o system_prompt para ajustar tom e escopo de tarefas.

Consulte a documentação do seu backend de inferência para ver valores válidos e opções adicionais de configuração.

O agent-ui é adequado para uso em produção?

A skill agent-ui expõe um componente real de Agent para React/Next.js e um padrão de rota de proxy orientado a apps com perfil de produção. No entanto, a prontidão para produção depende de como você:

• Gerencia chaves de API e variáveis de ambiente.
• Adiciona autenticação, autorização e rate limiting em torno de /api/inference/proxy.
• Monitora, faz log e protege o tráfego para o backend de inferência.

A skill fornece um ponto de partida sólido, mas você deve aplicar suas próprias políticas de segurança, observabilidade e tratamento de erros antes de ir para produção.

Onde posso ver a documentação upstream do agent-ui?

Depois de instalar a skill com:

npx skills add https://github.com/inferen-sh/skills --skill agent-ui

abra:

• ui/agent-ui/SKILL.md

Esse arquivo é mantido no repositório inferen-sh/skills e contém o guia de início rápido upstream (comandos de instalação, snippet da rota de proxy, configuração de env e exemplo de uso de componente) para o componente agent-ui.