The Basics

Magma is a TypeScript framework that makes building AI agents simple and intuitive. No complex chains or confusing abstractions - just write the logic you want your agent to have in standard Class form.

​

Key Features

• Simple: Build production-ready agents in minutes
• Flexible: Use any major AI provider (OpenAI, Anthropic, Google, Groq)
• Powerful: Add tools, middleware, jobs, and hooks as needed
• Observable: Full visibility into your agent’s behavior

​

Your First Agent

Creating a basic agent is as simple as:

import { MagmaAgent } from "@pompeii-labs/magma";

export default class MyAgent extends MagmaAgent {
    // We will build on this in the upcoming sections,
    // But this is actually a functional, basic conversational agent!
}

​

Choosing a Provider

You can choose a provider in the constructor of your agent. You can also change the provider config at any time using the setProviderConfig method. Just make sure you have your environment variables set up for the providers you choose.

import { MagmaAgent } from "@pompeii-labs/magma";

export default class MyAgent extends MagmaAgent {
    
    // The super method is required if you add a constructor to your agent
    // It can be empty, or you can pass in a provider config
    constructor() {
        super({
            providerConfig: {
                provider: 'anthropic',
                model: 'claude-3-5-sonnet-20240620',
            },
        });
    }

}

​

Using System Prompts

System prompts are a good way to give your agent a bit of context on how to behave. You can use the getSystemPrompts method to define the system prompts for your agent.

import { MagmaAgent } from "@pompeii-labs/magma";

export default class MyAgent extends MagmaAgent {

    // System prompts are defined by a function
    // so we can define them dynamically
    getSystemPrompts(): MagmaSystemMessage[] {
        return [
            {
                role: 'system',
                content: `You talk like a pirate`,
            },
        ];
    }

}

​

Managing State

Because Magma Agents are class-based, you can manage state in your agent by simply adding properties to the class. These properties are available to all methods in your agent.

import { MagmaAgent } from "@pompeii-labs/magma";

export default class MyAgent extends MagmaAgent {

    // You can add any custom properties you want to your agent
    myCustomState: number = 3;

    // We can use the state of the agent however we want
    // like to conditionally modify a system prompt
    getSystemPrompts(): MagmaSystemMessage[] {
        return [
            {
                role: 'system',
                content: `You talk like a pirate`,
            },
            {
                role: 'system',
                content: `${
                    this.myCustomState > 0
                    ? 'The value is greater than 0'
                    : 'The value is less than or equal to 0'
                }`,
            }
        ];
    }

}

​

The Setup Method

Sometimes you’ll need to initialize your agent in a way that isn’t possible in the constructor. The setup method is called when the agent is instantiated, and it can be asynchronous. It is a good place to initialize values for your agent, fetch starting data, etc.

import { MagmaAgent } from "@pompeii-labs/magma";

export default class MyAgent extends MagmaAgent {

    myCustomState: number = 0;

    // You can fetch data from an API
    // or do any other asynchronous operations
    async setup() {
        const data = await this.fetchData();

        this.myCustomState = data;
    }

}

​

Agent Structure

Magma uses decorators to make the development experience as smooth as possible, and to keep the code clean and readable.

There are four types of decorators you can use:

• Tools: Functions your agent can call to read/write external data, perform tasks, etc.
• Middleware: Add functions that run before and after your agent’s main function and tool executions
• Hooks: Exposing webooks into your agent, allowing your agent to respond to events from external systems
• Jobs: Run tasks on a schedule on your agent

A big part of the magic of Magma is the ability to deploy your agent to the cloud and have it run in a completely scalable and managed environment.

To do this, your project needs to have a few things:

• A .ts file with a default export that is a class that extends MagmaAgent (as shown in the Your First Agent section)
• A valid package.json file with the magma framework installed, and your agent’s entrypoint in the main field. Example: "main": "myAgent.ts"
• .env file with the necessary environment variables for your agent, including your AI provider’s API key, etc.