Skip to main content

​
Prerequisites

If you’d like to use Blocks with other providers such as Gitlab or Bitbucket, please reach out: dev@blocks.team.
1

Install Blocks

pip install blocks-sdk
2

Initialize Blocks

blocks init --key <your-api-key>
We’ll verify your API key and create a .blocks directory in the current working directory.
3

Create an agent

The easiest way to create an agent is to use the create command.
blocks create slack-agent
This will create a new agent in the .blocks directory with the following structure:
.blocks/
    slack-agent/
        main.py
        requirements.txt
Below is an example agent you can copy to get started that uses Smolagents to implement a simple Slack agent that responds in the same thread as the user that mentioned it.
import os
import slack_sdk

from enum import Enum
from blocks import agent, on
from smolagents import CodeAgent, WebSearchTool, LiteLLMModel
from pydantic import BaseModel

SLACK_TOKEN = os.getenv("SLACK_TOKEN")

class Models(str, Enum):
  gpt_5 = "gpt-5"
  claude4sonnet = "claude-sonnet-4-20250514"

class SmolAgentConfig(BaseModel):
  model: Models = Models.gpt_5

@agent(name="custom-slack")
@on("slack.mention")
def custom_slack(input, config: SmolAgentConfig):
  event = input.get("event")
  text = event.get("text", "")
  channel = event.get("channel", "")
  ts = event.get("ts", "")

  model = LiteLLMModel(
      model_id=config.model,
  )
  agent = CodeAgent(tools=[WebSearchTool()], model=model)
  agent.run(text)

  client = slack_sdk.WebClient(token=SLACK_TOKEN)
  client.chat_postMessage(channel=channel, text="Agent is thinking...", thread_ts=ts)

  for _, step in enumerate(agent.memory.steps):
      messages = step.to_messages()
      for message in messages:
          for content_message in message.content:
              final_message = content_message.get("text", "")
              if final_message and content_message.get("role") != "user":
                  client.chat_postMessage(channel=channel, text=final_message, thread_ts=ts)
4

Register an agent

Agents are registered with the push command; specify the filename relative to your current working directory. All agents defined the file will be registered, however you can only register one file at a time.
blocks push .blocks/slack-agent/main.py

​
Project Structure

The .blocks directory is where agent source code is defined. A typical project structure looks like the following: 
.blocks/
    agent-1/
        main.py
        requirements.txt
    agent-2/
        main.py
        requirements.txt
    agent-3.py
Dependencies are isolated to each agent, and there are no restrictions for supported pip packages.

​
Version Control

Ideally, your agents will be checked into some git provider for version control and storage, just like any other source code. We do preserve the state of registered agents, but do not implement git for version control. However, this is something we can add if requested.

​
Where do I get an API key?

API keys are created and managed in the dashboard.