DaydreamsAI

A Daydreams agent is composed of several core building blocks that work in a continuous loop:

1. Inputs: Listen for external events (e.g., a Discord message) and trigger the agent.
2. Contexts: Provide the persistent memory and state (e.g., chat history) that the agent uses to maintain continuity.
3. Actions: Perform specific tasks or fetch data (e.g., getting weather) based on the agent's reasoning.
4. Outputs: Send information or perform actions back to the external world (e.g., sending a Discord message).

These are all tied together using createDreams, which accepts a model, contexts, inputs, outputs, and actions.

import { createDreams, context, action, input, output } from "@daydreamsai/core";
import { openai } from "@ai-sdk/openai";
import * as z from "zod";

// 1. INPUT
const discordInput = input({
  type: "discord:message",
  schema: z.object({ content: z.string(), userId: z.string(), channelId: z.string() }),
  subscribe: (send, agent) => {
    // ... subscription logic
    return () => discord.removeAllListeners("messageCreate");
  },
});

// 2. ACTION
const getWeather = action({
  name: "get-weather",
  description: "Gets current weather for a city",
  schema: z.object({ city: z.string().describe("City name") }),
  handler: async ({ city }) => {
    // ... logic
    return { temperature: 72, condition: "sunny", city };
  },
});

// 3. OUTPUT
const discordOutput = output({
  type: "discord:message",
  description: "Sends a message to Discord",
  schema: z.string(),
  attributes: z.object({ channelId: z.string() }),
  handler: async (message, ctx) => {
    const { channelId } = ctx.outputRef.params;
    await discord.send(channelId, message);
    return { sent: true };
  },
});

// 4. CONTEXT
const chatContext = context({
  type: "chat",
  schema: z.object({ userId: z.string() }),
  create: () => ({ messages: [] }),
});

// 5. AGENT
const agent = createDreams({
  model: openai("gpt-4o"),
  contexts: [chatContext],
  inputs: [discordInput],
  outputs: [discordOutput],
  actions: [getWeather],
});

In Daydreams, the architecture is split between Services (Infrastructure) and Extensions (Features). Understanding this distinction is critical for designing scalable agent capabilities.

Services (The "How to Connect")

Services manage the underlying infrastructure. They are responsible for managing connections to external systems like databases or APIs and handling their lifecycle (startup/shutdown).

• Purpose: Manage infrastructure and shared utilities.
• Contents: API clients, database connections, and environment-based configuration.
• Lifecycle: register() $\rightarrow$ boot().
• Usage: Typically used by multiple extensions to avoid duplicating connection logic.

Extensions (The "What Agent Can Do")

Extensions bundle complete, cohesive feature sets for a specific domain. They represent the actual capabilities an agent possesses.

• Purpose: Provide complete features and platform support (e.g., Discord, Twitter).
• Contents: Actions, contexts, inputs, and outputs.
• Lifecycle: install() when added to an agent.
• Usage: Agents consume extensions directly to gain functionality.

Comparison Summary

The Composed Contexts pattern allows contexts to work together using the .use() method. This is the most powerful pattern, enabling you to build modular, scalable systems where a primary context can dynamically include other contexts based on the current state or arguments.

Key capabilities:

• Share common functionality: Include analytics, auth, or logging contexts in every interaction.
• Conditional features: Use .use() to include specific contexts (like a premiumContext) only when certain conditions are met (e.g., state.args.customerTier === 'vip').
• Modular design: Build complex behaviors by composing small, specialized contexts.

import { context, action } from "@daydreamsai/core";
import * as z from "zod";

// ... (analyticsContext, profileContext, premiumContext definitions) ...

// Smart chat context that composes all the above
const smartChatContext = context({
  type: "chat",
  schema: z.object({ userId: z.string() }),
  create: () => ({ messages: [] }),
})
  .use((state) => [
    // Always include analytics for every user
    { context: analyticsContext, args: { userId: state.args.userId } },
    
    // Always include profile  
    { context: profileContext, args: { userId: state.args.userId } },
    
    // Include premium features only for premium users
    state.memory.userTier === "premium" 
      ? { context: premiumContext, args: { userId: state.args.userId } }
      : null,
  ].filter(Boolean));

Custom Keys

By default, context instances use a type:key format. You can override this by providing a key function in the context definition that generates a unique ID based on the args.

Dynamic Instructions

Instead of a static string, instructions can be a function that receives the current state (including args and memory), allowing the LLM's persona or constraints to change based on the context state.

// Custom Key
const customContext = context({
  type: "user-session",
  schema: z.object({ userId: z.string(), sessionType: z.string() }),
  key: (args) => `${args.userId}-${args.sessionType}`,
  create: () => ({ data: {} })
});

// Dynamic Instructions
const adaptiveContext = context({
  type: "adaptive",
  schema: z.object({ userTier: z.string() }),
  create: () => ({ features: [] }),
  instructions: (state) => {
    return state.args.userTier === "premium" 
      ? "You are a premium assistant." 
      : "You are a standard assistant.";
  }
});