feat: add AgentSpec for per-agent identity and system prompt parameterization

Implements Feature 2 of the Multi-Agent Future Roadmap (all 3 phases).

- New `BaseAgent/agent_spec.py`: `AgentSpec` dataclass with `name`, `role`,
  `system_prompt_override`, `tool_names`, `skill_names`, `llm`, `source`,
  and `temperature` fields.
- `BaseAgent/__init__.py`: exports `AgentSpec`.
- `prompts.py`: replaces hardcoded biomedical role with `{role_description}`
  slot; adds `_DEFAULT_ROLE_DESCRIPTION` constant for the fallback value.
- `base_agent.py`: `BaseAgent.__init__` accepts `spec: AgentSpec | None`;
  `configure()` applies `spec.tool_names` / `spec.skill_names` filters;
  `_generate_system_prompt()` injects `spec.role` or returns
  `spec.system_prompt_override` directly. Explicit kwargs always beat spec.
- `tests/test_agent_spec.py`: 22 unit tests (no API key required).
- `examples/08_agent_identity.py`: demonstrates role injection, tool subset,
  model override, prompt override, and backwards compatibility.

`spec=None` is the default; all existing behaviour is unchanged.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: BinglanLi

BaseAgent/__init__.py

@@ -5,7 +5,8 @@
 from .base_agent import BaseAgent
 from .events import AgentEvent, EventType
 from .resources import Skill
+from .agent_spec import AgentSpec
 
 __version__ = "0.1.0"
 __author__ = "BaseAgent Contributors"
-__all__ = ["BaseAgent", "AgentEvent", "EventType", "Skill"]
+__all__ = ["BaseAgent", "AgentEvent", "EventType", "Skill", "AgentSpec"]

BaseAgent/agent_spec.py

@@ -0,0 +1,56 @@
+"""
+AgentSpec: Identity and persona configuration for a BaseAgent instance.
+
+Used by the multi-agent system to give each agent a distinct name, role,
+tool subset, skill subset, and optional model override.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from BaseAgent.llm import SourceType
+
+
+@dataclass
+class AgentSpec:
+    """Identity and configuration for a single agent.
+
+    When passed to ``BaseAgent(spec=...)``, the spec:
+
+    * Sets ``agent.name`` (used for attribution in multi-agent logs).
+    * Injects ``role`` into the system prompt header.
+    * Optionally restricts which tools and skills are visible to this agent.
+    * Optionally overrides the LLM model, provider, and temperature.
+
+    All fields except ``name`` and ``role`` are optional.  When a field is
+    ``None`` the corresponding ``BaseAgentConfig`` default is used unchanged,
+    so omitting a field never changes existing behaviour.
+
+    Args:
+        name: Unique agent identifier, e.g. ``"ontology_analyst"``.
+        role: One-line description injected into the system prompt, e.g.
+            ``"a biomedical ontology analyst that …"``.
+        system_prompt_override: If provided, replaces the entire generated
+            system prompt.  ``name`` and ``role`` are still stored but
+            ``role`` is not injected.
+        tool_names: If provided, only the named tools are enabled for this
+            agent.  ``None`` means all loaded tools are enabled.
+        skill_names: If provided, only the named skills are enabled.
+            Skills with ``trigger="manual"`` are never removed regardless of
+            this list.  ``None`` means all loaded skills are enabled.
+        llm: Model name override, e.g. ``"claude-sonnet-4-20250514"``.
+        source: Provider override, e.g. ``"Anthropic"``.
+        temperature: Sampling temperature override.
+    """
+
+    name: str
+    role: str
+    system_prompt_override: str | None = None
+    tool_names: list[str] | None = None
+    skill_names: list[str] | None = None
+    llm: str | None = None
+    source: "SourceType | None" = None
+    temperature: float | None = None

BaseAgent/base_agent.py

@@ -33,8 +33,10 @@
     _CUSTOM_SOFTWARE_SECTION,
     _SKILLS_SECTION,
     _SKILL_ENTRY_TEMPLATE,
+    _DEFAULT_ROLE_DESCRIPTION,
 )
 from BaseAgent.resources import Skill
+from BaseAgent.agent_spec import AgentSpec
 from BaseAgent.config import default_config
 from BaseAgent.resource_manager import ResourceManager
 from BaseAgent.retriever import ToolRetriever
@@ -61,6 +63,7 @@ def __init__(
         checkpoint_db_path: str | None = None,
         require_approval: str | None = None,
         skills_directory: str | None = None,
+        spec: AgentSpec | None = None,
     ):
         """
         Args:
