> ## 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.

# Define agents and tools

> Configure EigenPal agent instructions, schemas, triggers and execution guards, and create synchronous tools with inferred arguments and validated results.

Define an agent with `createAgent` from `@eigenpal/automations`. You supply its
instructions, schemas and capabilities; EigenPal uses that definition when you
start a run. The [quickstart](/sdks/automations) includes a complete invoice agent.

## createAgent options

Only `name` is required when you construct the definition. Execution also requires
nonblank instructions, supplied inline or in `AGENT.md`.

* **`name: string`**: required display name. The Git folder determines identity.
* **`description?: string`**: description for discovery.
* **`instructions?: string`**: nonblank instructions, up to 128 KiB. Inline text
  overrides the package-local `AGENT.md`; EigenPal does not concatenate them. If
  omitted, EigenPal reads that file from the run's pinned source commit.
* **`model?: string`**: configured organization model identifier. Omit it to use
  the platform's configured selection.
* **`inputSchema?`**: object schema for run input.
* **`outputSchema?`**: object schema for the final answer and inferred evaluator types.
* **`tools?`**: map of model-facing names to `createTool` definitions. Up to 16
  custom tools. Built-in names such as `read`, `bash`, `finish` and `resource_read`
  are reserved.
* **`resources?`**: map of imported knowledge, rule and template definitions.
  Keys become aliases in resource tools. See [Shared resources](/sdks/automations/resources).
* **`guards?`**: array of execution limits, described below. At most 32 entries.
* **`triggers?`**: API and email trigger configuration, described below.

Filesystem access defaults to off. Use
[`.withFilesystem()`](/sdks/automations/filesystem) to opt in. Evaluators belong on
the [evaluation chain](/sdks/automations/evaluations), not in `createAgent` options.

## Schema types and validation

Prefer Zod 4 for inference. Use `z.strictObject` when extra properties should fail
validation; ordinary `z.object` compiles using its input schema behavior.

You can also supply a raw JSON Schema object. Raw schemas and absent schemas infer
`unknown`, so callback code must narrow values itself. Schema roots must represent
objects, or be exactly `{}` to declare no constraints.

Zod describes the JSON Schema contract; EigenPal does not run Zod parsing effects.
Transforms, coercion, defaults, catches, custom refinements, overwrites and `.trim()`
fail compilation. Use representable checks such as `.min()` and `.nonnegative()`.

Export inferred types for application code:

```ts theme={null}
import type { InferInput, InferOutput } from '@eigenpal/automations';
import invoice from './agent.ts';

type InvoiceInput = InferInput<typeof invoice>;
type InvoiceOutput = InferOutput<typeof invoice>;
```

These are authoring types. The API client does not infer a remote agent's output
schema from a string run target.

## createTool options

```ts tools.ts theme={null}
import { createTool } from '@eigenpal/automations';
import { z } from 'zod';

export const calculateTotal = createTool({
  description: 'Calculate invoice tax and total.',
  inputSchema: z.object({ subtotal: z.number().nonnegative(), rate: z.number().nonnegative() }),
  outputSchema: z.strictObject({ tax: z.number(), total: z.number() }),
  execute: ({ subtotal, rate }) => {
    const tax = Math.round(subtotal * rate * 100) / 100;
    return { tax, total: subtotal + tax };
  },
});
```

All four properties are required:

* `description`: nonblank explanation of when the model should use the tool.
* `inputSchema`: object schema; validates arguments before invocation and infers
  the `execute` parameter.
* `outputSchema`: object schema; validates the returned result and checks its
  TypeScript shape.
* `execute`: synchronous callback returning the result object. Local helpers and
  constants can be bundled. It receives no host filesystem, network or secrets.

Attach the imported tool as `tools: { calculateTotal }` in `createAgent`.
Callbacks use the [same isolated runtime](/sdks/automations/callbacks) in both agent
modes. Sandbox packages do not become tool callback imports.

## Execution guards

Import `maxTurns`, `maxTimeMs` and `maxCredits`, then pass their results in `guards`:

```ts theme={null}
guards: [maxTurns(10), maxTimeMs(60_000), maxCredits(100)];
```

* **`maxTurns(n)`**: maximum model requests, including retries.
* **`maxTimeMs(n)`**: maximum active execution time, including preparation. Time
  parked for human review does not count.
* **`maxCredits(n)`**: maximum model credits. One credit is one cent; sandbox compute
  is billed separately. Use the time guard to bound active sandbox execution.

`maxTurns` and `maxTimeMs` require positive integers; `maxCredits` accepts a positive
finite number. Repeating a guard applies the strictest value. Limits
continue across supported human-review resumes. The platform ceilings are 128
turns, 20 active minutes and 10,000 model credits, subject to tighter deployment
limits. Credit checks use actual usage, never a reservation or a cost estimate.
The last model request may take usage past `maxCredits`; the next request stops.
Account credits work the same way: a positive balance permits work, actual usage
may overdraw it, and no further paid work starts once the balance is exhausted.
Pay-as-you-go subscriptions can continue according to their billing settings.

## Triggers

```ts theme={null}
triggers: {
  api: true,
  email: {
    enabled: true,
    aliases: [{
      address: 'invoices@example.com',
      allowlist: ['accounts@example.com'],
      requireSenderAuth: true,
      replyConfig: { on: 'always' },
      enabled: true,
    }],
  },
}
```

`api` defaults to enabled. Email defaults to disabled when absent. An alias can
be an address string or an object with `address`, optional `enabled`,
`requireSenderAuth`, `replyConfig` and `allowlist`.

Omit `allowlist` to preserve platform ownership; set it to `[]` to deny all senders.
Trigger enablement edits in Studio change the versioned draft and take effect
when you release it. Email alias management keeps its routing-management behavior.
Dynamic TypeScript configuration may require editing source rather than Studio controls.

## Immutable composition

Chaining returns a new definition. You can reuse a base agent or add filesystem
access after its evaluators and pass rule. A completed pass closes further
evaluator/pass registration while keeping `.withFilesystem()` available.

No `.asTool()` or general agent-to-agent callback context is available in this SDK.
Use the API client to start an agent from your application.


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