Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

3.1 KB
Raw Blame

title: SDK description: Create agents and Sessions from your own TypeScript program with @adelie/core.

@adelie/core is the same engine the CLI and the server run inside, and it embeds directly into your own program. On this page you install the SDK, make a model available to it, and run a first program that creates an agent, starts a Session and prints the model's replies.

Before you begin

  • Node.js >= 24.
  • An API key for one model provider, unless a model is already configured on this machine.

Install the SDK

In your project directory, install the package:

npm install @adelie/core

Configure a model

The SDK reads the same data root as the desktop app and the CLI, ~/.adelie/data. A model configured in the desktop app or the CLI is immediately usable, so there is nothing to configure twice.

If this machine has no model configured yet, the shortest path is to install the CLI and configure one there:

npm install -g @adelie/cli
penguin config model add --provider deepseek --model-id deepseek-flash --api-key sk-... --set-default

Replace sk-... with your API key. The CLI writes the model to the data root, and the SDK can use it right away.

You can also keep credentials off disk entirely. When a model entry has no inline api_key, AgentHub (the LLM gateway library) reads environment variables such as DEEPSEEK_API_KEY, ANTHROPIC_API_KEY, OPENAI_API_KEY and GEMINI_API_KEY. A .env file in the working directory is loaded automatically.

Run your first program

Save this program in your project and run it:

import { createAgent, isCompleteModelMessage, userText } from "@adelie/core";

const agent = await createAgent({ agentId: "default_agent" });
const session = await agent.createSession({ workspaceDir: process.cwd() });

for await (const output of session.run([userText("Create hello.txt containing hi")], {
  approve: async () => "allow",
})) {
  if (isCompleteModelMessage(output) && output.payload.type === "text") {
    console.log(output.payload.text);
  }
}

The program asks the agent to create hello.txt, using the current directory as the Session's Workspace, and prints each complete text reply from the model.

How the program works

  • createAgent loads an agent's configuration by id: its prompts, tools and runtime parameters. default_agent is the agent seeded when the data root is initialized.
  • session.run() returns an async iterator that yields OmniMessages one by one. The guard in the loop picks out complete model text messages; tool calls, thinking blocks and everything else arrive on the same stream.
  • approve is the approval callback, and returning "allow" permits everything. Tools & Approval describes how the four approval modes map onto tools.

Next steps