Skip to content

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.

feat(blocks): add AutoPilotBlock for invoking AutoPilot from graphs (#12439)

Zamil Majdy5d9a169e04bd
diff --git a/autogpt_platform/backend/backend/blocks/autopilot.py b/autogpt_platform/backend/backend/blocks/autopilot.py
new file mode 100644
index 0000000000..88eea3fbd2
--- /dev/null
+++ b/autogpt_platform/backend/backend/blocks/autopilot.py
@@ -0,0 +1,376 @@
+from __future__ import annotations
+
+import asyncio
+import contextvars
+import json
+import logging
+from typing import TYPE_CHECKING, Any
+
+from typing_extensions import TypedDict # Needed for Python <3.12 compatibility
+
+from backend.blocks._base import (
+ Block,
+ BlockCategory,
+ BlockOutput,
+ BlockSchemaInput,
+ BlockSchemaOutput,
+)
+from backend.data.model import SchemaField
+
+if TYPE_CHECKING:
+ from backend.data.execution import ExecutionContext
+
+logger = logging.getLogger(__name__)
+
+# Block ID shared between autopilot.py and copilot prompting.py.
+AUTOPILOT_BLOCK_ID = "c069dc6b-c3ed-4c12-b6e5-d47361e64ce6"
+
+
+class ToolCallEntry(TypedDict):
+ """A single tool invocation record from an autopilot execution."""
+
+ tool_call_id: str
+ tool_name: str
+ input: Any
+ output: Any | None
+ success: bool | None
+
+
+class TokenUsage(TypedDict):
+ """Aggregated token counts from the autopilot stream."""
+
+ prompt_tokens: int
+ completion_tokens: int
+ total_tokens: int
+
+
+class AutoPilotBlock(Block):
+ """Execute tasks using AutoGPT AutoPilot with full access to platform tools.
+
+ The autopilot can manage agents, access workspace files, fetch web content,
+ run blocks, and more. This block enables sub-agent patterns (autopilot calling
+ autopilot) and scheduled autopilot execution via the agent executor.
+ """
+
+ class Input(BlockSchemaInput):
+ """Input schema for the AutoPilot block."""
+
+ prompt: str = SchemaField(
+ description=(
+ "The task or instruction for the autopilot to execute. "
+ "The autopilot has access to platform tools like agent management, "
+ "workspace files, web fetch, block execution, and more."
+ ),
+ placeholder="Find my agents and list them",
+ advanced=False,
+ )
+
+ system_context: str = SchemaField(
+ description=(
+ "Optional additional context prepended to the prompt. "
+ "Use this to constrain autopilot behavior, provide domain "
+ "context, or set output format requirements."
+ ),
+ default="",
+ advanced=True,
+ )
+
+ session_id: str = SchemaField(
+ description=(
+ "Session ID to continue an existing autopilot conversation. "
+ "Leave empty to start a new session. "
+ "Use the session_id output from a previous run to continue."
+ ),
+ default="",
+ advanced=True,
+ )
+
+ max_recursion_depth: int = SchemaField(
+ description=(
+ "Maximum nesting depth when the autopilot calls this block "
+ "recursively (sub-agent pattern). Prevents infinite loops."
+ ),
+ default=3,
+ ge=1,
+ le=10,
+ advanced=True,
+ )
+
+ # timeout_seconds removed: the SDK manages its own heartbeat-based
+ # timeouts internally; wrapping with asyncio.timeout corrupts the
+ # SDK's internal stream (see service.py CRITICAL comment).
+
+ class Output(BlockSchemaOutput):
+ """Output schema for the AutoPilot block."""
+
+ response: str = SchemaField(
+ description="The final text response from the autopilot."
+ )
+ tool_calls: list[ToolCallEntry] = SchemaField(
+ description=(
+ "List of tools called during execution. Each entry has "
+ "tool_call_id, tool_name, input, output, and success fields."
+ ),
+ )
+ conversation_history: str = SchemaField(
+ description=(
+ "Current turn messages (user prompt + assistant reply) as JSON. "
+ "It can be used for logging or analysis."
+ ),
+ )
+ session_id: str = SchemaField(
+ description=(
+ "Session ID for this conversation. "
+ "Pass this back to continue the conversation in a future run."
+ ),
+ )
+ token_usage: TokenUsage = SchemaField(
+ description=(
+ "Token usage statistics: prompt_tokens, "
+ "completion_tokens, total_tokens."
+ ),
+ )
+
+ def __init__(self):
+ super().__init__(
+ id=AUTOPILOT_BLOCK_ID,
+ description=(
+ "Execute tasks using AutoGPT AutoPilot with full access to "
+ "platform tools (agent management, workspace files, web fetch, "
+ "block execution, and more). Enables sub-agent patterns and "
+ "scheduled autopilot execution."
+ ),
+ categories={BlockCategory.AI, BlockCategory.AGENT},
+ input_schema=AutoPilotBlock.Input,
+ output_schema=AutoPilotBlock.Output,
+ test_input={
+ "prompt": "List my agents",
+ "system_context": "",
+ "session_id": "",
+ "max_recursion_depth": 3,
+ },
+ test_output=[
+ ("response", "You have 2 agents: Agent A and Agent B."),
+ ("tool_calls", []),
+ (
+ "conversation_history",
+ '[{"role": "user", "content": "List my agents"}]',
+ ),
+ ("session_id", "test-session-id"),
+ (
+ "token_usage",
+ {
+ "prompt_tokens": 100,
+ "completion_tokens": 50,
+ "total_tokens": 150,
+ },
+ ),
+ ],
+ test_mock={
+ "create_session": lambda *args, **kwargs: "test-session-id",
+ "execute_copilot": lambda *args, **kwargs: (
+ "You have 2 agents: Agent A and Agent B.",
+ [],
+ '[{"role": "user", "content": "List my agents"}]',
+ "test-session-id",
+ {
+ "prompt_tokens": 100,
+ "completion_tokens": 50,
+ "total_tokens": 150,
+ },
+ ),
+ },
+ )
+
+ async def create_session(self, user_id: str) -> str:
+ """Create a new chat session and return its ID (mockable for tests)."""
+ from backend.copilot.model import create_chat_session
+
+ session = await create_chat_session(user_id)
+ return session.session_id
+
+ async def execute_copilot(
+ self,
+ prompt: str,
+ system_context: str,
+ session_id: str,
+ max_recursion_depth: int,
+ user_id: str,
+ ) -> tuple[str, list[ToolCallEntry], str, str, TokenUsage]:
+ """Invoke the copilot and collect all stream results.
+
+ Delegates to :func:`collect_copilot_response` — the shared helper that
+ consumes ``stream_chat_completion_sdk`` without wrapping it in an
+ ``asyncio.timeout`` (the SDK manages its own heartbeat-based timeouts).
+
+ Args:
+ prompt: The user task/instruction.
+ system_context: Optional context prepended to the prompt.
+ session_id: Chat session to use.
+ max_recursion_depth: Maximum allowed recursion nesting.
+ user_id: Authenticated user ID.
+
+ Returns:
+ A tuple of (response_text, tool_calls, history_json, session_id, usage).
+ """
+ from backend.copilot.sdk.collect import collect_copilot_response
+
+ tokens = _check_recursion(max_recursion_depth)
+ try:
+ effective_prompt = prompt
+ if system_context:
+ effective_prompt = f"[System Context: {system_context}]\n\n{prompt}"
+
+ result = await collect_copilot_response(
+ session_id=session_id,
+ message=effective_prompt,
+ user_id=user_id,
+ )
+
+ # Build a lightweight conversation summary from streamed data.
+ turn_messages: list[dict[str, Any]] = [
+ {"role": "user", "content": effective_prompt},
+ ]
+ if result.tool_calls:
+ turn_messages.append(
+ {
+ "role": "assistant",
+ "content": result.response_text,
+ "tool_calls": result.tool_calls,
+ }
+ )
+ else:
+ turn_messages.append(
+ {"role": "assistant", "content": result.response_text}
+ )
+ history_json = json.dumps(turn_messages, default=str)
+
+ tool_calls: list[ToolCallEntry] = [
+ {
+ "tool_call_id": tc["tool_call_id"],
+ "tool_name": tc["tool_name"],
+ "input": tc["input"],
+ "output": tc["output"],
+ "success": tc["success"],
+ }
+ for tc in result.tool_calls
+ ]
+
+ usage: TokenUsage = {
+ "prompt_tokens": result.prompt_tokens,
+ "completion_tokens": result.completion_tokens,
+ "total_tokens": result.total_tokens,
+ }
+
+ return (
+ result.response_text,
+ tool_calls,
+ history_json,
+ session_id,
+ usage,
+ )
+ finally:
+ _reset_recursion(tokens)
+
+ async def run(
+ self,
+ input_data: Input,
+ *,
+ execution_context: ExecutionContext,
+ **kwargs,
+ ) -> BlockOutput:
+ """Validate inputs, invoke the autopilot, and yield structured outputs.
+
+ Yields session_id even on failure so callers can inspect/resume the session.
+ """
+ if not input_data.prompt.strip():
+ yield "error", "Prompt cannot be empty."
+ return
+
+ if not execution_context.user_id:
+ yield "error", "Cannot run autopilot without an authenticated user."
+ return
+
+ if input_data.max_recursion_depth < 1:
+ yield "error", "max_recursion_depth must be at least 1."
+ return
+
+ # Create session eagerly so the user always gets the session_id,
+ # even if the downstream stream fails (avoids orphaned sessions).
+ sid = input_data.session_id
+ if not sid:
+ sid = await self.create_session(execution_context.user_id)
+
+ # NOTE: No asyncio.timeout() here — the SDK manages its own
+ # heartbeat-based timeouts internally. Wrapping with asyncio.timeout
+ # would cancel the task mid-flight, corrupting the SDK's internal
+ # anyio memory stream (see service.py CRITICAL comment).
+ try:
+ response, tool_calls, history, _, usage = await self.execute_copilot(
+ prompt=input_data.prompt,
+ system_context=input_data.system_context,
+ session_id=sid,
+ max_recursion_depth=input_data.max_recursion_depth,
+ user_id=execution_context.user_id,
+ )
+
+ yield "response", response
+ yield "tool_calls", tool_calls
+ yield "conversation_history", history
+ yield "session_id", sid
+ yield "token_usage", usage
+ except asyncio.CancelledError:
+ yield "session_id", sid
+ yield "error", "AutoPilot execution was cancelled."
+ raise
+ except Exception as exc:
+ yield "session_id", sid
+ yield "error", str(exc)
+
+
+# ---------------------------------------------------------------------------
+# Helpers – placed after the block class for top-down readability.
+# ---------------------------------------------------------------------------
+
+# Task-scoped recursion depth counter & chain-wide limit.
+# contextvars are scoped to the current asyncio task, so concurrent
+# graph executions each get independent counters.
+_autopilot_recursion_depth: contextvars.ContextVar[int] = contextvars.ContextVar(
+ "_autopilot_recursion_depth", default=0
+)
+_autopilot_recursion_limit: contextvars.ContextVar[int | None] = contextvars.ContextVar(
+ "_autopilot_recursion_limit", default=None
+)
+
+
+def _check_recursion(
+ max_depth: int,
+) -> tuple[contextvars.Token[int], contextvars.Token[int | None]]:
+ """Check and increment recursion depth.
+
+ Returns ContextVar tokens that must be passed to ``_reset_recursion``
+ when the caller exits to restore the previous depth.
+
+ Raises:
+ RuntimeError: If the current depth already meets or exceeds the limit.
+ """
+ current = _autopilot_recursion_depth.get()
+ inherited = _autopilot_recursion_limit.get()
+ limit = max_depth if inherited is None else min(inherited, max_depth)
+ if current >= limit:
+ raise RuntimeError(
+ f"AutoPilot recursion depth limit reached ({limit}). "
+ "The autopilot has called itself too many times."
+ )
+ return (
+ _autopilot_recursion_depth.set(current + 1),
+ _autopilot_recursion_limit.set(limit),
+ )
+
+
+def _reset_recursion(
+ tokens: tuple[contextvars.Token[int], contextvars.Token[int | None]],
+) -> None:
+ """Restore recursion depth and limit to their previous values."""
+ _autopilot_recursion_depth.reset(tokens[0])
+ _autopilot_recursion_limit.reset(tokens[1])
diff --git a/autogpt_platform/backend/backend/blocks/test/test_autopilot.py b/autogpt_platform/backend/backend/blocks/test/test_autopilot.py
new file mode 100644
index 0000000000..2526bf1455
--- /dev/null
+++ b/autogpt_platform/backend/backend/blocks/test/test_autopilot.py
@@ -0,0 +1,223 @@
+"""Tests for AutoPilotBlock: recursion guard, streaming, validation, and error paths."""
+
+import asyncio
+from unittest.mock import AsyncMock
+
+import pytest
+
+from backend.blocks.autopilot import (
+ AUTOPILOT_BLOCK_ID,
+ AutoPilotBlock,
+ _autopilot_recursion_depth,
+ _autopilot_recursion_limit,
+ _check_recursion,
+ _reset_recursion,
+)
+from backend.data.execution import ExecutionContext
+
+
+def _make_context(user_id: str = "test-user-123") -> ExecutionContext:
+ """Helper to build an ExecutionContext for tests."""
+ return ExecutionContext(
+ user_id=user_id,
+ graph_id="graph-1",
+ graph_exec_id="gexec-1",
+ graph_version=1,
+ node_id="node-1",
+ node_exec_id="nexec-1",
+ )
+
+
+# ---------------------------------------------------------------------------
+# Recursion guard unit tests
+# ---------------------------------------------------------------------------
+
+
+class TestCheckRecursion:
+ """Unit tests for _check_recursion / _reset_recursion."""
+
+ def test_first_call_increments_depth(self):
+ tokens = _check_recursion(3)
+ try:
+ assert _autopilot_recursion_depth.get() == 1
+ assert _autopilot_recursion_limit.get() == 3
+ finally:
+ _reset_recursion(tokens)
+
+ def test_reset_restores_previous_values(self):
+ assert _autopilot_recursion_depth.get() == 0
+ assert _autopilot_recursion_limit.get() is None
+ tokens = _check_recursion(5)
+ _reset_recursion(tokens)
+ assert _autopilot_recursion_depth.get() == 0
+ assert _autopilot_recursion_limit.get() is None
+
+ def test_exceeding_limit_raises(self):
+ t1 = _check_recursion(2)
+ try:
+ t2 = _check_recursion(2)
+ try:
+ with pytest.raises(RuntimeError, match="recursion depth limit"):
+ _check_recursion(2)
+ finally:
+ _reset_recursion(t2)
+ finally:
+ _reset_recursion(t1)
+
+ def test_nested_calls_respect_inherited_limit(self):
+ """Inner call with higher max_depth still respects outer limit."""
+ t1 = _check_recursion(2) # sets limit=2
+ try:
+ t2 = _check_recursion(10) # inner wants 10, but inherited is 2
+ try:
+ # depth is now 2, limit is min(10, 2) = 2 → should raise
+ with pytest.raises(RuntimeError, match="recursion depth limit"):
+ _check_recursion(10)
+ finally:
+ _reset_recursion(t2)
+ finally:
+ _reset_recursion(t1)
+
+ def test_limit_of_one_blocks_immediately_on_second_call(self):
+ t1 = _check_recursion(1)
+ try:
+ with pytest.raises(RuntimeError):
+ _check_recursion(1)
+ finally:
+ _reset_recursion(t1)
+
+
+# ---------------------------------------------------------------------------
+# AutoPilotBlock.run() validation tests
+# ---------------------------------------------------------------------------
+
+
+class TestRunValidation:
+ """Tests for input validation in AutoPilotBlock.run()."""
+
+ @pytest.fixture
+ def block(self):
+ return AutoPilotBlock()
+
+ @pytest.mark.asyncio
+ async def test_empty_prompt_yields_error(self, block):
+ block.Input # ensure schema is accessible
+ input_data = block.Input(prompt=" ", max_recursion_depth=3)
+ ctx = _make_context()
+ outputs = {}
+ async for name, value in block.run(input_data, execution_context=ctx):
+ outputs[name] = value
+ assert outputs.get("error") == "Prompt cannot be empty."
+ assert "response" not in outputs
+
+ @pytest.mark.asyncio
+ async def test_missing_user_id_yields_error(self, block):
+ input_data = block.Input(prompt="hello", max_recursion_depth=3)
+ ctx = _make_context(user_id="")
+ outputs = {}
+ async for name, value in block.run(input_data, execution_context=ctx):
+ outputs[name] = value
+ assert "authenticated user" in outputs.get("error", "")
+
+ @pytest.mark.asyncio
+ async def test_successful_run_yields_all_outputs(self, block):
+ """With execute_copilot mocked, run() should yield all 5 success outputs."""
+ mock_result = (
+ "Hello world",
+ [],
+ '[{"role":"user","content":"hi"}]',
+ "sess-abc",
+ {"prompt_tokens": 10, "completion_tokens": 5, "total_tokens": 15},
+ )
+ block.execute_copilot = AsyncMock(return_value=mock_result)
+ block.create_session = AsyncMock(return_value="sess-abc")
+
+ input_data = block.Input(prompt="hi", max_recursion_depth=3)
+ ctx = _make_context()
+ outputs = {}
+ async for name, value in block.run(input_data, execution_context=ctx):
+ outputs[name] = value
+
+ assert outputs["response"] == "Hello world"
+ assert outputs["tool_calls"] == []
+ assert outputs["session_id"] == "sess-abc"
+ assert outputs["token_usage"]["total_tokens"] == 15
+ assert "error" not in outputs
+
+ @pytest.mark.asyncio
+ async def test_exception_yields_error(self, block):
+ """On unexpected failure, run() should yield an error output."""
+ block.execute_copilot = AsyncMock(side_effect=RuntimeError("boom"))
+ block.create_session = AsyncMock(return_value="sess-fail")
+
+ input_data = block.Input(prompt="do something", max_recursion_depth=3)
+ ctx = _make_context()
+ outputs = {}
+ async for name, value in block.run(input_data, execution_context=ctx):
+ outputs[name] = value
+
+ assert outputs["session_id"] == "sess-fail"
+ assert "boom" in outputs.get("error", "")
+
+ @pytest.mark.asyncio
+ async def test_cancelled_error_yields_error_and_reraises(self, block):
+ """CancelledError should yield error, then re-raise."""
+ block.execute_copilot = AsyncMock(side_effect=asyncio.CancelledError())
+ block.create_session = AsyncMock(return_value="sess-cancel")
+
+ input_data = block.Input(prompt="do something", max_recursion_depth=3)
+ ctx = _make_context()
+ outputs = {}
+ with pytest.raises(asyncio.CancelledError):
+ async for name, value in block.run(input_data, execution_context=ctx):
+ outputs[name] = value
+
+ assert outputs["session_id"] == "sess-cancel"
+ assert "cancelled" in outputs.get("error", "").lower()
+
+ @pytest.mark.asyncio
+ async def test_existing_session_id_skips_create(self, block):
+ """When session_id is provided, create_session should not be called."""
+ mock_result = (
+ "ok",
+ [],
+ "[]",
+ "existing-sid",
+ {"prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0},
+ )
+ block.execute_copilot = AsyncMock(return_value=mock_result)
+ block.create_session = AsyncMock()
+
+ input_data = block.Input(
+ prompt="test", session_id="existing-sid", max_recursion_depth=3
+ )
+ ctx = _make_context()
+ async for _ in block.run(input_data, execution_context=ctx):
+ pass
+
+ block.create_session.assert_not_called()
+
+
+# ---------------------------------------------------------------------------
+# Block registration / ID tests
+# ---------------------------------------------------------------------------
+
+
+class TestBlockRegistration:
+ def test_block_id_matches_constant(self):
+ block = AutoPilotBlock()
+ assert block.id == AUTOPILOT_BLOCK_ID
+
+ def test_max_recursion_depth_has_upper_bound(self):
+ """Schema should enforce le=10."""
+ schema = AutoPilotBlock.Input.model_json_schema()
+ max_rec = schema["properties"]["max_recursion_depth"]
+ assert (
+ max_rec.get("maximum") == 10 or max_rec.get("exclusiveMaximum", 999) <= 11
+ )
+
+ def test_output_schema_has_no_duplicate_error_field(self):
+ """Output should inherit error from BlockSchemaOutput, not redefine it."""
+ # The field should exist (inherited) but there should be no explicit
+ # redefinition. We verify by checking the class __annotations__ directly.
+ assert "error" not in AutoPilotBlock.Output.__annotations__
diff --git a/autogpt_platform/backend/backend/copilot/prompting.py b/autogpt_platform/backend/backend/copilot/prompting.py
index 2c5b733259..8815f4ce33 100644
--- a/autogpt_platform/backend/backend/copilot/prompting.py
+++ b/autogpt_platform/backend/backend/copilot/prompting.py
@@ -6,10 +6,11 @@ handling the distinction between:
- Local mode vs E2B mode (storage/filesystem differences)
"""
+from backend.blocks.autopilot import AUTOPILOT_BLOCK_ID
from backend.copilot.tools import TOOL_REGISTRY
# Shared technical notes that apply to both SDK and baseline modes
-_SHARED_TOOL_NOTES = """\
+_SHARED_TOOL_NOTES = f"""\
### Sharing files with the user
After saving a file to the persistent workspace with `write_workspace_file`,
@@ -81,18 +82,34 @@ that would be corrupted by text encoding.
Example — committing an image file to GitHub:
```json
-{
- "files": [{
+{{
+ "files": [{{
"path": "docs/hero.png",
"content": "workspace://abc123#image/png",
"operation": "upsert"
- }]
-}
+ }}]
+}}
```
### Sub-agent tasks
- When using the Task tool, NEVER set `run_in_background` to true.
All tasks must run in the foreground.
+
+### Delegating to another autopilot (sub-autopilot pattern)
+Use the **AutoPilotBlock** (`run_block` with block_id
+`{AUTOPILOT_BLOCK_ID}`) to delegate a task to a fresh
+autopilot instance. The sub-autopilot has its own full tool set and can
+perform multi-step work autonomously.
+
+- **Input**: `prompt` (required) — the task description.
+ Optional: `system_context` to constrain behavior, `session_id` to
+ continue a previous conversation, `max_recursion_depth` (default 3).
+- **Output**: `response` (text), `tool_calls` (list), `session_id`
+ (for continuation), `conversation_history`, `token_usage`.
+
+Use this when a task is complex enough to benefit from a separate
+autopilot context, e.g. "research X and write a report" while the
+parent autopilot handles orchestration.
"""
diff --git a/autogpt_platform/backend/backend/copilot/sdk/__init__.py b/autogpt_platform/backend/backend/copilot/sdk/__init__.py
index db97fdd8fb..905e5351cc 100644
--- a/autogpt_platform/backend/backend/copilot/sdk/__init__.py
+++ b/autogpt_platform/backend/backend/copilot/sdk/__init__.py
@@ -24,10 +24,14 @@ from typing import TYPE_CHECKING, Any
# Static imports for type checkers so they can resolve __all__ entries
# without executing the lazy-import machinery at runtime.
if TYPE_CHECKING:
+ from .collect import CopilotResult as CopilotResult
+ from .collect import collect_copilot_response as collect_copilot_response
from .service import stream_chat_completion_sdk as stream_chat_completion_sdk
from .tool_adapter import create_copilot_mcp_server as create_copilot_mcp_server
__all__ = [
+ "CopilotResult",
+ "collect_copilot_response",
"stream_chat_completion_sdk",
"create_copilot_mcp_server",
]
@@ -35,6 +39,8 @@ __all__ = [
# Dispatch table for PEP 562 lazy imports. Each entry is a (module, attr)
# pair so new exports can be added without touching __getattr__ itself.
_LAZY_IMPORTS: dict[str, tuple[str, str]] = {
+ "CopilotResult": (".collect", "CopilotResult"),
+ "collect_copilot_response": (".collect", "collect_copilot_response"),
"stream_chat_completion_sdk": (".service", "stream_chat_completion_sdk"),
"create_copilot_mcp_server": (".tool_adapter", "create_copilot_mcp_server"),
}
diff --git a/autogpt_platform/backend/backend/copilot/sdk/collect.py b/autogpt_platform/backend/backend/copilot/sdk/collect.py
new file mode 100644
index 0000000000..ea687a98d7
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/sdk/collect.py
@@ -0,0 +1,108 @@
+"""Public helpers for consuming a copilot stream as a simple request-response.
+
+This module exposes :class:`CopilotResult` and :func:`collect_copilot_response`
+so that callers (e.g. the AutoPilot block) can consume the copilot stream
+without implementing their own event loop.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class CopilotResult:
+ """Aggregated result from consuming a copilot stream.
+
+ Returned by :func:`collect_copilot_response` so callers don't need to
+ implement their own event-loop over the raw stream events.
+ """
+
+ __slots__ = (
+ "response_text",
+ "tool_calls",
+ "prompt_tokens",
+ "completion_tokens",
+ "total_tokens",
+ )
+
+ def __init__(self) -> None:
+ self.response_text: str = ""
+ self.tool_calls: list[dict[str, Any]] = []
+ self.prompt_tokens: int = 0
+ self.completion_tokens: int = 0
+ self.total_tokens: int = 0
+
+
+async def collect_copilot_response(
+ *,
+ session_id: str,
+ message: str,
+ user_id: str,
+ is_user_message: bool = True,
+) -> CopilotResult:
+ """Consume :func:`stream_chat_completion_sdk` and return aggregated results.
+
+ This is the recommended entry-point for callers that need a simple
+ request-response interface (e.g. the AutoPilot block) rather than
+ streaming individual events. It avoids duplicating the event-collection
+ logic and does NOT wrap the stream in ``asyncio.timeout`` — the SDK
+ manages its own heartbeat-based timeouts internally.
+
+ Args:
+ session_id: Chat session to use.
+ message: The user message / prompt.
+ user_id: Authenticated user ID.
+ is_user_message: Whether this is a user-initiated message.
+
+ Returns:
+ A :class:`CopilotResult` with the aggregated response text,
+ tool calls, and token usage.
+
+ Raises:
+ RuntimeError: If the stream yields a ``StreamError`` event.
+ """
+ from backend.copilot.response_model import (
+ StreamError,
+ StreamTextDelta,
+ StreamToolInputAvailable,
+ StreamToolOutputAvailable,
+ StreamUsage,
+ )
+
+ from .service import stream_chat_completion_sdk
+
+ result = CopilotResult()
+ response_parts: list[str] = []
+ tool_calls_by_id: dict[str, dict[str, Any]] = {}
+
+ async for event in stream_chat_completion_sdk(
+ session_id=session_id,
+ message=message,
+ is_user_message=is_user_message,
+ user_id=user_id,
+ ):
+ if isinstance(event, StreamTextDelta):
+ response_parts.append(event.delta)
+ elif isinstance(event, StreamToolInputAvailable):
+ entry: dict[str, Any] = {
+ "tool_call_id": event.toolCallId,
+ "tool_name": event.toolName,
+ "input": event.input,
+ "output": None,
+ "success": None,
+ }
+ result.tool_calls.append(entry)
+ tool_calls_by_id[event.toolCallId] = entry
+ elif isinstance(event, StreamToolOutputAvailable):
+ if tc := tool_calls_by_id.get(event.toolCallId):
+ tc["output"] = event.output
+ tc["success"] = event.success
+ elif isinstance(event, StreamUsage):
+ result.prompt_tokens += event.prompt_tokens
+ result.completion_tokens += event.completion_tokens
+ result.total_tokens += event.total_tokens
+ elif isinstance(event, StreamError):
+ raise RuntimeError(f"Copilot error: {event.errorText}")
+
+ result.response_text = "".join(response_parts)
+ return result
diff --git a/autogpt_platform/backend/backend/util/text.py b/autogpt_platform/backend/backend/util/text.py
index 6258b42a1a..b1e7eb2f85 100644
--- a/autogpt_platform/backend/backend/util/text.py
+++ b/autogpt_platform/backend/backend/util/text.py
@@ -260,6 +260,7 @@ class _RestrictedEnvironment(SandboxedEnvironment):
# Mirrors the frontend exception list in frontend/src/lib/utils.ts.
_CAMELCASE_EXCEPTIONS: dict[str, str] = {
"Auto GPT": "AutoGPT",
+ "Auto Pilot": "AutoPilot",
"Open AI": "OpenAI",
"You Tube": "YouTube",
"Git Hub": "GitHub",
diff --git a/autogpt_platform/backend/scripts/generate_block_docs.py b/autogpt_platform/backend/scripts/generate_block_docs.py
index 25ad0a3be7..5afb6a7aec 100644
--- a/autogpt_platform/backend/scripts/generate_block_docs.py
+++ b/autogpt_platform/backend/scripts/generate_block_docs.py
@@ -114,13 +114,19 @@ CATEGORY_FILE_MAP = {
def class_name_to_display_name(class_name: str) -> str:
"""Convert BlockClassName to 'Block Class Name'."""
+ from backend.util.text import _CAMELCASE_EXCEPTIONS
+
# Remove 'Block' suffix (only at the end, not all occurrences)
name = class_name.removesuffix("Block")
# Insert space before capitals
name = re.sub(r"([a-z])([A-Z])", r"\1 \2", name)
# Handle consecutive capitals (e.g., 'HTTPRequest' -> 'HTTP Request')
name = re.sub(r"([A-Z]+)([A-Z][a-z])", r"\1 \2", name)
- return name.strip()
+ name = name.strip()
+ # Restore brand names that shouldn't be split
+ for split_form, brand in _CAMELCASE_EXCEPTIONS.items():
+ name = name.replace(split_form, brand)
+ return name
def type_to_readable(type_schema: dict[str, Any] | Any) -> str:
diff --git a/docs/integrations/README.md b/docs/integrations/README.md
index 1ac7fc763a..9fd90e8444 100644
--- a/docs/integrations/README.md
+++ b/docs/integrations/README.md
@@ -332,7 +332,7 @@ Below is a comprehensive list of all available blocks, categorized by their prim
| [Post To Facebook](block-integrations/ayrshare/post_to_facebook.md#post-to-facebook) | Post to Facebook using Ayrshare |
| [Post To GMB](block-integrations/ayrshare/post_to_gmb.md#post-to-gmb) | Post to Google My Business using Ayrshare |
| [Post To Instagram](block-integrations/ayrshare/post_to_instagram.md#post-to-instagram) | Post to Instagram using Ayrshare |
-| [Post To Linked In](block-integrations/ayrshare/post_to_linkedin.md#post-to-linked-in) | Post to LinkedIn using Ayrshare |
+| [Post To LinkedIn](block-integrations/ayrshare/post_to_linkedin.md#post-to-linkedin) | Post to LinkedIn using Ayrshare |
| [Post To Pinterest](block-integrations/ayrshare/post_to_pinterest.md#post-to-pinterest) | Post to Pinterest using Ayrshare |
| [Post To Reddit](block-integrations/ayrshare/post_to_reddit.md#post-to-reddit) | Post to Reddit using Ayrshare |
| [Post To Snapchat](block-integrations/ayrshare/post_to_snapchat.md#post-to-snapchat) | Post to Snapchat using Ayrshare |
@@ -340,7 +340,7 @@ Below is a comprehensive list of all available blocks, categorized by their prim
| [Post To Threads](block-integrations/ayrshare/post_to_threads.md#post-to-threads) | Post to Threads using Ayrshare |
| [Post To Tik Tok](block-integrations/ayrshare/post_to_tiktok.md#post-to-tik-tok) | Post to TikTok using Ayrshare |
| [Post To X](block-integrations/ayrshare/post_to_x.md#post-to-x) | Post to X / Twitter using Ayrshare |
-| [Post To You Tube](block-integrations/ayrshare/post_to_youtube.md#post-to-you-tube) | Post to YouTube using Ayrshare |
+| [Post To YouTube](block-integrations/ayrshare/post_to_youtube.md#post-to-youtube) | Post to YouTube using Ayrshare |
| [Publish To Medium](block-integrations/misc.md#publish-to-medium) | Publishes a post to Medium |
| [Read Discord Messages](block-integrations/discord/bot_blocks.md#read-discord-messages) | Reads messages from a Discord channel using a bot token |
| [Reddit Get My Posts](block-integrations/misc.md#reddit-get-my-posts) | Fetch posts created by the authenticated Reddit user (you) |
@@ -616,6 +616,7 @@ Below is a comprehensive list of all available blocks, categorized by their prim
| Block Name | Description |
|------------|-------------|
| [Agent Executor](block-integrations/misc.md#agent-executor) | Executes an existing agent inside your agent |
+| [AutoPilot](block-integrations/misc.md#autopilot) | Execute tasks using AutoGPT AutoPilot with full access to platform tools (agent management, workspace files, web fetch, block execution, and more) |
## CRM Services
diff --git a/docs/integrations/block-integrations/ayrshare/post_to_linkedin.md b/docs/integrations/block-integrations/ayrshare/post_to_linkedin.md
index 5d062a02a3..08e82ef0b1 100644
--- a/docs/integrations/block-integrations/ayrshare/post_to_linkedin.md
+++ b/docs/integrations/block-integrations/ayrshare/post_to_linkedin.md
@@ -3,16 +3,14 @@
Blocks for posting content to LinkedIn using the Ayrshare social media management API.
<!-- END MANUAL -->
-## Post To Linked In
+## Post To LinkedIn
### What it is
Post to LinkedIn using Ayrshare
### How it works
<!-- MANUAL: how_it_works -->
-This block uses Ayrshare's social media API to post content to LinkedIn. It handles text posts, images, videos, and documents, with support for scheduling and audience targeting. The block authenticates through Ayrshare's API.
-
-LinkedIn-specific features include visibility controls, comment management, and targeting by country, seniority, industry, and other demographics (requires 300+ followers in target audience).
+_Add technical explanation here._
<!-- END MANUAL -->
### Inputs
@@ -53,11 +51,7 @@ LinkedIn-specific features include visibility controls, comment management, and
### Possible use case
<!-- MANUAL: use_case -->
-**Thought Leadership**: Automatically share blog posts or industry insights with professional network.
-
-**Scheduled Content**: Queue up a week's worth of LinkedIn posts with scheduled publishing times.
-
-**Targeted Announcements**: Share company updates targeted to specific industries or seniority levels.
+_Add practical use case examples here._
<!-- END MANUAL -->
---
diff --git a/docs/integrations/block-integrations/ayrshare/post_to_youtube.md b/docs/integrations/block-integrations/ayrshare/post_to_youtube.md
index 4210ac8571..df21c43ef3 100644
--- a/docs/integrations/block-integrations/ayrshare/post_to_youtube.md
+++ b/docs/integrations/block-integrations/ayrshare/post_to_youtube.md
@@ -3,16 +3,14 @@
Blocks for uploading videos to YouTube using the Ayrshare social media management API.
<!-- END MANUAL -->
-## Post To You Tube
+## Post To YouTube
### What it is
Post to YouTube using Ayrshare
### How it works
<!-- MANUAL: how_it_works -->
-This block uses Ayrshare's API to upload videos to YouTube. It handles video uploads with extensive metadata including titles, descriptions, tags, custom thumbnails, playlist assignment, category selection, and visibility controls (public, private, unlisted).
-
-The block supports YouTube Shorts (up to 3 minutes), geographic targeting to allow or block specific countries, subtitle files (SRT/SBV format), synthetic/AI content disclosure, kids content labeling, and subscriber notification controls. Videos can be scheduled for specific publish times.
+_Add technical explanation here._
<!-- END MANUAL -->
### Inputs
@@ -57,11 +55,7 @@ The block supports YouTube Shorts (up to 3 minutes), geographic targeting to all
### Possible use case
<!-- MANUAL: use_case -->
-**Video Publishing Pipeline**: Automate video uploads with thumbnails, descriptions, and playlist organization for content creators.
-
-**YouTube Shorts Automation**: Publish short-form vertical videos to YouTube Shorts with proper metadata and hashtags.
-
-**Multi-Region Content**: Upload videos with geographic restrictions for region-specific content licensing or compliance.
+_Add practical use case examples here._
<!-- END MANUAL -->
---
diff --git a/docs/integrations/block-integrations/misc.md b/docs/integrations/block-integrations/misc.md
index ad6300ae88..02f9cdf1f8 100644
--- a/docs/integrations/block-integrations/misc.md
+++ b/docs/integrations/block-integrations/misc.md
@@ -38,6 +38,47 @@ Input and output schemas define the expected data structure for communication be
---
+## AutoPilot
+
+### What it is
+Execute tasks using AutoGPT AutoPilot with full access to platform tools (agent management, workspace files, web fetch, block execution, and more). Enables sub-agent patterns and scheduled autopilot execution.
+
+### How it works
+<!-- MANUAL: how_it_works -->
+This block invokes the platform's copilot system directly via `stream_chat_completion_sdk`. It creates (or resumes) a chat session, streams the autopilot's response collecting text deltas, tool call details, and token usage, then returns the aggregated results. A recursion depth guard prevents infinite loops when the autopilot calls this block as a sub-agent.
+<!-- END MANUAL -->
+
+### Inputs
+
+| Input | Description | Type | Required |
+|-------|-------------|------|----------|
+| prompt | The task or instruction for the autopilot to execute. The autopilot has access to platform tools like agent management, workspace files, web fetch, block execution, and more. | str | Yes |
+| system_context | Optional additional context prepended to the prompt. Use this to constrain autopilot behavior, provide domain context, or set output format requirements. | str | No |
+| session_id | Session ID to continue an existing autopilot conversation. Leave empty to start a new session. Use the session_id output from a previous run to continue. | str | No |
+| max_recursion_depth | Maximum nesting depth when the autopilot calls this block recursively (sub-agent pattern). Prevents infinite loops. | int | No |
+
+### Outputs
+
+| Output | Description | Type |
+|--------|-------------|------|
+| error | Error message if the operation failed | str |
+| response | The final text response from the autopilot. | str |
+| tool_calls | List of tools called during execution. Each entry has tool_call_id, tool_name, input, output, and success fields. | List[ToolCallEntry] |
+| conversation_history | Current turn messages (user prompt + assistant reply) as JSON. It can be used for logging or analysis. | str |
+| session_id | Session ID for this conversation. Pass this back to continue the conversation in a future run. | str |
+| token_usage | Token usage statistics: prompt_tokens, completion_tokens, total_tokens. | TokenUsage |
+
+### Possible use case
+<!-- MANUAL: use_case -->
+**Scheduled Reports**: Schedule an autopilot to run daily that checks workspace files, summarizes recent agent activity, and posts a report.
+
+**Multi-Step AI Workflows**: Chain autopilot blocks where one gathers data and another analyzes it, enabling complex AI pipelines within the graph editor.
+
+**Sub-Agent Delegation**: Delegate a research or formatting task to a sub-autopilot while the parent agent handles orchestration.
+<!-- END MANUAL -->
+
+---
+
## Create Reddit Post
### What it is