cleveragents/cleveragents-core

Fork 3

Update built-in actors to use v3 YAML format with `type` field #10882

New issue

Closed

opened 2026-04-28 06:55:04 +00:00 by hurui200320 · 1 comment

hurui200320 commented

2026-04-28 06:55:04 +00:00

Member

Metadata

Commit Message: fix(actor): add v3 YAML text generation for built-in actors
Branch: bugfix/m3-built-in-actor-v3-yaml

Labels

Type/Bug
Priority/High
State/Unverified

Milestone

Milestone: v3.8.0

Background and Context

Built-in actors (e.g., openai/gpt-4, anthropic/claude-3-opus) are automatically generated from the provider registry and stored in the database. These actors are intended to work identically to custom actors added via YAML.

Issue #10807 (PR #10818) fixed the agents actor run command for custom actors by ensuring the ReactiveConfigParser recognizes v3 YAML format and synthesizes execution routes. However, built-in actors continue to fail silently because they lack the required v3 type field in their stored configuration.

This inconsistency prevents developers from using agents actor run with built-in actors, forcing them to create redundant custom actors for testing and quick experimentation.

Current Behavior

Built-in actors are created in actor/registry.py:ensure_built_in_actors() without a type field:

config_blob={
    "provider": "openai",
    "model": "gpt-4",
    "capabilities": {...},
    "unsafe": False,
    "source": "provider-registry",
    "graph_descriptor": {...}
}
# yaml_text is NOT provided → stored as None

When agents actor run retrieves the actor, the config is serialized to YAML without the type key:

capabilities:
  supports_tools: true
graph_descriptor:
  model: gpt-4
  provider: openai
model: gpt-4
provider: openai
source: provider-registry
unsafe: false

The ReactiveConfigParser._is_v3_format() check fails (no type key), resulting in:

Empty agents and routes dictionaries
run_single_shot() returns empty output silently
No error message to indicate what went wrong

Test evidence:

PARSING BUILT-IN ACTOR (config_blob serialized to YAML):
Is v3 format? False
Built config agents: []
Built config routes: []
RESULT: Would FAIL (empty)

Expected Behavior

Built-in actors should be stored with proper v3 YAML text including the type field:

name: openai/gpt-4
type: llm
model: openai/gpt-4
description: Built-in actor from provider registry (openai/gpt-4)
provider: openai
capabilities:
  supports_tools: true
unsafe: false
source: provider-registry

This ensures:

ReactiveConfigParser._is_v3_format() recognizes the actor as v3 format
Agents and routes are synthesized correctly via _synthesise_single_node_route()
agents actor run openai/gpt-4 "test" executes the LLM and returns output
Built-in and custom actors behave identically

Acceptance Criteria

Built-in actors created by ensure_built_in_actors() include yaml_text field with v3 format
Generated YAML includes type: llm field
Generated YAML includes description field (required by v3 schema)
agents actor run openai/gpt-4 "test" returns non-empty output (when LLM is configured)
All existing actor tests continue to pass
New BDD scenario added: "Built-in actors work with agents actor run"
No breaking changes to actor list/show/remove commands
Migration strategy documented for existing built-in actors

Supporting Information

Root Cause Analysis

The issue lies in the interaction between three components:

Built-in Actor Storage (actor/registry.py:ensure_built_in_actors()) - No yaml_text stored
Config Resolution (cli/commands/_resolve_actor.py:resolve_config_files()) - Serializes config_blob without type
Configuration Parsing (reactive/config_parser.py:ReactiveConfigParser._build()) - Doesn't recognize as v3 format

Issue #10861: Original bug report - agents actor run fails for built-in actors
Issue #10807: Related fix for custom actors (PR #10818)
Commit d512123d: Support v3 Actor YAML schema in CLI registration
Commit 0127b6f7: Synthesise execution route for type:llm actors

Technical Notes