@@ -77,10 +80,27 @@ def __init__(
                 "always" — interrupt before every code block;
                 "dangerous_only" — interrupt only for bash/R code.
             skills_directory: Path to a directory of SKILL.md files to load on startup.
+            spec: Optional agent identity and persona.  When provided, ``spec.name``,
+                ``spec.role``, ``spec.tool_names``, ``spec.skill_names``,
+                ``spec.llm``, ``spec.source``, and ``spec.temperature`` override
+                the corresponding defaults.  Explicit keyword arguments take
+                priority over spec fields.
         """
+        self.spec = spec
+
+        # Agent name: from spec, or default
+        self.name: str = spec.name if spec is not None else "agent"
+
+        # Resolve settings: explicit kwargs > spec > default_config
         self.path = path if path is not None else default_config.path
-        self.llm_model_name = llm if llm is not None else default_config.llm
-        self.source = source if source is not None else default_config.source
+        self.llm_model_name = (
+            llm if llm is not None
+            else (spec.llm if spec is not None and spec.llm is not None else default_config.llm)
+        )
+        self.source = (
+            source if source is not None
+            else (spec.source if spec is not None and spec.source is not None else default_config.source)
+        )
         self.timeout_seconds = timeout_seconds if timeout_seconds is not None else default_config.timeout_seconds
         self.base_url = base_url if base_url is not None else default_config.base_url
         self.api_key = api_key if api_key is not None else default_config.api_key
@@ -96,6 +116,13 @@ def __init__(
         #TODO: add self-critic mode
         self.self_critic = False
 
+        # Temperature: explicit kwarg not exposed yet, so spec takes precedence over default
+        _temperature = (
+            spec.temperature
+            if spec is not None and spec.temperature is not None
+            else default_config.temperature
+        )
+
         # Initialize the LLM agent
         self.source, self.llm = get_llm(
             self.llm_model_name,
@@ -104,6 +131,7 @@ def __init__(
             base_url=self.base_url,
             api_key=self.api_key,
             config=default_config,
+            temperature=_temperature,
         )
 
         # Initialize the resource manager (replaces ToolRegistry)
@@ -694,9 +722,20 @@ def _generate_system_prompt(
             When tool retriever is not used, all resources have selected=True by default.
             When tool retriever is used, only retrieved resources are marked selected=True.
         """
+        # If the spec provides a full override, return it directly
+        if self.spec is not None and self.spec.system_prompt_override is not None:
+            return self.spec.system_prompt_override
+
         # Base prompt
         prompt_modifier = get_base_prompt_template(self_critic=self_critic)
-        prompt_format_dict = {}
+
+        # Role description: from spec, or fall back to the default
+        role_description = (
+            self.spec.role
+            if self.spec is not None
+            else _DEFAULT_ROLE_DESCRIPTION
+        )
+        prompt_format_dict = {"role_description": role_description}
 
         # Add custom resources section from resource manager
         custom_tools = self.resource_manager.collection.custom_tools
@@ -825,6 +864,13 @@ def configure(self, self_critic=False, test_time_scale_round=0):
         if self.skills_directory:
             self.load_skills(self.skills_directory)
 
+        # Apply AgentSpec resource filters (must happen after resources are loaded)
+        if self.spec is not None:
+            if self.spec.tool_names is not None:
+                self.resource_manager.select_tools_by_names(self.spec.tool_names)
+            if self.spec.skill_names is not None:
+                self.resource_manager.select_skills_by_names(self.spec.skill_names)
+
         # Generate the system prompt (will be built automatically from ResourceManager)
         self.system_prompt = self._generate_system_prompt(
             self_critic=self_critic,

BaseAgent/prompts.py

@@ -4,9 +4,13 @@
 
 from textwrap import dedent
 
+_DEFAULT_ROLE_DESCRIPTION = (
+    "a helpful biomedical assistant assigned with the task of problem-solving"
+)
+
 _SYSTEM_PROMPT_HEADER = \
 """
-You are a helpful biomedical assistant assigned with the task of problem-solving.
+You are {role_description}.
 To achieve this, you will be using an interactive coding environment equipped with a variety of tool functions, data, and softwares to assist you throughout the process.
 
 Given a task, make a plan first. The plan should be a numbered list of steps that you will take to solve the task. Be specific and detailed.