Agents API

Contents

Agents API#

Agent classes and interfaces for MassGen.

Chat Agent#

Agent Configuration#

Agent configuration for MassGen framework following input_cases_reference.md Simplified configuration focused on the proven binary decision approach.

TODO: This file is outdated - check claude_code config and deprecated patterns. Update to reflect current backend architecture.

class massgen.agent_config.TimeoutConfig(orchestrator_timeout_seconds: int = 1800)[source]#

Bases: object

Configuration for timeout settings in MassGen.

Parameters:

orchestrator_timeout_seconds – Maximum time for orchestrator coordination (default: 1800s = 30min)

orchestrator_timeout_seconds: int = 1800#
__init__(orchestrator_timeout_seconds: int = 1800) → None#
class massgen.agent_config.CoordinationConfig(enable_planning_mode: bool = False, planning_mode_instruction: str = 'During coordination, describe what you would do without actually executing actions. Only provide concrete implementation details without calling external APIs or tools.', max_orchestration_restarts: int = 0, enable_agent_task_planning: bool = False, max_tasks_per_plan: int = 10, task_planning_filesystem_mode: bool = False, enable_memory_filesystem_mode: bool = False, use_skills: bool = False, massgen_skills: ~typing.List[str] = <factory>, skills_directory: str = '.agent/skills')[source]#

Bases: object

Configuration for coordination behavior in MassGen.

Parameters:

  • enable_planning_mode – If True, agents plan without executing actions during coordination. Only the winning agent executes actions during final presentation. If False, agents execute actions during coordination (default behavior).

  • planning_mode_instruction – Custom instruction to add when planning mode is enabled.

  • max_orchestration_restarts – Maximum number of times orchestration can be restarted after post-evaluation determines the answer is insufficient. For example, max_orchestration_restarts=2 allows 3 total attempts (initial + 2 restarts). Default is 0 (no restarts).

  • enable_agent_task_planning – If True, agents receive task planning MCP tools for managing their own task lists with dependencies. This enables agents to break down complex work, track progress, and coordinate based on dependencies.

  • max_tasks_per_plan – Maximum number of tasks allowed in an agent’s task plan.

  • task_planning_filesystem_mode – If True, task planning MCP writes tasks to tasks/ directory in agent workspace for transparency and cross-agent visibility.

  • enable_memory_filesystem_mode – If True, enables filesystem-based memory system with two-tier hierarchy (short-term and long-term). Memory MCP tools are provided for creating/updating/loading memories. Short-term memories auto-inject into all agents’ system prompts. Long-term memories load on-demand. Inspired by Letta’s context hierarchy.

  • use_skills – If True, enables skills system using openskills. Agents can invoke skills via bash commands (openskills read <skill-name>). Requires command line execution to be enabled.

  • massgen_skills – List of MassGen built-in skills to enable. Available skills: - “file_search”: File search skill (no dir needed) When workspace/ is needed for file operations, it is created automatically.

  • skills_directory – Path to the skills directory. Default is .agent/skills which is where openskills installs skills. This directory is scanned for available skills.

enable_planning_mode: bool = False#
planning_mode_instruction: str = 'During coordination, describe what you would do without actually executing actions. Only provide concrete implementation details without calling external APIs or tools.'#
max_orchestration_restarts: int = 0#
enable_agent_task_planning: bool = False#
max_tasks_per_plan: int = 10#
task_planning_filesystem_mode: bool = False#
enable_memory_filesystem_mode: bool = False#
use_skills: bool = False#
massgen_skills: List[str]#
skills_directory: str = '.agent/skills'#
__init__(enable_planning_mode: bool = False, planning_mode_instruction: str = 'During coordination, describe what you would do without actually executing actions. Only provide concrete implementation details without calling external APIs or tools.', max_orchestration_restarts: int = 0, enable_agent_task_planning: bool = False, max_tasks_per_plan: int = 10, task_planning_filesystem_mode: bool = False, enable_memory_filesystem_mode: bool = False, use_skills: bool = False, massgen_skills: ~typing.List[str] = <factory>, skills_directory: str = '.agent/skills') → None#
class massgen.agent_config.AgentConfig(backend_params: ~typing.Dict[str, ~typing.Any] = <factory>, message_templates: MessageTemplates | None = None, voting_sensitivity: str = 'lenient', max_new_answers_per_agent: int | None = None, answer_novelty_requirement: str = 'lenient', agent_id: str | None = None, timeout_config: ~massgen.agent_config.TimeoutConfig = <factory>, coordination_config: ~massgen.agent_config.CoordinationConfig = <factory>, skip_coordination_rounds: bool = False, debug_final_answer: str | None = None, enable_nlip: bool = False, nlip_config: ~typing.Dict[str, ~typing.Any] | None = None)[source]#

