Agent authoring SDK

Use @eigenpal/automations to define what an agent does in your organization’s Git repository. Start with a normal agent, then add tools, reusable resources and evaluations. Opt into a filesystem sandbox when the task needs files or shell scripts.

Choose the right package

@eigenpal/automations defines agents. Import createAgent, createTool, resource factories and evaluation helpers in your Git source. You do not need an API key to construct a definition or check its types. This package does not start runs.
@eigenpal/sdk calls the API. Import EigenpalClient in your application to start agents and workflows, inspect runs, upload files and manage datasets. Authenticate the client with an API key.

You can use both: author agents/invoice-reviewer/agent.ts with the authoring SDK, release it, then call client.run('agents.invoice-reviewer', input) with the API client.

Install

In your organization’s source repository:

npm install @eigenpal/automations zod
npm install --save-dev typescript

The published ESM package requires Node.js 22 or later. Use Zod 4 schemas for inferred tool arguments and agent outputs. The CLI can scaffold the project with eigenpal agents init invoice-reviewer --template agent.

Define your first agent

Create agents/invoice-reviewer/agent.ts:

agent.ts

import { createAgent, createTool, maxCredits, maxTimeMs, maxTurns } from '@eigenpal/automations';
import { z } from 'zod';

export default createAgent({
  name: 'Invoice reviewer',
  instructions: 'Use calculateTotal to check the invoice. Return the total and a short summary.',
  inputSchema: z.object({ subtotal: z.number().nonnegative() }),
  outputSchema: z.strictObject({ total: z.number(), summary: z.string() }),
  tools: {
    calculateTotal: createTool({
      description: 'Calculate the total including 20% tax.',
      inputSchema: z.object({ subtotal: z.number().nonnegative() }),
      outputSchema: z.strictObject({ total: z.number() }),
      execute: ({ subtotal }) => ({ total: Math.round(subtotal * 1.2 * 100) / 100 }),
    }),
  },
  guards: [maxTurns(10), maxTimeMs(60_000), maxCredits(100)],
  triggers: { api: true },
});

This agent needs no filesystem sandbox. The model can invoke calculateTotal, and EigenPal validates its final output. With subtotal: 100, the calculation tool returns { total: 120 }; the model supplies the summary. name is a display name. The folder agents/invoice-reviewer establishes the agent’s identity. Rename the display name without changing its run target.

Check and release

Use the example project’s strict TypeScript configuration or the CLI scaffold to enable .ts imports and check types with tsc --noEmit. Then validate against your deployment and release from the agent directory:

cd agents/invoice-reviewer
eigenpal agents validate
eigenpal agents save
eigenpal agents release patch
eigenpal agents sync agents.invoice-reviewer

You need CLI authentication for these deployment operations. validate captures source and resources and checks them with the deployment’s isolated compiler. save validates, commits and pushes. release creates an immutable source tag; sync selects the released version for execution.

Run from your application

Install @eigenpal/sdk in the calling application and use its API client:

import { EigenpalClient } from '@eigenpal/sdk';

const client = new EigenpalClient({ apiKey: process.env.EIGENPAL_API_KEY });
const result = await client.run(
  'agents.invoice-reviewer',
  { subtotal: 100 },
  { waitForCompletion: 60 }
);

if (result.finished) console.log(result.output);

You can also run the agent from Studio or with eigenpal run agents.invoice-reviewer --input-json '{"subtotal":100}'. See API client runs for polling and run inspection.

How source becomes a run

Your TypeScript stays in Git. EigenPal captures the selected commit, validates the definition and converts schemas/configuration into runtime data. It retains custom callback code in a separate executable bundle. This lets the platform validate inputs and outputs without executing arbitrary source on the application host. A run pins its source, resource files and compiled definition. Historical runs and supported human-review resumes keep that snapshot instead of loading your newest edits. Compilation does not execute tools on sample data or call an LLM judge. The low-level compileAgent export from @eigenpal/automations/compiler accepts an already loaded definition and returns JSON data. It does not capture directory resources, read Git, publish a release or execute an agent. Use CLI validation for a complete source package, and local typechecking for editor feedback.

Continue building

Agents and tools

Schemas, instructions, guards, triggers and typed custom tools.

Filesystem access

Repository workspaces, empty workspaces and sandbox packages.

Shared resources

Define knowledge, rules, templates and directory skills.

Evaluations

Typed scores, LLM judges and a pass decision.

Read Callback capabilities before writing tools or evaluators that depend on a runtime API. Explore the open-source SDK and complete IDE examples for all authoring modes.

Overview

Agent authoring

TypeScript API client

Python API client

Choose the right package

Install

Define your first agent

Check and release

Run from your application

How source becomes a run

Continue building

Agents and tools

Filesystem access

Shared resources

Evaluations

​Choose the right package

​Install

​Define your first agent

​Check and release

​Run from your application

​How source becomes a run

​Continue building

Agents and tools

Filesystem access

Shared resources

Evaluations

Choose the right package

Install

Define your first agent

Check and release

Run from your application

How source becomes a run

Continue building