AutoGPT is the vision of accessible AI for everyone, to use and to build on. Our mission is to provide the tools, so that you can focus on what matters.
Contributing to AutoGPT Agent Server: Creating and Testing Blocks
This guide will walk you through the process of creating and testing a new block for the AutoGPT Agent Server, using the WikipediaSummaryBlock as an example.
!!! tip "New SDK-Based Approach" For a more comprehensive guide using the new SDK pattern with ProviderBuilder and advanced features like OAuth and webhooks, see the Block SDK Guide.
Understanding Blocks and Testing
Blocks are reusable components that can be connected to form a graph representing an agent's behavior. Each block has inputs, outputs, and a specific function. Proper testing is crucial to ensure blocks work correctly and consistently.
Block Auto-Discovery
All block modules are automatically discovered and imported at startup. The block loader in backend/blocks/__init__.py uses Path(__file__).parent.rglob("*.py") to find every .py file in the blocks/ directory tree. Files named __init__.py and those starting with test_ are excluded.
This means:
- You do not need to manually register your block anywhere — just create the file and your
Blocksubclass will be picked up automatically. - Any module-level side effects (e.g., global registrations, print statements) in your block files will execute on import. Keep block packages clean and avoid side-effect-heavy code at module scope.
- Block auto-discovery does not replace provider setup. For a new API-key integration, follow the provider auth setup below: add the provider name, credentials, display metadata, and integration icon. Frontend provider data is loaded dynamically; no manual frontend provider registration is needed.
Creating and Testing a New Block
Follow these steps to create and test a new block:
Create a new Python file for your block in the
autogpt_platform/backend/backend/blocksdirectory. Name it descriptively and use snake_case. For example:get_wikipedia_summary.py.Import necessary modules and create a class that inherits from
Block. Make sure to include all necessary imports for your block.Every block should contain the following:
from backend.blocks._base import Block, BlockSchemaInput, BlockSchemaOutput, BlockOutputExample for the Wikipedia summary block:
from backend.blocks._base import Block, BlockSchemaInput, BlockSchemaOutput, BlockOutput from backend.utils.get_request import GetRequest import requests class WikipediaSummaryBlock(Block, GetRequest): # Block implementation will go hereDefine the input and output schemas using
BlockSchema. These schemas specify the data structure that the block expects to receive (input) and produce (output).- The input schema defines the structure of the data the block will process. Each field in the schema represents a required piece of input data.
- The output schema defines the structure of the data the block will return after processing. Each field in the schema represents a piece of output data.
Example:
class Input(BlockSchemaInput): topic: str # The topic to get the Wikipedia summary for class Output(BlockSchemaOutput): summary: str # The summary of the topic from WikipediaImplement the
__init__method, including test data and mocks:!!! important Use UUID generator (e.g. https://www.uuidgenerator.net/) for every new block
idand do not make up your own. Alternatively, you can run this python code to generate an uuid:print(__import__('uuid').uuid4())def __init__(self): super().__init__( # Unique ID for the block, used across users for templates # If you are an AI leave it as is or change to "generate-proper-uuid" id="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", input_schema=WikipediaSummaryBlock.Input, # Assign input schema output_schema=WikipediaSummaryBlock.Output, # Assign output schema # Provide sample input, output and test mock for testing the block test_input={"topic": "Artificial Intelligence"}, test_output=("summary", "summary content"), test_mock={"get_request": lambda url, json: {"extract": "summary content"}}, )id: A unique identifier for the block.input_schemaandoutput_schema: Define the structure of the input and output data.
Let's break down the testing components:
test_input: This is a sample input that will be used to test the block. It should be a valid input according to your Input schema.test_output: This is the expected output when running the block with thetest_input. It should match your Output schema. For non-deterministic outputs or when you only want to assert the type, you can use Python types instead of specific values. In this example,("summary", str)asserts that the output key is "summary" and its value is a string.test_mock: This is crucial for blocks that make network calls. It provides a mock function that replaces the actual network call during testing.
In this case, we're mocking the
get_requestmethod to always return a dictionary with an 'extract' key, simulating a successful API response. This allows us to test the block's logic without making actual network requests, which could be slow, unreliable, or rate-limited.Implement the
runmethod with error handling. This should contain the main logic of the block:def run(self, input_data: Input, **kwargs) -> BlockOutput: try: topic = input_data.topic url = f"https://en.wikipedia.org/api/rest_v1/page/summary/{topic}" response = self.get_request(url, json=True) yield "summary", response['extract'] except requests.exceptions.HTTPError as http_err: raise RuntimeError(f"HTTP error occurred: {http_err}")- Try block: Contains the main logic to fetch and process the Wikipedia summary.
- API request: Send a GET request to the Wikipedia API.
- Error handling: Handle various exceptions that might occur during the API request and data processing. We don't need to catch all exceptions, only the ones we expect and can handle. The uncaught exceptions will be automatically yielded as
errorin the output. Any block that raises an exception (or yields anerroroutput) will be marked as failed. Prefer raising exceptions over yieldingerror, as it will stop the execution immediately. - Yield: Use
yieldto output the results. Prefer to output one result object at a time. If you are calling a function that returns a list, you can yield each item in the list separately. You can also yield the whole list as well, but do both rather than yielding the list. For example: If you were writing a block that outputs emails, you'd yield each email as a separate result object, but you could also yield the whole list as an additional single result object. Yielding output namederrorwill break the execution right away and mark the block execution as failed. - kwargs: The
kwargsparameter is used to pass additional arguments to the block. It is not used in the example above, but it is available to the block. You can also have args as inline signatures in the run method aladef run(self, input_data: Input, *, user_id: str, **kwargs) -> BlockOutput:. Available kwargs are:user_id: The ID of the user running the block.graph_id: The ID of the agent that is executing the block. This is the same for every version of the agentgraph_exec_id: The ID of the execution of the agent. This changes every time the agent has a new "run"node_exec_id: The ID of the execution of the node. This changes every time the node is executednode_id: The ID of the node that is being executed. It changes every version of the graph, but not every time the node is executed.execution_context: AnExecutionContextobject containing user_id, graph_exec_id, workspace_id, and session_id. Required for file handling.
Handling Files in Blocks
When your block needs to work with files (images, videos, documents), use store_media_file() from backend.util.file. This function handles downloading, validation, virus scanning, and storage.
Import:
from backend.data.execution import ExecutionContext
from backend.util.file import store_media_file
from backend.util.type import MediaFileType
The return_format parameter determines what you get back:
| Format | Use When | Returns |
|---|---|---|
"for_local_processing" |
Processing with local tools (ffmpeg, MoviePy, PIL) | Local file path (e.g., "image.png") |
"for_external_api" |
Sending content to external APIs (Replicate, OpenAI) | Data URI (e.g., "data:image/png;base64,...") |
"for_block_output" |
Returning output from your block | Smart: workspace:// in CoPilot, data URI in graphs |
Examples:
async def run(
self,
input_data: Input,
*,
execution_context: ExecutionContext,
**kwargs,
) -> BlockOutput:
# PROCESSING: Need to work with file locally (ffmpeg, MoviePy, PIL)
local_path = await store_media_file(
file=input_data.video,
execution_context=execution_context,
return_format="for_local_processing",
)
# local_path = "video.mp4" - use with Path, ffmpeg, subprocess, etc.
full_path = get_exec_file_path(execution_context.graph_exec_id, local_path)
# EXTERNAL API: Need to send content to an API like Replicate
image_b64 = await store_media_file(
file=input_data.image,
execution_context=execution_context,
return_format="for_external_api",
)
# image_b64 = "data:image/png;base64,iVBORw0..." - send to external API
# OUTPUT: Returning result from block to user/next block
result_url = await store_media_file(
file=generated_image_url,
execution_context=execution_context,
return_format="for_block_output",
)
yield "image_url", result_url
# In CoPilot: result_url = "workspace://abc123" (persistent, context-efficient)
# In graphs: result_url = "data:image/png;base64,..." (for next block/display)
Key points:
for_block_outputis the only format that auto-adapts to execution context- Always use
for_block_outputfor block outputs unless you have a specific reason not to - Never manually check for
workspace_id- letfor_block_outputhandle the logic - The function handles URLs, data URIs,
workspace://references, and local paths as input
Field Types
oneOf fields
oneOf allows you to specify that a field must be exactly one of several possible options. This is useful when you want your block to accept different types of inputs that are mutually exclusive.
Example:
attachment: Union[Media, DeepLink, Poll, Place, Quote] = SchemaField(
discriminator='discriminator',
description="Attach either media, deep link, poll, place or quote - only one can be used"
)
The discriminator parameter tells AutoGPT which field to look at in the input to determine which type it is.
In each model, you need to define the discriminator value:
class Media(BaseModel):
discriminator: Literal['media']
media_ids: List[str]
class DeepLink(BaseModel):
discriminator: Literal['deep_link']
direct_message_deep_link: str
OptionalOneOf fields
OptionalOneOf is similar to oneOf but allows the field to be optional (None). This means the field can be either one of the specified types or None.
Example:
attachment: Union[Media, DeepLink, Poll, Place, Quote] | None = SchemaField(
discriminator='discriminator',
description="Optional attachment - can be media, deep link, poll, place, quote or None"
)
The key difference is the | None which makes the entire field optional.
Blocks with authentication
Our system supports auth offloading for API keys and OAuth2 authorization flows. Adding a block with API key authentication is straight-forward, as is adding a block for a service that we already have OAuth2 support for.
Implementing the block itself is relatively simple. On top of the instructions above,
you're going to add a credentials parameter to the Input model and the run method:
from backend.data.model import (
APIKeyCredentials,
OAuth2Credentials,
Credentials,
)
from backend.blocks._base import Block, BlockOutput, BlockSchemaInput, BlockSchemaOutput
from backend.data.model import CredentialsField
from backend.integrations.providers import ProviderName
# API Key auth:
class BlockWithAPIKeyAuth(Block):
class Input(BlockSchemaInput):
# Note that the type hint below is require or you will get a type error.
# The first argument is the provider name, the second is the credential type.
credentials: CredentialsMetaInput[
Literal[ProviderName.GITHUB], Literal["api_key"]
] = CredentialsField(
description="The GitHub integration can be used with "
"any API key with sufficient permissions for the blocks it is used on.",
)
# ...
def run(
self,
input_data: Input,
*,
credentials: APIKeyCredentials,
**kwargs,
) -> BlockOutput:
...
# OAuth:
class BlockWithOAuth(Block):
class Input(BlockSchemaInput):
# Note that the type hint below is require or you will get a type error.
# The first argument is the provider name, the second is the credential type.
credentials: CredentialsMetaInput[
Literal[ProviderName.GITHUB], Literal["oauth2"]
] = CredentialsField(
required_scopes={"repo"},
description="The GitHub integration can be used with OAuth.",
)
# ...
def run(
self,
input_data: Input,
*,
credentials: OAuth2Credentials,
**kwargs,
) -> BlockOutput:
...
# API Key auth + OAuth:
class BlockWithAPIKeyAndOAuth(Block):
class Input(BlockSchemaInput):
# Note that the type hint below is require or you will get a type error.
# The first argument is the provider name, the second is the credential type.
credentials: CredentialsMetaInput[
Literal[ProviderName.GITHUB], Literal["api_key", "oauth2"]
] = CredentialsField(
required_scopes={"repo"},
description="The GitHub integration can be used with OAuth, "
"or any API key with sufficient permissions for the blocks it is used on.",
)
# ...
def run(
self,
input_data: Input,
*,
credentials: Credentials,
**kwargs,
) -> BlockOutput:
...
The credentials will be automagically injected by the executor in the back end.
The APIKeyCredentials and OAuth2Credentials models are defined here.
To use them in e.g. an API request, you can either access the token directly:
# credentials: APIKeyCredentials
response = requests.post(
url,
headers={
"Authorization": f"Bearer {credentials.api_key.get_secret_value()})",
},
)
# credentials: OAuth2Credentials
response = requests.post(
url,
headers={
"Authorization": f"Bearer {credentials.access_token.get_secret_value()})",
},
)
or use the shortcut credentials.auth_header():
# credentials: APIKeyCredentials | OAuth2Credentials
response = requests.post(
url,
headers={"Authorization": credentials.auth_header()},
)
The backend discovers provider names from the ProviderName enum and the SDK's AutoRegistry.
The _auth.py pattern below uses a ProviderName member, so add the new provider to that enum. SDK integrations can instead register provider names through ProviderBuilder; see the Block SDK Guide.
ProviderName definition
--8<-- "autogpt_platform/backend/backend/integrations/providers.py:ProviderName"
API-Key-Only Provider Auth (Recommended Pattern)
For integrations that only use API key authentication (no OAuth), keep credential definitions in _auth.py and register display metadata separately. The setup is:
- Add to
ProviderNameenum inbackend/integrations/providers.py - Create
_auth.pyin your block package with credentials type, field factory, and test credentials - Create the block using the credentials field from
_auth.py - Create
_config.pywith the provider description and supported auth types for the settings UI - Add the integration icon as described below
Here's the complete _auth.py pattern (using ZeroBounce as a reference):
from typing import Literal
from pydantic import SecretStr
from backend.data.model import APIKeyCredentials, CredentialsField, CredentialsMetaInput
from backend.integrations.providers import ProviderName
# Type aliases for your provider
MyProviderCredentials = APIKeyCredentials
MyProviderCredentialsInput = CredentialsMetaInput[
Literal[ProviderName.MY_PROVIDER],
Literal["api_key"],
]
# Field factory for use in block Input schemas
def MyProviderCredentialsField() -> MyProviderCredentialsInput:
return CredentialsField(
description="The My Provider integration requires an API key.",
)
# Test credentials for block tests
TEST_CREDENTIALS = APIKeyCredentials(
id="01234567-89ab-cdef-0123-456789abcdef",
provider="my_provider",
api_key=SecretStr("mock-my-provider-api-key"),
title="Mock My Provider API key",
expires_at=None,
)
TEST_CREDENTIALS_INPUT = {
"provider": TEST_CREDENTIALS.provider,
"id": TEST_CREDENTIALS.id,
"type": TEST_CREDENTIALS.type,
"title": TEST_CREDENTIALS.title,
}
Then use it in your block:
from ._auth import MyProviderCredentials, MyProviderCredentialsField, MyProviderCredentialsInput
class MyBlock(Block):
class Input(BlockSchemaInput):
credentials: MyProviderCredentialsInput = MyProviderCredentialsField()
# ... other inputs
async def run(
self,
input_data: Input,
*,
credentials: MyProviderCredentials,
**kwargs,
) -> BlockOutput:
api_key = credentials.api_key.get_secret_value()
# ... use the API key
yield "result", ...
Register the provider metadata in _config.py, following backend/blocks/zerobounce/_config.py:
from backend.integrations.providers import ProviderName
from backend.sdk import ProviderBuilder
my_provider = (
ProviderBuilder(ProviderName.MY_PROVIDER.value)
.with_description("A short description of the integration")
.with_supported_auth_types("api_key")
.build()
)
This metadata tells the settings UI which connection methods to offer. It does not replace the credentials declared in _auth.py. The block loader imports _config.py automatically, and .build() registers the provider. OAuth, webhooks, and cost tracking use additional ProviderBuilder methods described in the Block SDK Guide.
Multiple credentials inputs
Multiple credentials inputs are supported, under the following conditions:
- The name of each of the credentials input fields must end with
_credentials. - The names of the credentials input fields must match the names of the corresponding
parameters on the
run(..)method of the block. - If more than one of the credentials parameters are required,
test_credentialsis adict[str, Credentials], with for each required credentials input the parameter name as the key and suitable test credentials as the value.
Adding an OAuth2 service integration
To add support for a new OAuth2-authenticated service, you'll need to add an OAuthHandler.
All our existing handlers and the base class can be found here.
Every handler must implement the following parts of the BaseOAuthHandler interface:
--8<-- "autogpt_platform/backend/backend/integrations/oauth/base.py:BaseOAuthHandler1"
--8<-- "autogpt_platform/backend/backend/integrations/oauth/base.py:BaseOAuthHandler2"
--8<-- "autogpt_platform/backend/backend/integrations/oauth/base.py:BaseOAuthHandler3"
--8<-- "autogpt_platform/backend/backend/integrations/oauth/base.py:BaseOAuthHandler4"
--8<-- "autogpt_platform/backend/backend/integrations/oauth/base.py:BaseOAuthHandler5"
--8<-- "autogpt_platform/backend/backend/integrations/oauth/base.py:BaseOAuthHandler6"
As you can see, this is modeled after the standard OAuth2 flow.
Aside from implementing the OAuthHandler itself, adding a handler into the system requires two more things:
- Adding the handler class to
HANDLERS_BY_NAMEunderintegrations/oauth/__init__.py
--8<-- "autogpt_platform/backend/backend/integrations/oauth/__init__.py:HANDLERS_BY_NAMEExample"
- Adding
{provider}_client_idand{provider}_client_secretto the application'sSecretsunderutil/settings.py
--8<-- "autogpt_platform/backend/backend/util/settings.py:OAuthServerCredentialsExample"
Adding to the frontend
Integration Icon (Required)
When adding a new integration provider, you must add a PNG icon at:
autogpt_platform/frontend/public/integrations/{provider_name}.png
The frontend block menu dynamically loads icons using the URL /integrations/{integration.name}.png (see PaginatedIntegrationList.tsx). If the icon file is missing, the block will show a broken image in the builder UI.
Use the same provider_name that matches your ProviderName enum value (lowercase). For example, if your provider is ProviderName.SLACK, the icon should be at frontend/public/integrations/slack.png.
Frontend Provider Registration
No manual frontend provider registration is required. The credentials provider context fetches provider names from the backend, and the integrations UI uses the description and supported_auth_types returned by GET /integrations/providers. Set those fields in the backend provider configuration as shown above.
Block credential inputs derive their accepted credential types from the block's input schema. CredentialsProviderName is a string type; CredentialsType describes authentication methods, not provider names, so neither needs a new frontend enum entry for a provider.
The credentials list has an optional providerIcons map in frontend/src/components/contextual/CredentialsInput/helpers.ts; unlisted providers use a fallback icon. This is separate from the PNG asset required by the block menu.
Example: GitHub integration
- GitHub blocks with API key + OAuth2 support:
blocks/github
--8<-- "autogpt_platform/backend/backend/blocks/github/issues.py:GithubCommentBlockExample"
- GitHub OAuth2 handler:
integrations/oauth/github.py
--8<-- "autogpt_platform/backend/backend/integrations/oauth/github.py:GithubOAuthHandlerExample"
Example: Google integration
- Google OAuth2 handler:
integrations/oauth/google.py
--8<-- "autogpt_platform/backend/backend/integrations/oauth/google.py:GoogleOAuthHandlerExample"
You can see that google has defined a DEFAULT_SCOPES variable, this is used to set the scopes that are requested no matter what the user asks for.
--8<-- "autogpt_platform/backend/backend/blocks/google/_auth.py:GoogleOAuthIsConfigured"
You can also see that GOOGLE_OAUTH_IS_CONFIGURED is used to disable the blocks that require OAuth if the oauth is not configured. This is in the __init__ method of each block. This is because there is no api key fallback for google blocks so we need to make sure that the oauth is configured before we allow the user to use the blocks.
Webhook-triggered Blocks
Webhook-triggered blocks allow your agent to respond to external events in real-time. These blocks are triggered by incoming webhooks from third-party services rather than being executed manually.
Creating and running a webhook-triggered block involves three main components:
- The block itself, which specifies:
- Inputs for the user to select a resource and events to subscribe to
- A
credentialsinput with the scopes needed to manage webhooks - Logic to turn the webhook payload into outputs for the webhook block
- The
WebhooksManagerfor the corresponding webhook service provider, which handles:- (De)registering webhooks with the provider
- Parsing and validating incoming webhook payloads
- The credentials system for the corresponding service provider, which may include an
OAuthHandler
There is more going on under the hood, e.g. to store and retrieve webhooks and their links to nodes, but to add a webhook-triggered block you shouldn't need to make changes to those parts of the system.
Creating a Webhook-triggered Block
To create a webhook-triggered block, follow these additional steps on top of the basic block creation process:
Define
webhook_configin your block's__init__method.Example:
GitHubPullRequestTriggerBlock--8<-- "autogpt_platform/backend/backend/blocks/github/triggers.py:example-webhook_config"BlockWebhookConfigdefinition--8<-- "autogpt_platform/backend/backend/blocks/_base.py:BlockWebhookConfig"Define event filter input in your block's Input schema. This allows the user to select which specific types of events will trigger the block in their agent.
Example:
GitHubPullRequestTriggerBlock--8<-- "autogpt_platform/backend/backend/blocks/github/triggers.py:example-event-filter"- The name of the input field (
eventsin this case) must matchwebhook_config.event_filter_input. - The event filter itself must be a Pydantic model with only boolean fields.
- The name of the input field (
Include payload field in your block's Input schema.
Example:
GitHubTriggerBase--8<-- "autogpt_platform/backend/backend/blocks/github/triggers.py:example-payload-field"Define
credentialsinput in your block's Input schema.- Its scopes must be sufficient to manage a user's webhooks through the provider's API
- See Blocks with authentication for further details
Process webhook payload and output relevant parts of it in your block's
runmethod.Example:
GitHubPullRequestTriggerBlockdef run(self, input_data: Input, **kwargs) -> BlockOutput: yield "payload", input_data.payload yield "sender", input_data.payload["sender"] yield "event", input_data.payload["action"] yield "number", input_data.payload["number"] yield "pull_request", input_data.payload["pull_request"]Note that the
credentialsparameter can be omitted if the credentials aren't used at block runtime, like in the example.
Adding a Webhooks Manager
To add support for a new webhook provider, you'll need to create a WebhooksManager that implements the BaseWebhooksManager interface:
--8<-- "autogpt_platform/backend/backend/integrations/webhooks/_base.py:BaseWebhooksManager1"
--8<-- "autogpt_platform/backend/backend/integrations/webhooks/_base.py:BaseWebhooksManager2"
--8<-- "autogpt_platform/backend/backend/integrations/webhooks/_base.py:BaseWebhooksManager3"
--8<-- "autogpt_platform/backend/backend/integrations/webhooks/_base.py:BaseWebhooksManager4"
--8<-- "autogpt_platform/backend/backend/integrations/webhooks/_base.py:BaseWebhooksManager5"
--8<-- "autogpt_platform/backend/backend/integrations/webhooks/_base.py:BaseWebhooksManager6"
!!! info "Signature verification (verify_signature)"
If the upstream provider signs its deliveries (e.g. GitHub's
X-Hub-Signature-256, Airtable's X-Airtable-Content-MAC), override
verify_signature and use hmac.compare_digest for the comparison.
Raise fastapi.HTTPException(403) on missing/invalid signatures.
If the provider has no signing scheme (consumer wearables, simple
"POST to this URL" tools), leave the default in place. The webhook
URL's UUID is then the bearer secret — document that for users.
And add a reference to your WebhooksManager class in load_webhook_managers:
--8<-- "autogpt_platform/backend/backend/integrations/webhooks/__init__.py:load_webhook_managers"
Example: GitHub Webhook Integration
GitHub Webhook triggers: blocks/github/triggers.py
--8<-- "autogpt_platform/backend/backend/blocks/github/triggers.py:GithubTriggerExample"
GitHub Webhooks Manager: integrations/webhooks/github.py
--8<-- "autogpt_platform/backend/backend/integrations/webhooks/github.py:GithubWebhooksManager"
Key Points to Remember
- Unique ID: Give your block a unique ID in the init method.
- Input and Output Schemas: Define clear input and output schemas.
- Error Handling: Implement error handling in the
runmethod. - Output Results: Use
yieldto output results in therunmethod. - Testing: Provide test input and output in the init method for automatic testing.
Understanding the Testing Process
The testing of blocks is handled by test_block.py, which does the following:
- It calls the block with the provided
test_input. If the block has acredentialsfield,test_credentialsis passed in as well. - If a
test_mockis provided, it temporarily replaces the specified methods with the mock functions. - It then asserts that the output matches the
test_output.
For the WikipediaSummaryBlock:
- The test will call the block with the topic "Artificial Intelligence".
- Instead of making a real API call, it will use the mock function, which returns
{"extract": "summary content"}. - It will then check if the output key is "summary" and its value is a string.
This approach allows us to test the block's logic comprehensively without relying on external services, while also accommodating non-deterministic outputs.
Security Best Practices for SSRF Prevention
When creating blocks that handle external URL inputs or make network requests, it's crucial to use the platform's built-in SSRF protection mechanisms. The backend.util.request module provides a secure Requests wrapper class that should be used for all HTTP requests.
Using the Secure Requests Wrapper
from backend.util.request import requests
class MyNetworkBlock(Block):
def run(self, input_data: Input, **kwargs) -> BlockOutput:
try:
# The requests wrapper automatically validates URLs and blocks dangerous requests
response = requests.get(input_data.url)
yield "result", response.text
except ValueError as e:
# URL validation failed
raise RuntimeError(f"Invalid URL provided: {e}")
except requests.exceptions.RequestException as e:
# Request failed
raise RuntimeError(f"Request failed: {e}")
The Requests wrapper provides these security features:
URL Validation:
- Blocks requests to private IP ranges (RFC 1918)
- Validates URL format and protocol
- Resolves DNS and checks IP addresses
- Supports whitelisting trusted origins
Secure Defaults:
- Disables redirects by default
- Raises exceptions for non-200 status codes
- Supports custom headers and validators
Protected IP Ranges: The wrapper denies requests to these networks:
--8<-- "autogpt_platform/backend/backend/util/request.py:BLOCKED_IP_NETWORKS"
Custom Request Configuration
If you need to customize the request behavior:
from backend.util.request import Requests
# Create a custom requests instance with specific trusted origins
custom_requests = Requests(
trusted_origins=["api.trusted-service.com"],
raise_for_status=True,
extra_headers={"User-Agent": "MyBlock/1.0"}
)
Error Handling
Blocks should raise appropriate exceptions for errors that users can fix. The executor classifies errors based on whether they inherit from ValueError - these are treated as "expected failures" (user-fixable) rather than system errors.
Block Exception Classes
Import from backend.util.exceptions:
from backend.util.exceptions import BlockInputError, BlockExecutionError
| Exception | Use Case | Example |
|---|---|---|
BlockInputError |
Invalid user input, validation failures, missing required fields | Bad API key format, invalid URL, missing credentials |
BlockExecutionError |
Runtime failures the user can address | API errors, auth failures, resource not found, rate limits |
ValueError |
Simple cases (auto-wrapped to BlockExecutionError) |
Basic validation errors |
Raising Exceptions
from backend.util.exceptions import BlockInputError, BlockExecutionError
class MyBlock(Block):
async def run(self, input_data: Input, **kwargs) -> BlockOutput:
# Input validation - use BlockInputError
if not input_data.api_key:
raise BlockInputError(
message="API key is required",
block_name=self.name,
block_id=self.id,
)
try:
result = await self.call_api(input_data)
yield "result", result
except AuthenticationError as e:
# API/runtime errors - use BlockExecutionError
raise BlockExecutionError(
message=f"Authentication failed: {e}",
block_name=self.name,
block_id=self.id,
) from e
What NOT to Catch
Don't catch errors that require system admin intervention:
- Out of money/credits
- Unreachable infrastructure
- Database connection failures
- Internal server errors from your own services
Let these propagate as unexpected errors so they get proper attention.
Data Models
Use pydantic base models over dict and typeddict where possible. Avoid untyped models for block inputs and outputs as much as possible
File Input
You can use MediaFileType to handle the importing and exporting of files out of the system. Explore how its used through the system before using it in a block schema.
Tips for Effective Block Testing
Provide realistic test_input: Ensure your test input covers typical use cases.
Define appropriate test_output:
- For deterministic outputs, use specific expected values.
- For non-deterministic outputs or when only the type matters, use Python types (e.g.,
str,int,dict). - You can mix specific values and types, e.g.,
("key1", str), ("key2", 42).
Use test_mock for network calls: This prevents tests from failing due to network issues or API changes.
Consider omitting test_mock for blocks without external dependencies: If your block doesn't make network calls or use external resources, you might not need a mock.
Consider edge cases: Include tests for potential error conditions in your
runmethod.Update tests when changing block behavior: If you modify your block, ensure the tests are updated accordingly.
By following these steps, you can create new blocks that extend the functionality of the AutoGPT Agent Server.
Standalone Unit Tests
In addition to the inline test_input/test_output/test_mock approach described above, you can write standalone unit tests for more complex validation. Place test files alongside your block as {block_name}_test.py (e.g., my_block_test.py).
!!! warning "Test file naming and auto-discovery"
The block loader in backend/blocks/__init__.py skips files whose names start with test_ but still auto-imports files ending in _test.py at startup. Keep _test.py modules free of module-level side effects (no top-level patch(...) / network calls / fixtures-with-side-effects), or name your file test_{block_name}.py to opt out of auto-import entirely.
Test Structure
Two patterns are supported:
1. Drive the block directly (mirror backend/blocks/slack/slack_test.py) — gives you full control over inputs, mocks, and output assertions:
import pytest
from unittest.mock import AsyncMock, MagicMock, patch
from backend.blocks.my_provider._auth import TEST_CREDENTIALS, TEST_CREDENTIALS_INPUT
from backend.blocks.my_provider.my_block import MyBlock
async def _collect_outputs(block, input_data, credentials):
outputs: dict[str, object] = {}
async for name, value in block.run(input_data, credentials=credentials):
outputs[name] = value
return outputs
@pytest.mark.asyncio
async def test_my_block_success():
block = MyBlock()
input_data = MyBlock.Input(
credentials=TEST_CREDENTIALS_INPUT,
query="test query",
)
mock_resp = MagicMock()
mock_resp.json.return_value = {"result": "test data"}
# Patch where the symbol is *used*. The block ecosystem uses
# `backend.util.request.Requests` (httpx under the hood), not stdlib `requests`.
with patch(
"backend.blocks.my_provider.my_block.Requests.post",
new_callable=AsyncMock,
return_value=mock_resp,
):
outputs = await _collect_outputs(block, input_data, TEST_CREDENTIALS)
assert outputs["result"] == "test data"
2. Run the block's inline test_input / test_output / test_mock via the framework helper. The helper takes a block instance only and reads the test data defined on the block itself:
import pytest
from backend.blocks.my_provider.my_block import MyBlock
from backend.util.test import execute_block_test
@pytest.mark.asyncio
async def test_my_block_inline_fixtures():
await execute_block_test(MyBlock())
Key Points
TEST_CREDENTIALS_INPUT(from_auth.py) is used to construct theInputobject — it contains the credential metadata (provider, id, type).TEST_CREDENTIALS(from_auth.py) is passed toblock.run(..., credentials=...)— it contains the actual mock API key/token.execute_block_test(block)runs the block against its own inlinetest_input/test_output/test_mockattributes (set in__init__). It does not acceptinput_data=orcredentials=and does not return outputs.- The block attribute for test credentials is
test_credentials(nottest_credentials_input) when using the inline test pattern in__init__. - Use
pytest.mark.asynciofor async blockrun()methods. Mock the HTTP layer where it is used — typicallybackend.util.request.Requests(orhttpx.AsyncClient), not stdlibrequests.
Running Tests
# Run a specific block's standalone tests
poetry run pytest backend/blocks/my_provider/my_block_test.py -xvs
# Run all block tests (inline test_input/test_output validation)
poetry run pytest backend/blocks/test/test_block.py -xvs
# Test a specific block by name (inline tests)
poetry run pytest 'backend/blocks/test/test_block.py::test_available_blocks[MyBlock]' -xvs
Block Documentation Sync
After creating or modifying blocks, you must regenerate the block documentation to keep it in sync with the code.
Generating Documentation
cd autogpt_platform/backend
poetry run python scripts/generate_block_docs.py
For provider packages, the generator writes one page per Python module:
docs/integrations/block-integrations/{provider}/{module}.md
For example, backend/blocks/zerobounce/validate_emails.py generates docs/integrations/block-integrations/zerobounce/validate_emails.md. Top-level block modules are grouped into category pages such as docs/integrations/block-integrations/basic.md.
CI Enforcement
The "Block Documentation Sync Check" CI workflow (.github/workflows/docs-block-sync.yml) runs on every PR that touches files in backend/blocks/ or docs/integrations/. It runs the generator in --check mode and fails the build if docs are out of sync.
If CI fails with a docs sync error, run the generator locally, commit the updated docs, and push.
Manual Sections
The generated docs support manually-written content that is preserved across regeneration. Use these markers in the generated markdown files:
<!-- MANUAL: use_case -->
Your custom usage examples here. This will not be overwritten.
<!-- END MANUAL -->
Use the generator-supported block sections how_it_works, use_case, and extras, or file-level file_description and additional_content. Keep the existing markers rather than inventing section names. These sections hold usage examples, caveats, and integration notes that cannot be generated from block metadata.