How to Configure Custom Blocks in AutoGPT Platform: A Developer's Guide

Configure custom blocks in AutoGPT Platform by extending the Block base class from backend/data/block.py, defining Pydantic input/output schemas, and saving your implementation under autogpt_platform/backend/backend/blocks/ where the platform automatically discovers and registers it.

The AutoGPT Platform from Significant-Gravitas/AutoGPT uses a modular block architecture to compose agent execution graphs. When you configure custom blocks in AutoGPT Platform, you create reusable Python components that handle API integrations, data processing, and file operations. This guide covers the exact source file locations, base classes, and security patterns required to build blocks that integrate seamlessly with the platform's execution engine and testing framework.

Understanding the Custom Block Architecture

Custom blocks are the primary extension mechanism for adding new capabilities to agents. Each block consists of three core components defined in autogpt_platform/backend/backend/data/block.py:

• The Block base class – Provides automatic registration, UUID handling, schema validation, and test orchestration infrastructure.
• Input/Output schemas – Pydantic models inheriting from BlockSchemaInput and BlockSchemaOutput that declare the data structure a block expects and returns.
• Test configuration – The __init__ method accepts test_input, test_output, and optional test_mock parameters that enable automated unit testing without external network dependencies.

The platform automatically discovers any Python file placed under autogpt_platform/backend/backend/blocks/ and exposes the block through the library UI, provided the class properly inherits from Block.

Step-by-Step Workflow to Configure Custom Blocks

Follow this exact workflow to create a production-ready block:

1. Create the Python file under autogpt_platform/backend/backend/blocks/ using snake_case naming (e.g., wikipedia_summary.py).

2. Import the core classes from the backend data module:

   from backend.data.block import Block, BlockSchemaInput, BlockSchemaOutput, BlockOutput

3. Define input and output schemas as nested classes inheriting from BlockSchemaInput and BlockSchemaOutput. Use standard Pydantic field types or credential metadata for authentication.

4. Implement __init__ with a unique UUID (generated via uuid.uuid4() or hardcoded), schema references, and test data dictionaries.

5. Implement the run method to perform the block's logic. Yield key-value pairs using the syntax yield "field_name", value. Raise BlockInputError or BlockExecutionError from backend/util/exceptions.py for expected failure conditions.

6. Add authentication (optional) by declaring a credentials field in the input schema using CredentialsMetaInput and CredentialsField from backend/data/model.py.

7. Handle files (optional) by invoking store_media_file() from backend/util/file.py, specifying the return format as for_local_processing, for_external_api, or for_block_output.

8. Commit the file to the repository. The platform scans the blocks directory at startup and automatically includes new blocks in the execution engine.

Implementing Input and Output Schemas

Schemas define the contract between your block and the agent graph. The BlockSchemaInput and BlockSchemaOutput base classes from backend/data/block.py provide validation and type serialization.

For blocks requiring API keys or OAuth2 tokens, import CredentialsMetaInput, CredentialsField, and APIKeyCredentials from backend/data/model.py. Declare the provider using the ProviderName enum from backend/integrations/providers.py. The executor injects the proper credential objects at runtime based on the user-configured connection.

Secure API Integration and File Handling

All outbound HTTP calls must use the secure request wrapper from backend/util/request.py rather than the standard requests library. This wrapper enforces SSRF protection and standardizes error handling across the platform.

When working with media files, use store_media_file() from backend/util/file.py to generate context-aware references. This ensures files are properly staged for local processing, external API transmission, or block output serialization according to the execution context.

Code Examples for AutoGPT Platform Blocks

Minimal Custom Block Skeleton

This example demonstrates the basic structure required for registration:

# autogpt_platform/backend/backend/blocks/my_custom_block.py

from backend.data.block import Block, BlockSchemaInput, BlockSchemaOutput, BlockOutput
import uuid

class MyCustomBlock(Block):
    class Input(BlockSchemaInput):
        prompt: str

    class Output(BlockSchemaOutput):
        response: str

    def __init__(self):
        super().__init__(
            id=str(uuid.uuid4()),
            input_schema=MyCustomBlock.Input,
            output_schema=MyCustomBlock.Output,
            test_input={"prompt": "Hello world"},
            test_output=("response", str),
            test_mock={},
        )

    def run(self, input_data: Input, **kwargs) -> BlockOutput:
        result = f"Echo: {input_data.prompt}"
        yield "response", result

Block with Secure HTTP Requests

This implementation from blocks/wikipedia_summary.py shows external API integration using the secure wrapper:

# autogpt_platform/backend/backend/blocks/wikipedia_summary.py

