Skip to content

AgentSpec

autogen.beta.spec.AgentSpec #

Bases: BaseModel

JSON-serializable specification of an Agent.

Captures the declarative, data-only parts of an Agent: name, prompt, tool names, and response schema.

Non-serializable parts (middleware, callbacks, dependencies, dynamic prompts) are intentionally excluded and must be supplied at reconstruction time via :meth:to_agent.

name instance-attribute #

name

prompt class-attribute instance-attribute #

prompt = Field(default_factory=list)

tool_names class-attribute instance-attribute #

tool_names = Field(default_factory=list)

response_schema class-attribute instance-attribute #

response_schema = None

from_agent classmethod #

from_agent(agent)

Create an AgentSpec from a live Agent instance.

Only serializable state is captured. Dynamic prompts, middleware, callbacks, and dependencies are dropped.

Source code in autogen/beta/spec.py 
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
@classmethod
def from_agent(cls, agent: Agent) -> "AgentSpec":
    """Create an ``AgentSpec`` from a live ``Agent`` instance.

    Only serializable state is captured. Dynamic prompts, middleware,
    callbacks, and dependencies are dropped.
    """

    tool_names: list[str] = [t.name for t in agent.tools]

    # Response schema
    rs_spec: ResponseSchemaSpec | None = None
    rs = agent._response_schema
    if rs is not None and rs.json_schema is not None:
        rs_spec = ResponseSchemaSpec(
            name=rs.name,
            description=rs.description,
            json_schema=rs.json_schema,
        )

    return cls(
        name=agent.name,
        prompt=list(agent._system_prompt),
        tool_names=tool_names,
        response_schema=rs_spec,
    )

to_agent #

to_agent(*, available_tools=(), config=None, hitl_hook=None, middleware=(), observers=(), dependencies=None, variables=None, response_schema=None, plugins=())

Reconstruct an Agent from this spec.

Source code in autogen/beta/spec.py 
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
def to_agent(
    self,
    *,
    available_tools: Iterable[Tool | Callable[..., Any]] = (),
    config: ModelConfig | None = None,
    hitl_hook: HumanHook | None = None,
    middleware: Iterable[MiddlewareFactory] = (),
    observers: Iterable[Observer] = (),
    dependencies: dict[Any, Any] | None = None,
    variables: dict[str, Any] | None = None,
    response_schema: ResponseProto[Any] | type | None = None,
    plugins: Iterable[Plugin] = (),
) -> Agent:
    """Reconstruct an ``Agent`` from this spec."""

    # Build name -> tool index from available_tools
    tool_index: dict[str, Tool] = {}

    tools_to_visit = [FunctionTool.ensure_tool(t) for t in available_tools]
    while tools_to_visit:
        tool = tools_to_visit.pop()
        tool_index[tool.name] = tool
        if isinstance(tool, Toolkit):
            tools_to_visit.extend(tool.tools)

    # Resolve tools by name
    resolved_tools: list[Tool] = []
    missing: list[str] = []
    for name in self.tool_names:
        if name in tool_index:
            resolved_tools.append(tool_index[name])
        else:
            missing.append(name)

    if missing:
        raise ToolResolutionError(missing, sorted(tool_index.keys()))

    # Response schema: explicit param > spec > None
    final_rs = response_schema
    if final_rs is None and self.response_schema is not None:
        final_rs = self.response_schema.to_response_schema()

    return Agent(
        name=self.name,
        prompt=list(self.prompt),
        config=config,
        hitl_hook=hitl_hook,
        tools=resolved_tools,
        middleware=middleware,
        observers=observers,
        dependencies=dependencies,
        variables=variables,
        response_schema=final_rs,
        plugins=plugins,
    )