Matilda
Contact
Agent SDK · Running agents

Agent.

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

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

TypeScript
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

Fieldtypedescription
namestringAgent name. Must be non-empty. Required.
instructionsAgentInstructionsStatic string or dynamic function (see below).
contextstringAdditional context appended to instructions under a Context: header.
purposeAgentPurposeControls the default responseMode and how the server routes the request. Defaults to 'code'.
responseModeChatResponseModeOverride the response mode. If omitted, derived from purpose.
metadataRecord<string, unknown>Custom data available to dynamic instructions. Frozen on construction. Defaults to {}.

AgentPurpose

TypeScript
type AgentPurpose = 'code' | 'analysis' | 'general';
PurposeresponseMode default
'code''auto'
'analysis''deep'
'general''auto'

Dynamic instructions

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

TypeScript
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

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

AgentRunContext

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

TypeScript
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

Fieldtypedescription
promptstringThe user's message. Required.
purposeAgentPurposeFallback purpose if agent doesn't specify one.
agentAgent | AgentOptionsOptional agent to use. Defaults to a generic agent.
instructionsAgentInstructionsOverride the agent's instructions.
contextstringOverride the agent's context.
metadataRecord<string, unknown>Merge with agent's metadata.
conversationIdstringAssociate with a conversation thread.
fileIdsstring[]File IDs to attach.
clientToolsClientTool[]Client tools to advertise.
responseModeChatResponseModeOverride response mode.

Returns Promise<ChatRequest>.