Agents & sessions

This page describes how we think about agents, sessions, and tools. The code samples show a target shape for a future SDK, not a current implementation.

Agents

An agent is defined once and reused across many sessions. A rough interface might look like this:

// This is design, not a real client.
const client = new EunoiaClient({ apiKey: "YOUR_KEY" });

const researchAgent = await client.agents.create({
  id: "lab-research-assistant",
  model: "eunoia-v1",
  role: "research-assistant",
  tools: ["browser", "python"],
  memory: {
    mode: "neuroplastic",
    retention: "long",
  },
  safety: {
    maxRisk: "medium",
    allowTools: ["browser", "python"],
  },
});

The important part isn't the exact function names. It's that the structure is explicit:

• which model is used,
• which tools it can call,
• how memory behaves,
• what safety rules apply.

Sessions

A session is created when a user (or another system) starts interacting with an agent:

const session = await client.sessions.create({
  agentId: "lab-research-assistant",
  userId: "user-123",
  context: {
    projectId: "experiment-42",
  },
});

All subsequent messages and tool calls live inside this session. That means we can:

• log behaviour against a single ID,
• attach Velin's emotional signals,
• review and debug a full interaction, not just a line of text.

Messages and tools

Within a session, messages might look like:

const turn = await session.chat.send({
  message: "Summarise these three papers and propose one experiment.",
  attachments: [
    { type: "pdf", url: "https://example.com/paper1.pdf" },
    { type: "pdf", url: "https://example.com/paper2.pdf" },
  ],
});

Behind the scenes, the agent chooses when to call tools, when to ask for clarification, and how to manage context. The API surface makes those choices auditable.

Why not just completions?

Simple completion-style endpoints are easy to expose but painful to use for anything serious. They hide:

• which model version was used,
• how tools were called,
• what the safety rules were at the time.

Our internal work is built on agents and sessions, so when we eventually expose external APIs, we plan to build around the same ideas.