# 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

```typescript
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

```typescript
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

```typescript
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:

```typescript
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.