> For the complete documentation index, see [llms.txt](https://docs.ainu.pro/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ainu.pro/core-concepts/agents.md).

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ainu.pro/core-concepts/agents.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.