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(backend/copilot): Streamline AutoPilot agent creation (#13579)

Reinier van der Leer0f85be0a1ee6
diff --git a/autogpt_platform/backend/backend/blocks/code_executor.py b/autogpt_platform/backend/backend/blocks/code_executor.py
index fa2c5d9791..9ae29e798d 100644
--- a/autogpt_platform/backend/backend/blocks/code_executor.py
+++ b/autogpt_platform/backend/backend/blocks/code_executor.py
@@ -60,6 +60,18 @@ TEST_CREDENTIALS_INPUT = {
}
+_MAIN_RESULT_DESCRIPTION = (
+ "The main result from the code execution (the script's final "
+ "expression). Its `json` sub-field is ONLY populated when the "
+ "result is a dict/object/map — bare lists, strings, and "
+ "numbers land in `text` as a string instead. To pass "
+ "structured data downstream via `main_result_#_json_#_<key>` "
+ "links, end the script with a key-value structure in the "
+ "script's language (e.g. `{'items': my_list}` in Python, "
+ "`({items: myList})` in JavaScript)."
+)
+
+
class MainCodeExecutionResult(BaseModel):
"""
*Pydantic model mirroring `e2b_code_interpreter.Result`*
@@ -242,10 +254,12 @@ class ExecuteCodeBlock(Block, BaseE2BExecutorMixin):
variables: dict[str, Any] = SchemaField(
title="Variables (Python/JS only)",
description=(
- "Variables defined here can be used directly in your Python or "
- "JavaScript code. Values wired in from other blocks keep their "
- "type; default values set on this node come in as strings, so parse "
- "them in your code if you need a number or other type."
+ "Variables defined here can be used directly in your code. "
+ "Each key (`variables_#_{name}`) is injected directly as a local "
+ "variable with the same name (`{name}`) in your code. "
+ "Values wired in from other blocks keep their type; default values set "
+ "on this node come in as strings, so parse them in your code "
+ "if you need a number or other type."
),
default_factory=dict,
advanced=False,
@@ -288,7 +302,8 @@ class ExecuteCodeBlock(Block, BaseE2BExecutorMixin):
class Output(BlockSchemaOutput):
main_result: MainCodeExecutionResult = SchemaField(
- title="Main Result", description="The main result from the code execution"
+ title="Main Result",
+ description=_MAIN_RESULT_DESCRIPTION,
)
results: list[CodeExecutionResult] = SchemaField(
description="List of results from the code execution"
@@ -532,7 +547,8 @@ class ExecuteCodeStepBlock(Block, BaseE2BExecutorMixin):
class Output(BlockSchemaOutput):
main_result: MainCodeExecutionResult = SchemaField(
- title="Main Result", description="The main result from the code execution"
+ title="Main Result",
+ description=_MAIN_RESULT_DESCRIPTION,
)
results: list[CodeExecutionResult] = SchemaField(
description="List of results from the code execution"
diff --git a/autogpt_platform/backend/backend/copilot/anthropic_rates.json b/autogpt_platform/backend/backend/copilot/anthropic_rates.json
index 158c517c5f..69848a1913 100644
--- a/autogpt_platform/backend/backend/copilot/anthropic_rates.json
+++ b/autogpt_platform/backend/backend/copilot/anthropic_rates.json
@@ -442,6 +442,40 @@
"supports_xhigh_reasoning_effort": true,
"tool_use_system_prompt_tokens": 346
},
+ "claude-opus-4-8": {
+ "cache_creation_input_token_cost": 6.25e-06,
+ "cache_creation_input_token_cost_above_1hr": 1e-05,
+ "cache_read_input_token_cost": 5e-07,
+ "input_cost_per_token": 5e-06,
+ "litellm_provider": "anthropic",
+ "max_input_tokens": 1000000,
+ "max_output_tokens": 128000,
+ "max_tokens": 128000,
+ "mode": "chat",
+ "output_cost_per_token": 2.5e-05,
+ "provider_specific_entry": {
+ "fast": 6.0,
+ "us": 1.1
+ },
+ "search_context_cost_per_query": {
+ "search_context_size_high": 0.01,
+ "search_context_size_low": 0.01,
+ "search_context_size_medium": 0.01
+ },
+ "supports_assistant_prefill": false,
+ "supports_computer_use": true,
+ "supports_function_calling": true,
+ "supports_max_reasoning_effort": true,
+ "supports_minimal_reasoning_effort": true,
+ "supports_pdf_input": true,
+ "supports_prompt_caching": true,
+ "supports_reasoning": true,
+ "supports_response_schema": true,
+ "supports_tool_choice": true,
+ "supports_vision": true,
+ "supports_xhigh_reasoning_effort": true,
+ "tool_use_system_prompt_tokens": 346
+ },
"claude-sonnet-4-20250514": {
"cache_creation_input_token_cost": 3.75e-06,
"cache_creation_input_token_cost_above_1hr": 6e-06,
@@ -587,6 +621,36 @@
"supports_tool_choice": true,
"supports_vision": true,
"tool_use_system_prompt_tokens": 346
+ },
+ "claude-sonnet-5": {
+ "cache_creation_input_token_cost": 3.75e-06,
+ "cache_creation_input_token_cost_above_1hr": 6e-06,
+ "cache_read_input_token_cost": 3e-07,
+ "input_cost_per_token": 3e-06,
+ "litellm_provider": "anthropic",
+ "max_input_tokens": 1000000,
+ "max_output_tokens": 128000,
+ "max_tokens": 128000,
+ "mode": "chat",
+ "output_cost_per_token": 1.5e-05,
+ "search_context_cost_per_query": {
+ "search_context_size_high": 0.01,
+ "search_context_size_low": 0.01,
+ "search_context_size_medium": 0.01
+ },
+ "supports_assistant_prefill": false,
+ "supports_computer_use": true,
+ "supports_function_calling": true,
+ "supports_max_reasoning_effort": true,
+ "supports_minimal_reasoning_effort": true,
+ "supports_pdf_input": true,
+ "supports_prompt_caching": true,
+ "supports_reasoning": true,
+ "supports_response_schema": true,
+ "supports_tool_choice": true,
+ "supports_vision": true,
+ "supports_xhigh_reasoning_effort": true,
+ "tool_use_system_prompt_tokens": 346
}
}
}
diff --git a/autogpt_platform/backend/backend/copilot/baseline/transcript_integration_test.py b/autogpt_platform/backend/backend/copilot/baseline/transcript_integration_test.py
index d0840af747..69783dc373 100644
--- a/autogpt_platform/backend/backend/copilot/baseline/transcript_integration_test.py
+++ b/autogpt_platform/backend/backend/copilot/baseline/transcript_integration_test.py
@@ -105,7 +105,7 @@ class TestResolveBaselineModel:
assert (
ChatConfig.model_fields["fast_standard_model"].default
- == "anthropic/claude-sonnet-4-6"
+ == "anthropic/claude-sonnet-5"
)
def test_fast_advanced_default_is_opus(self):
@@ -116,7 +116,7 @@ class TestResolveBaselineModel:
assert (
ChatConfig.model_fields["fast_advanced_model"].default
- == "anthropic/claude-opus-4.7"
+ == "anthropic/claude-opus-4-8"
)
def test_standard_and_advanced_cells_differ_on_fast(self):
diff --git a/autogpt_platform/backend/backend/copilot/config.py b/autogpt_platform/backend/backend/copilot/config.py
index 6140f87928..fcc812f3e7 100644
--- a/autogpt_platform/backend/backend/copilot/config.py
+++ b/autogpt_platform/backend/backend/copilot/config.py
@@ -53,7 +53,7 @@ _DEFAULT_SIMULATION_MODEL = "google/gemini-2.5-flash-lite"
# at the cloud default" so it can rewrite to ``fast_standard_model`` under
# local transport (otherwise an "advanced" tier request 404s against
# Ollama's OpenAI shim — no ``anthropic/`` slugs there).
-_DEFAULT_FAST_ADVANCED_MODEL = "anthropic/claude-opus-4.7"
+_DEFAULT_FAST_ADVANCED_MODEL = "anthropic/claude-opus-4-8"
TransportName = Literal["subscription", "openrouter", "direct_anthropic", "local"]
@@ -202,7 +202,7 @@ class ChatConfig(BaseSettings):
# ``CHAT_FAST_MODEL``) are preserved via ``validation_alias`` so
# existing deployments continue to override the same effective cell.
fast_standard_model: str = Field(
- default="anthropic/claude-sonnet-4-6",
+ default="anthropic/claude-sonnet-5",
validation_alias=AliasChoices(
"CHAT_FAST_STANDARD_MODEL",
"CHAT_FAST_MODEL",
@@ -220,7 +220,7 @@ class ChatConfig(BaseSettings):
"the cloud default — see ``_apply_local_aux_models``.",
)
thinking_standard_model: str = Field(
- default="anthropic/claude-sonnet-4-6",
+ default="anthropic/claude-sonnet-5",
validation_alias=AliasChoices(
"CHAT_THINKING_STANDARD_MODEL",
"CHAT_MODEL",
@@ -229,7 +229,7 @@ class ChatConfig(BaseSettings):
"tier. LD override: ``copilot-model-routing[thinking][standard]``.",
)
thinking_advanced_model: str = Field(
- default="anthropic/claude-opus-4.7",
+ default="anthropic/claude-opus-4-8",
validation_alias=AliasChoices(
"CHAT_THINKING_ADVANCED_MODEL",
"CHAT_ADVANCED_MODEL",
@@ -1050,7 +1050,7 @@ class ChatConfig(BaseSettings):
when the transport asks for it.
The cloud defaults are ``openai/gpt-4o-mini`` / ``google/gemini-...``
- / ``anthropic/claude-opus-4.7`` — fine on OpenRouter, instant 404
+ / ``anthropic/claude-opus-4-8`` — fine on OpenRouter, instant 404
on a local backend (no provider slugs there). Operators on the
local transport otherwise have to repeat the same Ollama slug
across half a dozen ``CHAT_*_MODEL`` envs. Only fires when the
@@ -1059,7 +1059,7 @@ class ChatConfig(BaseSettings):
Covers ``title_model`` + ``simulation_model`` (aux call sites)
AND ``fast_advanced_model`` (the "advanced" baseline tier);
without the advanced derivation, a user clicking the advanced
- toggle in the UI sends ``anthropic/claude-opus-4.7`` to Ollama
+ toggle in the UI sends ``anthropic/claude-opus-4-8`` to Ollama
and gets a model-not-found 404. The boot-time vendor validator
is skipped under local transport so this misconfig wouldn't
surface until the first advanced-tier turn.
diff --git a/autogpt_platform/backend/backend/copilot/config_test.py b/autogpt_platform/backend/backend/copilot/config_test.py
index dd4987a69c..19f210ff02 100644
--- a/autogpt_platform/backend/backend/copilot/config_test.py
+++ b/autogpt_platform/backend/backend/copilot/config_test.py
@@ -245,7 +245,7 @@ class TestSdkModelVendorCompatibility:
# aux check.
aux_api_key="or-aux-key",
)
- assert cfg.thinking_standard_model == "anthropic/claude-sonnet-4-6"
+ assert cfg.thinking_standard_model == "anthropic/claude-sonnet-5"
def test_openrouter_with_kimi_override_succeeds(self):
"""Kimi slug round-trips cleanly when OpenRouter is on — exercised
@@ -592,7 +592,7 @@ class TestLocalAuxModels:
def test_cloud_transport_does_not_inherit(self):
"""Cloud transports leave the per-field cloud defaults alone — an
operator might genuinely want gpt-4o-mini for titles even though
- their primary model is anthropic/claude-sonnet-4-6."""
+ their primary model is anthropic/claude-sonnet-5."""
cfg = ChatConfig(
use_openrouter=True,
api_key="or-key",
@@ -600,7 +600,7 @@ class TestLocalAuxModels:
)
assert cfg.title_model == "anthropic/claude-haiku-4-5"
assert cfg.simulation_model == "google/gemini-2.5-flash-lite"
- assert cfg.fast_advanced_model == "anthropic/claude-opus-4.7"
+ assert cfg.fast_advanced_model == "anthropic/claude-opus-4-8"
class TestLocalRequirementsValidator:
diff --git a/autogpt_platform/backend/backend/copilot/prompting.py b/autogpt_platform/backend/backend/copilot/prompting.py
index a2b4e99aeb..251f6ebda8 100644
--- a/autogpt_platform/backend/backend/copilot/prompting.py
+++ b/autogpt_platform/backend/backend/copilot/prompting.py
@@ -220,6 +220,14 @@ Correct flow for *any* integration request:
intermediate tool calls out of the parent context.
- Do NOT invoke `AutoPilotBlock` via `run_block`; use `run_sub_session`
instead.
+- For multi-step build/edit work, maintain a `build_state.json` workspace
+ file recording the identifiers you will need again: library agent IDs +
+ graph IDs + current versions, schedule IDs (full UUIDs), trigger/preset
+ IDs, and credential status (a short `notes` field per entry may record why
+ the entry last changed). Update it after every `create_agent`/`edit_agent`/
+ schedule change; re-read it before acting when the conversation has been
+ summarized ("session is being continued..."). Never rely on conversation
+ memory for UUIDs.
#### Closing out a task list (MANDATORY)
Before your final assistant message in a turn that used `TodoWrite`, emit
@@ -368,6 +376,23 @@ not promise a card — call the tool first, then describe it.
`connect_integration(provider="github")`. The card the tool surfaces
does the job better than the sentence.
+### Grounded claims — CRITICAL
+
+Every factual claim in your reply must be backed by a tool result from this
+turn or an earlier turn you can still see:
+
+- **Outcomes**: never state that an email was sent, an event was created, a
+ file was written, etc., unless that specific output appears in the
+ execution result. If an expected output is absent, say so and investigate —
+ do not infer success from `COMPLETED`.
+- **Run status**: `COMPLETED` with empty `outputs` is a red flag, not a
+ success. Before reporting, check `node_executions` (and `nodes_failed`)
+ for FAILED/INCOMPLETE nodes.
+- **Platform state** (schedules, agent versions, triggers, credentials):
+ verify with a read tool (`list_schedules`, `find_library_agent`, ...)
+ before asserting how things are configured — never answer from memory of
+ how the platform "should" work.
+
### Pre-flight with `validate_only`
`run_block(id, {})` is NOT always a safe probe — for blocks with no
diff --git a/autogpt_platform/backend/backend/copilot/sdk/agent_generation_guide.md b/autogpt_platform/backend/backend/copilot/sdk/agent_generation_guide.md
index cd94b12061..ebd604da38 100644
--- a/autogpt_platform/backend/backend/copilot/sdk/agent_generation_guide.md
+++ b/autogpt_platform/backend/backend/copilot/sdk/agent_generation_guide.md
@@ -15,10 +15,18 @@ Gmail, Slack, and Google Docs — which for delivery?") and **wait for
the answer**.
**Skip** when the goal already specifies every dimension (e.g. "scrape
-prices from Amazon and email me daily").
+prices from Amazon and email me daily"). Data-shape questions are usually
+better answered by sampling (`run_block`, workflow step 2) than by asking
+the user.
### Workflow for Creating/Editing Agents
+**Design once, briefly.** Pick the simplest graph that satisfies the stated
+requirements and commit; do not revisit architecture unless a requirement
+changed, validation or a run failed, or the design turns out not to fulfill
+the user's goal. Design questions that depend on data shape are answered by
+sampling (step 2), not by deliberation.
+
1. **Library check (REQUIRED before `create_agent`)**: Call
`find_library_agent(for_creation=true, goal_summary="<one-sentence summary>")`
to look for a functionally similar agent the user already owns. If
@@ -29,7 +37,16 @@ prices from Amazon and email me daily").
`library_check_ack=true` — **never set this proactively**. Builder-
bound sessions bypass this gate automatically.
-2. **Show the plan**: Once step 1 is past, call `decompose_goal` with
+2. **Sample real data BEFORE designing (data-driven agents)**: when the
+ agent will consume external data (a database, API, mailbox, feed), fetch
+ a real sample **before** planning the graph: `run_block` the reader block
+ with the user's actual source. Two benefits: you design against the real
+ field names/types instead of guesses, and missing credentials surface
+ immediately as a connect card the user can complete while you continue.
+ If the sample fails on credentials, ask the user to connect and **stop
+ designing until you've seen the data**. Skip only when the data shape is
+ fully specified by the user or trivially known.
+3. **Show the plan**: Once steps 1–2 are past, call `decompose_goal` with
plain-English steps that describe **what the agent does for the
user**, not blocks or wiring — e.g. for a YouTube summarizer:
"Accept a YouTube URL", "Fetch the transcript", "Generate a
@@ -38,45 +55,67 @@ prices from Amazon and email me daily").
continue building in the same turn. Keep `description` plain
English; put block class names and wiring verbs in the separate
`block_name` and `action` fields.
-3. **If editing**: First narrow to the specific agent by UUID, then fetch its
+4. **If editing**: First narrow to the specific agent by UUID, then fetch its
graph: `find_library_agent(query="<agent_id>", include_graph=true)`. This
returns the full graph structure (nodes + links). **Never edit blindly** —
always inspect the current graph first so you know exactly what to change.
Avoid using `include_graph=true` with broad keyword searches, as fetching
multiple graphs at once is expensive and consumes LLM context budget.
-4. **Discover blocks**: Call `find_block(query, include_schemas=true, for_agent_generation=true)` to
+5. **Discover blocks**: Call `find_block(query, for_agent_generation=true)` to
search for relevant blocks. This returns block IDs, names, descriptions,
- and full input/output schemas. The `for_agent_generation=true` flag is
+ and categories; to see a block's full input/output schema, call
+ `run_block` with the block's id and no inputs. The `for_agent_generation=true` flag is
required to surface graph-only blocks such as AgentInputBlock,
AgentDropdownInputBlock, AgentOutputBlock, OrchestratorBlock,
and WebhookBlock and MCPToolBlock. (When running MCP tools interactively
in CoPilot outside agent generation, use `run_mcp_tool` instead.)
-5. **Find library agents for sub-agent composition**: Call `find_library_agent`
+6. **Find library agents for sub-agent composition**: Call `find_library_agent`
(default mode, no `for_creation` flag) to discover reusable agents that
can be composed as sub-agents via `AgentExecutorBlock`. This is distinct
from the create-time similarity check in step 1 — here you're looking
for building blocks, not asking "does the user already have this?".
-6. **Generate/modify JSON**: Build or modify the agent JSON using block schemas:
- - Use block IDs from step 4 as `block_id` in nodes
+7. **Generate/modify JSON**: Build or modify the agent JSON using block schemas:
+ - Use block IDs from step 5 as `block_id` in nodes
- Wire outputs to inputs using links
- Set design-time config in `input_default`
- Use `AgentInputBlock` for values the user provides at runtime
- When editing, apply targeted changes and preserve unchanged parts
-7. **Write to workspace**: Save the JSON to a workspace file so the user
- can review it: `write_workspace_file(filename="agent.json", content=...)`
-8. **Validate**: Call `validate_agent_graph` with the agent JSON to check
- for errors
-9. **Fix if needed**: Call `fix_agent_graph` to auto-fix common issues,
- or fix manually based on the error descriptions. Iterate until valid.
-10. **Save**: Call `create_agent` (new) or `edit_agent` (existing) with
- the final `agent_json`.
-11. **Dry-run**: ALWAYS call `run_agent` with `dry_run=True` and
+8. **Write to workspace**: Save the JSON to a workspace file so the user
+ can review it: `write_workspace_file(filename="agent.json", content=...)`.
+ Write it **pretty-printed** (2-space indent, one field per line) — later
+ fixes then become small targeted edits instead of full-file rewrites.
+ Keep ONE canonical `agent.json`: apply changes to it in place (targeted
+ string/line edits via your file tools or `python3` + `json` in
+ `bash_exec`); never fork `agent_fixed.json` / `agent_v2.json` variants
+ and never rewrite the whole file to change a few nodes.
+9. **Validate**: Call `validate_agent_graph` with the agent JSON to check
+ for errors. For any non-trivial graph, pass the file from step 8 by
+ reference instead of re-emitting the JSON inline:
+ `agent_json="@@agptfile:workspace:///agent.json"` (a plain string — the
+ platform reads and parses the file). This avoids re-generating large
+ JSON in tool arguments, where it can get truncated.
+10. **Fix if needed**: Call `fix_agent_graph` to auto-fix common issues,
+ or fix manually based on the error descriptions. Iterate until valid.
+ Pass `write_to="agent.json"` so the fixed JSON is written back to the
+ workspace file (pretty-printed) and the response returns a file
+ reference — chain it straight into the next step without re-emitting
+ the graph.
+11. **Save**: Call `create_agent` (new) or `edit_agent` (existing) with
+ the final `agent_json` — again by file reference when it lives in a
+ file: `agent_json="@@agptfile:workspace:///agent.json"`.
+12. **Dry-run**: ALWAYS call `run_agent` with `dry_run=True` and
`wait_for_result=120` to verify the agent works end-to-end.
-12. **Inspect & fix**: Check the dry-run output for errors. If issues are
+13. **Inspect & fix**: Check the dry-run output for errors. If issues are
found, call `edit_agent` to fix and dry-run again. Repeat until the
simulation passes or the problems are clearly unfixable.
See "REQUIRED: Dry-Run Verification Loop" section below for details.
+**After every `edit_agent` on an agent that is scheduled or referenced by
+other agents**: (1) `list_schedules()` (unfiltered) and recreate any schedule
+pinned to an older version (delete + `run_agent` with cron); (2) if other
+agents call this one via `AgentExecutorBlock`, update their pinned
+`graph_version` too. Editing without this leaves the old version running.
+
### Agent JSON Structure
```json
@@ -165,7 +204,7 @@ descriptions; read and follow those when `find_block` surfaces a match.
cost orders of magnitude more than deterministic blocks. When a task has an
equivalent non-AI solution — e.g. parsing, filtering, math, string formatting,
date handling, conditionals, code execution — use the deterministic block
- (e.g. `CodeExecutionBlock`, `ConditionBlock`) instead of an LLM. Reserve AI
+ (e.g. `ExecuteCodeBlock`, `ConditionBlock`) instead of an LLM. Reserve AI
for what genuinely needs it (open-ended reasoning, summarization, generation).
Don't spend the user's money on AI for work plain logic can do.
- **Name & description**: Include `name` and `description` in the agent JSON
@@ -188,6 +227,11 @@ descriptions; read and follow those when `find_block` surfaces a match.
- **is_static links**: Set `is_static: true` when the link carries a
design-time constant (matches a field in inputSchema with a default).
- **ConditionBlock**: Needs a `StoreValueBlock` wired to its `value2` input.
+- **Datetimes & schedules**: always pass an explicit `timezone` when
+ scheduling (`run_agent` cron) and confirm the user's timezone for any
+ block that creates calendar events or timestamps; check the block schema
+ for how it expects timezone info rather than assuming ISO offsets are
+ honored.
- **StoreValueBlock vs PersistInformationBlock** — these are NOT interchangeable:
- `StoreValueBlock` (ID: `1ff065e9-88e8-4358-9d82-8dc91f622ba9`) — holds a
constant **within one run only** (ephemeral). Use it to reuse a single output value
@@ -316,8 +360,9 @@ field from `source_name: "tools"` on the Orchestrator side.
### REQUIRED: Dry-Run Verification Loop (create -> dry-run -> fix)
-After creating or editing an agent, you MUST dry-run it before telling the
-user the agent is ready. NEVER skip this step.
+After creating or editing an agent — including one-line fixes — you MUST
+dry-run it before telling the user it is ready or fixed. An edit that was
+not re-verified is not a fix. NEVER skip this step.
#### Step-by-step workflow
@@ -357,6 +402,8 @@ user the agent is ready. NEVER skip this step.
- Data flows through every link with non-null, correctly-typed values
- The final `AgentOutputBlock` contains a meaningful result
- Status is `COMPLETED`
+- Every declared AgentOutput received a non-empty value; a missing declared
+ output means a broken link even when status is COMPLETED
**Bad output** (needs fixing):
- Status is `FAILED` — check the error message for the failing node
@@ -375,6 +422,17 @@ user the agent is ready. NEVER skip this step.
so the LLM can produce a realistic mock response without connecting to the
MCP server.
+**What dry-run does NOT catch**: `ExecuteCodeBlock` scripts are simulated,
+not executed — runtime errors (name errors, encoding issues, bad JSON
+handling) only appear in a real run. Orchestrator/LLM blocks run with 1
+iteration and may return empty output without indicating failure.
+Block-parameter type mismatches that the provider API validates server-side
+(e.g. filter property types) also only fail at runtime. **Therefore: before
+declaring a production issue fixed, do one real (wet) run with realistic
+inputs — after asking the user, since wet runs have real side effects
+(emails, calendar events, credits). Tell the user what side effects the test
+will produce.**
+
### Example: Simple AI Text Processor
A minimal agent with input, processing, and output:
@@ -476,7 +534,7 @@ scheduled agent**. Only split when some runs would otherwise do nothing.
2. **Retrieve stored state**: `RetrieveInformationBlock`
(ID: `d8710fc9-6e29-481e-a7d5-165eb16f8471`), scope `within_agent`, loads
previously-seen item IDs.
-3. **Compare**: a `CodeExecutionBlock` diffs fetched items against stored
+3. **Compare**: an `ExecuteCodeBlock` diffs fetched items against stored
state and outputs the new ones (if any).
4. **Store updated state**: `PersistInformationBlock`
(ID: `1d055e55-a2b9-4547-8311-907d05b0304d`), scope `within_agent`, saves
diff --git a/autogpt_platform/backend/backend/copilot/sdk/env.py b/autogpt_platform/backend/backend/copilot/sdk/env.py
index 8aa7fa6359..815dd46706 100644
--- a/autogpt_platform/backend/backend/copilot/sdk/env.py
+++ b/autogpt_platform/backend/backend/copilot/sdk/env.py
@@ -117,12 +117,21 @@ def build_sdk_env(
env["CLAUDE_CODE_DISABLE_AUTO_MEMORY"] = "1"
env["CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC"] = "1"
# Strip Anthropic-specific beta headers that OpenRouter rejects.
- # NOTE: this disables ALL experimental betas including context-1m-2025-08-07
- # (1M context window) and context-management-2025-06-27. This is intentional:
- # OpenRouter compatibility takes priority, and Anthropic direct mode ignores
- # this flag harmlessly (those betas are not enabled there either by default).
+ # NOTE: this disables ALL experimental betas including
+ # context-management-2025-06-27. This is intentional: OpenRouter
+ # compatibility takes priority, and Anthropic direct mode ignores this
+ # flag harmlessly (those betas are not enabled there either by default).
env["CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS"] = "1"
+ # Pin the CLI's perceived context window at the 200K default. 1M context
+ # is GA (no beta header) on Sonnet 4.6+/5 and newer CLIs enable it by
+ # default via their model capability table (native_1m) or server-side
+ # flags; this kill-switch gates every 1M branch in the CLI's window
+ # resolution, so the autocompact trigger below stays anchored to 200K
+ # across SDK upgrades. (The experimental-betas flag above no longer
+ # covers 1M — it stopped being a beta.)
+ env["CLAUDE_CODE_DISABLE_1M_CONTEXT"] = "1"
+
# Auto-compaction trigger threshold (CLI default: ~93% of perceived window).
# The override caps Anthropic cache-creation cost; Moonshot routes skip it
# because their OpenRouter endpoint returns ``cache_create=0`` (no cache
@@ -133,9 +142,7 @@ def build_sdk_env(
not is_moonshot_model(model)
and config.claude_agent_autocompact_pct_override > 0
):
- env["CLAUDE_AUTOCOMPACT_PCT_OVERRIDE"] = str(
- config.claude_agent_autocompact_pct_override
- )
+ env["CLAUDE_AUTOCOMPACT_PCT_OVERRIDE"] = str(_autocompact_pct_for_model(model))
# Disable gzip on API responses to prevent ZlibError decompression
# failures (see oven-sh/bun#23149, anthropics/claude-code#18302).
@@ -148,3 +155,24 @@ def build_sdk_env(
)
return env
+
+
+# Sonnet 5's tokenizer counts ~30% more tokens than 4.x for the same text,
+# so the same 50%-of-200K trigger would compact at ~77% of the *text* budget
+# 4.x sessions get. Scaling the trigger by the inflation factor keeps the
+# effective text-equivalent context at parity (50% -> 65% = 130K tokens
+# ~= 100K 4.x-tokens' worth), without touching the perceived window.
+_SONNET_5_TOKENIZER_INFLATION = 1.3
+
+
+def _autocompact_pct_for_model(model: str | None) -> int:
+ """Auto-compaction trigger percentage for ``model``.
+
+ Base value from config; Sonnet 5 is scaled up by the tokenizer-inflation
+ factor (capped at 90, below the CLI's ~93% internal ceiling) so its
+ compaction fires at the same text-equivalent point as on 4.x models.
+ """
+ pct = config.claude_agent_autocompact_pct_override
+ if model and "claude-sonnet-5" in model:
+ pct = min(round(pct * _SONNET_5_TOKENIZER_INFLATION), 90)
+ return pct
diff --git a/autogpt_platform/backend/backend/copilot/sdk/env_test.py b/autogpt_platform/backend/backend/copilot/sdk/env_test.py
index 209937d9d8..0f6ed78483 100644
--- a/autogpt_platform/backend/backend/copilot/sdk/env_test.py
+++ b/autogpt_platform/backend/backend/copilot/sdk/env_test.py
@@ -502,3 +502,68 @@ class TestBuildSdkEnvLocalTransportGuard:
RuntimeError, match=r"transport 'local'.*doesn't support the SDK"
):
build_sdk_env()
+
+
+class TestAutocompactPctSonnet5Scaling:
+ """Sonnet 5's trigger percentage is scaled by the ~1.3x tokenizer
+ inflation so compaction fires at the same text-equivalent point as on
+ 4.x models (50% -> 65% = 130K tokens of the pinned 200K window
+ ~= 100K 4.x-tokens' worth)."""
+
+ @pytest.mark.parametrize("model", ["anthropic/claude-sonnet-5", "claude-sonnet-5"])
+ def test_sonnet_5_scaled(self, model):
+ cfg = _make_config(
+ use_openrouter=False, claude_agent_autocompact_pct_override=50
+ )
+ with patch("backend.copilot.sdk.env.config", cfg):
+ from backend.copilot.sdk.env import build_sdk_env
+
+ result = build_sdk_env(model=model)
+
+ assert result.get("CLAUDE_AUTOCOMPACT_PCT_OVERRIDE") == "65"
+
+ @pytest.mark.parametrize(
+ "model",
+ [
+ "anthropic/claude-sonnet-4-6",
+ "anthropic/claude-sonnet-4-5", # substring near-miss guard
+ "anthropic/claude-opus-4-7",
+ ],
+ )
+ def test_non_sonnet_5_not_scaled(self, model):
+ cfg = _make_config(
+ use_openrouter=False, claude_agent_autocompact_pct_override=50
+ )
+ with patch("backend.copilot.sdk.env.config", cfg):
+ from backend.copilot.sdk.env import build_sdk_env
+
+ result = build_sdk_env(model=model)
+
+ assert result.get("CLAUDE_AUTOCOMPACT_PCT_OVERRIDE") == "50"
+
+ def test_scaled_value_capped_below_cli_ceiling(self):
+ cfg = _make_config(
+ use_openrouter=False, claude_agent_autocompact_pct_override=80
+ )
+ with patch("backend.copilot.sdk.env.config", cfg):
+ from backend.copilot.sdk.env import build_sdk_env
+
+ result = build_sdk_env(model="anthropic/claude-sonnet-5")
+
+ assert result.get("CLAUDE_AUTOCOMPACT_PCT_OVERRIDE") == "90"
+
+
+class TestContextWindowPin:
+ """CLAUDE_CODE_DISABLE_1M_CONTEXT pins the CLI's perceived window at
+ 200K: 1M context is GA (not beta-gated) on Sonnet 4.6+/5, so the
+ experimental-betas flag alone no longer prevents a future CLI from
+ silently moving the autocompact trigger to ~500K."""
+
+ def test_disable_1m_context_set_in_all_modes(self):
+ cfg = _make_config(use_openrouter=False)
+ with patch("backend.copilot.sdk.env.config", cfg):
+ from backend.copilot.sdk.env import build_sdk_env
+
+ result = build_sdk_env(model="anthropic/claude-sonnet-5")
+
+ assert result.get("CLAUDE_CODE_DISABLE_1M_CONTEXT") == "1"
diff --git a/autogpt_platform/backend/backend/copilot/sdk/file_ref.py b/autogpt_platform/backend/backend/copilot/sdk/file_ref.py
index 6c638fc04e..73d8c48bf1 100644
--- a/autogpt_platform/backend/backend/copilot/sdk/file_ref.py
+++ b/autogpt_platform/backend/backend/copilot/sdk/file_ref.py
@@ -371,15 +371,17 @@ async def expand_file_refs_in_args(
value, user_id, session, raise_on_error=True
)
if isinstance(value, dict):
- # When the schema says this is an object but doesn't define
- # inner properties, skip expansion — the caller (e.g.
+ # When the schema says this is (or can be) an object but doesn't
+ # define inner properties, skip expansion — the caller (e.g.
# RunBlockTool) will expand with the actual nested schema.
- if (
- prop_schema is not None
- and prop_schema.get("type") == "object"
- and "properties" not in prop_schema
- ):
- return value
+ # ``type`` may be a union list, e.g. ["object", "string"] on
+ # ``agent_json`` parameters.
+ if prop_schema is not None and "properties" not in prop_schema:
+ prop_type = prop_schema.get("type")
+ if prop_type == "object" or (
+ isinstance(prop_type, list) and "object" in prop_type
+ ):
+ return value
nested_props = (prop_schema or {}).get("properties", {})
return {
k: await _expand(v, prop_schema=nested_props.get(k))
diff --git a/autogpt_platform/backend/backend/copilot/sdk/file_ref_test.py b/autogpt_platform/backend/backend/copilot/sdk/file_ref_test.py
index 03b0701cce..f876a0eec4 100644
--- a/autogpt_platform/backend/backend/copilot/sdk/file_ref_test.py
+++ b/autogpt_platform/backend/backend/copilot/sdk/file_ref_test.py
@@ -1976,3 +1976,60 @@ async def test_bare_ref_parquet_nan_replaced_with_none():
for cell in row:
if isinstance(cell, float):
assert not math.isnan(cell), f"NaN leaked: {row}"
+
+
+async def test_union_object_string_bare_ref_parses_to_dict():
+ """A bare ref in a slot typed ["object", "string"] (e.g. agent_json)
+ gets structured parsing — a JSON file arrives at the tool as a dict."""
+
+ async def _resolve(*_args, **_kwargs):
+ return '{"nodes": [{"id": "n1"}], "links": []}'
+
+ schema = {
+ "type": "object",
+ "properties": {"agent_json": {"type": ["object", "string"]}},
+ "required": ["agent_json"],
+ }
+
+ with patch(
+ "backend.copilot.sdk.file_ref.resolve_file_ref",
+ new=AsyncMock(side_effect=_resolve),
+ ):
+ result = await expand_file_refs_in_args(
+ {"agent_json": "@@agptfile:/home/user/agent.json"},
+ user_id="u1",
+ session=_make_session(),
+ input_schema=schema,
+ )
+ assert result["agent_json"] == {"nodes": [{"id": "n1"}], "links": []}
+
+
+async def test_union_object_string_dict_skips_inner_expansion():
+ """An inline dict in a ["object", "string"]-typed slot with no declared
+ properties is left untouched — inner strings that merely mention
+ @@agptfile syntax (e.g. prompt text in an agent graph) must not be
+ expanded."""
+
+ schema = {
+ "type": "object",
+ "properties": {"agent_json": {"type": ["object", "string"]}},
+ "required": ["agent_json"],
+ }
+ agent = {
+ "nodes": [{"id": "n1", "input_default": {"prompt": "@@agptfile:/x.json"}}],
+ "links": [],
+ }
+
+ with patch(
+ "backend.copilot.sdk.file_ref.resolve_file_ref",
+ new=AsyncMock(side_effect=AssertionError("should not be called")),
+ ):
+ result = await expand_file_refs_in_args(
+ {"agent_json": agent},
+ user_id="u1",
+ session=_make_session(),
+ input_schema=schema,
+ )
+ assert result["agent_json"] is agent
diff --git a/autogpt_platform/backend/backend/copilot/sdk/mcp_tool_guide.md b/autogpt_platform/backend/backend/copilot/sdk/mcp_tool_guide.md
index e4e4a161a3..6041b20657 100644
--- a/autogpt_platform/backend/backend/copilot/sdk/mcp_tool_guide.md
+++ b/autogpt_platform/backend/backend/copilot/sdk/mcp_tool_guide.md
@@ -4,8 +4,17 @@
`run_mcp_tool` follows a two-step pattern:
-1. **Discover** — call with only `server_url` to list available tools on the server.
-2. **Execute** — call again with `server_url`, `tool_name`, and `tool_arguments` to run a tool.
+1. **Discover** — call with only `server_url` to list available tools on the
+ server. The response contains each tool's name, description, and a compact
+ `params` summary (argument names, required ones marked `*`) — full input
+ schemas are omitted to save context.
+2. **Execute** — call again with `server_url`, `tool_name`, and
+ `tool_arguments` built from the description and `params` summary. If the
+ tool name or arguments are wrong, the error response includes a bounded
+ schema hint for that tool (very large schemas are reduced to their
+ top-level structure and marked truncated) or the list of valid tool
+ names — fix the call from that. Never re-run discovery just to see a
+ schema.
### Known hosted MCP servers
diff --git a/autogpt_platform/backend/backend/copilot/sdk/tool_adapter.py b/autogpt_platform/backend/backend/copilot/sdk/tool_adapter.py
index dd5aeac982..0a8b593819 100644
--- a/autogpt_platform/backend/backend/copilot/sdk/tool_adapter.py
+++ b/autogpt_platform/backend/backend/copilot/sdk/tool_adapter.py
@@ -752,20 +752,25 @@ def _make_truncating_wrapper(
# the wrapper instead.
if not args and required_args:
logger.warning(
- "[MCP] %s called with empty args (likely output "
- "token truncation) — returning guidance",
- tool_name,
+ f"[MCP] {tool_name} called with empty args (truncated or "
+ f"schema-rejected input) — returning guidance"
)
+ stop_msg = _check_circuit_breaker(tool_name, args)
+ _record_tool_failure(tool_name, args)
+ if stop_msg:
+ return _mcp_error(stop_msg)
return _mcp_error(
- f"Your call to {tool_name} had empty arguments — "
- f"this means your previous response was too long and "
- f"the tool call input was truncated by the API. "
- f"To fix this: break your work into smaller steps. "
- f"For large content, first write it to a file using "
- f"bash_exec with cat >> (append section by section), "
- f"then pass it via @@agptfile:filename reference. "
- f"Do NOT retry with the same approach — it will "
- f"be truncated again."
+ f"Your call to {tool_name} arrived with empty arguments. "
+ f"This means the arguments were dropped in transit: either "
+ f"your response hit the output-token limit mid-call, or an "
+ f"argument value did not match the parameter's declared "
+ f"type. Do NOT retry the same call — it will fail the same "
+ f"way. Instead, write the large argument value to a file "
+ f"first (bash_exec with cat >>, appending section by "
+ f"section, or reuse a file you already wrote), then call "
+ f'{tool_name} again passing the string "@@agptfile:<path>" '
+ f"as that argument's value. Object parameters such as "
+ f"agent_json accept this file-reference string directly."
)
original_args = args
diff --git a/autogpt_platform/backend/backend/copilot/sdk/tool_adapter_test.py b/autogpt_platform/backend/backend/copilot/sdk/tool_adapter_test.py
index 864c858656..a98c3f535b 100644
--- a/autogpt_platform/backend/backend/copilot/sdk/tool_adapter_test.py
+++ b/autogpt_platform/backend/backend/copilot/sdk/tool_adapter_test.py
@@ -1331,3 +1331,47 @@ class TestNavigableToolResultText:
]
)
assert _navigable_tool_result_text(multi) == multi
+
+
+class TestEmptyArgsCircuitBreaker:
+ """Empty-args calls give file-reference guidance and eventually trip the
+ circuit breaker instead of looping forever."""
+
+ @pytest.fixture(autouse=True)
+ def _init_context(self):
+ set_execution_context(
+ user_id="test",
+ session=None,
+ sandbox=None,
+ sdk_cwd="/tmp/test",
+ )
+
+ def _wrapper(self):
+ async def handler(_args):
+ raise AssertionError("handler must not run on empty args")
+
+ return _make_truncating_wrapper(
+ handler,
+ "create_agent",
+ input_schema={"type": "object", "properties": {"agent_json": {}}},
+ required_args=["agent_json"],
+ )
+
+ @pytest.mark.asyncio
+ async def test_guidance_recommends_file_reference(self):
+ result = await self._wrapper()({})
+ text = _text_from_mcp_result(result)
+ assert result.get("isError") is True
+ assert "@@agptfile" in text
+ assert "truncated by the API" not in text
+
+ @pytest.mark.asyncio
+ async def test_repeated_empty_args_trip_circuit_breaker(self):
+ wrapper = self._wrapper()
+ for _ in range(3):
+ result = await wrapper({})
+ assert "empty arguments" in _text_from_mcp_result(result)
+ result = await wrapper({})
+ text = _text_from_mcp_result(result)
+ assert "STOP" in text
+ assert "Do NOT retry" in text
diff --git a/autogpt_platform/backend/backend/copilot/tools/agent_generator/validator.py b/autogpt_platform/backend/backend/copilot/tools/agent_generator/validator.py
index c07c5b711b..6f787d55d5 100644
--- a/autogpt_platform/backend/backend/copilot/tools/agent_generator/validator.py
+++ b/autogpt_platform/backend/backend/copilot/tools/agent_generator/validator.py
@@ -161,6 +161,16 @@ class AgentValidator:
continue
required_inputs = block.get("inputSchema", {}).get("required", [])
+ # AgentExecutorBlock / MCPToolBlock carry their real input
+ # requirements in the node's dynamic schema (the sub-agent's /
+ # MCP tool's), not the static block schema — a required dynamic
+ # argument must not slip through validation.
+ dynamic_required = _dynamic_required_inputs(node)
+ if dynamic_required:
+ required_inputs = [
+ *required_inputs,
+ *[r for r in dynamic_required if r not in required_inputs],
+ ]
input_defaults = node.get("input_default", {})
node_id = node.get("id")
@@ -1239,6 +1249,29 @@ def _resolve_optional_union(schema: dict[str, Any]) -> dict[str, Any] | None:
return None
+def _dynamic_required_inputs(node: dict[str, Any]) -> list[str]:
+ """Required argument names from a node's dynamic input schema.
+
+ AgentExecutorBlock nodes carry the sub-agent's input schema in
+ ``input_default["input_schema"]``; MCPToolBlock nodes carry the MCP
+ tool's schema in ``input_default["tool_input_schema"]``. Their static
+ block schemas say nothing about these per-node requirements.
+ """
+ block_id = node.get("block_id", "")
+ if block_id not in (AGENT_EXECUTOR_BLOCK_ID, MCP_TOOL_BLOCK_ID):
+ return []
+ schema_field = (
+ "input_schema" if block_id == AGENT_EXECUTOR_BLOCK_ID else "tool_input_schema"
+ )
+ schema = node.get("input_default", {}).get(schema_field, {})
+ if not isinstance(schema, dict):
+ return []
+ required = schema.get("required")
+ if not isinstance(required, list):
+ return []
+ return [name for name in required if isinstance(name, str)]
+
+
def _schema_display_type(schema: dict[str, Any]) -> str:
"""Human-readable type label for error messages.
diff --git a/autogpt_platform/backend/backend/copilot/tools/agent_generator/validator_test.py b/autogpt_platform/backend/backend/copilot/tools/agent_generator/validator_test.py
index dd42ef8fe8..2383293444 100644
--- a/autogpt_platform/backend/backend/copilot/tools/agent_generator/validator_test.py
+++ b/autogpt_platform/backend/backend/copilot/tools/agent_generator/validator_test.py
@@ -1217,6 +1217,78 @@ class TestNestedChainEdgeCases:
assert v.validate_source_output_existence(agent, blocks) is False
+class TestDynamicRequiredInputs:
+ """Required arguments declared in a node's dynamic schema (MCP tool /
+ sub-agent input schema) must be enforced by validate_required_inputs —
+ the static block schema says nothing about them."""
+
+ def _mcp_node(self, input_default: dict) -> dict:
+ return _make_node(block_id=MCP_TOOL_BLOCK_ID, input_default=input_default)
+
+ def _mcp_block(self) -> dict:
+ return _make_block(block_id=MCP_TOOL_BLOCK_ID, name="MCPToolBlock")
+
+ def test_missing_required_dynamic_argument_fails(self):
+ v = AgentValidator()
+ node = self._mcp_node(
+ {
+ "server_url": "https://mcp.example.com/sse",
+ "selected_tool": "search",
+ "tool_input_schema": {
+ "properties": {"data": {"type": "string"}},
+ "required": ["data"],
+ },
+ }
+ )
+ agent = _make_agent(nodes=[node])
+
+ assert v.validate_required_inputs(agent, [self._mcp_block()]) is False
+ assert any("'data'" in e for e in v.errors)
+
+ def test_required_dynamic_argument_via_default_passes(self):
+ v = AgentValidator()
+ node = self._mcp_node(
+ {
+ "server_url": "https://mcp.example.com/sse",
+ "selected_tool": "search",
+ "tool_input_schema": {
+ "properties": {"data": {"type": "string"}},
+ "required": ["data"],
+ },
+ "data": "hello",
+ }
+ )
+ agent = _make_agent(nodes=[node])
+
+ assert v.validate_required_inputs(agent, [self._mcp_block()]) is True
+
+ def test_required_dynamic_argument_via_link_passes(self):
+ v = AgentValidator()
+ node = self._mcp_node(
+ {
+ "server_url": "https://mcp.example.com/sse",
+ "selected_tool": "search",
+ "tool_input_schema": {
+ "properties": {"data": {"type": "string"}},
+ "required": ["data"],
+ },
+ }
+ )
+ source = _make_node(block_id="block-1")
+ link = _make_link(
+ source_id=source["id"],
+ source_name="output",
+ sink_id=node["id"],
+ sink_name="data",
+ )
+ agent = _make_agent(nodes=[source, node], links=[link])
+
+ assert (
+ v.validate_required_inputs(agent, [self._mcp_block(), _make_block()])
+ is True
+ )
+
+
class TestAdditionalPropertiesChains:
"""Levels that allow additionalProperties accept the remaining chain —
the executor delivers arbitrary keys into such dicts at run time."""
diff --git a/autogpt_platform/backend/backend/copilot/tools/agent_output.py b/autogpt_platform/backend/backend/copilot/tools/agent_output.py
index 21c62bd9ce..8f89c169fd 100644
--- a/autogpt_platform/backend/backend/copilot/tools/agent_output.py
+++ b/autogpt_platform/backend/backend/copilot/tools/agent_output.py
@@ -19,7 +19,13 @@ from backend.data.execution import (
)
from .base import BaseTool
-from .execution_utils import TERMINAL_STATUSES, wait_for_execution
+from .execution_utils import (
+ TERMINAL_STATUSES,
+ NodeFailureSummary,
+ build_run_health_warning,
+ summarize_node_failures,
+ wait_for_execution,
+)
from .models import (
AgentOutputResponse,
ErrorResponse,
@@ -334,7 +340,9 @@ class AgentOutputTool(BaseTool):
)
node_executions_data = None
+ node_failures: list[NodeFailureSummary] = []
if isinstance(execution, GraphExecutionWithNodes):
+ node_failures = summarize_node_failures(execution.node_executions)
node_executions_data = [
{
"node_id": ne.node_id,
@@ -356,6 +364,7 @@ class AgentOutputTool(BaseTool):
outputs=dict(execution.outputs),
inputs_summary=execution.inputs if execution.inputs else None,
node_executions=node_executions_data,
+ nodes_failed=node_failures or None,
)
available_list = None
@@ -372,6 +381,14 @@ class AgentOutputTool(BaseTool):
# Build appropriate message based on execution status
if execution.status == ExecutionStatus.COMPLETED:
message = f"Found execution outputs for agent '{agent.name}'"
+ health_warning = build_run_health_warning(execution.outputs, node_failures)
+ if health_warning:
+ if not isinstance(execution, GraphExecutionWithNodes):
+ health_warning += (
+ " Re-call with show_execution_details=true to see the "
+ "per-node trace."
+ )
+ message += f". {health_warning}"
elif execution.status == ExecutionStatus.FAILED:
message = f"Execution for agent '{agent.name}' failed"
elif execution.status == ExecutionStatus.TERMINATED:
diff --git a/autogpt_platform/backend/backend/copilot/tools/agent_output_test.py b/autogpt_platform/backend/backend/copilot/tools/agent_output_test.py
new file mode 100644
index 0000000000..a1f62f1973
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/tools/agent_output_test.py
@@ -0,0 +1,92 @@
+"""Tests for AgentOutputTool response building — run-health surfacing.
+
+A COMPLETED graph run can contain FAILED nodes (node errors don't fail the
+run) or produce no outputs; the response message must surface that instead
+of reading as success.
+"""
+
+from unittest.mock import MagicMock
+
+from backend.data.execution import (
+ ExecutionStatus,
+ GraphExecution,
+ GraphExecutionWithNodes,
+)
+
+from .agent_output import AgentOutputTool
+
+
+def _agent() -> MagicMock:
+ agent = MagicMock()
+ agent.id = "lib-1"
+ agent.name = "Test Agent"
+ agent.graph_id = "graph-1"
+ return agent
+
+
+def _execution(*, with_nodes: bool, outputs: dict, node_executions: list):
+ spec = GraphExecutionWithNodes if with_nodes else GraphExecution
+ execution = MagicMock(spec=spec)
+ execution.id = "exec-1"
+ execution.status = ExecutionStatus.COMPLETED
+ execution.started_at = None
+ execution.ended_at = None
+ execution.outputs = outputs
+ execution.inputs = None
+ if with_nodes:
+ execution.node_executions = node_executions
+ return execution
+
+
+def _failed_node() -> MagicMock:
+ ne = MagicMock()
+ ne.status = ExecutionStatus.FAILED
+ ne.node_id = "n1"
+ ne.block_id = "block-x"
+ ne.output_data = {"error": ["boom exploded"]}
+ ne.input_data = {}
+ ne.start_time = None
+ ne.end_time = None
+ return ne
+
+
+def test_completed_with_failed_node_warns():
+ response = AgentOutputTool()._build_response(
+ agent=_agent(),
+ execution=_execution(
+ with_nodes=True,
+ outputs={"result": ["ok"]},
+ node_executions=[_failed_node()],
+ ),
+ available_executions=[],
+ session_id="sess-1",
+ )
+ assert "FAILED despite the COMPLETED" in response.message
+ assert response.execution.nodes_failed is not None
+ assert "show_execution_details" not in response.message
+
+
+def test_completed_empty_outputs_without_nodes_nudges_details():
+ """Without the per-node trace loaded, the warning nudges a re-call with
+ show_execution_details=true."""
+ response = AgentOutputTool()._build_response(
+ agent=_agent(),
+ execution=_execution(with_nodes=False, outputs={}, node_executions=[]),
+ available_executions=[],
+ session_id="sess-1",
+ )
+ assert "produced no outputs" in response.message
+ assert "show_execution_details=true" in response.message
+
+
+def test_healthy_completed_has_no_warning():
+ response = AgentOutputTool()._build_response(
+ agent=_agent(),
+ execution=_execution(
+ with_nodes=True, outputs={"result": ["ok"]}, node_executions=[]
+ ),
+ available_executions=[],
+ session_id="sess-1",
+ )
+ assert "WARNING" not in response.message
+ assert response.execution.nodes_failed is None
diff --git a/autogpt_platform/backend/backend/copilot/tools/create_agent.py b/autogpt_platform/backend/backend/copilot/tools/create_agent.py
index dbd6c12d3e..d5f4914825 100644
--- a/autogpt_platform/backend/backend/copilot/tools/create_agent.py
+++ b/autogpt_platform/backend/backend/copilot/tools/create_agent.py
@@ -9,7 +9,7 @@ from backend.copilot.tracking import track_library_check_outcome
from .agent_generator.pipeline import fetch_library_agents, fix_validate_and_save
from .base import BaseTool
-from .helpers import require_guide_read, require_library_check
+from .helpers import coerce_agent_json, require_guide_read, require_library_check
from .models import ErrorResponse, ToolResponseBase
logger = logging.getLogger(__name__)
@@ -40,8 +40,12 @@ class CreateAgentTool(BaseTool):
"type": "object",
"properties": {
"agent_json": {
- "type": "object",
- "description": "Agent graph with 'nodes' and 'links' arrays.",
+ "type": ["object", "string"],
+ "description": (
+ "Agent graph with 'nodes' and 'links' arrays, or the "
+ 'string "@@agptfile:<path>" to a JSON file '
+ "(preferred for large graphs)."
+ ),
},
"library_agent_ids": {
"type": "array",
@@ -80,7 +84,7 @@ class CreateAgentTool(BaseTool):
self,
user_id: str | None,
session: ChatSession,
- agent_json: dict[str, Any] | None = None,
+ agent_json: dict[str, Any] | str | None = None,
save: bool = True,
library_agent_ids: list[str] | None = None,
folder_id: str | None = None,
@@ -105,10 +109,13 @@ class CreateAgentTool(BaseTool):
user_id=user_id, session_id=session_id, outcome="bypassed_ack"
)
+ agent_json = coerce_agent_json(agent_json)
if not agent_json:
return ErrorResponse(
message=(
- "Please provide agent_json with the complete agent graph. "
+ "Please provide agent_json with the complete agent graph "
+ "as a JSON object, or as the string "
+ '"@@agptfile:<path>" referencing a JSON file. '
"Use find_block to discover blocks, then generate the JSON."
),
error="missing_agent_json",
diff --git a/autogpt_platform/backend/backend/copilot/tools/edit_agent.py b/autogpt_platform/backend/backend/copilot/tools/edit_agent.py
index 7ccdbf4e04..fcbdeeee88 100644
--- a/autogpt_platform/backend/backend/copilot/tools/edit_agent.py
+++ b/autogpt_platform/backend/backend/copilot/tools/edit_agent.py
@@ -10,7 +10,7 @@ from backend.data.model import is_credentials_field_name
from .agent_generator import get_agent_as_json
from .agent_generator.pipeline import fetch_library_agents, fix_validate_and_save
from .base import BaseTool
-from .helpers import require_guide_read
+from .helpers import coerce_agent_json, require_guide_read
from .models import ErrorResponse, ToolResponseBase
logger = logging.getLogger(__name__)
@@ -44,8 +44,12 @@ class EditAgentTool(BaseTool):
"description": "Graph ID or library agent ID to edit.",
},
"agent_json": {
- "type": "object",
- "description": "Updated agent JSON with nodes and links.",
+ "type": ["object", "string"],
+ "description": (
+ "Updated agent JSON with nodes and links, or the "
+ 'string "@@agptfile:<path>" to a JSON file '
+ "(preferred for large graphs)."
+ ),
},
"library_agent_ids": {
"type": "array",
@@ -66,7 +70,7 @@ class EditAgentTool(BaseTool):
user_id: str | None,
session: ChatSession,
agent_id: str = "",
- agent_json: dict[str, Any] | None = None,
+ agent_json: dict[str, Any] | str | None = None,
save: bool = True,
library_agent_ids: list[str] | None = None,
**kwargs,
@@ -105,10 +109,13 @@ class EditAgentTool(BaseTool):
session_id=session_id,
)
+ agent_json = coerce_agent_json(agent_json)
if not agent_json:
return ErrorResponse(
message=(
- "Please provide agent_json with the complete updated agent graph."
+ "Please provide agent_json with the complete updated agent "
+ "graph as a JSON object, or as the string "
+ '"@@agptfile:<path>" referencing a JSON file.'
),
error="missing_agent_json",
session_id=session_id,
diff --git a/autogpt_platform/backend/backend/copilot/tools/execution_utils.py b/autogpt_platform/backend/backend/copilot/tools/execution_utils.py
index 038fbfcff2..084c4a0c4e 100644
--- a/autogpt_platform/backend/backend/copilot/tools/execution_utils.py
+++ b/autogpt_platform/backend/backend/copilot/tools/execution_utils.py
@@ -2,14 +2,18 @@
import asyncio
import logging
-from typing import Any
+from typing import Any, Sequence
+from typing_extensions import TypedDict
+
+from backend.blocks import get_block
from backend.data.db_accessors import execution_db
from backend.data.execution import (
AsyncRedisExecutionEventBus,
ExecutionStatus,
GraphExecution,
GraphExecutionEvent,
+ NodeExecutionResult,
exec_channel,
)
@@ -185,3 +189,73 @@ def get_execution_outputs(execution: GraphExecution | None) -> dict[str, Any] |
if execution is None:
return None
return execution.outputs
+
+
+class NodeFailureSummary(TypedDict):
+ node_id: str
+ block_name: str
+ error: str | None
+
+
+# Per-node error detail cap: enough to identify the failure, small enough
+# that a many-failure run can't flood the tool response.
+_NODE_ERROR_MAX_CHARS = 500
+
+
+def summarize_node_failures(
+ node_executions: Sequence[NodeExecutionResult],
+) -> list[NodeFailureSummary]:
+ """Compact per-node failure summary for a graph execution.
+
+ A graph run can finish with status COMPLETED while individual nodes
+ FAILED — node errors don't fail the run. Surfacing them explicitly
+ prevents the assistant from reporting success based on the top-level
+ status alone.
+ """
+ failures: list[NodeFailureSummary] = []
+ for ne in node_executions:
+ if ne.status != ExecutionStatus.FAILED:
+ continue
+ block = get_block(ne.block_id)
+ error_values = ne.output_data.get("error") if ne.output_data else None
+ if isinstance(error_values, list):
+ error_str = str(error_values[0]) if error_values else None
+ elif error_values:
+ error_str = str(error_values)
+ else:
+ error_str = None
+ failures.append(
+ {
+ "node_id": ne.node_id,
+ "block_name": block.name if block else ne.block_id,
+ "error": error_str[:_NODE_ERROR_MAX_CHARS] if error_str else None,
+ }
+ )
+ return failures
+
+
+def build_run_health_warning(
+ outputs: dict[str, Any] | None,
+ node_failures: list[NodeFailureSummary],
+) -> str | None:
+ """Warning to include in a COMPLETED-run message, or None if healthy."""
+ if node_failures:
+ details = "; ".join(
+ f"{f['block_name']}: {f['error'] or 'no error detail'}"
+ for f in node_failures[:5]
+ )
+ return (
+ f"WARNING: {len(node_failures)} node(s) FAILED despite the COMPLETED "
+ f"status ({details}). Treat this run as unsuccessful — inspect "
+ "node_executions, fix the agent, and re-verify before reporting "
+ "success."
+ )
+ if not outputs:
+ return (
+ "WARNING: the run COMPLETED but produced no outputs. If this "
+ "agent declares AgentOutput blocks, that usually means a broken "
+ "link or a node that silently produced nothing — inspect "
+ "node_executions before reporting success. (Side-effect-only "
+ "agents with no declared outputs legitimately finish this way.)"
+ )
+ return None
diff --git a/autogpt_platform/backend/backend/copilot/tools/execution_utils_test.py b/autogpt_platform/backend/backend/copilot/tools/execution_utils_test.py
new file mode 100644
index 0000000000..093b4cbb5f
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/tools/execution_utils_test.py
@@ -0,0 +1,139 @@
+"""Tests for run-health helpers in execution_utils."""
+
+from datetime import datetime, timezone
+
+from backend.data.execution import ExecutionStatus, NodeExecutionResult
+
+from .execution_utils import build_run_health_warning, summarize_node_failures
+
+STORE_VALUE_BLOCK_ID = "1ff065e9-88e8-4358-9d82-8dc91f622ba9"
+
+
+def make_node_execution(
+ status: ExecutionStatus,
+ output_data: dict | None = None,
+ block_id: str = STORE_VALUE_BLOCK_ID,
+) -> NodeExecutionResult:
+ now = datetime.now(timezone.utc)
+ return NodeExecutionResult(
+ user_id="user-1",
+ graph_id="graph-1",
+ graph_version=1,
+ graph_exec_id="exec-1",
+ node_exec_id="node-exec-1",
+ node_id="node-1",
+ block_id=block_id,
+ status=status,
+ input_data={},
+ output_data=output_data or {},
+ add_time=now,
+ queue_time=None,
+ start_time=now,
+ end_time=now,
+ )
+
+
+def test_summarize_node_failures_extracts_failed_nodes():
+ failures = summarize_node_failures(
+ [
+ make_node_execution(ExecutionStatus.COMPLETED),
+ make_node_execution(
+ ExecutionStatus.FAILED,
+ output_data={"error": ["NameError: name 'variables' is not defined"]},
+ ),
+ ]
+ )
+
+ assert len(failures) == 1
+ assert failures[0]["node_id"] == "node-1"
+ assert failures[0]["block_name"] == "StoreValueBlock"
+ assert failures[0]["error"] == "NameError: name 'variables' is not defined"
+
+
+def test_summarize_node_failures_handles_missing_error_and_unknown_block():
+ failures = summarize_node_failures(
+ [make_node_execution(ExecutionStatus.FAILED, block_id="not-a-block-id")]
+ )
+
+ assert failures == [
+ {"node_id": "node-1", "block_name": "not-a-block-id", "error": None}
+ ]
+
+
+def test_summarize_node_failures_truncates_long_errors():
+ failures = summarize_node_failures(
+ [
+ make_node_execution(
+ ExecutionStatus.FAILED, output_data={"error": ["x" * 900]}
+ )
+ ]
+ )
+
+ assert failures[0]["error"] is not None
+ assert len(failures[0]["error"]) == 500
+
+
+def test_build_run_health_warning_reports_failed_nodes():
+ warning = build_run_health_warning(
+ outputs={"result": ["ok"]},
+ node_failures=[
+ {"node_id": "n1", "block_name": "CodeExecutionBlock", "error": "boom"}
+ ],
+ )
+
+ assert warning is not None
+ assert "1 node(s) FAILED" in warning
+ assert "CodeExecutionBlock: boom" in warning
+
+
+def test_build_run_health_warning_flags_empty_outputs():
+ warning = build_run_health_warning(outputs={}, node_failures=[])
+
+ assert warning is not None
+ assert "no outputs" in warning
+
+
+def test_build_run_health_warning_none_when_healthy():
+ assert build_run_health_warning({"result": ["ok"]}, []) is None
+
+
+def test_incomplete_nodes_are_not_flagged_as_failures():
+ """INCOMPLETE nodes are legal in a COMPLETED run — unexecuted branches
+ (e.g. a ConditionBlock's untaken path) finish INCOMPLETE by design, so
+ flagging them would false-positive every conditional agent. Only FAILED
+ nodes indicate a broken run."""
+ from unittest.mock import MagicMock
+
+ from backend.data.execution import ExecutionStatus
+
+ ne = MagicMock()
+ ne.status = ExecutionStatus.INCOMPLETE
+ ne.node_id = "n1"
+ ne.block_id = "block-x"
+ ne.output_data = {}
+
+ assert summarize_node_failures([ne]) == []
+
+
+def test_many_failures_capped_detail_but_full_count():
+ """The warning lists at most 5 failure details but counts all of them."""
+ from unittest.mock import MagicMock
+
+ from backend.data.execution import ExecutionStatus
+
+ nodes = []
+ for i in range(8):
+ ne = MagicMock()
+ ne.status = ExecutionStatus.FAILED
+ ne.node_id = f"n{i}"
+ ne.block_id = f"block-{i}"
+ ne.output_data = {"error": [f"boom {i}"]}
+ nodes.append(ne)
+
+ failures = summarize_node_failures(nodes)
+ assert len(failures) == 8
+
+ warning = build_run_health_warning({"out": ["x"]}, failures)
+ assert warning is not None
+ assert "8 node(s) FAILED" in warning
+ assert warning.count("boom") == 5
diff --git a/autogpt_platform/backend/backend/copilot/tools/find_block.py b/autogpt_platform/backend/backend/copilot/tools/find_block.py
index 3d3cf66a6f..44eb88727b 100644
--- a/autogpt_platform/backend/backend/copilot/tools/find_block.py
+++ b/autogpt_platform/backend/backend/copilot/tools/find_block.py
@@ -76,11 +76,6 @@ class FindBlockTool(BaseTool):
"type": "string",
"description": "Search keywords (e.g. 'email', 'http', 'ai').",
},
- "include_schemas": {
- "type": "boolean",
- "description": "Include full input/output schemas (for agent JSON generation).",
- "default": False,
- },
"for_agent_generation": {
"type": "boolean",
"description": (
@@ -103,7 +98,6 @@ class FindBlockTool(BaseTool):
user_id: str | None,
session: ChatSession,
query: str = "",
- include_schemas: bool = False,
for_agent_generation: bool = False,
**kwargs,
) -> ToolResponseBase:
@@ -113,7 +107,6 @@ class FindBlockTool(BaseTool):
user_id: User ID (required)
session: Chat session
query: Search query
- include_schemas: Whether to include block schemas in results
for_agent_generation: When True, bypasses the CoPilot exclusion filter
so graph-only blocks (INPUT, OUTPUT, ORCHESTRATOR, etc.) are visible.
@@ -194,12 +187,6 @@ class FindBlockTool(BaseTool):
),
categories=[c.value for c in block.categories],
)
- if include_schemas:
- info = block.get_info()
- summary.input_schema = info.inputSchema
- summary.output_schema = info.outputSchema
- summary.static_output = info.staticOutput
-
return BlockListResponse(
message=(
f"Found block '{block.name}' by ID. "
@@ -275,12 +262,6 @@ class FindBlockTool(BaseTool):
categories=[c.value for c in block.categories],
)
- if include_schemas:
- info = block.get_info()
- summary.input_schema = info.inputSchema
- summary.output_schema = info.outputSchema
- summary.static_output = info.staticOutput
-
blocks.append(summary)
if len(blocks) >= _TARGET_RESULTS:
diff --git a/autogpt_platform/backend/backend/copilot/tools/find_block_test.py b/autogpt_platform/backend/backend/copilot/tools/find_block_test.py
index c607286cac..f165f9a3e5 100644
--- a/autogpt_platform/backend/backend/copilot/tools/find_block_test.py
+++ b/autogpt_platform/backend/backend/copilot/tools/find_block_test.py
@@ -601,8 +601,9 @@ class TestFindBlockFiltering:
)
@pytest.mark.asyncio(loop_scope="session")
- async def test_include_schemas_false_omits_schemas(self):
- """Without include_schemas, schemas should be empty dicts."""
+ async def test_schemas_always_omitted(self):
+ """Schemas are never returned — full schemas context-bomb the model
+ (see run_block's schema-on-demand flow instead)."""
session = make_session(user_id=_TEST_USER_ID)
input_schema = {"properties": {"url": {"type": "string"}}, "required": ["url"]}
output_schema = {"properties": {"result": {"type": "string"}}}
@@ -636,7 +637,6 @@ class TestFindBlockFiltering:
user_id=_TEST_USER_ID,
session=session,
query="test",
- include_schemas=False,
)
assert isinstance(response, BlockListResponse)
@@ -645,8 +645,9 @@ class TestFindBlockFiltering:
assert response.blocks[0].static_output is False
@pytest.mark.asyncio(loop_scope="session")
- async def test_include_schemas_true_populates_schemas(self):
- """With include_schemas=true, schemas should be populated from block info."""
+ async def test_include_schemas_arg_is_ignored(self):
+ """A stray include_schemas=True argument (e.g. replayed from an old
+ transcript) must not re-enable schema payloads."""
session = make_session(user_id=_TEST_USER_ID)
input_schema = {"properties": {"url": {"type": "string"}}, "required": ["url"]}
output_schema = {"properties": {"result": {"type": "string"}}}
@@ -685,9 +686,8 @@ class TestFindBlockFiltering:
)
assert isinstance(response, BlockListResponse)
- assert response.blocks[0].input_schema == input_schema
- assert response.blocks[0].output_schema == output_schema
- assert response.blocks[0].static_output is True
+ assert response.blocks[0].input_schema == {}
+ assert response.blocks[0].output_schema == {}
class TestFindBlockDirectLookup:
diff --git a/autogpt_platform/backend/backend/copilot/tools/fix_agent.py b/autogpt_platform/backend/backend/copilot/tools/fix_agent.py
index 965d769fa8..5ef72a520f 100644
--- a/autogpt_platform/backend/backend/copilot/tools/fix_agent.py
+++ b/autogpt_platform/backend/backend/copilot/tools/fix_agent.py
@@ -1,13 +1,18 @@
"""FixAgentGraphTool - Auto-fixes common agent JSON issues."""
+import difflib
+import json
import logging
+import os
+import re
from typing import Any
+from backend.copilot.context import get_workspace_manager
from backend.copilot.model import ChatSession
from .agent_generator.validation import AgentFixer, AgentValidator, get_blocks_as_dicts
from .base import BaseTool
-from .helpers import require_guide_read
+from .helpers import coerce_agent_json, require_guide_read
from .models import ErrorResponse, FixResultResponse, ToolResponseBase
logger = logging.getLogger(__name__)
@@ -39,9 +44,20 @@ class FixAgentGraphTool(BaseTool):
"type": "object",
"properties": {
"agent_json": {
- "type": "object",
+ "type": ["object", "string"],
"description": (
- "The agent JSON to fix. Must contain 'nodes' and 'links' arrays."
+ "The agent JSON to fix ('nodes' + 'links' arrays), or "
+ 'the string "@@agptfile:<path>" to a JSON file '
+ "(preferred for large graphs)."
+ ),
+ },
+ "write_to": {
+ "type": "string",
+ "description": (
+ "Workspace filename (no directories) to write the "
+ "fixed JSON to (pretty-printed, overwrites). The "
+ "response then returns an @@agptfile ref to pass to "
+ "create_agent/edit_agent instead of the full JSON."
),
},
},
@@ -52,7 +68,8 @@ class FixAgentGraphTool(BaseTool):
self,
user_id: str | None,
session: ChatSession,
- agent_json: dict | None = None,
+ agent_json: dict | str | None = None,
+ write_to: str = "",
**kwargs,
) -> ToolResponseBase:
session_id = session.session_id if session else None
@@ -61,9 +78,13 @@ class FixAgentGraphTool(BaseTool):
if guide_gate is not None:
return guide_gate
- if not agent_json or not isinstance(agent_json, dict):
+ agent_json = coerce_agent_json(agent_json)
+ if not agent_json:
return ErrorResponse(
- message="Please provide a valid agent JSON object.",
+ message=(
+ "Please provide a valid agent JSON object, or the string "
+ '"@@agptfile:<path>" referencing a JSON file.'
+ ),
error="Missing or invalid agent_json parameter",
session_id=session_id,
)
@@ -101,28 +122,106 @@ class FixAgentGraphTool(BaseTool):
is_valid = False
if is_valid:
- return FixResultResponse(
- message=(
- f"Applied {len(fixes_applied)} fix(es). Agent graph is now valid!"
- ),
- fixed_agent_json=fixed_agent,
- fixes_applied=fixes_applied,
- fix_count=len(fixes_applied),
- valid_after_fix=True,
- remaining_errors=[],
- session_id=session_id,
- )
-
- return FixResultResponse(
- message=(
+ message = f"Applied {len(fixes_applied)} fix(es). Agent graph is now valid!"
+ else:
+ message = (
f"Applied {len(fixes_applied)} fix(es), but "
f"{len(remaining_errors)} issue(s) remain. "
"Review the remaining errors and fix manually."
- ),
- fixed_agent_json=fixed_agent,
+ )
+
+ fixed_ref: str | None = None
+ fix_diff: str | None = None
+ if write_to := write_to.strip():
+ fixed_ref, write_note = await _write_fixed_agent(
+ fixed_agent, write_to, user_id, session_id
+ )
+ message += write_note
+ if fixed_ref and fixes_applied:
+ fix_diff = _build_fix_diff(agent_json, fixed_agent, write_to)
+
+ return FixResultResponse(
+ message=message,
+ fixed_agent_json=None if fixed_ref else fixed_agent,
+ fixed_agent_ref=fixed_ref,
+ fix_diff=fix_diff,
fixes_applied=fixes_applied,
fix_count=len(fixes_applied),
- valid_after_fix=False,
- remaining_errors=remaining_errors,
+ valid_after_fix=is_valid,
+ remaining_errors=remaining_errors if not is_valid else [],
session_id=session_id,
)
+
+
+async def _write_fixed_agent(
+ fixed_agent: dict[str, Any],
+ write_to: str,
+ user_id: str | None,
+ session_id: str | None,
+) -> tuple[str | None, str]:
+ """Write the fixed agent JSON to a workspace file, pretty-printed.
+
+ Returns (file reference to pass to create_agent/edit_agent, message
+ note). On any failure the reference is None and the note explains the
+ fallback to inline JSON.
+ """
+ if not re.fullmatch(r"[\w][\w.-]*", write_to):
+ return None, (
+ f" NOTE: write_to must be a plain filename (got {write_to!r}); "
+ "returning the fixed JSON inline instead."
+ )
+ if not user_id or not session_id:
+ return None, (
+ " NOTE: write_to requires an authenticated session; "
+ "returning the fixed JSON inline instead."
+ )
+ try:
+ manager = await get_workspace_manager(user_id, session_id)
+ rec = await manager.write_file(
+ content=json.dumps(fixed_agent, indent=2).encode("utf-8"),
+ filename=write_to,
+ overwrite=True,
+ metadata={"origin": "agent-created"},
+ )
+ except Exception as e:
+ logger.warning(f"fix_agent_graph: failed to write {write_to!r}: {e}")
+ return None, (
+ f" NOTE: could not write {os.path.basename(write_to)}; "
+ "returning the fixed JSON inline instead."
+ )
+ ref = f"@@agptfile:workspace://{rec.path}"
+ return ref, (
+ f" Fixed JSON written to workspace file {rec.path} — pass "
+ f'agent_json="{ref}" to create_agent/edit_agent (do not re-emit '
+ "the JSON)."
+ )
+
+
+_MAX_DIFF_CHARS = 4000
+
+
+def _build_fix_diff(
+ original: dict[str, Any], fixed: dict[str, Any], filename: str
+) -> str | None:
+ """Unified diff of the applied fixes against the pretty-printed JSON.
+
+ Lets the model keep its mental copy of the (just-overwritten) workspace
+ file current without re-reading it. Both sides are normalized with
+ ``json.dumps(indent=2)`` — the "after" side is byte-identical to what
+ ``_write_fixed_agent`` wrote.
+ """
+ diff_lines = difflib.unified_diff(
+ json.dumps(original, indent=2).splitlines(keepends=True),
+ json.dumps(fixed, indent=2).splitlines(keepends=True),
+ fromfile=f"{filename} (before fixes)",
+ tofile=f"{filename} (after fixes)",
+ n=2,
+ )
+ diff = "".join(diff_lines)
+ if not diff:
+ return None
+ if len(diff) > _MAX_DIFF_CHARS:
+ diff = diff[:_MAX_DIFF_CHARS] + (
+ "\n... [diff truncated — re-read the file before making " "targeted edits]"
+ )
+ return diff
diff --git a/autogpt_platform/backend/backend/copilot/tools/fix_agent_test.py b/autogpt_platform/backend/backend/copilot/tools/fix_agent_test.py
index 5664471f07..6f3062b245 100644
--- a/autogpt_platform/backend/backend/copilot/tools/fix_agent_test.py
+++ b/autogpt_platform/backend/backend/copilot/tools/fix_agent_test.py
@@ -1,6 +1,6 @@
"""Tests for FixAgentGraphTool."""
-from unittest.mock import MagicMock, patch
+from unittest.mock import AsyncMock, MagicMock, patch
import pytest
@@ -187,3 +187,127 @@ async def test_fixer_exception_returns_error(tool, session):
assert isinstance(result, ErrorResponse)
assert result.error is not None
assert "fix_exception" in result.error
+
+
+def _agent(nodes_extra: dict | None = None) -> dict:
+ node = {
+ "id": "node-1",
+ "block_id": "block-1",
+ "input_default": {},
+ "metadata": {"position": {"x": 0, "y": 0}},
+ }
+ if nodes_extra:
+ node.update(nodes_extra)
+ return {"nodes": [node], "links": []}
+
+
+def _fix_patches(fixed_agent: dict, fixes: list[str]):
+ mock_fixer = MagicMock()
+ mock_fixer.apply_all_fixes = MagicMock(return_value=fixed_agent)
+ mock_fixer.get_fixes_applied.return_value = fixes
+
+ mock_validator = MagicMock()
+ mock_validator.validate.return_value = (True, None)
+ mock_validator.errors = []
+
+ return (
+ patch(
+ "backend.copilot.tools.fix_agent.get_blocks_as_dicts",
+ return_value=[],
+ ),
+ patch("backend.copilot.tools.fix_agent.AgentFixer", return_value=mock_fixer),
+ patch(
+ "backend.copilot.tools.fix_agent.AgentValidator",
+ return_value=mock_validator,
+ ),
+ )
+
+
+async def test_write_to_returns_file_ref_and_diff(tool, session):
+ """write_to persists the fixed JSON and returns a ref + diff instead of
+ the full JSON."""
+ agent_json = _agent()
+ fixed_agent = _agent({"id": "node-1-fixed"})
+
+ mock_record = MagicMock()
+ mock_record.path = "/agent.json"
+ mock_manager = MagicMock()
+ mock_manager.write_file = AsyncMock(return_value=mock_record)
+
+ p1, p2, p3 = _fix_patches(fixed_agent, ["Fixed node UUID format"])
+ with (
+ p1,
+ p2,
+ p3,
+ patch(
+ "backend.copilot.tools.fix_agent.get_workspace_manager",
+ new=AsyncMock(return_value=mock_manager),
+ ),
+ ):
+ result = await tool._execute(
+ user_id=_TEST_USER_ID,
+ session=session,
+ agent_json=agent_json,
+ write_to="agent.json",
+ )
+
+ assert isinstance(result, FixResultResponse)
+ assert result.fixed_agent_ref == "@@agptfile:workspace:///agent.json"
+ assert result.fixed_agent_json is None
+ assert result.fix_diff is not None
+ assert "node-1-fixed" in result.fix_diff
+ assert "@@agptfile:workspace:///agent.json" in result.message
+
+ written = mock_manager.write_file.call_args.kwargs
+ assert written["filename"] == "agent.json"
+ assert written["overwrite"] is True
+ assert b'\n "nodes"' in written["content"] # pretty-printed
+
+
+async def test_write_to_with_directory_falls_back_inline(tool, session):
+ """write_to containing a path separator is rejected; JSON stays inline."""
+ agent_json = _agent()
+
+ p1, p2, p3 = _fix_patches(dict(agent_json), [])
+ with p1, p2, p3:
+ result = await tool._execute(
+ user_id=_TEST_USER_ID,
+ session=session,
+ agent_json=agent_json,
+ write_to="subdir/agent.json",
+ )
+
+ assert isinstance(result, FixResultResponse)
+ assert result.fixed_agent_ref is None
+ assert result.fixed_agent_json is not None
+ assert "plain filename" in result.message
+
+
+async def test_write_to_failure_falls_back_inline(tool, session):
+ """A workspace write failure degrades to inline JSON with a note."""
+ agent_json = _agent()
+
+ p1, p2, p3 = _fix_patches(dict(agent_json), ["fix"])
+ with (
+ p1,
+ p2,
+ p3,
+ patch(
+ "backend.copilot.tools.fix_agent.get_workspace_manager",
+ new=AsyncMock(side_effect=RuntimeError("workspace down")),
+ ),
+ ):
+ result = await tool._execute(
+ user_id=_TEST_USER_ID,
+ session=session,
+ agent_json=agent_json,
+ write_to="agent.json",
+ )
+
+ assert isinstance(result, FixResultResponse)
+ assert result.fixed_agent_ref is None
+ assert result.fixed_agent_json is not None
+ assert "could not write" in result.message
diff --git a/autogpt_platform/backend/backend/copilot/tools/helpers.py b/autogpt_platform/backend/backend/copilot/tools/helpers.py
index f21e60ca83..89bb1fecfb 100644
--- a/autogpt_platform/backend/backend/copilot/tools/helpers.py
+++ b/autogpt_platform/backend/backend/copilot/tools/helpers.py
@@ -1111,3 +1111,26 @@ def require_library_check(session: ChatSession, tool_name: str):
),
session_id=session.session_id,
)
+
+
+def coerce_agent_json(
+ agent_json: dict[str, Any] | str | None,
+) -> dict[str, Any] | None:
+ """Coerce an ``agent_json`` tool argument into a dict.
+
+ A bare ``@@agptfile:`` reference is expanded and JSON-parsed into a dict
+ by the SDK layer before the tool runs, but a raw JSON string can still
+ arrive — e.g. a reference embedded in surrounding text, or a file that
+ failed structured parsing. Returns None when the value cannot be
+ interpreted as a JSON object.
+ """
+ if isinstance(agent_json, dict):
+ return agent_json
+ if isinstance(agent_json, str) and agent_json.strip():
+ try:
+ parsed = json.loads(agent_json)
+ except json.JSONDecodeError:
+ return None
+ if isinstance(parsed, dict):
+ return parsed
+ return None
diff --git a/autogpt_platform/backend/backend/copilot/tools/helpers_test.py b/autogpt_platform/backend/backend/copilot/tools/helpers_test.py
index e40c68c3bf..2a87a84ec6 100644
--- a/autogpt_platform/backend/backend/copilot/tools/helpers_test.py
+++ b/autogpt_platform/backend/backend/copilot/tools/helpers_test.py
@@ -11,6 +11,7 @@ from backend.copilot.constants import COPILOT_NODE_PREFIX, COPILOT_SESSION_PREFI
from backend.copilot.tools.helpers import (
BlockPreparation,
check_hitl_review,
+ coerce_agent_json,
execute_block,
prepare_block_for_execution,
require_library_check,
@@ -1548,3 +1549,26 @@ class TestRequireLibraryCheck:
session = make_session("user-lib-check", guide_read=False, library_check=False)
session.metadata.builder_graph_id = "some-graph-id"
assert require_library_check(session, "create_agent") is None
+
+
+class TestCoerceAgentJson:
+ def test_dict_passes_through(self):
+ agent = {"nodes": [{"id": "n1"}], "links": []}
+ assert coerce_agent_json(agent) is agent
+
+ def test_json_object_string_is_parsed(self):
+ assert coerce_agent_json('{"nodes": [], "links": []}') == {
+ "nodes": [],
+ "links": [],
+ }
+
+ def test_unparseable_string_returns_none(self):
+ assert coerce_agent_json("@@agptfile:/home/user/agent.json") is None
+
+ def test_json_non_object_string_returns_none(self):
+ assert coerce_agent_json('["nodes"]') is None
+
+ def test_none_and_empty_return_none(self):
+ assert coerce_agent_json(None) is None
+ assert coerce_agent_json("") is None
+ assert coerce_agent_json(" ") is None
diff --git a/autogpt_platform/backend/backend/copilot/tools/models.py b/autogpt_platform/backend/backend/copilot/tools/models.py
index e0a47acaf5..9a977beead 100644
--- a/autogpt_platform/backend/backend/copilot/tools/models.py
+++ b/autogpt_platform/backend/backend/copilot/tools/models.py
@@ -6,6 +6,7 @@ from typing import Any, Literal
from pydantic import BaseModel, Field, model_validator
+from backend.copilot.tools.execution_utils import NodeFailureSummary
from backend.data.graph import BaseGraph, GraphTriggerInfo
from backend.data.model import CredentialsMetaInput
@@ -460,6 +461,7 @@ class ExecutionOutputInfo(BaseModel):
outputs: dict[str, list[Any]]
inputs_summary: dict[str, Any] | None = None
node_executions: list[dict[str, Any]] | None = None
+ nodes_failed: list[NodeFailureSummary] | None = None
class AgentOutputResponse(ToolResponseBase):
@@ -749,7 +751,17 @@ class MCPToolInfo(BaseModel):
name: str
description: str
- input_schema: dict[str, Any]
+ params: str | None = Field(
+ default=None,
+ description="Compact argument summary: top-level input field names, "
+ "required ones marked with *.",
+ )
+ input_schema: dict[str, Any] | None = Field(
+ default=None,
+ description="Full input schema. Omitted in discovery responses to "
+ "keep them small; the execution error path returns the failed "
+ "tool's full schema on demand.",
+ )
class MCPToolsDiscoveredResponse(ToolResponseBase):
@@ -815,7 +827,11 @@ class FixResultResponse(ToolResponseBase):
"""Response for fix_agent_graph tool."""
type: ResponseType = ResponseType.AGENT_BUILDER_FIX_RESULT
- fixed_agent_json: dict[str, Any]
+ # None when the fixed JSON was written to a workspace file instead
+ # (see fixed_agent_ref + fix_diff).
+ fixed_agent_json: dict[str, Any] | None = None
+ fixed_agent_ref: str | None = None
+ fix_diff: str | None = None
fixes_applied: list[str] = Field(default_factory=list)
fix_count: int = 0
valid_after_fix: bool = False
diff --git a/autogpt_platform/backend/backend/copilot/tools/run_agent.py b/autogpt_platform/backend/backend/copilot/tools/run_agent.py
index 3e5393f84d..1e75f79428 100644
--- a/autogpt_platform/backend/backend/copilot/tools/run_agent.py
+++ b/autogpt_platform/backend/backend/copilot/tools/run_agent.py
@@ -24,7 +24,13 @@ from backend.util.timezone_utils import (
)
from .base import BaseTool
-from .execution_utils import get_execution_outputs, wait_for_execution
+from .execution_utils import (
+ NodeFailureSummary,
+ build_run_health_warning,
+ get_execution_outputs,
+ summarize_node_failures,
+ wait_for_execution,
+)
from .helpers import get_inputs_from_schema
from .models import (
AgentDetails,
@@ -904,21 +910,26 @@ class RunAgentTool(BaseTool):
if completed and completed.status == ExecutionStatus.COMPLETED:
outputs = get_execution_outputs(completed)
- # Inline the per-node execution trace on dry-runs so the
- # LLM can inspect "did every block run, what did each
- # produce?" without a follow-up view_agent_output call.
- # Empty final outputs on a COMPLETED dry-run almost always
- # mean a node silently produced nothing / a link was wired
- # wrong — the trace is what lets the model debug that.
+ # A COMPLETED graph run can still contain FAILED nodes (node
+ # errors don't fail the run), so always fetch the per-node
+ # trace to check run health. The full trace is inlined in the
+ # response only on dry-runs — where the LLM needs it to debug
+ # wiring ("did every block run, what did each produce?")
+ # without a follow-up view_agent_output call — to keep wet-run
+ # responses small.
node_executions_data = None
- if dry_run:
- try:
- detailed = await execution_db().get_graph_execution(
- user_id=user_id,
- execution_id=execution.id,
- include_node_executions=True,
+ node_failures: list[NodeFailureSummary] = []
+ try:
+ detailed = await execution_db().get_graph_execution(
+ user_id=user_id,
+ execution_id=execution.id,
+ include_node_executions=True,
+ )
+ if isinstance(detailed, GraphExecutionWithNodes):
+ node_failures = summarize_node_failures(
+ detailed.node_executions
)
- if isinstance(detailed, GraphExecutionWithNodes):
+ if dry_run:
node_executions_data = [
{
"node_id": ne.node_id,
@@ -937,21 +948,30 @@ class RunAgentTool(BaseTool):
}
for ne in detailed.node_executions
]
- except Exception:
- logger.warning(
- "run_agent: failed to load node executions for "
- "dry-run %s; returning summary only",
- execution.id,
- exc_info=True,
- )
+ except Exception:
+ logger.warning(
+ "run_agent: failed to load node executions for "
+ "execution %s; returning summary only",
+ execution.id,
+ exc_info=True,
+ )
await _safe_link_to_chat_share(
session_id=session_id, execution_id=execution.id
)
- return AgentOutputResponse(
- message=(
+ health_warning = build_run_health_warning(outputs, node_failures)
+ if health_warning:
+ message = (
+ f"Agent '{library_agent.name}' finished with status "
+ f"COMPLETED. {health_warning} "
+ f"View at {library_agent_link}."
+ )
+ else:
+ message = (
f"Agent '{library_agent.name}' completed successfully. "
f"View at {library_agent_link}."
- ),
+ )
+ return AgentOutputResponse(
+ message=message,
session_id=session_id,
agent_name=library_agent.name,
agent_id=library_agent.graph_id,
@@ -964,6 +984,7 @@ class RunAgentTool(BaseTool):
ended_at=completed.ended_at,
outputs=outputs or {},
node_executions=node_executions_data,
+ nodes_failed=node_failures or None,
),
)
elif completed and completed.status == ExecutionStatus.FAILED:
diff --git a/autogpt_platform/backend/backend/copilot/tools/run_agent_test.py b/autogpt_platform/backend/backend/copilot/tools/run_agent_test.py
index 3105885d5a..400e92ba06 100644
--- a/autogpt_platform/backend/backend/copilot/tools/run_agent_test.py
+++ b/autogpt_platform/backend/backend/copilot/tools/run_agent_test.py
@@ -4,6 +4,7 @@ from unittest.mock import AsyncMock, MagicMock, patch
import orjson
import pytest
+from backend.data.execution import ExecutionStatus
from backend.executor.utils import is_credential_validation_error_message
from backend.util.exceptions import GraphValidationError
@@ -1190,3 +1191,168 @@ async def test_maybe_save_preset_creates_with_default_name():
assert preset_arg.name == "My Agent"
assert preset_arg.inputs == {"x": 1}
assert preset_arg.graph_id == "g1"
+
+
+def _completed_run_mocks(
+ mocker,
+ *,
+ outputs: dict,
+ node_executions: list | None = None,
+ detailed_fetch_error: Exception | None = None,
+):
+ """Wire the waited-COMPLETED path: library agent, execution, waiter,
+ outputs, and the detailed per-node trace fetch."""
+ from unittest.mock import MagicMock
+
+ from backend.data.execution import GraphExecutionWithNodes
+
+ lib = MagicMock()
+ lib.graph_id = "graph-1"
+ lib.graph_version = 1
+ lib.name = "Test Agent"
+ lib.id = "lib-1"
+ mocker.patch(
+ "backend.copilot.tools.run_agent.get_or_create_library_agent",
+ AsyncMock(return_value=lib),
+ )
+ mocker.patch("backend.copilot.tools.run_agent.track_agent_run_success")
+ mocker.patch(
+ "backend.copilot.tools.run_agent._safe_link_to_chat_share", AsyncMock()
+ )
+ mocker.patch(
+ "backend.api.features.orgs.db.get_user_default_team",
+ AsyncMock(return_value=("org-1", "team-1")),
+ )
+ execution = MagicMock()
+ execution.id = "exec-1"
+ mocker.patch(
+ "backend.copilot.tools.run_agent.execution_utils.add_graph_execution",
+ AsyncMock(return_value=execution),
+ )
+ completed = MagicMock()
+ completed.status = ExecutionStatus.COMPLETED
+ completed.started_at = None
+ completed.ended_at = None
+ mocker.patch(
+ "backend.copilot.tools.run_agent.wait_for_execution",
+ AsyncMock(return_value=completed),
+ )
+ mocker.patch(
+ "backend.copilot.tools.run_agent.get_execution_outputs",
+ return_value=outputs,
+ )
+ detailed = MagicMock(spec=GraphExecutionWithNodes)
+ detailed.node_executions = node_executions or []
+ db = MagicMock()
+ if detailed_fetch_error is not None:
+ db.get_graph_execution = AsyncMock(side_effect=detailed_fetch_error)
+ else:
+ db.get_graph_execution = AsyncMock(return_value=detailed)
+ mocker.patch(
+ "backend.copilot.tools.run_agent.execution_db",
+ return_value=db,
+ )
+ return lib
+
+
+def _failed_node(node_id: str = "n1") -> "MagicMock":
+ from unittest.mock import MagicMock
+
+ ne = MagicMock()
+ ne.status = ExecutionStatus.FAILED
+ ne.node_id = node_id
+ ne.block_id = "block-x"
+ ne.output_data = {"error": ["boom exploded"]}
+ ne.input_data = {}
+ ne.start_time = None
+ ne.end_time = None
+ return ne
+
+
+async def _run_waited(mocker, *, dry_run: bool):
+ from unittest.mock import MagicMock
+
+ tool = RunAgentTool()
+ session = make_session(user_id="user-1")
+ session.organization_id = "org-1"
+ session.team_id = "team-1"
+ graph = MagicMock()
+ graph.id = "graph-1"
+ graph.version = 1
+ graph.name = "Test Agent"
+ return await tool._run_agent(
+ user_id="user-1",
+ session=session,
+ graph=graph,
+ graph_credentials={},
+ inputs={},
+ dry_run=dry_run,
+ wait_for_result=30,
+ )
+
+
[email protected](loop_scope="session")
+async def test_completed_run_with_failed_node_warns_and_reports(mocker):
+ """A COMPLETED run with a FAILED node must NOT read as success: the
+ message carries the warning and the response carries nodes_failed."""
+ _completed_run_mocks(
+ mocker, outputs={"result": ["ok"]}, node_executions=[_failed_node()]
+ )
+ response = await _run_waited(mocker, dry_run=False)
+
+ assert "finished with status COMPLETED" in response.message
+ assert "FAILED despite the COMPLETED" in response.message
+ assert "completed successfully" not in response.message
+ assert response.execution.nodes_failed is not None
+ assert response.execution.nodes_failed[0]["error"] == "boom exploded"
+
+
[email protected](loop_scope="session")
+async def test_completed_run_with_empty_outputs_warns(mocker):
+ _completed_run_mocks(mocker, outputs={}, node_executions=[])
+ response = await _run_waited(mocker, dry_run=False)
+
+ assert "produced no outputs" in response.message
+ assert "completed successfully" not in response.message
+
+
[email protected](loop_scope="session")
+async def test_healthy_completed_run_reports_success(mocker):
+ _completed_run_mocks(mocker, outputs={"result": ["ok"]}, node_executions=[])
+ response = await _run_waited(mocker, dry_run=False)
+
+ assert "completed successfully" in response.message
+ assert response.execution.nodes_failed is None
+
+
[email protected](loop_scope="session")
+async def test_wet_run_omits_node_trace_dry_run_inlines_it(mocker):
+ """The full per-node trace is inlined only on dry runs (LLM debugging);
+ wet-run responses stay small."""
+ _completed_run_mocks(
+ mocker, outputs={"result": ["ok"]}, node_executions=[_failed_node()]
+ )
+ wet = await _run_waited(mocker, dry_run=False)
+ assert wet.execution.node_executions is None
+
+ _completed_run_mocks(
+ mocker, outputs={"result": ["ok"]}, node_executions=[_failed_node()]
+ )
+ dry = await _run_waited(mocker, dry_run=True)
+ assert dry.execution.node_executions is not None
+ assert dry.execution.node_executions[0]["status"] == "FAILED"
+
+
[email protected](loop_scope="session")
+async def test_detailed_fetch_failure_degrades_to_summary(mocker):
+ """When the per-node trace fetch raises, the run response still returns
+ (summary only) instead of crashing."""
+ _completed_run_mocks(
+ mocker,
+ outputs={"result": ["ok"]},
+ detailed_fetch_error=RuntimeError("db down"),
+ )
+ response = await _run_waited(mocker, dry_run=False)
+
+ assert "completed successfully" in response.message
+ assert response.execution.nodes_failed is None
diff --git a/autogpt_platform/backend/backend/copilot/tools/run_mcp_tool.py b/autogpt_platform/backend/backend/copilot/tools/run_mcp_tool.py
index c510c9262a..b8efb11159 100644
--- a/autogpt_platform/backend/backend/copilot/tools/run_mcp_tool.py
+++ b/autogpt_platform/backend/backend/copilot/tools/run_mcp_tool.py
@@ -1,5 +1,6 @@
"""Tool for discovering and executing MCP (Model Context Protocol) server tools."""
+import json
import logging
from typing import Any
from urllib.parse import urlparse
@@ -36,6 +37,15 @@ from .models import (
logger = logging.getLogger(__name__)
+# Discovery-response size caps: keep multi-tool catalogs small enough that a
+# 20-tool server doesn't consume a meaningful share of the context window.
+# All inputs here are server-controlled, so every dimension is bounded:
+# tool count, description length, and per-tool params-summary length.
+_TOOL_DESCRIPTION_MAX_CHARS = 300
+_ERROR_SCHEMA_MAX_CHARS = 4000
+_DISCOVERY_MAX_TOOLS = 100
+_PARAMS_SUMMARY_MAX_CHARS = 400
+
# HTTP status codes that indicate authentication is required
_AUTH_STATUS_CODES = {401, 403}
@@ -340,19 +350,39 @@ class RunMCPToolTool(BaseTool):
inspect tool schemas and choose one to execute in a follow-up call.
"""
tools = await client.list_tools()
+ # Full input schemas are deliberately omitted: a server like Notion
+ # exposes 20 tools whose schemas total ~67KB (~17K tokens) — enough
+ # to trigger context compaction on its own. The compact per-tool
+ # param summary covers tool selection; the full schema of a single
+ # tool is delivered on demand via the execution error path.
+ # Tool count and params-summary length are bounded too — both are
+ # server-controlled and would otherwise be unbounded context cost.
+ dropped_tools = max(0, len(tools) - _DISCOVERY_MAX_TOOLS)
tool_infos = [
MCPToolInfo(
name=t.name,
- description=t.description,
- input_schema=t.input_schema,
+ description=(t.description or "")[:_TOOL_DESCRIPTION_MAX_CHARS],
+ params=_summarize_params(t.input_schema),
)
- for t in tools
+ for t in tools[:_DISCOVERY_MAX_TOOLS]
]
host = server_host(server_url)
+ truncation_note = (
+ f" NOTE: {dropped_tools} additional tool(s) were omitted from "
+ "this listing to bound context size."
+ if dropped_tools
+ else ""
+ )
return MCPToolsDiscoveredResponse(
message=(
- f"Discovered {len(tool_infos)} tool(s) on {host}. "
- "Call run_mcp_tool again with tool_name and tool_arguments to execute one."
+ f"Discovered {len(tool_infos)} tool(s) on {host}."
+ f"{truncation_note} Full input "
+ "schemas are omitted to save context — `params` lists each "
+ "tool's argument names with required ones marked `*`. Call "
+ "run_mcp_tool again with tool_name and tool_arguments to "
+ "execute one; if the arguments are wrong, the error response "
+ "includes a schema hint for that tool. Do NOT re-run "
+ "discovery after an argument error."
),
server_url=server_url,
tools=tool_infos,
@@ -408,8 +438,12 @@ class RunMCPToolTool(BaseTool):
for item in result.content
if item.get("type") == "text"
)
+ hint = await self._build_error_hint(client, tool_name)
return ErrorResponse(
- message=f"MCP tool '{tool_name}' returned an error: {error_text or 'Unknown error'}",
+ message=(
+ f"MCP tool '{tool_name}' returned an error: "
+ f"{error_text or 'Unknown error'}{hint}"
+ ),
session_id=session_id,
)
@@ -424,6 +458,31 @@ class RunMCPToolTool(BaseTool):
session_id=session_id,
)
+ async def _build_error_hint(self, client: MCPClient, tool_name: str) -> str:
+ """Self-correction hint appended to tool-error responses.
+
+ Discovery omits full input schemas (context cost), so this is where
+ the model gets the one schema it actually needs: the failed tool's.
+ For a misspelled tool name, list the available names instead. Both
+ beat the model's fallback of re-running discovery, which re-injects
+ the entire multi-tool catalog into context.
+ """
+ try:
+ tools = await client.list_tools()
+ match = next((t for t in tools if t.name == tool_name), None)
+ if match is not None:
+ schema_json = _bounded_schema_hint(match.input_schema)
+ return f" Input schema for '{tool_name}': {schema_json}"
+ names = ", ".join(t.name for t in tools[:40])
+ return (
+ f" No tool named '{tool_name}' exists on this server. "
+ f"Available tools: {names}"
+ )
+ except Exception:
+ # Best-effort — a failed hint lookup must not mask the original
+ # tool error.
+ return ""
+
async def _lookup_tool_schema(
self,
client: MCPClient,
@@ -525,3 +584,61 @@ class RunMCPToolTool(BaseTool):
graph_id=None,
graph_version=None,
)
+
+
+def _summarize_params(schema: dict | None) -> str | None:
+ """Compact one-line argument summary for a tool's input schema.
+
+ Returns ``"query*, limit, filter"`` style output — top-level property
+ names with required ones marked ``*`` — or ``None`` when the schema has
+ no usable properties. Nested structure is intentionally dropped; the
+ full schema is available via the execution error path.
+ """
+ if not isinstance(schema, dict):
+ return None
+ properties = schema.get("properties")
+ if not isinstance(properties, dict) or not properties:
+ return None
+ required = schema.get("required")
+ required_names = set(required) if isinstance(required, list) else set()
+ summary = ", ".join(
+ f"{name}*" if name in required_names else name for name in properties
+ )
+ if len(summary) > _PARAMS_SUMMARY_MAX_CHARS:
+ summary = summary[:_PARAMS_SUMMARY_MAX_CHARS] + "…"
+ return summary
+
+
+def _bounded_schema_hint(schema: dict | None) -> str:
+ """Serialize *schema* for an error hint, bounded to a parseable size.
+
+ Small schemas pass through verbatim. Oversized ones are reduced
+ structurally — top-level properties keep only their ``type`` and a
+ shortened ``description``, plus the ``required`` list and a
+ ``$truncated`` marker — so the hint stays valid JSON instead of a
+ sliced string.
+ """
+ full = json.dumps(schema)
+ if len(full) <= _ERROR_SCHEMA_MAX_CHARS:
+ return full
+ if not isinstance(schema, dict):
+ return full[:_ERROR_SCHEMA_MAX_CHARS]
+
+ properties = schema.get("properties")
+ reduced_props: dict[str, Any] = {}
+ if isinstance(properties, dict):
+ for name, prop in properties.items():
+ entry: dict[str, Any] = {}
+ if isinstance(prop, dict):
+ if "type" in prop:
+ entry["type"] = prop["type"]
+ if isinstance(prop.get("description"), str):
+ entry["description"] = prop["description"][:120]
+ reduced_props[name] = entry
+ reduced = {
+ "type": schema.get("type", "object"),
+ "properties": reduced_props,
+ "required": schema.get("required", []),
+ "$truncated": "nested structure omitted to bound context size",
+ }
+ return json.dumps(reduced)
diff --git a/autogpt_platform/backend/backend/copilot/tools/run_mcp_tool_test.py b/autogpt_platform/backend/backend/copilot/tools/run_mcp_tool_test.py
new file mode 100644
index 0000000000..fb192bbd5c
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/tools/run_mcp_tool_test.py
@@ -0,0 +1,67 @@
+"""Tests for run_mcp_tool's context-size bounding helpers.
+
+MCP servers control tool counts, descriptions, and schemas — every
+dimension surfaced to the model must stay bounded or a large catalog can
+context-bomb the session.
+"""
+
+import json
+
+from backend.copilot.tools.run_mcp_tool import (
+ _ERROR_SCHEMA_MAX_CHARS,
+ _PARAMS_SUMMARY_MAX_CHARS,
+ _bounded_schema_hint,
+ _summarize_params,
+)
+
+
+class TestBoundedSchemaHint:
+ def test_small_schema_passes_through_verbatim(self):
+ schema = {
+ "type": "object",
+ "properties": {"query": {"type": "string"}},
+ "required": ["query"],
+ }
+ assert json.loads(_bounded_schema_hint(schema)) == schema
+
+ def test_oversized_schema_reduces_to_valid_marked_json(self):
+ schema = {
+ "type": "object",
+ "properties": {
+ f"field_{i}": {
+ "type": "object",
+ "description": "x" * 300,
+ "properties": {"nested": {"type": "string", "enum": ["v"] * 50}},
+ }
+ for i in range(40)
+ },
+ "required": ["field_0"],
+ }
+ assert len(json.dumps(schema)) > _ERROR_SCHEMA_MAX_CHARS
+
+ hint = _bounded_schema_hint(schema)
+ payload = json.loads(hint) # must be valid JSON, not a sliced string
+ assert "$truncated" in payload
+ assert payload["required"] == ["field_0"]
+ assert set(payload["properties"]) == set(schema["properties"])
+ # Nested structure is dropped; per-property entries keep type +
+ # shortened description only.
+ assert "properties" not in payload["properties"]["field_0"]
+ assert len(payload["properties"]["field_0"]["description"]) <= 120
+ assert len(hint) < len(json.dumps(schema))
+
+
+class TestSummarizeParams:
+ def test_marks_required_and_caps_length(self):
+ schema = {
+ "properties": {f"param_{i:03d}": {"type": "string"} for i in range(100)},
+ "required": ["param_000"],
+ }
+ summary = _summarize_params(schema)
+ assert summary is not None
+ assert summary.startswith("param_000*")
+ assert len(summary) <= _PARAMS_SUMMARY_MAX_CHARS + 1 # +ellipsis
+
+ def test_no_properties_returns_none(self):
+ assert _summarize_params({}) is None
+ assert _summarize_params(None) is None
diff --git a/autogpt_platform/backend/backend/copilot/tools/test_run_mcp_tool.py b/autogpt_platform/backend/backend/copilot/tools/test_run_mcp_tool.py
index 82d6badcb5..d7093f7c95 100644
--- a/autogpt_platform/backend/backend/copilot/tools/test_run_mcp_tool.py
+++ b/autogpt_platform/backend/backend/copilot/tools/test_run_mcp_tool.py
@@ -197,6 +197,9 @@ async def test_discover_tools_returns_discovered_response():
assert response.tools[0].name == "fetch"
assert response.tools[1].name == "search"
assert response.server_url == _SERVER_URL
+ # Full schemas are omitted from discovery to keep the payload small
+ assert response.tools[0].input_schema is None
+ assert response.tools[1].input_schema is None
@pytest.mark.asyncio(loop_scope="session")
@@ -500,6 +503,132 @@ async def test_execute_tool_returns_error_on_tool_failure():
assert "nonexistent" in response.message
[email protected](loop_scope="session")
+async def test_discovery_summarizes_params_and_truncates_description():
+ """Discovery returns a compact params summary instead of full schemas."""
+ tool = RunMCPToolTool()
+ session = make_session(_USER_ID)
+
+ t = MagicMock()
+ t.name = "notion-search"
+ t.description = "x" * 500
+ t.input_schema = {
+ "type": "object",
+ "properties": {"query": {"type": "string"}, "limit": {"type": "integer"}},
+ "required": ["query"],
+ }
+
+ with patch(
+ "backend.copilot.tools.run_mcp_tool.validate_url_host", new_callable=AsyncMock
+ ):
+ with patch(
+ "backend.copilot.tools.run_mcp_tool.auto_lookup_mcp_credential",
+ new_callable=AsyncMock,
+ return_value=None,
+ ):
+ mock_client = AsyncMock()
+ mock_client.list_tools = AsyncMock(return_value=[t])
+ with patch(
+ "backend.copilot.tools.run_mcp_tool.MCPClient",
+ return_value=mock_client,
+ ):
+ response = await tool._execute(
+ user_id=_USER_ID,
+ session=session,
+ server_url=_SERVER_URL,
+ )
+
+ assert isinstance(response, MCPToolsDiscoveredResponse)
+ assert response.tools[0].params == "query*, limit"
+ assert response.tools[0].input_schema is None
+ assert len(response.tools[0].description) == 300
+
+
[email protected](loop_scope="session")
+async def test_tool_error_includes_failed_tools_schema():
+ """A failing tool call returns that tool's full schema as a hint so the
+ model can self-correct without re-running the (large) discovery step."""
+ tool = RunMCPToolTool()
+ session = make_session(_USER_ID)
+
+ known = _make_tool_list("known-tool")[0]
+ known.input_schema = {
+ "type": "object",
+ "properties": {"page_id": {"type": "string"}},
+ "required": ["page_id"],
+ }
+
+ with patch(
+ "backend.copilot.tools.run_mcp_tool.validate_url_host", new_callable=AsyncMock
+ ):
+ with patch(
+ "backend.copilot.tools.run_mcp_tool.auto_lookup_mcp_credential",
+ new_callable=AsyncMock,
+ return_value=None,
+ ):
+ mock_result = _make_call_result(
+ [{"type": "text", "text": "Missing required argument"}], is_error=True
+ )
+ mock_client = AsyncMock()
+ mock_client.call_tool = AsyncMock(return_value=mock_result)
+ mock_client.list_tools = AsyncMock(return_value=[known])
+ with patch(
+ "backend.copilot.tools.run_mcp_tool.MCPClient",
+ return_value=mock_client,
+ ):
+ response = await tool._execute(
+ user_id=_USER_ID,
+ session=session,
+ server_url=_SERVER_URL,
+ tool_name="known-tool",
+ tool_arguments={},
+ )
+
+ assert isinstance(response, ErrorResponse)
+ assert "Input schema for 'known-tool'" in response.message
+ assert "page_id" in response.message
+
+
[email protected](loop_scope="session")
+async def test_unknown_tool_error_lists_available_names():
+ """A call to a nonexistent tool returns the valid tool names as a hint."""
+ tool = RunMCPToolTool()
+ session = make_session(_USER_ID)
+
+ with patch(
+ "backend.copilot.tools.run_mcp_tool.validate_url_host", new_callable=AsyncMock
+ ):
+ with patch(
+ "backend.copilot.tools.run_mcp_tool.auto_lookup_mcp_credential",
+ new_callable=AsyncMock,
+ return_value=None,
+ ):
+ mock_result = _make_call_result(
+ [{"type": "text", "text": "Tool not found"}], is_error=True
+ )
+ mock_client = AsyncMock()
+ mock_client.call_tool = AsyncMock(return_value=mock_result)
+ mock_client.list_tools = AsyncMock(
+ return_value=_make_tool_list("notion-search", "notion-fetch")
+ )
+ with patch(
+ "backend.copilot.tools.run_mcp_tool.MCPClient",
+ return_value=mock_client,
+ ):
+ response = await tool._execute(
+ user_id=_USER_ID,
+ session=session,
+ server_url=_SERVER_URL,
+ tool_name="notion-retrieve-page",
+ tool_arguments={},
+ )
+
+ assert isinstance(response, ErrorResponse)
+ assert "No tool named 'notion-retrieve-page'" in response.message
+ assert "notion-search" in response.message
+ assert "notion-fetch" in response.message
+
+
# ---------------------------------------------------------------------------
# Auth / credential flow
# ---------------------------------------------------------------------------
diff --git a/autogpt_platform/backend/backend/copilot/tools/tool_schema_test.py b/autogpt_platform/backend/backend/copilot/tools/tool_schema_test.py
index 6639e0c6e8..6f1ac10d35 100644
--- a/autogpt_platform/backend/backend/copilot/tools/tool_schema_test.py
+++ b/autogpt_platform/backend/backend/copilot/tools/tool_schema_test.py
@@ -87,7 +87,10 @@ from backend.copilot.tools import TOOL_REGISTRY
# Bumped 45000 -> 47000 on the dev merge: dev added the proactive chat-platform
# tools (post_to_chat_platform + list_chat_platform_channels, ~1.4k chars) on top
# of the trigger/preset tools above, so the merged registry needs both deltas.
-_CHAR_BUDGET = 47_000
+# Bumped 47000 -> 47800 on the post-#13601 dev merge: the registry now carries
+# the full merged tool set (webhook-trigger + preset lifecycle + docs/building
+# tools) at 47461 chars; ~340 headroom so routine wording tweaks don't trip it.
+_CHAR_BUDGET = 47_800
@pytest.fixture(scope="module")
diff --git a/autogpt_platform/backend/backend/copilot/tools/validate_agent.py b/autogpt_platform/backend/backend/copilot/tools/validate_agent.py
index 401e842204..68ce954a79 100644
--- a/autogpt_platform/backend/backend/copilot/tools/validate_agent.py
+++ b/autogpt_platform/backend/backend/copilot/tools/validate_agent.py
@@ -7,7 +7,7 @@ from backend.copilot.model import ChatSession
from .agent_generator.validation import AgentValidator, get_blocks_as_dicts
from .base import BaseTool
-from .helpers import require_guide_read
+from .helpers import coerce_agent_json, require_guide_read
from .models import ErrorResponse, ToolResponseBase, ValidationResultResponse
logger = logging.getLogger(__name__)
@@ -39,8 +39,12 @@ class ValidateAgentGraphTool(BaseTool):
"type": "object",
"properties": {
"agent_json": {
- "type": "object",
- "description": "Agent JSON with 'nodes' and 'links' arrays.",
+ "type": ["object", "string"],
+ "description": (
+ "Agent JSON with 'nodes' and 'links' arrays, or the "
+ 'string "@@agptfile:<path>" to a JSON file '
+ "(preferred for large graphs)."
+ ),
},
},
"required": ["agent_json"],
@@ -50,7 +54,7 @@ class ValidateAgentGraphTool(BaseTool):
self,
user_id: str | None,
session: ChatSession,
- agent_json: dict | None = None,
+ agent_json: dict | str | None = None,
**kwargs,
) -> ToolResponseBase:
session_id = session.session_id if session else None
@@ -59,9 +63,13 @@ class ValidateAgentGraphTool(BaseTool):
if guide_gate is not None:
return guide_gate
- if not agent_json or not isinstance(agent_json, dict):
+ agent_json = coerce_agent_json(agent_json)
+ if not agent_json:
return ErrorResponse(
- message="Please provide a valid agent JSON object.",
+ message=(
+ "Please provide a valid agent JSON object, or the string "
+ '"@@agptfile:<path>" referencing a JSON file.'
+ ),
error="Missing or invalid agent_json parameter",
session_id=session_id,
)
diff --git a/autogpt_platform/backend/backend/copilot/tools/validate_agent_test.py b/autogpt_platform/backend/backend/copilot/tools/validate_agent_test.py
index 52b5ccc27d..1fe63568db 100644
--- a/autogpt_platform/backend/backend/copilot/tools/validate_agent_test.py
+++ b/autogpt_platform/backend/backend/copilot/tools/validate_agent_test.py
@@ -158,3 +158,48 @@ async def test_validation_exception_returns_error(tool, session):
assert isinstance(result, ErrorResponse)
assert result.error is not None
assert "validation_exception" in result.error
+
+
+async def test_agent_json_as_json_string(tool, session):
+ """agent_json passed as a raw JSON string is parsed and validated."""
+ agent_json = (
+ '{"nodes": [{"id": "node-1", "block_id": "block-1", '
+ '"input_default": {}, "metadata": {"position": {"x": 0, "y": 0}}}], '
+ '"links": []}'
+ )
+
+ mock_validator = MagicMock()
+ mock_validator.validate.return_value = (True, None)
+ mock_validator.errors = []
+
+ with (
+ patch(
+ "backend.copilot.tools.validate_agent.get_blocks_as_dicts",
+ return_value=[],
+ ),
+ patch(
+ "backend.copilot.tools.validate_agent.AgentValidator",
+ return_value=mock_validator,
+ ),
+ ):
+ result = await tool._execute(
+ user_id=_TEST_USER_ID,
+ session=session,
+ agent_json=agent_json,
+ )
+
+ assert isinstance(result, ValidationResultResponse)
+ assert result.valid is True
+
+
+async def test_agent_json_unresolved_file_ref_string_returns_error(tool, session):
+ """An unexpanded @@agptfile reference (not valid JSON) returns a clear error."""
+ result = await tool._execute(
+ user_id=_TEST_USER_ID,
+ session=session,
+ agent_json="@@agptfile:/home/user/agent.json",
+ )
+ assert isinstance(result, ErrorResponse)
+ assert "@@agptfile" in result.message
diff --git a/autogpt_platform/backend/backend/executor/simulator.py b/autogpt_platform/backend/backend/executor/simulator.py
index 12e5856d6b..26f797471e 100644
--- a/autogpt_platform/backend/backend/executor/simulator.py
+++ b/autogpt_platform/backend/backend/executor/simulator.py
@@ -32,10 +32,12 @@ import inspect
import json
import logging
import math
-from collections.abc import AsyncGenerator
+from collections.abc import AsyncGenerator, Callable
from typing import Any
+import jsonschema
from openai.types import CompletionUsage
+from openai.types.chat import ChatCompletionMessageParam
from backend.blocks.agent import AgentExecutorBlock
from backend.blocks.io import AgentInputBlock, AgentOutputBlock
@@ -119,6 +121,17 @@ def _truncate_input_values(input_data: dict[str, Any]) -> dict[str, Any]:
return {k: _truncate_value(v) for k, v in input_data.items()}
+_MAX_SCHEMA_JSON_CHARS = 6000
+
+
+def _truncate_schema_json(schema: dict[str, Any]) -> str:
+ """Compact-dump a JSON schema for the prompt, truncating oversized ones."""
+ dumped = json.dumps(schema)
+ if len(dumped) > _MAX_SCHEMA_JSON_CHARS:
+ return dumped[:_MAX_SCHEMA_JSON_CHARS] + "... [TRUNCATED]"
+ return dumped
+
+
def _describe_schema_pins(schema: dict[str, Any]) -> str:
"""Format output pins as a bullet list for the prompt."""
properties = schema.get("properties", {})
@@ -142,6 +155,7 @@ async def _call_llm_for_simulation(
*,
label: str = "simulate",
user_id: str | None = None,
+ output_validator: Callable[[dict[str, Any]], list[str]] | None = None,
) -> dict[str, Any]:
"""Send a simulation prompt to the LLM and return the parsed JSON dict.
@@ -151,9 +165,14 @@ async def _call_llm_for_simulation(
recorded against the triggering ``user_id``'s rate-limit counter via
``persist_and_record_usage`` (same rails as every copilot turn).
+ When *output_validator* is provided, parsed outputs that fail it are fed
+ back to the LLM as a correction message and retried within the same
+ retry budget. If retries run out, the last parsed output is returned
+ anyway (a structurally imperfect simulation beats failing the dry run).
+
Raises:
RuntimeError: If no LLM client is available.
- ValueError: If all retry attempts are exhausted.
+ ValueError: If all retry attempts are exhausted without parseable JSON.
"""
client = get_openai_client(prefer_openrouter=True)
if client is None:
@@ -188,16 +207,18 @@ async def _call_llm_for_simulation(
model = _simulator_model()
last_error: Exception | None = None
+ last_parsed: dict[str, Any] | None = None
+ messages: list[ChatCompletionMessageParam] = [
+ {"role": "system", "content": system_prompt},
+ {"role": "user", "content": user_prompt},
+ ]
for attempt in range(_MAX_JSON_RETRIES):
try:
response = await client.chat.completions.create(
model=model,
temperature=_TEMPERATURE,
response_format={"type": "json_object"},
- messages=[
- {"role": "system", "content": system_prompt},
- {"role": "user", "content": user_prompt},
- ],
+ messages=messages,
extra_body=extra_body,
)
if not response.choices:
@@ -207,6 +228,31 @@ async def _call_llm_for_simulation(
if not isinstance(parsed, dict):
raise ValueError(f"LLM returned non-object JSON: {raw[:200]}")
+ schema_problems = output_validator(parsed) if output_validator else []
+ if schema_problems:
+ last_parsed = parsed
+ last_error = ValueError(
+ f"simulated output failed schema validation: {schema_problems}"
+ )
+ logger.warning(
+ f"simulate({label}): schema mismatch on attempt "
+ f"{attempt + 1}/{_MAX_JSON_RETRIES}: {schema_problems}"
+ )
+ messages = messages + [
+ {"role": "assistant", "content": raw},
+ {
+ "role": "user",
+ "content": (
+ "Your simulated output does not conform to the "
+ "block's output schema:\n- "
+ + "\n- ".join(schema_problems)
+ + "\nRespond again with a single corrected JSON "
+ "object that conforms to the output schema."
+ ),
+ },
+ ]
+ continue
+
usage = response.usage
if usage is not None:
logger.debug(
@@ -247,6 +293,15 @@ async def _call_llm_for_simulation(
logger.error("simulate(%s): LLM call failed: %s", label, e, exc_info=True)
break
+ if last_parsed is not None:
+ # Schema-conformance retries ran out but we do have parseable output:
+ # a structurally imperfect simulation beats failing the whole dry run.
+ logger.warning(
+ f"simulate({label}): returning schema-non-conformant output "
+ f"after {_MAX_JSON_RETRIES} attempts: {last_error}"
+ )
+ return last_parsed
+
msg = (
f"[SIMULATOR ERROR — NOT A BLOCK FAILURE] Failed after {_MAX_JSON_RETRIES} "
f"attempts: {last_error}"
@@ -371,6 +426,13 @@ def build_simulation_prompt(block: Any, input_data: dict[str, Any]) -> tuple[str
## Output Schema (what you must return)
{output_pins}
+
+Full output JSON Schema — every pin value MUST conform to it, including
+nested keys (downstream nodes extract nested fields like `pin_#_subfield`,
+so getting the inner structure right matters as much as the top level):
+```json
+{_truncate_schema_json(output_schema)}
+```
{implementation_section}
Your task: given the current inputs, produce realistic simulated outputs for this block.
{"Study the block's run() source code above to understand exactly how inputs are transformed to outputs." if run_source else "Use the block description and schemas to infer realistic outputs."}
@@ -667,7 +729,11 @@ async def simulate_block(
try:
parsed = await _call_llm_for_simulation(
- system_prompt, user_prompt, label=label, user_id=user_id
+ system_prompt,
+ user_prompt,
+ label=label,
+ user_id=user_id,
+ output_validator=_make_output_validator(output_schema),
)
# Track which pins were yielded so we can fill in missing required
@@ -705,6 +771,33 @@ async def simulate_block(
yield "error", str(e)
+def _make_output_validator(
+ output_schema: dict[str, Any],
+) -> Callable[[dict[str, Any]], list[str]]:
+ """Build a validator that checks simulated outputs against *output_schema*.
+
+ ``required`` is dropped — the simulator legitimately omits pins with no
+ meaningful value, and ``simulate_block`` back-fills missing required pins
+ with defaults. What this catches is *structurally wrong* fabrications:
+ e.g. a list where the schema declares an object, which silently breaks
+ ``pin_#_subfield`` links downstream. Returns human-readable problems,
+ empty when the output conforms.
+ """
+ relaxed = {**output_schema, "required": []}
+ validator = jsonschema.Draft202012Validator(relaxed)
+
+ def _validate(parsed: dict[str, Any]) -> list[str]:
+ problems: list[str] = []
+ for err in validator.iter_errors(parsed):
+ path = "/".join(str(p) for p in err.absolute_path) or "(root)"
+ problems.append(f"{path}: {err.message[:200]}")
+ if len(problems) >= 5:
+ break
+ return problems
+
+ return _validate
+
+
def _default_for_schema(pin_schema: dict[str, Any]) -> Any:
"""Return a sensible default value for a JSON schema type."""
pin_type = pin_schema.get("type", "string")
diff --git a/autogpt_platform/backend/backend/executor/simulator_test.py b/autogpt_platform/backend/backend/executor/simulator_test.py
index 6b5c3db251..fe03354183 100644
--- a/autogpt_platform/backend/backend/executor/simulator_test.py
+++ b/autogpt_platform/backend/backend/executor/simulator_test.py
@@ -23,7 +23,10 @@ from backend.blocks.llm import LlmModel
from backend.blocks.orchestrator import ExecutionMode, OrchestratorBlock
from backend.executor.simulator import (
_DEFAULT_SIMULATOR_MODEL,
+ _MAX_JSON_RETRIES,
+ _call_llm_for_simulation,
_extract_cost_usd,
+ _make_output_validator,
_truncate_input_values,
_truncate_value,
build_simulation_prompt,
@@ -882,3 +885,114 @@ class TestSimulatorCostTracking:
outputs.append((name, data))
assert ("result", "simulated") in outputs
+
+
+class TestSchemaConformantSimulation:
+ """Simulated outputs are validated against the block's output schema and
+ retried with corrective feedback; structure fabrications (e.g. a list
+ where the schema says object) no longer reach downstream nodes
+ unchallenged."""
+
+ _OUTPUT_SCHEMA: dict[str, Any] = {
+ "type": "object",
+ "properties": {
+ "main_result": {
+ "type": "object",
+ "properties": {"text": {"type": "string"}},
+ },
+ "response": {"type": "string"},
+ },
+ "required": ["main_result", "response"],
+ }
+
+ def test_validator_accepts_conforming_output(self) -> None:
+ validate = _make_output_validator(self._OUTPUT_SCHEMA)
+ assert validate({"main_result": {"text": "hi"}, "response": "ok"}) == []
+
+ def test_validator_ignores_missing_required_pins(self) -> None:
+ """Omitted pins are legitimate (simulate_block back-fills them)."""
+ validate = _make_output_validator(self._OUTPUT_SCHEMA)
+ assert validate({"response": "ok"}) == []
+
+ def test_validator_flags_wrong_structure(self) -> None:
+ validate = _make_output_validator(self._OUTPUT_SCHEMA)
+ problems = validate({"main_result": [{"type": "string", "value": "x"}]})
+ assert problems
+ assert "main_result" in problems[0]
+
+ def test_prompt_includes_full_output_schema(self) -> None:
+ block = _make_block(output_schema=self._OUTPUT_SCHEMA)
+ system_prompt, _ = build_simulation_prompt(block, {"query": "q"})
+ assert "Full output JSON Schema" in system_prompt
+ assert '"main_result"' in system_prompt
+
+ def _client_with_responses(self, contents: list[str]) -> tuple[Any, AsyncMock]:
+ responses = [_sim_completion(content=c, usage=_sim_usage()) for c in contents]
+ create_mock = AsyncMock(side_effect=responses)
+ client = type(
+ "MC",
+ (),
+ {
+ "chat": type(
+ "C",
+ (),
+ {"completions": type("CC", (), {"create": create_mock})()},
+ )()
+ },
+ )()
+ return client, create_mock
+
+ @pytest.mark.asyncio
+ async def test_nonconforming_output_retried_with_feedback(self) -> None:
+ client, create_mock = self._client_with_responses(
+ [
+ '{"main_result": ["wrong"], "response": "ok"}',
+ '{"main_result": {"text": "right"}, "response": "ok"}',
+ ]
+ )
+ with (
+ patch(
+ "backend.executor.simulator.get_openai_client",
+ return_value=client,
+ ),
+ patch(
+ "backend.executor.simulator.persist_and_record_usage",
+ new=AsyncMock(return_value=0),
+ ),
+ ):
+ parsed = await _call_llm_for_simulation(
+ "sys",
+ "user",
+ output_validator=_make_output_validator(self._OUTPUT_SCHEMA),
+ )
+
+ assert parsed == {"main_result": {"text": "right"}, "response": "ok"}
+ assert create_mock.call_count == 2
+ retry_messages = create_mock.call_args_list[1].kwargs["messages"]
+ assert any(
+ "does not conform" in str(m.get("content", "")) for m in retry_messages
+ )
+
+ @pytest.mark.asyncio
+ async def test_returns_last_parsed_when_retries_exhausted(self) -> None:
+ """A structurally imperfect simulation beats failing the dry run."""
+ bad = '{"main_result": ["still wrong"], "response": "ok"}'
+ client, create_mock = self._client_with_responses([bad] * _MAX_JSON_RETRIES)
+ with (
+ patch(
+ "backend.executor.simulator.get_openai_client",
+ return_value=client,
+ ),
+ patch(
+ "backend.executor.simulator.persist_and_record_usage",
+ new=AsyncMock(return_value=0),
+ ),
+ ):
+ parsed = await _call_llm_for_simulation(
+ "sys",
+ "user",
+ output_validator=_make_output_validator(self._OUTPUT_SCHEMA),
+ )
+
+ assert parsed == {"main_result": ["still wrong"], "response": "ok"}
+ assert create_mock.call_count == _MAX_JSON_RETRIES
diff --git a/autogpt_platform/frontend/src/app/api/openapi.json b/autogpt_platform/frontend/src/app/api/openapi.json
index 77b975e08a..abbd12a4ee 100644
--- a/autogpt_platform/frontend/src/app/api/openapi.json
+++ b/autogpt_platform/frontend/src/app/api/openapi.json
@@ -16363,6 +16363,16 @@
{ "type": "null" }
],
"title": "Node Executions"
+ },
+ "nodes_failed": {
+ "anyOf": [
+ {
+ "items": { "$ref": "#/components/schemas/NodeFailureSummary" },
+ "type": "array"
+ },
+ { "type": "null" }
+ ],
+ "title": "Nodes Failed"
}
},
"type": "object",
@@ -18381,14 +18391,22 @@
"properties": {
"name": { "type": "string", "title": "Name" },
"description": { "type": "string", "title": "Description" },
+ "params": {
+ "anyOf": [{ "type": "string" }, { "type": "null" }],
+ "title": "Params",
+ "description": "Compact argument summary: top-level input field names, required ones marked with *."
+ },
"input_schema": {
- "additionalProperties": true,
- "type": "object",
- "title": "Input Schema"
+ "anyOf": [
+ { "additionalProperties": true, "type": "object" },
+ { "type": "null" }
+ ],
+ "title": "Input Schema",
+ "description": "Full input schema. Omitted in discovery responses to keep them small; the execution error path returns the failed tool's full schema on demand."
}
},
"type": "object",
- "required": ["name", "description", "input_schema"],
+ "required": ["name", "description"],
"title": "MCPToolInfo",
"description": "Information about a single MCP tool discovered from a server."
},
@@ -18932,6 +18950,19 @@
],
"title": "NodeExecutionResult"
},
+ "NodeFailureSummary": {
+ "properties": {
+ "node_id": { "type": "string", "title": "Node Id" },
+ "block_name": { "type": "string", "title": "Block Name" },
+ "error": {
+ "anyOf": [{ "type": "string" }, { "type": "null" }],
+ "title": "Error"
+ }
+ },
+ "type": "object",
+ "required": ["node_id", "block_name", "error"],
+ "title": "NodeFailureSummary"
+ },
"NodeModel": {
"properties": {
"id": { "type": "string", "title": "Id" },
diff --git a/docs/integrations/block-integrations/misc.md b/docs/integrations/block-integrations/misc.md
index 65a995269e..4ac469cc06 100644
--- a/docs/integrations/block-integrations/misc.md
+++ b/docs/integrations/block-integrations/misc.md
@@ -58,7 +58,7 @@ Tool and block identifiers provided in `tools` and `blocks` are validated at run
| 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 |
-| tools | Tool names to filter. Works with tools_exclude to form an allow-list or deny-list. Leave empty to apply no tool filter. | List["add_understanding" \| "bash_exec" \| "browser_act" \| "browser_navigate" \| "browser_screenshot" \| "connect_integration" \| "continue_run_block" \| "create_agent" \| "create_feature_request" \| "create_folder" \| "customize_agent" \| "decompose_goal" \| "delete_folder" \| "delete_preset" \| "delete_schedule" \| "delete_skill" \| "delete_workspace_file" \| "edit_agent" \| "find_agent" \| "find_block" \| "find_library_agent" \| "fix_agent_graph" \| "get_agent_building_guide" \| "get_doc_page" \| "get_mcp_guide" \| "get_platform_info" \| "get_sub_session_result" \| "list_agent_triggers" \| "list_chat_platform_channels" \| "list_folders" \| "list_presets" \| "list_schedules" \| "list_skills" \| "list_workspace_files" \| "memory_forget_confirm" \| "memory_forget_search" \| "memory_search" \| "memory_store" \| "move_agents_to_folder" \| "move_folder" \| "post_to_chat_platform" \| "read_skill" \| "read_workspace_file" \| "run_agent" \| "run_block" \| "run_mcp_tool" \| "run_sub_session" \| "schedule_followup" \| "search_docs" \| "search_feature_requests" \| "setup_agent_webhook_trigger" \| "store_skill" \| "update_folder" \| "update_preset" \| "validate_agent_graph" \| "view_agent_output" \| "web_fetch" \| "web_search" \| "write_workspace_file" \| "Agent" \| "Edit" \| "Glob" \| "Grep" \| "Read" \| "Task" \| "TodoWrite" \| "WebSearch" \| "Write"] | No |
+| tools | Tool names to filter. Works with tools_exclude to form an allow-list or deny-list. Leave empty to apply no tool filter. | List["add_understanding" \| "bash_exec" \| "browser_act" \| "browser_navigate" \| "browser_screenshot" \| "connect_integration" \| "continue_run_block" \| "create_agent" \| "create_feature_request" \| "create_folder" \| "customize_agent" \| "decompose_goal" \| "delete_folder" \| "delete_preset" \| "delete_schedule" \| "delete_skill" \| "delete_workspace_file" \| "edit_agent" \| "enter_agent_building_mode" \| "find_agent" \| "find_block" \| "find_library_agent" \| "fix_agent_graph" \| "get_agent_building_guide" \| "get_doc_page" \| "get_mcp_guide" \| "get_platform_info" \| "get_sub_session_result" \| "list_agent_triggers" \| "list_chat_platform_channels" \| "list_folders" \| "list_presets" \| "list_schedules" \| "list_skills" \| "list_workspace_files" \| "memory_forget_confirm" \| "memory_forget_search" \| "memory_search" \| "memory_store" \| "move_agents_to_folder" \| "move_folder" \| "post_to_chat_platform" \| "read_skill" \| "read_workspace_file" \| "run_agent" \| "run_block" \| "run_mcp_tool" \| "run_sub_session" \| "schedule_followup" \| "search_docs" \| "search_feature_requests" \| "setup_agent_webhook_trigger" \| "store_skill" \| "update_folder" \| "update_preset" \| "validate_agent_graph" \| "view_agent_output" \| "web_fetch" \| "web_search" \| "write_workspace_file" \| "Agent" \| "Edit" \| "Glob" \| "Grep" \| "Read" \| "Task" \| "TodoWrite" \| "WebSearch" \| "Write"] | No |
| tools_exclude | Controls how the 'tools' list is interpreted. True (default): 'tools' is a deny-list — listed tools are blocked, all others are allowed. An empty 'tools' list means allow everything. False: 'tools' is an allow-list — only listed tools are permitted. | bool | No |
| blocks | Block identifiers to filter when the copilot uses run_block. Each entry can be: a block name (e.g. 'HTTP Request'), a full block UUID, or the first 8 hex characters of the UUID (e.g. 'c069dc6b'). Works with blocks_exclude. Leave empty to apply no block filter. | List[str] | No |
| blocks_exclude | Controls how the 'blocks' list is interpreted. True (default): 'blocks' is a deny-list — listed blocks are blocked, all others are allowed. An empty 'blocks' list means allow everything. False: 'blocks' is an allow-list — only listed blocks are permitted. | bool | No |
@@ -247,7 +247,7 @@ The sandbox includes pip and npm pre-installed. Set timeout to limit execution t
| Input | Description | Type | Required |
|-------|-------------|------|----------|
| setup_commands | Shell commands to set up the sandbox before running the code. You can use `curl` or `git` to install your desired Debian based package manager. `pip` and `npm` are pre-installed. These commands are executed with `sh`, in the foreground. | List[str] | No |
-| variables | Variables defined here can be used directly in your Python or JavaScript code. Values wired in from other blocks keep their type; default values set on this node come in as strings, so parse them in your code if you need a number or other type. | Dict[str, Any] | No |
+| variables | Variables defined here can be used directly in your code. Each key (`variables_#_{name}`) is injected directly as a local variable with the same name (`{name}`) in your code. Values wired in from other blocks keep their type; default values set on this node come in as strings, so parse them in your code if you need a number or other type. | Dict[str, Any] | No |
| code | Code to execute in the sandbox | str | No |
| language | Programming language to execute | "python" \| "js" \| "bash" \| "r" \| "java" | No |
| timeout | Execution timeout in seconds | int | No |
@@ -259,7 +259,7 @@ The sandbox includes pip and npm pre-installed. Set timeout to limit execution t
| Output | Description | Type |
|--------|-------------|------|
| error | Error message if the operation failed | str |
-| main_result | The main result from the code execution | Main Result |
+| main_result | The main result from the code execution (the script's final expression). Its `json` sub-field is ONLY populated when the result is a dict/object/map — bare lists, strings, and numbers land in `text` as a string instead. To pass structured data downstream via `main_result_#_json_#_<key>` links, end the script with a key-value structure in the script's language (e.g. `{'items': my_list}` in Python, `({items: myList})` in JavaScript). | Main Result |
| results | List of results from the code execution | List[CodeExecutionResult] |
| response | Text output (if any) of the main execution result | str |
| stdout_logs | Standard output logs from execution | str |
@@ -303,7 +303,7 @@ Use this for multi-step code execution where each step builds on previous result
| Output | Description | Type |
|--------|-------------|------|
| error | Error message if the operation failed | str |
-| main_result | The main result from the code execution | Main Result |
+| main_result | The main result from the code execution (the script's final expression). Its `json` sub-field is ONLY populated when the result is a dict/object/map — bare lists, strings, and numbers land in `text` as a string instead. To pass structured data downstream via `main_result_#_json_#_<key>` links, end the script with a key-value structure in the script's language (e.g. `{'items': my_list}` in Python, `({items: myList})` in JavaScript). | Main Result |
| results | List of results from the code execution | List[CodeExecutionResult] |
| response | Text output (if any) of the main execution result | str |
| stdout_logs | Standard output logs from execution | str |