# How to Configure Custom Blocks in AutoGPT Platform: A Developer's Guide > Learn to configure custom blocks in AutoGPT Platform. Extend the Block base class, define schemas, and register your implementation for seamless integration. A developer's guide. - Repository: [AutoGPT/AutoGPT](https://github.com/Significant-Gravitas/AutoGPT) - Tags: how-to-guide - Published: 2026-02-24 --- **Configure custom blocks in AutoGPT Platform by extending the `Block` base class from [`backend/data/block.py`](https://github.com/Significant-Gravitas/AutoGPT/blob/main/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`](https://github.com/Significant-Gravitas/AutoGPT/blob/main/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`](https://github.com/Significant-Gravitas/AutoGPT/blob/main/wikipedia_summary.py)). 2. **Import the core classes** from the backend data module: ```python 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`](https://github.com/Significant-Gravitas/AutoGPT/blob/main/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`](https://github.com/Significant-Gravitas/AutoGPT/blob/main/backend/data/model.py). 7. **Handle files (optional)** by invoking `store_media_file()` from [`backend/util/file.py`](https://github.com/Significant-Gravitas/AutoGPT/blob/main/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`](https://github.com/Significant-Gravitas/AutoGPT/blob/main/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`](https://github.com/Significant-Gravitas/AutoGPT/blob/main/backend/data/model.py). Declare the provider using the `ProviderName` enum from [`backend/integrations/providers.py`](https://github.com/Significant-Gravitas/AutoGPT/blob/main/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`](https://github.com/Significant-Gravitas/AutoGPT/blob/main/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`](https://github.com/Significant-Gravitas/AutoGPT/blob/main/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: ```python # 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`](https://github.com/Significant-Gravitas/AutoGPT/blob/main/blocks/wikipedia_summary.py) shows external API integration using the secure wrapper: ```python # 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`](https://github.com/Significant-Gravitas/AutoGPT/blob/main/blocks/github_issues.py) demonstrates credential handling: ```python # 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`](https://github.com/Significant-Gravitas/AutoGPT/blob/main/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`](https://github.com/Significant-Gravitas/AutoGPT/blob/main/backend/util/request.py) for SSRF protection and `store_media_file()` from [`backend/util/file.py`](https://github.com/Significant-Gravitas/AutoGPT/blob/main/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`](https://github.com/Significant-Gravitas/AutoGPT/blob/main/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`](https://github.com/Significant-Gravitas/AutoGPT/blob/main/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`](https://github.com/Significant-Gravitas/AutoGPT/blob/main/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`](https://github.com/Significant-Gravitas/AutoGPT/blob/main/backend/util/exceptions.py) to signal expected error conditions to the execution engine.