Quickstart

Installation

Install the soma binary

curl -sSL https://trysoma.ai/install.sh | sh

Create a new project

The soma init command will create a new project from one of our git templates. Run soma init to see all available options.

Typescript / Vercel AI SDK
Python / Langchain

  soma init --template typescript-ai-sdk  hello-world-agent
  cd hello-world-agent
  # install dependencies. You can use any package manager you want.
  pnpm install
  # start the dev server
  soma dev --clean

  soma init --template python-langchain-template  hello-world-agent
  cd hello-world-agent
  # install dependencies. You can use any package manager you want.
  uv sync
  # start the dev server
  soma dev --clean

Configure a secret management encryption key

Please run all the remaining commands in a separate terminal whilst the dev server is running.

An encryption key is necessary to keep secrets, MCP credentials and sensitive auth middleware configuration safe.

Local key
AWS KMS

  soma enc-key add local --file-name master.bin

Local encryption keys will be added to the .soma/envelope-encryption-keys/$filename file. Local keys are useful for development and testing. However if you intend to share this project or deploy it, we advise using AWS KMS or storing the local key as a CI secret and injecting it before running soma commads. You can migrate your encrypted data between different key types by using the soma enc-key migrate command.

Never commit the .soma/envelope-encryption-keys folder to version control.

  soma enc-key add aws --arn arn:aws:kms:eu-west-2:xxx:key/xxx --region eu-west-2

You will need to ensure your current terminal session has the required AWS environment variables set to access the KMS key. These are normally:

AWS_ACCESS_KEY_ID,
AWS_SECRET_ACCESS_KEY,
AWS_SESSION_TOKEN or,
AWS_PROFILE

Set up environment variables

  soma secret set OPENAI_API_KEY xxx

Our example agent uses OpenAI to generate responses.

Explore Soma, debug your agent

via UI

Open your browser to http://localhost:3000. Navigate to the “Agent 2 Agent” > “Chat”. Send a message to your agent and wait for the response.

Configure MCP functions

via UI

Open your browser to http://localhost:3000. Navigate to the “Bridge MCP functions” > “Enable functions”.From here, you can see a list of pre-build Bridge MCP functions, mainly for integrating with third-party SaaS providers. Additionally, you should also see any provider from your project’s functions folder which you can now configure and enable.

Next steps

The anatomy of a Soma project

Learn about our file based project structure and configuration options

Enable secure MCP functions

Learn about enabling secure MCP functions for your agent

Common agent patterns

How to build chat, workflow or a combination of both agents

Introduction

Deployment

Getting started

Security, authentication & access control

Common patterns

Usage with AI frameworks

Secure MCP functions

Invoking your agent

Testing & evals

Fault tolerance & resumability

Installation

Next steps

The anatomy of a Soma project

Enable secure MCP functions

Common agent patterns

​Installation

​Next steps

The anatomy of a Soma project

Enable secure MCP functions

Common agent patterns

Installation

Next steps