Bases: object

Configuration for MassGen agents using the proven binary decision framework.

This configuration implements the simplified approach from input_cases_reference.md that eliminates perfectionism loops through clear binary decisions.

Parameters:

  • backend_params – Settings passed directly to LLM backend (includes tool enablement)

  • message_templates – Custom message templates (None=default)

  • agent_id – Optional agent identifier for this configuration

  • custom_system_instruction – Additional system instruction prepended to evaluation message

  • timeout_config – Timeout and resource limit configuration

  • coordination_config – Coordination behavior configuration (e.g., planning mode)

  • skip_coordination_rounds – Debug/test mode - skip voting rounds and go straight to final presentation (default: False)

  • voting_sensitivity – Controls how critical agents are when voting (“lenient”, “balanced”, “strict”)

  • max_new_answers_per_agent – Maximum number of new answers each agent can provide (None = unlimited)

  • answer_novelty_requirement – How different new answers must be from existing ones (“lenient”, “balanced”, “strict”)

backend_params: Dict[str, Any]#
message_templates: MessageTemplates | None = None#
voting_sensitivity: str = 'lenient'#
max_new_answers_per_agent: int | None = None#
answer_novelty_requirement: str = 'lenient'#
agent_id: str | None = None#
timeout_config: TimeoutConfig#
coordination_config: CoordinationConfig#
skip_coordination_rounds: bool = False#
debug_final_answer: str | None = None#
enable_nlip: bool = False#
nlip_config: Dict[str, Any] | None = None#
property custom_system_instruction: str | None#

Use backend-specific system prompt parameters instead.

For Claude Code: use append_system_prompt or system_prompt in backend_params For other backends: use their respective system prompt parameters

Type:

DEPRECATED

init_nlip_router(tool_manager: Any | None = None, mcp_executor: Any | None = None) → None[source]#

Initialize NLIP router if NLIP is enabled.

Parameters:

  • tool_manager – Optional tool manager instance to use with router

  • mcp_executor – Optional callable to execute MCP tools directly

property nlip_router: Any | None#

Get NLIP router instance.

classmethod create_chatcompletion_config(model: str = 'gpt-oss-120b', enable_web_search: bool = False, enable_code_interpreter: bool = False, **kwargs) → AgentConfig[source]#

Create ChatCompletion configuration following proven patterns.

Parameters:

  • model – Opensource Model Name

  • enable_web_search – Enable web search via Responses API

  • enable_code_interpreter – Enable code execution for computational tasks

  • **kwargs – Additional backend parameters

Examples

# Basic configuration config = AgentConfig.create_chatcompletion_config(“gpt-oss-120b”)

# Research task with web search config = AgentConfig.create_chatcompletion_config(“gpt-oss-120b”, enable_web_search=True)

# Computational task with code execution config = AgentConfig.create_chatcompletion_config(“gpt-oss-120b”, enable_code_interpreter=True)

classmethod create_openai_config(model: str = 'gpt-4o-mini', enable_web_search: bool = False, enable_code_interpreter: bool = False, **kwargs) → AgentConfig[source]#

Create OpenAI configuration following proven patterns.

Parameters:

  • model – OpenAI model name

  • enable_web_search – Enable web search via Responses API

  • enable_code_interpreter – Enable code execution for computational tasks

  • **kwargs – Additional backend parameters

Examples

# Basic configuration config = AgentConfig.create_openai_config(“gpt-4o-mini”)

# Research task with web search config = AgentConfig.create_openai_config(“gpt-4o”, enable_web_search=True)

# Computational task with code execution config = AgentConfig.create_openai_config(“gpt-4o”, enable_code_interpreter=True)

classmethod create_claude_config(model: str = 'claude-3-sonnet-20240229', enable_web_search: bool = False, enable_code_execution: bool = False, **kwargs) → AgentConfig[source]#

Create Anthropic Claude configuration.

Parameters:

  • model – Claude model name

  • enable_web_search – Enable builtin web search tool

  • enable_code_execution – Enable builtin code execution tool

  • **kwargs – Additional backend parameters

classmethod create_grok_config(model: str = 'grok-2-1212', enable_web_search: bool = False, **kwargs) → AgentConfig[source]#

Create xAI Grok configuration.

Parameters:

  • model – Grok model name

  • enable_web_search – Enable Live Search feature

  • **kwargs – Additional backend parameters

