@aster/agent

Canonical source: packages/agent/README.md · Edit the source file

The primary authoring SDK for building Aster agents. It provides Agent.make() for agent definitions, tool() for typed tool authoring, the full runtime type surface, and low-level turn helpers.

Install

npm install @aster/agent

Use the root package for agent definitions, tool helpers, runtime types, and convenience imports. Use @aster/agent/turn when you want the dedicated low-level turn-processing entrypoint.

Quick start

import { Agent } from "@aster/agent"

export default Agent.make({
  id: "my-agent",
  name: "My Agent",
  systemPrompt: "You are a helpful assistant.",
  async run(input, runtime) {
    runtime.log(`Running in @space ${runtime.context.spaceSlug}`)
    return { result: `You said: ${input.prompt}` }
  },
})

Defining tools

Use tool() to create strongly typed tools with schema validation and automatic input coercion.

import { tool } from "@aster/agent"

const echo = tool({
  name: "echo",
  description: "Echo the input text",
  schema: tool.schema.Object({
    text: tool.schema.String({ minLength: 1 }),
    count: tool.schema.Number(),
    verbose: tool.schema.Optional(tool.schema.Boolean({ default: false })),
  }),
  async execute(args) {
    // args is typed as { text: string; count: number; verbose: boolean }
    return args.text.repeat(args.count)
  },
})

tool.schema exposes the underlying schema builder used by the SDK. Use it to define Object, String, Number, Boolean, Array, Optional, and similar shapes. Inputs are parsed before execute() runs, so numeric and boolean fields can be safely coerced from string inputs.

Register tools on your agent definition:

export default Agent.make({
  id: "my-agent",
  name: "My Agent",
  tools: [echo],
  async run(input, runtime) { /* ... */ },
})

Validation helpers

• Agent.make(input) — marks an object as a valid agent definition.
• isAgentDefinition(value) — type guard that checks for the definition marker, id, name, and run function.

Entrypoints

Entrypoint	Contents
@aster/agent	Agent.make, Agent.is, isAgentDefinition, tool, marker constants, turn helpers, and the full runtime type surface.
@aster/agent/tool	tool factory function with tool.schema (TypeBox Type namespace).
@aster/agent/runtime	Agent.make, Agent.is, Agent.turn, and isAgentDefinition.
@aster/agent/turn	Agent.turn.

Related packages

• @aster/agent provides the standalone tool-package authoring surface.
• capabilities/plugins/deep-research, capabilities/plugins/excel, capabilities/plugins/jujutsu, and capabilities/plugins/powerpoint contain example extension-owned agents that use this SDK.