Installation

Prerequisites

• An environment with Python 3.10 or later installed.
• Blocks account and API key.
• Completed onboarding.

If you’d like to use Blocks with other providers such as Gitlab or Bitbucket, please reach out: [e-mail].

1. Install Blocks

   bash

   pip install blocks-sdk
   

2. Initialize Blocks

   bash

   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.

   bash

   blocks create hello-world
   

   This will create a new agent in the .blocks directory with the following structure:

   .blocks/
       hello-world/
           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.

   ./blocks/hello-world/main.py

   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.

   bash

   blocks push .blocks/hello_world/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.