# Agent

> Configure agents with instructions, tools, compaction, and resumable state.

Source: https://maincode.com/docs/agent-sdk-agent
Section: Agent SDK · Matilda documentation

---

An `Agent` is a named, immutable persona with optional instructions, context, purpose, and metadata. You can pass a plain `AgentOptions` object anywhere an `Agent` is accepted — the SDK normalises it.

## `Agent` class

```ts
import { Agent } from '@maincode-ai/matilda-agent-sdk';

const reviewer = new Agent({
  name: 'code-reviewer',
  purpose: 'code',
  instructions: 'Review code for correctness, security, and readability.',
  context: 'Project: matilda-core\nLanguage: TypeScript',
  metadata: { team: 'platform' },
});
```

The `Agent` class is immutable and reusable — construct once, run many times.

### `AgentOptions`

| Field | Type | Description |
| - | - | - |
| `name` | `string` | Agent name. Must be non-empty. Required. |
| `instructions` | `AgentInstructions` | Static string or dynamic function (see below). |
| `context` | `string` | Additional context appended to instructions under a Context: header. |
| `purpose` | `AgentPurpose` | Controls the default responseMode and how the server routes the request. Defaults to 'code'. |
| `responseMode` | `ChatResponseMode` | Override the response mode. If omitted, derived from purpose. |
| `metadata` | `Record<string, unknown>` | Custom data available to dynamic instructions. Frozen on construction. Defaults to {}. |

## `AgentPurpose`

```ts
type AgentPurpose = 'code' | 'analysis' | 'general';
```

| Purpose | `responseMode` default |
| - | - |
| `'code'` | `'auto'` |
| `'analysis'` | `'deep'` |
| `'general'` | `'auto'` |

## Dynamic instructions

Instructions can be a function that receives runtime context, letting you customise behaviour per-call:

```ts
const agent = new Agent({
  name: 'code-reviewer',
  purpose: 'code',
  instructions: ({ input, metadata }) => {
    const lang = (metadata.language as string) ?? 'auto-detect';
    const strictness = (metadata.strictness as string) ?? 'normal';
    return [
      'Review the following code.',
      `Language: ${lang}`,
      `Strictness: ${strictness}`,
      'Focus on: correctness, security, and readability.',
    ].join('\n');
  },
});

const result = await run(agent, 'function add(a, b) { return a + b }', {
  metadata: { language: 'JavaScript', strictness: 'strict' },
});
```

### `AgentInstructions`

```ts
type AgentInstructions =
  | string
  | ((context: AgentRunContext) => string | Promise<string>);
```

### `AgentRunContext`

```ts
interface AgentRunContext {
  agentName: string;
  input: string;
  purpose: AgentPurpose;
  metadata: Readonly<Record<string, unknown>>;
}
```

## How agent messages are constructed

The SDK packs the agent's identity, instructions, context, and the user's prompt into a single user message with labelled sections:

```text
Agent: code-reviewer

Instructions:
Review the following code.
Language: JavaScript
...

Context:
Project: matilda-core

Code task:
function add(a, b) { return a + b }
```

## `buildAgentChatRequest(opts)`

Low-level builder that constructs the `ChatRequest` object without executing it. Useful for testing, logging, or custom execution paths.

```ts
import { buildAgentChatRequest } from '@maincode-ai/matilda-agent-sdk';

const request = await buildAgentChatRequest({
  prompt: 'Fix the failing test',
  agent: { name: 'helper', purpose: 'code' },
  instructions: 'Be specific.',
  context: 'Project root: /repo',
  conversationId: 'conv-1',
  fileIds: ['file-1'],
  clientTools: [{ name: 'read_file', description: 'Read a file', parameters: { type: 'object' } }],
});

// request.messages, request.responseMode, request.conversation_id, etc.
```

### `BuildAgentChatRequestOptions`

| Field | Type | Description |
| - | - | - |
| `prompt` | `string` | The user's message. Required. |
| `purpose` | `AgentPurpose` | Fallback purpose if agent doesn't specify one. |
| `agent` | `Agent \| AgentOptions` | Optional agent to use. Defaults to a generic agent. |
| `instructions` | `AgentInstructions` | Override the agent's instructions. |
| `context` | `string` | Override the agent's context. |
| `metadata` | `Record<string, unknown>` | Merge with agent's metadata. |
| `conversationId` | `string` | Associate with a conversation thread. |
| `fileIds` | `string[]` | File IDs to attach. |
| `clientTools` | `ClientTool[]` | Client tools to advertise. |
| `responseMode` | `ChatResponseMode` | Override response mode. |

Returns `Promise<ChatRequest>`.