Agent registry

Currently, agents are configured and registered programmatically in Hybrid Groups. An agent configuration includes system instructions, model settings, MCP servers and other tools.

Example

See agents.py for agent configuration and registration, and the tutorial for usage examples.

A common setup is to have a system agent and zero or more specialized agents. The system agent can use other agents in the registry as subagents, and selects them based on their description.

System agent

A system agent monitors all messages in a group session. It may decide to stay silent or respond to a message, depending on message content, context and system instructions. Default instructions for a system agent can be loaded with system_agent_instructions().

from hygroup.agent.default import AgentSettings, MCPSettings
from hygroup.agent.system import system_agent_instructions
from pydantic_ai.models.google import GoogleModelSettings


def system_agent_config():
    brave_search_settings = MCPSettings(
        server_config={
            "command": "npx",
            "args": ["-y", "@modelcontextprotocol/server-brave-search"],
            "env": {
                "BRAVE_API_KEY": "${BRAVE_API_KEY}",
            },
        },
    )

    system_agent_settings = AgentSettings(
        instructions=system_agent_instructions(),
        model="gemini-2.5-flash",
        model_settings=GoogleModelSettings(
            google_thinking_config={
                "include_thoughts": True,
            }
        ),
        mcp_settings=[brave_search_settings],
        tools=[get_weather_forecast],
    )

    return {
        "name": "system",
        "description": "The system agent.",
        "settings": system_agent_settings,
    }

The model in AgentSettings is a Pydantic AI model name, model_settings are general Pydantic AI ModelSettings or those of a specific model provider, like GoogleModelSettings.

The configuration returned from system_agent_config() is added to the AgentRegistry with the add_config() method. The registry is persisted to registry_path with save().

import asyncio
from hygroup.agent.registry import AgentRegistry


async def main():
    agent_registry = AgentRegistry(registry_path=".data/agents/registry.json")
    agent_registry.add_config(**system_agent_config())
    # ...

    await agent_registry.save()


if __name__ == "__main__":
    asyncio.run(main())

MCP settings

MCP servers are configured with the MCPSettings class. The server_config dictionary may include variables of pattern ${VAR_NAME}. These are substituted with environment variables and user secrets at runtime. User secrets take precedence over environment variables.

Remote MCP servers of Composio service connectors must be configured with two special variables, a COMPOSIO_USER_ID and a toolkit-specific COMPOSIO_<TOOLKIT>_ID where <TOOLKIT> is the name of a Composio toolkit in uppercase letters, as shown in the following office agent configuration.

def office_agent_config(template: InstructionsTemplate):
    gmail_settings = MCPSettings(
        server_config={
            "url": "https://mcp.composio.dev/composio/server/${COMPOSIO_GMAIL_ID}?user_id=${COMPOSIO_USER_ID}",
        },
    )

    googlecalendar_settings = MCPSettings(
        server_config={
            "url": "https://mcp.composio.dev/composio/server/${COMPOSIO_GOOGLECALENDAR_ID}?user_id=${COMPOSIO_USER_ID}",
        },
    )

    googledrive_settings = MCPSettings(
        server_config={
            "url": "https://mcp.composio.dev/composio/server/${COMPOSIO_GOOGLEDRIVE_ID}?user_id=${COMPOSIO_USER_ID}",
        },
    )

    agent_settings = AgentSettings(
        model="openai:gpt-5-mini",
        instructions=template.apply(OFFICE_AGENT_ROLE, OFFICE_AGENT_STEPS),
        mcp_settings=[
            gmail_settings,
            googlecalendar_settings,
            googledrive_settings,
        ],
    )

    return {
        "name": "office",
        "description": "An agent that can manage the user's Gmail, Google Calendar, and Google Drive.",
        "settings": agent_settings,
        "emoji": "paperclip",
    }

Values for toolkit-specific variables are generated during Composio MCP server setup. COMPOSIO_USER_IDs are generated during access authorization, and then stored as user secrets.

Scoped registries

The AgentRegistries class supports multiple registries scoped to specific Slack channels. For example, with .data/agents as the root_path

from hygroup.agent.registry import AgentRegistries


agent_registries = AgentRegistries(root_path=".data/agents")

and this registry hierarchy

.data/agents/
├── registry.json
├── my-channel-1/
│   └── registry.json
├── my-channel-2/
│   └── registry.json

Hybrid Groups loads the registries as follows:

• .data/agents/my-channel-1/registry.json for Slack channel my-channel-1
• .data/agents/my-channel-2/registry.json for Slack channel my-channel-2
• .data/agents/registry.json for all other Slack channels