theokit-agents

TheoKit Agents & Tools

Server Surface — agents/*.ts (zero-config convention)

Create an agents/<name>.ts file at the project root. It is automatically served at POST /api/agents/<name> (dev + build) with no manual route wiring.

// agents/chat.ts
import { AgentBuilder } from '@theokit/agents'
import { z } from 'zod'

export default AgentBuilder.create()
  .input(z.object({ message: z.string() }))
  .model('openrouter/openai/gpt-4o-mini')
  .system('You are a helpful assistant.')
  .build()

The endpoint streams the ai-sdk UIMessageStream that useAgent (client hook) consumes. @theokit/sdk runs the agent; conversation turns auto-persist per session — the SDK owns storage.

Provider resolution: the FIRST segment of the model id picks the provider, and that decides which key is needed — openrouter/… needs OPENROUTER_API_KEY, anthropic/… needs ANTHROPIC_API_KEY, openai/… needs OPENAI_API_KEY. A bare vendor prefix is a selection of that vendor, not a hint: reaching OpenAI's catalog through OpenRouter means naming the gateway first (openrouter/openai/gpt-4o-mini). Set the matching key in .env.

Advanced Surface — @Agent Decorator (DI / class-based)

When you need dependency injection or composition, build the agent from capabilities (@theokit/agents). Each capability enriches the same compiled options; conflicts fail fast.

// server/agents/assistant.agent.ts
import { applyCapabilities, AgentConfigCapability, ModelCapability } from '@theokit/agents'

export const assistantAgent = applyCapabilities([
  new ModelCapability('openrouter/openai/gpt-4o-mini'),
  new AgentConfigCapability({
    systemPrompt: 'You are a helpful assistant.',
    maxIterations: 5,
  }),
])
// The framework runs the LLM loop via @theokit/sdk.

Tools — tool()

Declare a tool with the tool() builder from theokit/server/define, then chain it onto the agent with .tool(…). It is the same API agents/tools/weather.ts in this project uses — read that file for a working one.