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

# Sessions

Under the hood, Magma uses `sessions` to handle the context and state of the agent.

`sessions` are an incredibly powerful feature in the Mamga ecosytem because testing and optimizing agents requires accessing the unique instances of your agent. With `sessions`, you can snapshot different states, contexts, and interactions of your agent.

A new session is created when a `hook` is triggered with a new `session id`, or when the agent is accessed via the `agent api` with a new `session id`.

When one of these events is triggered without a `session id`, a new temporary session is created to handle the agent interactions.

## Agent API

The `agent api` is a way to interact with the agent via websocket or http requests.

When using the `agent api`, you can specify a `session id` to interact with a specific session of the agent.

**HTTP Request**

You can specify the `session id` as a field in the body of the request when accessing your agent via the `/chat` route.

```typescript theme={null}
const response = await fetch(`https://api.magmadeploy.com/v1/chat`, {
    method: 'POST',
    headers: {
        'x-api-key': <public-api-key>,
        'Content-Type': 'application/json',
        Accept: 'application/json',
    },
    body: JSON.stringify({
        sessionId, // optional, but required if you'd like to access a specific session
        messages, // required, the messages array to generate a completion for
    })
});
```

**WebSocket Connection**

When using the websocket, you can specify the `session id` using a query parameter.

`wss://api.magmadeploy.com/v1?agent_id=<agent_id>&api_key=<agent_public_api_key>&sessionId=<session_id>`

If you are triggering a connection from a service that does not allow you to add query parameters, you can convert them to key=value path parameters

`wss://api.magmadeploy.com/v1/agentId=<agent_id>/apiKey=<agent_public_api_key>/sessionId=<session_id>`

***

## Hooks

When using hooks, you can specify which session should handle the hook. This is done by specifying where in the hook request the session id is located.

```typescript theme={null}
@hook('user-update', { session: (req: Request) => req.body.userId} )
async updateUser(req: Request, res: Response) {
    const { userId, data } = req.body;
}
```

In this example, the agent that handles the hook is the agent with a `sessionId` that matches `req.body.userId`.
See [Hook Advanced Usage](/magma-framework/hooks#advanced-usage) for more details

***

## Jobs

When you declare a job as non-static, it will be scheduled on every session of the agent that is created.

```typescript theme={null}
@job('* * * * *')
async sessionJob() {
    console.log('This job will run for every session of the agent')
}
```

This can be helpful for tasks that are user-specific, and should be run for each user.

***