feat(agent): add custom-agent self-updates with user isolation by yangzheli · Pull Request #2713 · bytedance/deer-flow

yangzheli · 2026-05-04T04:27:19Z

Fixes #2616、#2722

Summary

Add the update_agent builtin and custom-agent prompt guidance so agents can persist their own SOUL.md / config.yaml updates through the supported tool path instead of shell or write_file.
Store custom agent definitions per effective user at {base_dir}/users/{user_id}/agents/{agent_name}/, while keeping the legacy shared {base_dir}/agents/{agent_name}/ layout readable as an unmigrated fallback.
Update the agents API plus setup_agent / update_agent tooling to resolve agents in user context and avoid name collisions with legacy shared agents.
Extend the user-isolation migration to move legacy custom agents into the per-user layout, preserving colliding legacy copies under migration-conflicts for manual review.

Test plan

Commit hooks passed: ruff lint, ruff format.
Added and updated backend tests covering path resolution, agents API behavior, setup/update tools, and migration handling for custom agents.

Screenshot

After

…tes (bytedance#2616) Custom agents had no built-in way to persist updates to their own SOUL.md / config.yaml from a normal chat — `setup_agent` was only bound during the bootstrap flow, so when the user asked the agent to refine its description or personality, the agent would shell out via bash/write_file and the edits landed in a temporary sandbox/tool workspace instead of `{base_dir}/agents/{agent_name}/`. Changes: - New `update_agent` builtin tool with partial-update semantics (only the fields you pass are written) and atomic temp-file + os.replace writes so a failed update never corrupts existing SOUL.md / config.yaml. - Lead agent now binds `update_agent` in the non-bootstrap path whenever `agent_name` is set in the runtime context. Default agent (no agent_name) and bootstrap flow are unchanged. - New `<self_update>` system-prompt section is injected for custom agents, instructing them to use `update_agent` — and explicitly NOT bash / write_file — to persist self-updates. - Tests: 11 new cases in `tests/test_update_agent_tool.py` covering validation (missing/invalid agent_name, unknown agent, no fields), partial updates (soul-only, description-only, skills=[] vs omitted), no-op detection, atomic-write safety, and AgentConfig round-tripping; plus 2 new cases in `tests/test_lead_agent_prompt.py` covering the self-update prompt section. - Docs: updated backend/CLAUDE.md builtin tools list and tools.mdx (en/zh) with the new tool description.

WillemJiang · 2026-05-04T05:33:59Z

@yangzheli, thanks for the contribution. Since we don't want to share the agent across the system, we should use the user ID to separate the agent settings and prevent other users from accessing the agent.

Copilot

Pull request overview

Adds a first-class mechanism for custom agents to persist self-updates (SOUL/config) from within normal chat runs, avoiding sandbox-local edits and ensuring changes apply on subsequent turns.

Changes:

Introduces a new builtin tool update_agent with partial-update semantics and atomic per-file writes for SOUL.md and config.yaml.
Binds update_agent to the lead agent only for non-bootstrap custom-agent sessions and injects a <self_update> prompt section guiding correct usage.
Adds backend tests and updates docs (EN/ZH) to describe the new tool and behavior.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
frontend/src/content/zh/harness/tools.mdx	Documents `update_agent` usage and partial-update semantics (ZH).
frontend/src/content/en/harness/tools.mdx	Documents `update_agent` usage and partial-update semantics (EN).
backend/tests/test_update_agent_tool.py	Adds validation/behavior/atomicity tests for `update_agent`.
backend/tests/test_lead_agent_prompt.py	Adds coverage for the new `<self_update>` prompt section.
backend/packages/harness/deerflow/tools/builtins/update_agent_tool.py	Implements the `update_agent` tool and atomic write helper.
backend/packages/harness/deerflow/tools/builtins/init.py	Exports `update_agent` from builtin tools.
backend/packages/harness/deerflow/agents/lead_agent/prompt.py	Injects `<self_update>` section for custom agents.
backend/packages/harness/deerflow/agents/lead_agent/agent.py	Binds `update_agent` only for non-bootstrap custom-agent sessions.
backend/CLAUDE.md	Updates builtin tools list to include `update_agent`.

…at/agent-user-isolation

Store custom agent definitions under the effective user, keep legacy agents readable until migration, and cover API/tool/migration behavior with tests. Co-authored-by: Cursor <cursoragent@cursor.com>

yangzheli · 2026-05-04T12:22:55Z

@yangzheli, thanks for the contribution. Since we don't want to share the agent across the system, we should use the user ID to separate the agent settings and prevent other users from accessing the agent.

Addressed all review comments in a8a4aa4. The custom agent is now persisted under the effective user. Please take another look when you have a moment.

WillemJiang · 2026-05-05T07:32:05Z

@yangzheli Here are some additional comments for this PR, please check them out.

Inconsistent write target: API endpoint vs. tool (Medium)

API update_agent endpoint writes to resolve_agent_dir() (may be legacy path)
The update_agent tool always writes to paths.user_agent_dir() (per-user only)
Result: updating via API keeps a legacy agent in legacy; updating via tool creates a per-user copy and orphans the legacy file

Frontend docs path mismatch (Low)

tools.mdx states {base_dir}/agents/{agent_name}/ but implementation writes to {base_dir}/users/{user_id}/agents/{agent_name}/

delete_agent deletes legacy agents for all users (Medium)

Uses resolve_agent_dir which may resolve to the shared legacy path — deletion removes it for all users in multi-user setups

Migration hard-codes user_id="default" (Low)

In multi-user setups, all legacy agents get assigned to default regardless of actual ownership

Verify update_agent not reachable during bootstrap (Low)

The tool is bound when agent_name is truthy; confirm bootstrap path returns early to avoid both setup_agent and update_agent being available simultaneously

…at/custom-agent-self-updates

yangzheli · 2026-05-05T10:33:30Z

Addressed in abd35d4.

Unify write/delete targets via paths.user_agent_dir()
Fix frontend docs path
Add --user-id argument to migration script

WillemJiang requested a review from Copilot May 4, 2026 05:34

Copilot started reviewing on behalf of WillemJiang May 4, 2026 05:34 View session

Copilot AI reviewed May 4, 2026

View reviewed changes

Merge branch 'main' of https://github.com/yangzheli/deer-flow into fe…

d1242d7

…at/agent-user-isolation

yangzheli marked this pull request as draft May 4, 2026 10:54

feat(agent): isolate custom agents per user

a8a4aa4

Store custom agent definitions under the effective user, keep legacy agents readable until migration, and cover API/tool/migration behavior with tests. Co-authored-by: Cursor <cursoragent@cursor.com>

yangzheli changed the title ~~feat(agent): add update_agent tool for in-chat custom-agent self-updates~~ feat(agent): add custom-agent self-updates with user isolation May 4, 2026

yangzheli marked this pull request as ready for review May 4, 2026 12:22

yangzheli added 2 commits May 5, 2026 16:14

Merge branch 'main' of https://github.com/yangzheli/deer-flow into fe…

3f689dd

…at/custom-agent-self-updates

feat: consistent write/delete targets & add --user-id to migration

abd35d4

yangzheli closed this May 5, 2026

yangzheli reopened this May 5, 2026

Merge branch 'main' into feat/custom-agent-self-updates

8784c21

WillemJiang approved these changes May 5, 2026

View reviewed changes

WillemJiang added this to the 2.0-m1 milestone May 5, 2026

WillemJiang merged commit 59c4a3f into bytedance:main May 5, 2026
6 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(agent): add custom-agent self-updates with user isolation#2713

feat(agent): add custom-agent self-updates with user isolation#2713
WillemJiang merged 6 commits intobytedance:mainfrom
yangzheli:feat/custom-agent-self-updates

yangzheli commented May 4, 2026 •

edited

Loading

Uh oh!

WillemJiang commented May 4, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

yangzheli commented May 4, 2026

Uh oh!

WillemJiang commented May 5, 2026

Uh oh!

yangzheli commented May 5, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

yangzheli commented May 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Screenshot

After

Uh oh!

WillemJiang commented May 4, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

yangzheli commented May 4, 2026

Uh oh!

WillemJiang commented May 5, 2026

Uh oh!

yangzheli commented May 5, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

yangzheli commented May 4, 2026 •

edited

Loading