Skip to content

Components · Reference

Agent

A generic Effect AI agent service, typed streaming API, client atoms, and localized assistant widget with tools, approvals, context, and references.

Last updated October 8, 2026

Overview

agent installs a complete generic agent foundation: Effect request and event schemas, a streaming AI service, scoped client atoms, and a controlled React widget. It supports serializable history, multi-round tool execution, approval responses, contextual resources, @ references, streamed Markdown, tool activity, and English and French labels. Authentication, model selection, toolkit composition, and application-specific resources remain application-owned.

Install

shell
bunx shadcn@latest add @krak-stack/agent

Included Files

  • services/agent/schema.ts - generic resource schemas and the /agent SSE HttpApi group
  • services/agent/index.ts - AgentService streaming implementation
  • services/agent/client/atom.ts - scoped state, event reduction, submit, reset, and interruption-ready effects
  • services/agent/client/widget.tsx - controlled localized assistant widget

API Setup

Create the group with your application's resource schema and add it to the root API.

ts
export const AgentApiGroup = makeAgentApiGroup(Resource);
export class AppApi extends HttpApi.make("app").add(AgentApiGroup) {}

In the handler, authenticate the request, build a request-scoped toolkit and system prompt, then return AgentService.stream. Provide the selected LanguageModel and AgentService.layer where the API layers are assembled.

Client Setup

Adapt your generated SSE client to the atom factory, then bind a scope to the widget.

tsx
const agent = makeAgentAtoms({
  stream: (get, request) => apiClient.agent.stream({ payload: request }),
});

const state = useAtomValue(agent.state(scope));
const submit = useAtomSet(agent.submit, { mode: "promiseExit" });

<AgentWidget
  state={state}
  locale={locale}
  messages={{ es: { send: "Enviar mensaje" } }}
  onSubmit={(action) => submit({ action, scope })}
  onInterrupt={() => interrupt()}
  onReset={() => reset(scope)}
/>

Pass context for the resource currently being viewed and availableReferences to enable searchable @reference mentions. Resource values are generic and validated by the schema supplied to makeAgentApiGroup.

Localization

The widget receives the active locale through its locale prop. English and French defaults are built in, while the locale-keyed messages map supports any additional language without requiring an i18n provider.

Dependencies
Packages and shadcn components required by this registry item.

Dependencies

Registry Dependencies

Preview