> ## Documentation Index
> Fetch the complete documentation index at: https://docs.eigenpal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent authoring SDK

> Define Git-backed EigenPal agents in TypeScript with typed tools, shared resources, evaluations, and optional filesystem access using @eigenpal/automations.

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`](/sdks/typescript) 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:

```bash theme={null}
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`:

```ts agent.ts theme={null}
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](https://github.com/eigenpal/automations/tree/main/examples/agents)
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:

```bash theme={null}
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:

```ts theme={null}
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](/sdks/typescript/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](/sdks/automations/agents)**
>
> Schemas, instructions, guards, triggers and typed custom tools.

> **[Filesystem access](/sdks/automations/filesystem)**
>
> Repository workspaces, empty workspaces and sandbox packages.

> **[Shared resources](/sdks/automations/resources)**
>
> Define knowledge, rules, templates and directory skills.

> **[Evaluations](/sdks/automations/evaluations)**
>
> Typed scores, LLM judges and a pass decision.

Read [Callback capabilities](/sdks/automations/callbacks) before writing tools or
evaluators that depend on a runtime API. Explore the
[open-source SDK](https://github.com/eigenpal/automations) and
[complete IDE examples](https://github.com/eigenpal/automations/tree/main/examples/agents)
for all authoring modes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.