Built-in actors are regenerated on each ensure_built_in_actors() call, so existing instances will be updated automatically
The is_built_in=True flag prevents custom actors from overwriting built-in entries
The yaml_text field is optional in the Actor model, so backward compatibility is maintained during transition
No database migration script needed - actors will be refreshed automatically on next startup

Subtasks

Add _generate_builtin_actor_yaml() helper method to ActorRegistry class
Modify ensure_built_in_actors() to generate and pass yaml_text to upsert_actor()
Add BDD feature file: features/builtin_actor_v3_yaml.feature
Add BDD step definitions for new scenarios
Add unit tests: tests/actor/test_registry_builtin_yaml.py
Run nox -s tests - all tests must pass
Run nox -s coverage_report - verify coverage >=97%
Run nox (all default sessions) - fix any errors
Update CHANGELOG.md with entry for this fix
Verify manually: agents actor run works for built-in actors

Definition of Done

This issue is complete when:

All subtasks above are completed and checked off.
A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation.
The commit is pushed to the remote on the branch matching the Branch in Metadata exactly.
The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.
All automated CI checks pass (tests, linting, type checking, coverage, security scans).
The PR description includes this issue reference with correct dependency direction (PR blocks this issue).
The PR is assigned to the same milestone as this issue.
The PR carries the Type/Bug label.

Parent Link

Blocks: #10861 (agents actor run fails for built-in actors)

Blocking Links

None (this issue is not blocked by any other issues)

References

CONTRIBUTING.md: Creating Issues, Commit Message Format
Spec: docs/specification.md - Actor configuration (v3 schema), lines 4562-4566
Files:
- src/cleveragents/actor/registry.py - ensure_built_in_actors() method
- src/cleveragents/actor/schema.py - ActorConfigSchema definition
- src/cleveragents/cli/commands/_resolve_actor.py - Config resolution logic
- src/cleveragents/reactive/config_parser.py - Configuration parsing

