The Basics
Define an agent
Give it a name, instructions, a model, and your Pikku functions as tools. The agent calls them automatically.
const todoAssistant = pikkuAIAgent({
name: 'todo-assistant',
description: 'A helpful assistant that manages todos',
instructions: 'You help users manage their todo lists.',
model: 'openai/gpt-4o-mini',
tools: [listTodos, createTodo, completeTodo],
memory: {
storage: 'aiStorage',
lastMessages: 20,
},
maxSteps: 5,
temperature: 0.7,
})
Functions as tools
Your existing Pikku functions become agent tools — no adapter code needed
Any LLM provider
model: "openai/gpt-4o", "anthropic/claude-3-5-sonnet" — provider/model format
Conversation memory
Built-in thread-based message storage with configurable context window
Features
Streaming, memory, approval
Everything you need to build production AI agents — built into the framework.
Streaming
Real-time text deltas, tool calls, and results via channel events. Show progress as the agent works.
Memory
Thread-based conversation history, configurable context window, and optional working memory for persistent state.
Tool approval
Require human approval before executing sensitive tools. The agent suspends and waits for your decision.
Multi-agent
Agents can delegate to sub-agents. Each sub-agent gets its own session and tools.
Structured output
Define an output schema and the agent returns validated JSON — not just free-text responses.
AI middleware
Hook into modifyInput, modifyOutput, and modifyOutputStream to transform agent behavior.
Invocation
Run or stream
Two execution modes: get the full result at once, or stream events in real time as the agent thinks and acts.
// Non-streaming: get the full result
const result = await runAIAgent('todo-assistant', {
message: 'Create a task for tomorrow',
threadId: 'thread-123',
resourceId: 'user-456'
}, { singletonServices })
console.log(result.text) // Agent response
console.log(result.steps) // Tool calls made
console.log(result.usage) // Token usage
// Streaming: real-time events
await streamAIAgent('todo-assistant', {
message: 'Create a task',
threadId: 'thread-123',
resourceId: 'user-456'
}, channel, { singletonServices })
// Channel receives events:
// { type: 'text-delta', text: '...' }
// { type: 'tool-call', toolName: 'createTodo', args: {...} }
// { type: 'tool-result', result: {...} }
// { type: 'usage', tokens: { input: 150, output: 42 } }
// { type: 'done' }
Start building AI agents in 5 minutes
One command to scaffold a project with AI agent wiring already configured.
MIT Licensed · Works with OpenAI, Anthropic & more