AXAR AI Framework

To create a basic agent, extend the Agent class and use decorators to define the model and system prompt. The Agent class is generic, taking the input type and output type as parameters (e.g., Agent<string, string>).

import { model, systemPrompt, Agent } from '@axarai/axar';

// Define the agent.
@model('openai:gpt-4o-mini')
@systemPrompt('Be concise, reply with one sentence')
export class SimpleAgent extends Agent<string, string> {}

// Run the agent.
async function main() {
  const response = await new SimpleAgent().run(
    'Where does "hello world" come from?',
  );
  console.log(response);
}

main().catch(console.error);

To run the provided examples in the AXAR repository, ensure you have Node.js (v18+) and an OpenAI API key. Follow these steps to install dependencies, build the project, and execute a specific example file using ts-node.

# 1. Install dependencies
npm install

# 2. Build the project
npm run build

# 3. Set your OpenAI API key
export OPENAI_API_KEY='your_api_key'

# 4. Run a specific example
npx ts-node examples/simple-agent.ts

Before running the examples, ensure your environment meets the following requirements:

• Node.js: version 18 or higher
• npm: included with Node.js
• OpenAI API key: required for agent functionality

When defining the schema for an agent's inputs or outputs, use the InputOutputType type. This allows you to specify the expected data structure using several methods:

• Zod Schemas: Use z.object({...}) for complex validation.
• Schema Constructors: Use custom schema constructors.
• Primitives: Use standard JavaScript constructors like String, Number, or Boolean for simple types.

You can provide metadata for individual properties within a schema using PropertyOptions. This is used to describe specific fields.

Available options:

• description: A human-readable description of the property.
• example: An example value for the property.

const propertyOptions: PropertyOptions = {
  description: 'The primary email address of the user',
  example: 'dev@axar.ai'
};

When defining a schema, you can provide metadata for the entire schema using SchemaOptions. This is typically used with schema-level decorators to provide context for documentation or examples.

Available options:

• description: A human-readable description of the schema.
• example: An example value representing valid schema data.
• deprecated: A boolean indicating if the schema is deprecated.

const options: SchemaOptions = {
  description: 'A schema representing a user profile',
  example: { id: '123', email: 'user@example.com' },
  deprecated: false
};

The following decorators are used to configure agent behavior and data structures:

Agent Configuration:

• @model(modelName: string): Specifies the LLM model to use (e.g., 'openai:gpt-4o-mini').
• @systemPrompt(prompt?: string | (() => Promise<string>)): Sets the system-level instructions. If a method is decorated with this, it provides dynamic context.
• @output(schemaClass: any): Defines the expected structured output format for the agent.
• @tool(description: string): Marks a class method as a tool available to the agent.

Schema and Property Annotations:

• @schema(): Marks a class as a structured data schema.
• @property(description: string): Describes a field within a schema.
• @optional(): Marks a property as optional.
• @min(value: number) / @max(value: number): Defines numeric constraints for schema properties.

The @systemPrompt decorator allows you to provide instructions to the LLM. It can be used in two ways:

1. Class-level (Static): Pass a string to the decorator on the class. This prompt is prepended to the list of system prompts for the class.
2. Method-level (Dynamic): Apply the decorator to a method without arguments. The method must return a string or a Promise<string>. This allows you to generate prompts dynamically based on the agent's state.

// Static class-level prompt
@systemPrompt("Static system prompt.")
class ExampleClass {
  // Class implementation
}

// Dynamic method-level prompt
class ExampleClass {
  @systemPrompt
  async dynamicPromptMethod(): Promise<string> {
    return "Dynamic system prompt from the method.";
  }
}