# Building Declarative Agent Components with Configurable Patterns in AutoGen

> Learn to build declarative agent components with configurable patterns in AutoGen. Define agents, models, and teams using JSON or YAML for easy version control and re-instantiation.

- Repository: [Microsoft/autogen](https://github.com/microsoft/autogen)
- Tags: tutorial
- Published: 2026-03-07

---

**AutoGen provides a generic component configuration system that enables you to define agents, models, tools, terminations, and entire multi-agent teams as declarative JSON or YAML specifications that can be serialized, version-controlled, and re-instantiated across environments.**

The Microsoft AutoGen framework introduces a powerful **component configuration** architecture that transforms how you build and deploy AI agents. Instead of writing imperative Python code for every deployment, you can use configurable patterns to declare agent structures as portable specifications. This system, implemented in [`autogen_core/_component_config.py`](https://github.com/microsoft/autogen/blob/main/autogen_core/_component_config.py), allows you to treat agents and teams as data that can be stored, shared, and loaded dynamically.

## Core Component Configuration Architecture

The declarative system centers on four key abstractions defined in **[`autogen_core/_component_config.py`](https://github.com/microsoft/autogen/blob/main/autogen_core/_component_config.py)**:

- **`ComponentModel`** – A Pydantic model that serves as the serialization container. It stores the `provider` class string, `component_type`, `version`, `description`, `label`, and the component-specific `config` dictionary.
- **`Component`** – A mix-in class that marks any class as a declarative component. Subclasses must declare a `component_type` string and a `component_config_schema` (a Pydantic model) to define their configuration structure.
- **`ComponentToConfig` / `ComponentFromConfig`** – Protocols that enforce `_to_config()` (producing a `BaseModel` instance) and `_from_config()` (reconstructing the object from that model).
- **`ComponentLoader.load_component()`** – The factory method that resolves the `provider` string, imports the target class, validates the configuration against the schema, and invokes `_from_config()`. It also supports legacy versions through `_from_config_past_version()`.

## How Declarative Specifications Work

The workflow for building declarative agent components follows a consistent four-step pattern:

1. **Create** – Instantiate a component (e.g., an `AssistantAgent` or `RoundRobinGroupChat`).
2. **Dump** – Call `dump_component()` to generate a `ComponentModel` containing the full configuration state.
3. **Serialize** – Use `model_dump_json()` to produce portable JSON or YAML for storage or transmission.
4. **Load** – Reconstruct the object using `ComponentLoader.load_component(json_obj, DesiredClass)` or the class method `DesiredClass.load_component(json_obj)`.

The **`component-config.ipynb`** notebook in the AutoGen documentation demonstrates this workflow with minimal examples of custom component definitions.

## Declarative Teams in AgentChat

AutoGen AgentChat extends the core component system to multi-agent **teams**. Every team implementation—including `RoundRobinGroupChat`, `SelectorGroupChat`, and `Swarm`—inherits from `BaseGroupChat` and implements the `Component` interface.

Each team defines a configuration schema (e.g., `SelectorGroupChatConfig`) that declaratively lists:
- Participant agents and their configurations
- Model client specifications
- Termination conditions
- Optional selector functions or custom routing logic

When you call `team.dump_component()`, the method recursively serializes all nested components—agents, tools, and termination conditions—preserving the complete hierarchical structure in a single JSON document.

## Key Implementation Patterns

When building declarative agent components with configurable patterns, follow these established conventions:

- **Component Inheritance** – Subclass `ComponentBase[Config]` and `Component[Config]`, then define `component_type` and `component_config_schema` as class attributes.
- **Dump to JSON** – Invoke `dump_component()` to receive a `ComponentModel`, then call `model_dump_json()` to generate the shareable string.
- **Load from JSON** – Use `ComponentLoader.load_component(json_obj, DesiredClass)` for generic loading, or `DesiredClass.load_component(json_obj)` for type-specific reconstruction.
- **Nested Composition** – Teams, agents, and tools each implement the component interface, enabling recursive serialization where a team configuration contains complete agent specifications.
- **Version Safety** – Implement `_from_config_past_version()` to handle configuration migrations when `ComponentModel.version` differs from the current `component_version`.

## Practical Code Examples

### Defining a Custom Component

Create a declarative component by implementing the required mix-in methods:

```python
from autogen_core import Component, ComponentBase
from pydantic import BaseModel

class MyConfig(BaseModel):
    value: str

class MyComponent(ComponentBase[MyConfig], Component[MyConfig]):
    component_type = "custom"
    component_config_schema = MyConfig

    def __init__(self, value: str):
        self.value = value

    def _to_config(self) -> MyConfig:
        return MyConfig(value=self.value)

    @classmethod
    def _from_config(cls, config: MyConfig) -> "MyComponent":
        return cls(value=config.value)

```

### Serializing and Deserializing

Convert live objects to JSON and back:

```python
c = MyComponent("hello")
model = c.dump_component()               # Returns ComponentModel

json_str = model.model_dump_json(indent=2)  # Share or store this JSON

# Later reconstruction

loaded = MyComponent.load_component(model)
assert loaded.value == "hello"

```

### Loading a Declarative Team

Restore a complete multi-agent team from a saved specification:

```python
import json
from autogen_agentchat.teams import BaseGroupChat

# Load team specification from file

with open("team.json") as f:
    team_cfg = json.load(f)

team = BaseGroupChat.load_component(team_cfg)
await team.run(task="Plan a weekend trip to Seattle")

```

### AutoGen Studio Integration

To use declarative specifications in AutoGen Studio:

1. Open **AutoGen Studio → Team Builder → JSON Editor**.
2. Paste the JSON output from `team.dump_component().model_dump_json()`.
3. Switch to the visual view to see agents appear as interactive nodes.

## Summary

- **Declarative specifications** in AutoGen allow you to define agents, tools, and teams as JSON/YAML configurations rather than imperative code.
- The **`ComponentModel`** class and **`Component`** mix-in in [`autogen_core/_component_config.py`](https://github.com/microsoft/autogen/blob/main/autogen_core/_component_config.py) provide the foundation for serialization and deserialization.
- **`dump_component()`** and **`load_component()`** enable round-trip persistence of complex object hierarchies, including nested teams and agents.
- **AutoGen AgentChat** teams like `SelectorGroupChat` implement these patterns, allowing entire multi-agent workflows to be version-controlled and shared via AutoGen Studio.

## Frequently Asked Questions

### How do I create a custom declarative component in AutoGen?

Subclass both `ComponentBase[YourConfig]` and `Component[YourConfig]`, define `component_type` and `component_config_schema` as class attributes, then implement `_to_config()` to return your Pydantic config model and `_from_config()` to reconstruct the instance. This registers your class with the `ComponentLoader` system.

### What is the difference between dump_component() and load_component()?

`dump_component()` is an instance method that serializes a live object into a `ComponentModel` containing the full configuration state. `load_component()` is a class method or utility function that instantiates a new object from a `ComponentModel` or JSON dictionary by resolving the provider string and calling the class's `_from_config()` method.

### Can I version control my agent team configurations?

Yes. Because teams, agents, and tools implement the `Component` interface, you can serialize complete configurations to JSON using `model_dump_json()` and commit them to Git. The `ComponentModel.version` field tracks schema versions, and you can implement `_from_config_past_version()` to handle backward compatibility when loading older configurations.

### How does AutoGen Studio use declarative specifications?

AutoGen Studio consumes the same JSON format produced by `dump_component()`. You can export team configurations from Python code and import them into the Studio's Team Builder via the JSON Editor, or vice versa, enabling seamless transitions between code-based and visual development workflows.