mirror of
https://github.com/openai/codex.git
synced 2026-11-22 15:15:18 +00:00
Source multi-agent instructions from the model catalog (#38619)
## What changed - Add model-catalog messages for root and subagent roles, explicit delegation, and delegation hints. - Resolve role instructions in config, catalog, then bundled-default order, while preserving empty values as an explicit way to suppress fallback text. - Refresh catalog-provided role and mode instructions when the model changes, and give full-history forks the selected child model's subagent role without retaining the parent's role guidance. - Keep existing config overrides and reasoning-effort behavior, including proactive delegation for ultra reasoning effort. ## Testing - Cover message deserialization and preservation through model overrides. - Cover precedence, empty overrides, model switches, resumed sessions, and full-history subagent forks. GitOrigin-RevId: 4625cf7c6a5490176adddfaa0fb99100707daea9
This commit is contained in:
1 parent
14a6813fa8
commit
395723b238
30 files changed
+734
-231
No files matched your search
@@ -1,7 +1,9 @@
|
||||
use crate::config::edit::ConfigEdit;
|
||||
use crate::config::edit::ConfigEditsBuilder;
|
||||
use crate::config::edit::apply_blocking;
|
||||
use crate::context::ContextualUserFragment;
|
||||
use crate::plugins::plugins_manager_for_config;
|
||||
use crate::session::multi_agents::resolve_usage_hints;
|
||||
use assert_matches::assert_matches;
|
||||
use codex_config::CONFIG_TOML_FILE;
|
||||
use codex_config::ConfigLayerEntry;
|
||||
@@ -87,6 +89,7 @@ use codex_protocol::models::BUILT_IN_PERMISSION_PROFILE_WORKSPACE;
|
||||
use codex_protocol::models::ManagedFileSystemPermissions;
|
||||
use codex_protocol::models::PermissionProfile;
|
||||
use codex_protocol::models::SandboxEnforcement;
|
||||
use codex_protocol::openai_models::MultiAgentRoleMessages;
|
||||
use codex_protocol::permissions::FileSystemAccessMode;
|
||||
use codex_protocol::permissions::FileSystemPath;
|
||||
use codex_protocol::permissions::FileSystemSandboxEntry;
|
||||
@@ -10991,17 +10994,29 @@ max_concurrent_threads_per_session = 17
|
||||
|
||||
let config = resolve_multi_agent_v2_config(&config_toml);
|
||||
let concurrency_guidance = "There are 17 available concurrency slots, meaning that up to 17 agents can be active at once, including you.";
|
||||
let expected_suffix = format!(
|
||||
"{DEFAULT_MULTI_AGENT_V2_SHARED_USAGE_HINT_TEXT}\n{DEFAULT_MULTI_AGENT_V2_WAIT_AGENT_USAGE_HINT_TEXT}\n\n{concurrency_guidance}"
|
||||
);
|
||||
assert!(
|
||||
[
|
||||
config.root_agent_usage_hint_text,
|
||||
config.subagent_usage_hint_text,
|
||||
]
|
||||
.into_iter()
|
||||
.all(|hint| hint.is_some_and(|hint| hint.contains(expected_suffix.as_str())))
|
||||
assert!(config.wait_agent_enabled);
|
||||
for wait_agent_enabled in [true, false] {
|
||||
let mut config = config.clone();
|
||||
config.wait_agent_enabled = wait_agent_enabled;
|
||||
let usage_hints = resolve_usage_hints(&config, /*catalog*/ None);
|
||||
for hint in [usage_hints.root, usage_hints.subagent] {
|
||||
let hint = hint.expect("default usage hints should be present").body();
|
||||
assert!(hint.contains(concurrency_guidance));
|
||||
assert_eq!(
|
||||
hint.contains("When calling `wait_agent`, prefer longer waits"),
|
||||
wait_agent_enabled
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
let usage_hints = resolve_usage_hints(
|
||||
&config,
|
||||
Some(&MultiAgentRoleMessages {
|
||||
root: Some(String::new()),
|
||||
subagent: Some(String::new()),
|
||||
}),
|
||||
);
|
||||
assert!(usage_hints.root.is_none() && usage_hints.subagent.is_none());
|
||||
}
|
||||
|
||||
#[test]
|
||||
@@ -11026,6 +11041,23 @@ expose_spawn_agent_model_overrides = true
|
||||
config.subagent_usage_hint_text.as_deref(),
|
||||
Some("Subagent guidance.")
|
||||
);
|
||||
let usage_hints = resolve_usage_hints(
|
||||
&config,
|
||||
Some(&MultiAgentRoleMessages {
|
||||
root: Some("Catalog root base.".to_string()),
|
||||
subagent: Some("Catalog subagent base.".to_string()),
|
||||
}),
|
||||
);
|
||||
assert_eq!(
|
||||
(
|
||||
usage_hints.root.map(|hint| hint.body()),
|
||||
usage_hints.subagent.map(|hint| hint.body()),
|
||||
),
|
||||
(
|
||||
Some("Root guidance.".to_string()),
|
||||
Some("Subagent guidance.".to_string()),
|
||||
)
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
@@ -11033,18 +11065,39 @@ fn multi_agent_v2_exposes_model_overrides_by_default() {
|
||||
let config_toml =
|
||||
toml::from_str(r#"[features.multi_agent_v2]"#).expect("multi-agent v2 config should parse");
|
||||
|
||||
let config = resolve_multi_agent_v2_config(&config_toml);
|
||||
let mut config = resolve_multi_agent_v2_config(&config_toml);
|
||||
assert!(config.expose_spawn_agent_model_overrides);
|
||||
assert!(
|
||||
[
|
||||
config.root_agent_usage_hint_text,
|
||||
config.subagent_usage_hint_text,
|
||||
]
|
||||
.into_iter()
|
||||
.all(|hint| hint.is_some_and(|hint| {
|
||||
hint.ends_with(DEFAULT_MULTI_AGENT_V2_MODEL_OVERRIDE_USAGE_HINT_TEXT)
|
||||
}))
|
||||
);
|
||||
let usage_hints = resolve_usage_hints(&config, /*catalog*/ None);
|
||||
config.expose_spawn_agent_model_overrides = false;
|
||||
let usage_hints_without_model_overrides = resolve_usage_hints(&config, /*catalog*/ None);
|
||||
|
||||
for (hint, hint_without_model_overrides) in [
|
||||
(usage_hints.root, usage_hints_without_model_overrides.root),
|
||||
(
|
||||
usage_hints.subagent,
|
||||
usage_hints_without_model_overrides.subagent,
|
||||
),
|
||||
] {
|
||||
let hint = hint.expect("default usage hints should be present").body();
|
||||
let hint_without_model_overrides = hint_without_model_overrides
|
||||
.expect("default usage hints should be present without model overrides")
|
||||
.body();
|
||||
|
||||
let model_override_guidance = hint
|
||||
.strip_prefix(hint_without_model_overrides.as_str())
|
||||
.expect("model-override guidance should extend the base usage hint");
|
||||
for required_fragment in [
|
||||
"Full-history forks",
|
||||
"`fork_turns`",
|
||||
"`model`",
|
||||
"`reasoning_effort`",
|
||||
] {
|
||||
assert!(
|
||||
model_override_guidance.contains(required_fragment),
|
||||
"model-override guidance should contain {required_fragment}"
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
@@ -11108,7 +11161,7 @@ subagent_developer_instructions = " \t "
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn multi_agent_v2_empty_usage_hint_overrides_clear_default_hints() -> std::io::Result<()> {
|
||||
async fn multi_agent_v2_empty_usage_hint_overrides_are_preserved() -> std::io::Result<()> {
|
||||
let codex_home = TempDir::new()?;
|
||||
std::fs::write(
|
||||
codex_home.path().join(CONFIG_TOML_FILE),
|
||||
@@ -11125,8 +11178,22 @@ subagent_usage_hint_text = ""
|
||||
.build()
|
||||
.await?;
|
||||
|
||||
assert_eq!(config.multi_agent_v2.root_agent_usage_hint_text, None);
|
||||
assert_eq!(config.multi_agent_v2.subagent_usage_hint_text, None);
|
||||
let usage_hints = resolve_usage_hints(
|
||||
&config.multi_agent_v2,
|
||||
Some(&MultiAgentRoleMessages {
|
||||
root: Some("catalog root".to_string()),
|
||||
subagent: Some("catalog subagent".to_string()),
|
||||
}),
|
||||
);
|
||||
assert_eq!(
|
||||
(
|
||||
config.multi_agent_v2.root_agent_usage_hint_text.as_deref(),
|
||||
config.multi_agent_v2.subagent_usage_hint_text.as_deref(),
|
||||
usage_hints.root,
|
||||
usage_hints.subagent,
|
||||
),
|
||||
(Some(""), Some(""), None, None)
|
||||
);
|
||||
|
||||
Ok(())
|
||||
}
|
||||
|
||||
@@ -213,69 +213,7 @@ pub(crate) const DEFAULT_MULTI_AGENT_V2_MAX_CONCURRENT_THREADS_PER_SESSION: usiz
|
||||
pub(crate) const DEFAULT_MULTI_AGENT_V2_MIN_WAIT_TIMEOUT_MS: i64 = 10_000;
|
||||
pub(crate) const DEFAULT_MULTI_AGENT_V2_MAX_WAIT_TIMEOUT_MS: i64 = 3600 * 1000;
|
||||
pub(crate) const DEFAULT_MULTI_AGENT_V2_DEFAULT_WAIT_TIMEOUT_MS: i64 = 30_000;
|
||||
const DEFAULT_MULTI_AGENT_V2_ROOT_AGENT_USAGE_HINT_TEXT: &str = r#"You are `/root`, the primary agent in a team of agents collaborating to fulfill the user's goals.
|
||||
|
||||
At the start of your turn, you are the active agent.
|
||||
You can spawn sub-agents to handle subtasks, and those sub-agents can spawn their own sub-agents.
|
||||
All agents in the team, including the agents that you can assign tasks to, are equally intelligent and capable, and have access to the same set of tools.
|
||||
|
||||
You can use `spawn_agent` to create a new agent, `followup_task` to give an existing agent a new task and trigger a turn, and `send_message` to pass a message to a running agent without triggering a turn.
|
||||
Child agents can also spawn their own sub-agents.
|
||||
You can decide how much context you want to propagate to your sub-agents with the `fork_turns` parameter.
|
||||
|
||||
You will receive messages in the analysis channel in the form:
|
||||
```
|
||||
Message Type: MESSAGE | FINAL_ANSWER
|
||||
Task name: <recipient>
|
||||
Sender: <author>
|
||||
Payload:
|
||||
<payload text>
|
||||
```
|
||||
They may be addressed as to=/root
|
||||
"#;
|
||||
const DEFAULT_MULTI_AGENT_V2_SUBAGENT_USAGE_HINT_TEXT: &str = r#"You are an agent in a team of agents collaborating to complete a task.
|
||||
|
||||
You can spawn sub-agents to handle subtasks, and those sub-agents can spawn their own sub-agents. All agents in the team, including the agents that you can assign tasks to, are equally intelligent and capable, and have access to the same set of tools.
|
||||
|
||||
You can use `spawn_agent` to create a new agent, `followup_task` to give an existing agent a new task and trigger a turn, and `send_message` to pass a message to a running agent.
|
||||
Child agents can also spawn their own sub-agents.
|
||||
|
||||
When you provide a response in the final channel, that content is immediately delivered back to your parent agent.
|
||||
|
||||
You will receive messages in the analysis channel in the form:
|
||||
```
|
||||
Message Type: NEW_TASK | MESSAGE | FINAL_ANSWER
|
||||
Task name: <recipient>
|
||||
Sender: <author>
|
||||
Payload:
|
||||
<payload text>
|
||||
```
|
||||
You may also see them addressed as to=/root/..., which indicates your identity is /root/...
|
||||
"#;
|
||||
const DEFAULT_MULTI_AGENT_V2_MODEL_OVERRIDE_USAGE_HINT_TEXT: &str = "Full-history forks (`fork_turns` omitted or `\"all\"`) inherit the parent model and reasoning effort and do not accept overrides. Only set `model` or `reasoning_effort` when explicitly requested by the user, applicable `AGENTS.md` instructions, or skill instructions; when doing so, set `fork_turns` to `\"none\"` or a positive integer string.";
|
||||
const DEFAULT_MULTI_AGENT_V2_TOOL_NAMESPACE: &str = "collaboration";
|
||||
const DEFAULT_MULTI_AGENT_V2_WAIT_AGENT_USAGE_HINT_TEXT: &str =
|
||||
"When calling `wait_agent`, prefer longer waits (minutes) to avoid busy polling.";
|
||||
const DEFAULT_MULTI_AGENT_V2_SHARED_USAGE_HINT_TEXT: &str = r#"Note that collaboration tools cannot be called from inside `functions.exec`. Call `spawn_agent`, `send_message`, `followup_task`, `wait_agent`, `interrupt_agent`, and `list_agents` only as direct tool calls using the recipient shown in their tool definitions, such as `to=functions.collaboration.spawn_agent`, since they are intentionally absent from the `functions.exec` `tools.*` namespace. Available tools in `functions.exec` are explicitly described with a `tools` namespace in the developer message.
|
||||
|
||||
All agents share the same directory. In detail:
|
||||
- All agents have access to the same container and filesystem as you.
|
||||
- All agents use the same current working directory.
|
||||
- As a result, edits made by one agent are immediately visible to all other agents.
|
||||
"#;
|
||||
fn default_multi_agent_v2_usage_hint_text(
|
||||
usage_hint_text: &str,
|
||||
max_concurrency: usize,
|
||||
wait_agent_usage_hint_text: Option<&str>,
|
||||
) -> String {
|
||||
let wait_agent_usage_hint_text = match wait_agent_usage_hint_text {
|
||||
Some(wait_agent_usage_hint_text) => format!("{wait_agent_usage_hint_text}\n\n"),
|
||||
None => String::new(),
|
||||
};
|
||||
format!(
|
||||
"{usage_hint_text}\n{DEFAULT_MULTI_AGENT_V2_SHARED_USAGE_HINT_TEXT}\n{wait_agent_usage_hint_text}There are {max_concurrency} available concurrency slots, meaning that up to {max_concurrency} agents can be active at once, including you."
|
||||
)
|
||||
}
|
||||
|
||||
pub(crate) const HARD_MIN_MULTI_AGENT_V2_TIMEOUT_MS: i64 = 0;
|
||||
pub(crate) const HARD_MAX_MULTI_AGENT_V2_TIMEOUT_MS: i64 =
|
||||
@@ -1298,16 +1236,8 @@ impl MultiAgentV2Config {
|
||||
max_wait_timeout_ms: DEFAULT_MULTI_AGENT_V2_MAX_WAIT_TIMEOUT_MS,
|
||||
default_wait_timeout_ms: DEFAULT_MULTI_AGENT_V2_DEFAULT_WAIT_TIMEOUT_MS,
|
||||
usage_hint_text: None,
|
||||
root_agent_usage_hint_text: Some(default_multi_agent_v2_usage_hint_text(
|
||||
DEFAULT_MULTI_AGENT_V2_ROOT_AGENT_USAGE_HINT_TEXT,
|
||||
max_concurrent_threads_per_session,
|
||||
Some(DEFAULT_MULTI_AGENT_V2_WAIT_AGENT_USAGE_HINT_TEXT),
|
||||
)),
|
||||
subagent_usage_hint_text: Some(default_multi_agent_v2_usage_hint_text(
|
||||
DEFAULT_MULTI_AGENT_V2_SUBAGENT_USAGE_HINT_TEXT,
|
||||
max_concurrent_threads_per_session,
|
||||
Some(DEFAULT_MULTI_AGENT_V2_WAIT_AGENT_USAGE_HINT_TEXT),
|
||||
)),
|
||||
root_agent_usage_hint_text: None,
|
||||
subagent_usage_hint_text: None,
|
||||
subagent_developer_instructions: None,
|
||||
multi_agent_mode_hint_text: None,
|
||||
tool_namespace: Some(DEFAULT_MULTI_AGENT_V2_TOOL_NAMESPACE.to_string()),
|
||||
@@ -2725,42 +2655,15 @@ fn resolve_multi_agent_v2_config(config_toml: &ConfigToml) -> MultiAgentV2Config
|
||||
let expose_spawn_agent_model_overrides = base
|
||||
.and_then(|config| config.expose_spawn_agent_model_overrides)
|
||||
.unwrap_or(default.expose_spawn_agent_model_overrides);
|
||||
let root_agent_usage_hint_text = base
|
||||
.and_then(|config| config.root_agent_usage_hint_text.as_ref())
|
||||
.cloned();
|
||||
let subagent_usage_hint_text = base
|
||||
.and_then(|config| config.subagent_usage_hint_text.as_ref())
|
||||
.cloned();
|
||||
let wait_agent_enabled = base
|
||||
.and_then(|config| config.wait_agent_enabled)
|
||||
.unwrap_or(default.wait_agent_enabled);
|
||||
let default_wait_agent_usage_hint_text = if wait_agent_enabled {
|
||||
Some(DEFAULT_MULTI_AGENT_V2_WAIT_AGENT_USAGE_HINT_TEXT)
|
||||
} else {
|
||||
None
|
||||
};
|
||||
let mut default_root_agent_usage_hint_text = Some(default_multi_agent_v2_usage_hint_text(
|
||||
DEFAULT_MULTI_AGENT_V2_ROOT_AGENT_USAGE_HINT_TEXT,
|
||||
max_concurrent_threads_per_session,
|
||||
default_wait_agent_usage_hint_text,
|
||||
));
|
||||
let mut default_subagent_usage_hint_text = Some(default_multi_agent_v2_usage_hint_text(
|
||||
DEFAULT_MULTI_AGENT_V2_SUBAGENT_USAGE_HINT_TEXT,
|
||||
max_concurrent_threads_per_session,
|
||||
default_wait_agent_usage_hint_text,
|
||||
));
|
||||
if expose_spawn_agent_model_overrides {
|
||||
default_root_agent_usage_hint_text = Some(append_usage_hint_text(
|
||||
default_root_agent_usage_hint_text.as_deref(),
|
||||
DEFAULT_MULTI_AGENT_V2_MODEL_OVERRIDE_USAGE_HINT_TEXT,
|
||||
));
|
||||
default_subagent_usage_hint_text = Some(append_usage_hint_text(
|
||||
default_subagent_usage_hint_text.as_deref(),
|
||||
DEFAULT_MULTI_AGENT_V2_MODEL_OVERRIDE_USAGE_HINT_TEXT,
|
||||
));
|
||||
}
|
||||
let root_agent_usage_hint_text = resolve_optional_prompt_text(
|
||||
base.map(|config| &config.root_agent_usage_hint_text),
|
||||
default_root_agent_usage_hint_text,
|
||||
);
|
||||
let subagent_usage_hint_text = resolve_optional_prompt_text(
|
||||
base.map(|config| &config.subagent_usage_hint_text),
|
||||
default_subagent_usage_hint_text,
|
||||
);
|
||||
let subagent_developer_instructions = base
|
||||
.and_then(|config| config.subagent_developer_instructions.as_ref())
|
||||
.map(|instructions| instructions.trim().to_string());
|
||||
@@ -2941,24 +2844,6 @@ fn resolve_terminal_resize_reflow_config(config_toml: &ConfigToml) -> TerminalRe
|
||||
}
|
||||
}
|
||||
|
||||
fn resolve_optional_prompt_text(
|
||||
configured: Option<&Option<String>>,
|
||||
default: Option<String>,
|
||||
) -> Option<String> {
|
||||
match configured {
|
||||
Some(Some(value)) if value.is_empty() => None,
|
||||
Some(Some(value)) => Some(value.clone()),
|
||||
Some(None) | None => default,
|
||||
}
|
||||
}
|
||||
|
||||
fn append_usage_hint_text(usage_hint_text: Option<&str>, additional_text: &str) -> String {
|
||||
match usage_hint_text {
|
||||
Some(usage_hint_text) => format!("{usage_hint_text}\n\n{additional_text}"),
|
||||
None => additional_text.to_string(),
|
||||
}
|
||||
}
|
||||
|
||||
fn code_mode_toml_config(features: Option<&FeaturesToml>) -> Option<&CodeModeConfigToml> {
|
||||
match features?.code_mode.as_ref()? {
|
||||
FeatureToml::Enabled(_) => None,
|
||||
|
||||
Reference in new issue
Block a user