classmethod create_lmstudio_config(model: str = 'gpt-4o-mini', enable_web_search: bool = False, **kwargs) → AgentConfig[source]#

Create LM Studio configuration (OpenAI-compatible local server).

Parameters:

  • model – Local model name exposed by LM Studio

  • enable_web_search – No builtin web search; kept for interface parity

  • **kwargs – Additional backend parameters (e.g., base_url, api_key)

classmethod create_vllm_config(model: str | None = None, **kwargs) → AgentConfig[source]#

Create vLLM configuration (OpenAI-compatible local server).

classmethod create_sglang_config(model: str | None = None, **kwargs) → AgentConfig[source]#

Create SGLang configuration (OpenAI-compatible local server).

classmethod create_gemini_config(model: str = 'gemini-2.5-flash', enable_web_search: bool = False, enable_code_execution: bool = False, **kwargs) → AgentConfig[source]#

Create Google Gemini configuration.

Parameters:

  • model – Gemini model name

  • enable_web_search – Enable Google Search retrieval tool

  • enable_code_execution – Enable code execution tool

  • **kwargs – Additional backend parameters

classmethod create_zai_config(model: str = 'glm-4.5', base_url: str = 'https://api.z.ai/api/paas/v4/', **kwargs) → AgentConfig[source]#

Create ZAI configuration (OpenAI Chat Completions compatible).

Parameters:

  • model – ZAI model name (e.g., “glm-4.5”)

  • base_url – ZAI OpenAI-compatible API base URL

  • **kwargs – Additional backend parameters (e.g., temperature, top_p)

classmethod create_azure_openai_config(deployment_name: str = 'gpt-4', endpoint: str | None = None, api_key: str | None = None, api_version: str = '2024-02-15-preview', **kwargs) → AgentConfig[source]#

Create Azure OpenAI configuration.

Parameters:

  • deployment_name – Azure OpenAI deployment name (e.g., “gpt-4”, “gpt-35-turbo”)

  • endpoint – Azure OpenAI endpoint URL (optional, uses AZURE_OPENAI_ENDPOINT env var)

  • api_key – Azure OpenAI API key (optional, uses AZURE_OPENAI_API_KEY env var)

  • api_version – Azure OpenAI API version (default: 2024-02-15-preview)

  • **kwargs – Additional backend parameters (e.g., temperature, max_tokens)

Examples

Basic configuration using environment variables:

config = AgentConfig.create_azure_openai_config("gpt-4")

Custom endpoint and API key:

config = AgentConfig.create_azure_openai_config(
    deployment_name="gpt-4-turbo",
    endpoint="https://your-resource.openai.azure.com/",
    api_key="your-api-key"
)
classmethod create_claude_code_config(model: str = 'claude-sonnet-4-20250514', system_prompt: str | None = None, allowed_tools: list | None = None, disallowed_tools: list | None = None, max_thinking_tokens: int = 8000, cwd: str | None = None, **kwargs) → AgentConfig[source]#

Create Claude Code Stream configuration using claude-code-sdk.

This backend provides native integration with ALL Claude Code built-in tools by default, with security enforced through disallowed_tools. This gives maximum power while maintaining safety.

Parameters:

  • model – Claude model name (default: claude-sonnet-4-20250514)

  • system_prompt – Custom system prompt for the agent

  • allowed_tools – [LEGACY] List of allowed tools (use disallowed_tools instead)

  • disallowed_tools – List of dangerous operations to block (default: [“Bash(rm*)”, “Bash(sudo*)”, “Bash(su*)”, “Bash(chmod*)”, “Bash(chown*)”])

  • max_thinking_tokens – Maximum tokens for internal thinking (default: 8000)

  • cwd – Current working directory for file operations

  • **kwargs – Additional backend parameters

Examples

Maximum power configuration (recommended):

config = AgentConfig.create_claude_code_config()

Custom security restrictions:

config = AgentConfig.create_claude_code_config(
    disallowed_tools=["Bash(rm*)", "Bash(sudo*)", "WebSearch"]
)

Development task with custom directory:

config = AgentConfig.create_claude_code_config(
    cwd="/path/to/project",
    system_prompt="You are an expert developer assistant."
)

Legacy allowed_tools approach (not recommended):

config = AgentConfig.create_claude_code_config(
    allowed_tools=["Read", "Write", "Edit", "Bash"]
)
with_custom_instruction(instruction: str) → AgentConfig[source]#

Create a copy with custom system instruction.

with_agent_id(agent_id: str) → AgentConfig[source]#

Create a copy with specified agent ID.