from backend.data.block import Block, BlockSchemaInput, BlockSchemaOutput, BlockOutput
from backend.util.request import requests
import uuid

class WikipediaSummaryBlock(Block):
    class Input(BlockSchemaInput):
        topic: str

    class Output(BlockSchemaOutput):
        summary: str

    def __init__(self):
        super().__init__(
            id=str(uuid.uuid4()),
            input_schema=WikipediaSummaryBlock.Input,
            output_schema=WikipediaSummaryBlock.Output,
            test_input={"topic": "Artificial Intelligence"},
            test_output=("summary", str),
            test_mock={
                "get": lambda url, **_: {"extract": "AI is the simulation of human intelligence."}
            },
        )

    def run(self, input_data: Input, **kwargs) -> BlockOutput:
        url = f"https://en.wikipedia.org/api/rest_v1/page/summary/{input_data.topic}"
        response = requests.get(url)
        yield "summary", response.json()["extract"]

Block with API Key Authentication

This pattern from blocks/github_issues.py demonstrates credential handling:

# autogpt_platform/backend/backend/blocks/github_issues.py

from backend.data.block import Block, BlockSchemaInput, BlockSchemaOutput, BlockOutput
from backend.data.model import CredentialsMetaInput, APIKeyCredentials, CredentialsField
from backend.util.request import requests
from backend.integrations.providers import ProviderName
import uuid

class GithubIssuesBlock(Block):
    class Input(BlockSchemaInput):
        repository: str
        credentials: CredentialsMetaInput[
            ProviderName.GITHUB, "api_key"
        ] = CredentialsField(description="GitHub personal access token")

    class Output(BlockSchemaOutput):
        issue_titles: list[str]

    def __init__(self):
        super().__init__(
            id=str(uuid.uuid4()),
            input_schema=GithubIssuesBlock.Input,
            output_schema=GithubIssuesBlock.Output,
            test_input={"repository": "octocat/Hello-World"},
            test_output=("issue_titles", list),
            test_mock={"get": lambda url, headers, **_: {"items": [{"title": "Test issue"}]}},
        )

    def run(self, input_data: Input, *, credentials: APIKeyCredentials, **kwargs) -> BlockOutput:
        url = f"https://api.github.com/repos/{input_data.repository}/issues"
        resp = requests.get(url, headers={"Authorization": credentials.auth_header()})
        titles = [i["title"] for i in resp.json()]
        yield "issue_titles", titles

Summary

• Custom blocks are Python classes extending the Block base class in backend/data/block.py, providing the primary extension mechanism for AutoGPT Platform agents.
• File location matters: Save implementations under autogpt_platform/backend/backend/blocks/ for automatic discovery and UI registration.
• Schema validation uses Pydantic models derived from BlockSchemaInput and BlockSchemaOutput to enforce type safety across the execution graph.
• Testing infrastructure requires test_input, test_output, and test_mock definitions in __init__ to enable automated unit tests without network calls.
• Security compliance mandates using the requests wrapper from backend/util/request.py for SSRF protection and store_media_file() from backend/util/file.py for media handling.

Frequently Asked Questions

Where do I place custom block files in the AutoGPT Platform?

Place all custom block implementations under the autogpt_platform/backend/backend/blocks/ directory using snake_case filenames (e.g., my_api_block.py). The platform automatically scans this directory at startup and registers any class inheriting from the Block base class, making it available in the block library UI without manual configuration.

How does the AutoGPT Platform handle authentication for custom blocks?

Authentication is handled through the credentials field in your input schema using CredentialsMetaInput and CredentialsField from backend/data/model.py. You specify the provider (e.g., ProviderName.GITHUB) and credential type (e.g., "api_key" or "oauth2"). The executor injects the appropriate credential object (such as APIKeyCredentials) into the run method at runtime, retrieving the actual secrets from the user's configured connections.

What testing framework does AutoGPT Platform use for blocks?

The platform uses a built-in testing framework defined in the Block base class that leverages the test_input, test_output, and test_mock parameters supplied in __init__. When tests run, the platform executes run(test_input) and asserts that the output matches test_output specifications. The test_mock dictionary allows you to monkey-patch HTTP methods or other external calls, enabling unit tests to run without network dependencies or API rate limits.

How do I secure external HTTP requests in custom blocks?

Always import requests from backend/util/request.py rather than using the standard library. This wrapper enforces SSRF (Server-Side Request Forgery) protection by validating URLs against an allowlist and implements consistent error handling and logging. For API failures, raise BlockInputError or BlockExecutionError from backend/util/exceptions.py to signal expected error conditions to the execution engine.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}