> ## Documentation Index
> Fetch the complete documentation index at: https://docs.magmadeploy.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

```typescript myAgent.ts theme={null}
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.

<Tip>
  Magma handles the differences between providers for you, so your types don't need to change at all!
</Tip>

```typescript myAgent.ts theme={null}
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({
            provider: 'openai',
            model: 'gpt-4.1',
        });
    }

}
```

***

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

```typescript myAgent.ts theme={null}
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(): MagmaSystemMessageType[] {
        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.

```typescript myAgent.ts theme={null}
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.

```typescript myAgent.ts theme={null}
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**](/magma-framework/tools): Functions your agent can call to read/write external data, perform tasks, etc.
* [**Middleware**](/magma-framework/middleware): Add functions that run before and after your agent's main function and tool executions
* [**Hooks**](/magma-framework/hooks): Exposing webooks into your agent, allowing your agent to respond to events from external systems
* [**Jobs**](/magma-framework/jobs): Run tasks on a schedule on your agent

***

## Deployment

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](/magma-framework/basics#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.

<Tip>
  You can easily get started with a proper project configuration by using the `magma init` command, as covered in the [Quickstart](/get-started/quickstart) section.
</Tip>