classmethod for_research_task(model: str = 'gpt-4o', backend: str = 'openai') → AgentConfig[source]#

Create configuration optimized for research tasks.

Based on econometrics test success patterns: - Enables web search for literature review - Uses proven model defaults

classmethod for_computational_task(model: str = 'gpt-4o', backend: str = 'openai') → AgentConfig[source]#

Create configuration optimized for computational tasks.

Based on Tower of Hanoi test success patterns: - Enables code execution for calculations - Uses proven model defaults

classmethod for_analytical_task(model: str = 'gpt-4o-mini', backend: str = 'openai') → AgentConfig[source]#

Create configuration optimized for analytical tasks.

Based on general reasoning test patterns: - No special tools needed - Uses efficient model defaults

classmethod for_expert_domain(domain: str, expertise_level: str = 'expert', model: str = 'gpt-4o', backend: str = 'openai') → AgentConfig[source]#

Create configuration for domain expertise.

Parameters:

  • domain – Domain of expertise (e.g., “econometrics”, “computer science”)

  • expertise_level – Level of expertise (“expert”, “specialist”, “researcher”)

  • model – Model to use

  • backend – Backend provider

build_conversation(task: str, agent_summaries: Dict[str, str] | None = None, session_id: str | None = None) → Dict[str, Any][source]#

Build conversation using the proven MassGen approach.

Returns complete conversation configuration ready for backend. Automatically determines Case 1 vs Case 2 based on agent_summaries.

add_enforcement_message(conversation_messages: list) → list[source]#

Add enforcement message to conversation (Case 3 handling).

Parameters:

conversation_messages – Existing conversation messages

Returns:

Updated conversation messages with enforcement

continue_conversation(existing_messages: list, additional_message: Any = None, additional_message_role: str = 'user', enforce_tools: bool = False) → Dict[str, Any][source]#

Continue an existing conversation (Cases 3 & 4).

Parameters:

  • existing_messages – Previous conversation messages

  • additional_message – Additional message (str or dict for tool results)

  • additional_message_role – Role for additional message (“user”, “tool”, “assistant”)

  • enforce_tools – Whether to add tool enforcement message

Returns:

Updated conversation configuration

handle_case3_enforcement(existing_messages: list) → Dict[str, Any][source]#

Handle Case 3: Non-workflow response requiring enforcement.

Parameters:

existing_messages – Messages from agent that didn’t use tools

Returns:

Conversation with enforcement message added

add_tool_result(existing_messages: list, tool_call_id: str, result: str) → Dict[str, Any][source]#

Add tool result to conversation.

Parameters:

  • existing_messages – Previous conversation messages

  • tool_call_id – ID of the tool call this responds to

  • result – Tool execution result (success or error)

Returns:

Conversation with tool result added

handle_case4_error_recovery(existing_messages: list, clarification: str | None = None) → Dict[str, Any][source]#

Handle Case 4: Error recovery after tool failure.

Parameters:

  • existing_messages – Messages including tool error response

  • clarification – Optional clarification message

Returns:

Conversation ready for retry

get_backend_params() → Dict[str, Any][source]#

Get backend parameters (already includes tool enablement).

to_dict() → Dict[str, Any][source]#

Convert to dictionary for serialization.

classmethod from_dict(data: Dict[str, Any]) → AgentConfig[source]#

Create from dictionary (for deserialization).

__init__(backend_params: ~typing.Dict[str, ~typing.Any] = <factory>, message_templates: MessageTemplates | None = None, voting_sensitivity: str = 'lenient', max_new_answers_per_agent: int | None = None, answer_novelty_requirement: str = 'lenient', agent_id: str | None = None, timeout_config: ~massgen.agent_config.TimeoutConfig = <factory>, coordination_config: ~massgen.agent_config.CoordinationConfig = <factory>, skip_coordination_rounds: bool = False, debug_final_answer: str | None = None, enable_nlip: bool = False, nlip_config: ~typing.Dict[str, ~typing.Any] | None = None) → None#
massgen.agent_config.create_research_config(model: str = 'gpt-4o', backend: str = 'openai') → AgentConfig[source]#

Create configuration for research tasks (web search enabled).

massgen.agent_config.create_computational_config(model: str = 'gpt-4o', backend: str = 'openai') → AgentConfig[source]#

Create configuration for computational tasks (code execution enabled).

massgen.agent_config.create_analytical_config(model: str = 'gpt-4o-mini', backend: str = 'openai') → AgentConfig[source]#

Create configuration for analytical tasks (no special tools).

Coordination Tracker#

Contents