## Metadata - **Commit Message:** `fix(actor): add v3 YAML text generation for built-in actors` - **Branch:** `bugfix/m3-built-in-actor-v3-yaml` --- ## Labels - `Type/Bug` - `Priority/High` - `State/Unverified` --- ## Milestone - **Milestone:** v3.8.0 --- ## Background and Context Built-in actors (e.g., `openai/gpt-4`, `anthropic/claude-3-opus`) are automatically generated from the provider registry and stored in the database. These actors are intended to work identically to custom actors added via YAML. Issue #10807 (PR #10818) fixed the `agents actor run` command for **custom actors** by ensuring the `ReactiveConfigParser` recognizes v3 YAML format and synthesizes execution routes. However, built-in actors continue to fail silently because they lack the required v3 `type` field in their stored configuration. This inconsistency prevents developers from using `agents actor run` with built-in actors, forcing them to create redundant custom actors for testing and quick experimentation. --- ## Current Behavior Built-in actors are created in `actor/registry.py:ensure_built_in_actors()` without a `type` field: ```python config_blob={ "provider": "openai", "model": "gpt-4", "capabilities": {...}, "unsafe": False, "source": "provider-registry", "graph_descriptor": {...} } # yaml_text is NOT provided → stored as None ``` When `agents actor run` retrieves the actor, the config is serialized to YAML without the `type` key: ```yaml capabilities: supports_tools: true graph_descriptor: model: gpt-4 provider: openai model: gpt-4 provider: openai source: provider-registry unsafe: false ``` The `ReactiveConfigParser._is_v3_format()` check fails (no `type` key), resulting in: - Empty `agents` and `routes` dictionaries - `run_single_shot()` returns empty output silently - No error message to indicate what went wrong **Test evidence:** ``` PARSING BUILT-IN ACTOR (config_blob serialized to YAML): Is v3 format? False Built config agents: [] Built config routes: [] RESULT: Would FAIL (empty) ``` --- ## Expected Behavior Built-in actors should be stored with proper v3 YAML text including the `type` field: ```yaml name: openai/gpt-4 type: llm model: openai/gpt-4 description: Built-in actor from provider registry (openai/gpt-4) provider: openai capabilities: supports_tools: true unsafe: false source: provider-registry ``` This ensures: - `ReactiveConfigParser._is_v3_format()` recognizes the actor as v3 format - Agents and routes are synthesized correctly via `_synthesise_single_node_route()` - `agents actor run openai/gpt-4 "test"` executes the LLM and returns output - Built-in and custom actors behave identically --- ## Acceptance Criteria - [ ] Built-in actors created by `ensure_built_in_actors()` include `yaml_text` field with v3 format - [ ] Generated YAML includes `type: llm` field - [ ] Generated YAML includes `description` field (required by v3 schema) - [ ] `agents actor run openai/gpt-4 "test"` returns non-empty output (when LLM is configured) - [ ] All existing actor tests continue to pass - [ ] New BDD scenario added: "Built-in actors work with agents actor run" - [ ] No breaking changes to actor list/show/remove commands - [ ] Migration strategy documented for existing built-in actors --- ## Supporting Information ### Root Cause Analysis The issue lies in the interaction between three components: 1. **Built-in Actor Storage** (`actor/registry.py:ensure_built_in_actors()`) - No `yaml_text` stored 2. **Config Resolution** (`cli/commands/_resolve_actor.py:resolve_config_files()`) - Serializes `config_blob` without `type` 3. **Configuration Parsing** (`reactive/config_parser.py:ReactiveConfigParser._build()`) - Doesn't recognize as v3 format ### Related Issues and PRs - **Issue #10861:** Original bug report - `agents actor run` fails for built-in actors - **Issue #10807:** Related fix for custom actors (PR #10818) - **Commit `d512123d`:** Support v3 Actor YAML schema in CLI registration - **Commit `0127b6f7`:** Synthesise execution route for type:llm actors ### Technical Notes - Built-in actors are **regenerated** on each `ensure_built_in_actors()` call, so existing instances will be updated automatically - The `is_built_in=True` flag prevents custom actors from overwriting built-in entries - The `yaml_text` field is optional in the Actor model, so backward compatibility is maintained during transition - No database migration script needed - actors will be refreshed automatically on next startup --- ## Subtasks - [ ] Add `_generate_builtin_actor_yaml()` helper method to `ActorRegistry` class - [ ] Modify `ensure_built_in_actors()` to generate and pass `yaml_text` to `upsert_actor()` - [ ] Add BDD feature file: `features/builtin_actor_v3_yaml.feature` - [ ] Add BDD step definitions for new scenarios - [ ] Add unit tests: `tests/actor/test_registry_builtin_yaml.py` - [ ] Run `nox -s tests` - all tests must pass - [ ] Run `nox -s coverage_report` - verify coverage >=97% - [ ] Run `nox` (all default sessions) - fix any errors - [ ] Update CHANGELOG.md with entry for this fix - [ ] Verify manually: `agents actor run` works for built-in actors --- ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation. - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly. - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done. - All automated CI checks pass (tests, linting, type checking, coverage, security scans). - The PR description includes this issue reference with correct dependency direction (PR blocks this issue). - The PR is assigned to the same milestone as this issue. - The PR carries the `Type/Bug` label. --- ## Parent Link - **Blocks:** #10861 (agents actor run fails for built-in actors) --- ## Blocking Links - None (this issue is not blocked by any other issues) --- ## References - CONTRIBUTING.md: [Creating Issues](#creating-issues), [Commit Message Format](#commit-message-format) - Spec: `docs/specification.md` - Actor configuration (v3 schema), lines 4562-4566 - Files: - `src/cleveragents/actor/registry.py` - `ensure_built_in_actors()` method - `src/cleveragents/actor/schema.py` - `ActorConfigSchema` definition - `src/cleveragents/cli/commands/_resolve_actor.py` - Config resolution logic - `src/cleveragents/reactive/config_parser.py` - Configuration parsing

hurui200320 commented

2026-04-29 10:08:05 +00:00

Author

Member

close since dup with #10883

hurui200320 closed this issue

2026-04-29 10:08:05 +00:00