Agents

Agents are the core abstraction in AINU. They act as orchestrators for AI tasks, managing interactions between Providers, Tools, and other components.

Agents are designed to be lightweight, extensible, and unopinionated, allowing developers to define their workflows with maximum flexibility.

---

Agent Constructor

The Agent class is the primary way to create an agent in AINU. The constructor accepts an AgentOptions object, which allows you to configure the agent's behavior, connect it to a provider, and optionally pass tools.

Constructor Signature

constructor(options: AgentOptions)

The AgentOptions object is used to define the agent's configuration, including its provider, tools, and settings. Below, we’ll break down the AgentOptions type and its parameters.

---

AgentOptions

The AgentOptions type defines the parameters that can be passed to the Agent constructor. These include:

Available Parameters

Parameter	Type	Description
provider	Provider	Required. The provider that connects the agent to an AI model.
tools	Tool[]	Optional. An array of tools to extend the agent's functionality.
settings	AgentSettings	Optional. Configuration settings that define the agent's behavior.
clients	MCP[]	Optional. An array of MCP (Model Context Protocol) instances for external integrations.

Example

const agent = new Agent({
  provider: new Anthropic({ apiKey: "your-api-key" }),
  tools: [tool1, tool2], // Optional
  settings: {
    system: "You are a helpful assistant.",
    temperature: 0.7,
  },
});

---

AgentSettings

The AgentSettings type defines the configuration options for customizing the agent's behavior. These settings allow you to control how the agent interacts with the provider and generates responses.

Available Settings

Setting	Type	Default Value	Description
system	string	""	A system message that defines the agent's behavior or personality.
temperature	number	0.7	Controls the randomness of the agent's responses (0 = deterministic).
maxTokens	number	2048	The maximum number of tokens the agent can generate in a response.
topP	number	1	Controls nucleus sampling (higher values allow more diverse responses).
frequencyPenalty	number	0	Penalizes repeated tokens in the output.
presencePenalty	number	0	Encourages the agent to introduce new topics in its responses.

Example

const settings: AgentSettings = {
  system: "You are a friendly and knowledgeable assistant.",
  temperature: 0.5,
  maxTokens: 1500,
  topP: 0.9,
  frequencyPenalty: 0.2,
  presencePenalty: 0.1,
};

---

Example: Constructing an Agent

Here’s a complete example of constructing an agent with a provider, tools, and custom settings:

import { Agent, Anthropic, Tool } from "@ainulabs/ainu";
import { z } from "zod";

// Define a provider
const provider = new Anthropic({
  apiKey: "your-api-key", // Replace with your actual API key
});

// Define a tool (optional)
const exampleTool = new Tool("exampleTool", {
  description: "An example tool for demonstration purposes.",
  parameters: z.object({
    input: z.string(),
  }),
  handler: ({ input }) => `You entered: ${input}`,
});

// Define agent settings
const settings = {
  system: "You are a helpful assistant.",
  temperature: 0.7,
  maxTokens: 1000,
};

// Create the agent
const agent = new Agent({
  provider,
  tools: [exampleTool], // Optional
  settings,
});

// Use the agent
(async () => {
  const response = await agent.generateText({
    prompt: "What is the capital of France?",
  });

  console.log(response.data?.text); // Output: "The capital of France is Paris."
})();

---

Summary

The Agent class is the backbone of the AINU framework, enabling you to:

• Connect to AI providers.

• Customize behavior using AgentSettings.

• Optionally extend functionality with tools.

By understanding the Agent constructor, AgentOptions, and AgentSettings, you can create agents tailored to your specific use case. Continue to the Providers section to learn more about connecting agents to AI models.