AI Agents

Create AI agents through a single unified request definition. Mix providers and choose the best model for each task.

Overview

The Agent class is the core building block of Mozaik. It provides a consistent interface for interacting with different AI providers, making it easy to switch models or compare outputs.

Basic Usage

Create an agent by defining a command with your desired model:

basic-agent.ts

1import { MozaikAgent, MozaikRequest } from '@mozaik-ai/core'
2
3// Define the command configuration
4const request: MozaikRequest = {
5  model: 'claude-sonnet-4.5'
6}
7
8// Create the agent
9const agent = new MozaikAgent(request)
10
11// Execute a task
12const response = await agent.act('Write a React component for a todo list')
13
14console.log(response)

Command Configuration

The Command object lets you configure various aspects of the agent's behavior:

command-config.ts

1import { Agent, Command } from '@mozaik-ai/core'
2
3const command: Command = {
4  // Required: specify the model
5  model: 'gpt-5',
6  
7  // Optional: initial task for the agent
8  task: 'Analyze this codebase and suggest improvements',
9  
10  // Optional: conversation history
11  messages: [
12    { role: 'system', content: 'You are a helpful coding assistant' },
13    { role: 'user', content: 'Previous context...' }
14  ],
15  
16  // Optional: tools for function calling
17  tools: [...],
18  
19  // Optional: structured output schema
20  structuredOutput: myZodSchema
21}
22
23const agent = new Agent(command)

Provider Comparison

Easily compare outputs from different providers:

compare-providers.ts

1import { Agent } from '@mozaik-ai/core'
2
3const task = 'Explain the concept of closures in JavaScript'
4
5// Create agents for different providers
6const gptAgent = new Agent({ model: 'gpt-5' })
7const claudeAgent = new Agent({ model: 'claude-sonnet-4.5' })
8
9// Get responses from both
10const [gptResponse, claudeResponse] = await Promise.all([
11  gptAgent.act(task),
12  claudeAgent.act(task)
13])
14
15console.log('GPT-5:', gptResponse)
16console.log('Claude:', claudeResponse)

Tip

Running agents in parallel with Promise.all is a great way to compare model outputs or improve reliability through redundancy.

Best Practices

•Choose the right model: Use smaller models (gpt-5-nano) for simple tasks and larger models (gpt-5, claude-opus) for complex reasoning.
•Use system messages: Provide context and instructions via the messages array with role: 'system'.
•Type your responses: Use structured output with Zod schemas for predictable, typed responses.

Next Steps

Structured Output

Enforce exact response formats using schemas

Multi-turn Conversation

Maintain context across conversations