docs(platform): Example block

[Swiftyos]

This PR introduces ExampleBlock and ExampleTriggerBlock to showcase best practices for creating blocks, managing credentials, and integrating webhooks. Key changes:

• Added example blocks for standard and trigger-based workflows.
• Included mock credentials and cost configuration.
• Implemented webhook manager for event handling.

Purpose: This is an example PR, not intended for merging. We’re requesting reviews to ensure it captures the best practices for block creation and serves as an optimal reference for contributors.

⚠️ Nits are welcome on this PR. I want this as good as I can possibly make it.
This includes nits on docstrings and comments

Checklist

• Changes clearly listed
• Reviews requested to confirm best practices

[netlify]

✅ Deploy Preview for auto-gpt-docs-dev canceled.

Name	Link
🔨 Latest commit	8aba4a5
🔍 Latest deploy log	https://app.netlify.com/sites/auto-gpt-docs-dev/deploys/67d17719a510320008dcf118

[deepsource-io]

Here's the code health analysis summary for commits c1e3294..8aba4a5. View details on DeepSource ↗.

Analysis Summary

Analyzer	Status	Summary	Link
JavaScript	✅ Success		View Check ↗
Python	✅ Success	❗ 2 occurences introduced 🎯 1 occurence resolved	View Check ↗

---

💡 If you’re a repository administrator, you can configure the quality gates from the settings.

[netlify]

✅ Deploy Preview for auto-gpt-docs canceled.

Name	Link
🔨 Latest commit	8aba4a5
🔍 Latest deploy log	https://app.netlify.com/sites/auto-gpt-docs/deploys/67d17719210bd00008ab7607

[ntindle]

This is missing

• _api.py and _auth.py file formats for when you have more than one related block
• How to split blocks up into different files that are related
• best practices/examples of inputs and output formatting such as yielding the list and the items in the list as two separate things

im sure I’ll think of more but this is a good start

[Swiftyos]

I've made all the changes you've suggested. Though still need to make examples of these:

best practices/examples of inputs and output formatting such as yielding the list and the items in the list as two separate things

[AutoGPT-Agent]

The PR has several issues that need addressing before it can be approved:

1. The PR template is not properly filled out - the checkboxes for code changes and configuration changes are not marked
2. The test plan section is empty and not filled out despite this being a code change
3. Configuration changes are present (.env.example modified) but the corresponding checklist items are not checked off
4. While the PR description explains the purpose, it doesn't provide a clear list of changes as required

[AutoGPT-Agent]

The PR is well structured and follows most requirements but has some notable issues:

1. The PR template is filled out but missing some key checkmarks - particularly around the test plan which seems important for an example implementation
2. While the PR title has a scope 'docs(platform)', this may not be fully accurate since it's adding actual implementation code, not just documentation
3. The template appears to be partially filled but some sections like the test plan details are left unchecked

However, the implementation itself appears solid with appropriate documentation and the author explicitly states this is meant as an example PR for best practices, acknowledging it's not intended for merging. The changes are well documented and the implementation appears complete.

[majdyz]

Why is this client boilerplate needed?

[Swiftyos]

The purpose of this PR is capture the best practices of adding a new integration block. Creating a client seems to be how we have implemented this with other bocks.

Do you feel this is not best practice?
If so what would you suggest?

[majdyz]

Yes I think it makes sense when the SDK support is missing.

But stuff here getting copied over and over without any refactoring: these ended up being duplicated in the HTTP client part:

• Setting up Request class
• Set content type, passing header to Authorization
• Adding to trusted origin (which is not actually needed)

Other issues:

• Return the value of Dict which should be properly typed. (also the seems like our convention is using dict/list | None as opposed to Dict List Optional)

• Creating a custom exception, then catching it within the same class, shouldn't this be the other way, catching an HTTP error and wrapping it to the custom exception (if it's even needed)?

[ntindle]

we can use pydantic objects and that should be preferred except when there's a fuck off big response from the API. That case should be model dumpted to a "dict" and attached as a raw object. Github Apollo/smartlead do this

[majdyz]

Does this have to be a single event_data and be parsed manually later by another block?
The best practice is to avoid returning complex object as much as possible.

[Swiftyos]

@Pwuts can you help with best practice here please

[ntindle]

see generic webhook block pr

[majdyz]

Sorry I've been adding comment and forgot to submit it

[Pwuts]

so what's the difference between advanced and hidden?

[kcze]

Advanced are shown when user clicks Advanced toggle, I guess hidden are permanently hidden.
But then, does it need to be SchemaField?
That means it's still sent to the frontend unless this is explicitly avoided and possibly can be force-provided with data from the user, is this ok?

[Pwuts]

this should be more specifically typed if possible

[kcze]

I second this

[kcze]

1. We return weakly typed dict here; if function returns a specific structure it'd be better to return TypedDict/class/namedtuple or even pydantic model.
2. Why return empty string or id as separate item? Can't we just return it inside the dict?

[kcze]

Advanced are shown when user clicks Advanced toggle, I guess hidden are permanently hidden.
But then, does it need to be SchemaField?
That means it's still sent to the frontend unless this is explicitly avoided and possibly can be force-provided with data from the user, is this ok?

[kcze]

I'd explicitly mention not to include real keys here to not leak them.

[kcze]

Suggested change

	headers: Dict[str, str] = {
	headers: dict[str, str] = {

[kcze]

I second this

[AutoGPT-Agent]

The PR is well structured and follows most guidelines, but has some issues: 1) While the PR title has a scope in parentheses, it doesn't follow the exact conventional commit format which should be 'feat(scope): message' rather than docs(scope). 2) There is a partial checklist where some sections are filled but others are left incomplete (like the test plan section which has checkboxes but no indication if they were completed). 3) Changes in data/*.py files correctly handle user_id access.

[AutoGPT-Agent]

The PR is well structured and follows most requirements but has some minor issues that need addressing: 1) While the PR title has a scope 'docs(platform)', it appears this is more of a feat/feature PR since it's adding new example blocks and functionality rather than just documentation 2) The checklist in the template is partially filled - only 2 items are checked while others remain unchecked without explicit removal of inapplicable sections.

[AutoGPT-Agent]

The PR is well structured and follows the established patterns, but has a few issues that need to be addressed:

1. The PR title should contain a more specific scope than just 'docs' since this includes actual code changes - something like 'feat(blocks)' would be more appropriate
2. The PR template needs to be properly filled out - while they've included some items, the test plan and code changes checklist sections are not fully completed as required
3. The env.example update is documented but not explicitly checked off in the configuration changes section

However, these are relatively minor issues and the actual code changes look solid - proper user_id handling in data files, good documentation, and follows established patterns. The author also explicitly asks for feedback to improve it further.