Advanced Usage

16. Advanced Usage#

16.1. Team presets#

The team_preset argument controls how AutoGen routes messages between the agents. The default, RoundRobinGroupChat, steps through the agents in manifest order and is what you want for an auditable, predictable pipeline. The alternatives change the routing strategy:

Preset

Routing

When to use

RoundRobinGroupChat

Fixed sequential order

Standard pipeline; predictable, auditable turn order. (Default.)

SelectorGroupChat

An LLM selects the next agent

When the agent order should vary with the content of prior output.

MagenticOneGroupChat

A dedicated orchestrator

Complex multi-step reasoning where an orchestrator decomposes the task.

Swarm

Agent-to-agent handoff

Distributed, loosely coupled execution where agents pick their own successors.

 
job = client.submit(metadata, team_preset="SelectorGroupChat")

Note

Turns are bounded by the agent count Internally the team is run with max_turns equal to the number of agents in the manifest. With the default five-agent manifest, the conversation runs exactly five turns — one per agent. This matters when you write a custom manifest: the team will take as many turns as you have agents, so the agent that produces your final JSON must be the last one.

16.2. Custom agents manifest#

To change the agents’ instructions, supply your own YAML manifest. Point the constructor’s assets_dir at the directory that contains it, and name the file in submit():

client = MetadataReviewerClient.from_openai(
    model="gpt-4o",
    api_key="sk-...",
    assets_dir="/path/to/my/manifests/",
)

job = client.submit(metadata, manifest_file="custom_manifest.yml")

The YAML structure is a top-level agents_manifest list. Each entry needs a name and a system_message. The names define the agents’ identities in the pipeline; the system message is passed straight to the AutoGen agent. Entries missing either field are skipped with a warning.

agents_manifest:
  - name: primary
    system_message: |
      Examine the metadata and list any issues that are incorrect,
      missing, or inconsistent. Output a JSON array using the
      standard schema.
  - name: severity_scorer
    system_message: |
      Assign issue_severity (1-5) to each finding based on impact.
      Output a JSON array. Print a final line: TERMINATE

Note

Critical: end with TERMINATE The pipeline stops when an agent’s message contains the exact word TERMINATE. Your final agent’s system message must instruct it to print that word, or the run will continue until it hits the turn limit and may not return clean output. The final JSON the package returns is extracted from the last agent’s message, so make sure your last agent emits the complete result array.

16.3. The built-in exclusion rules#

In the default manifest, the critic removes any candidate matching the exclusion classes below, and the severity scorer applies the same classes as a down-weighting safety net — anything that slips past the critic but still matches is forced to severity 1. Understanding these rules explains why certain “issues” never appear in your output.

16.3.1. General exclusions (removed entirely)#

Capitalization-only; spacing or whitespace; style or stylistic preference; CRLF, newlines, blank lines, or trailing spaces; formatting or encoding; abbreviations; code-related issues; empty lists or empty arrays; missing fields; schema or schema-structure issues; mixed-type objects that reflect structural variation; and URL-structure issues.

16.3.2. Field-level exclusions (issues on these fields are removed)#

idno, proj_idno, version_statement, prod_date, version_date, changed, changed_by, contacts, topics, tags, database_id, visualization, and uri.

16.3.3. Data-state exclusions (removed)#

Issues about null or empty fields; empty lists; nested empty lists; and placeholder-only values with no semantic content.

If you need the reviewer to flag, say, capitalization or a normally-excluded field, write a custom manifest whose critic omits the relevant rule.

16.4. Bring your own client#

For full control — or for any AutoGen-compatible provider the factory methods do not cover — build the model client yourself and pass it to the constructor.

from autogen_ext.models.openai import AzureOpenAIChatCompletionClient
from ai4data.metadata.reviewer import MetadataReviewerClient

model_client = AzureOpenAIChatCompletionClient(
    model="gpt-4o",
    azure_endpoint="https://<resource>.openai.azure.com/",
    azure_deployment="<deployment>",
    api_version="2024-02-01",
    azure_ad_token="<static-token>",
)

client = MetadataReviewerClient(model_client=model_client)

Any object conforming to AutoGen’s ChatCompletionClient interface works. This is also the route to use a static Azure AD token instead of a token provider, as shown above.

Contents