Skip to content

symfonic.agent.builder

builder

Importable legacy builder whose build raises a migration error.

Use symfonic.Agent for native composition, or symfonic.migration.agent_from_config to translate a FrameworkConfig. The fluent methods preserve attribution for existing callers; there is no engine construction body behind the refusal.

AgentBuilder 

AgentBuilder(*, config: FrameworkConfig | None = None)

Legacy fluent surface; :meth:build always raises its migration error.

Start a builder, optionally extending an existing base config.

Parameters:

Name Type Description Default
config FrameworkConfig | None

A base :class:FrameworkConfig to layer overrides onto. Defaults to FrameworkConfig(). Anything the builder sets (model, domain, flags) overrides this base; everything else is inherited.

 None
Source code in src/symfonic/agent/builder.py 
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
def __init__(self, *, config: FrameworkConfig | None = None) -> None:
    """Start a builder, optionally extending an existing base config.

    Args:
        config: A base :class:`FrameworkConfig` to layer overrides onto.
            Defaults to ``FrameworkConfig()``. Anything the builder sets
            (model, domain, flags) overrides this base; everything else is
            inherited.
    """
    self._base_config = config
    self._provider: ModelProvider | None = None
    self._tools: list[Any] = []
    self._sub_specs: list[SubAgentSpec] = []
    self._overrides: dict[str, Any] = {}
    self._model_overrides: dict[str, Any] = {}
    self._domain: DomainTemplate | None = None
    self._domain_name: str | None = None
    self._domain_description: str | None = None
    self._orchestrator: MemoryOrchestrator | None = None
    self._embeddings: EmbeddingProvider | None = None
    self._in_memory: bool = False
    self._fallback_telemetry_sink: Callable[[Any], None] | None = None
    self._dispatch_outcome_sink: Callable[[Any], None] | None = None
    self._route_attempt_sink: Callable[[Any], None] | None = None

build 

build() -> NoReturn

Refuse legacy builder construction with a versioned migration error.

Raises:

Type Description
EntryPointRemovedError

Always, from 11.3 (CORE-388); names AgentBuilder. Use symfonic.Agent or AgentHost.
Source code in src/symfonic/agent/builder.py 
227
228
229
230
231
232
233
234
235
236
def build(self) -> NoReturn:
    """Refuse legacy builder construction with a versioned migration error.

    Raises:
        EntryPointRemovedError: Always, from 11.3 (CORE-388); names
            ``AgentBuilder``. Use ``symfonic.Agent`` or ``AgentHost``.
    """
    from symfonic.agent.entry_point_removal import EntryPointRemovedError

    raise EntryPointRemovedError("AgentBuilder")

dispatch_outcomes 

dispatch_outcomes(sink: Callable[[Any], None] | None) -> AgentBuilder

Observe real invocation route outcomes with a host-owned sink.

Source code in src/symfonic/agent/builder.py 
122
123
124
125
def dispatch_outcomes(self, sink: Callable[[Any], None] | None) -> AgentBuilder:
    """Observe real invocation route outcomes with a host-owned sink."""
    self._dispatch_outcome_sink = sink
    return self

domain 

domain(name: str | None = None, description: str | None = None, *, template: DomainTemplate | None = None) -> AgentBuilder

Set the agent's domain -- either a full template or name/desc.

Source code in src/symfonic/agent/builder.py 
80
81
82
83
84
85
86
87
88
89
90
91
92
93
def domain(
    self,
    name: str | None = None,
    description: str | None = None,
    *,
    template: DomainTemplate | None = None,
) -> AgentBuilder:
    """Set the agent's domain -- either a full ``template`` or name/desc."""
    if template is not None:
        self._domain = template
    else:
        self._domain_name = name
        self._domain_description = description
    return self

enable_hms 

enable_hms(on: bool = True) -> AgentBuilder

Toggle the HMS system-prompt pipeline (enable_hms_prompt).

Source code in src/symfonic/agent/builder.py 
102
103
104
105
def enable_hms(self, on: bool = True) -> AgentBuilder:
    """Toggle the HMS system-prompt pipeline (``enable_hms_prompt``)."""
    self._overrides["enable_hms_prompt"] = on
    return self

fallback_telemetry 

fallback_telemetry(sink: Callable[[Any], None] | None) -> AgentBuilder

Install a host-owned sink for metadata-only cutover fallbacks.

Source code in src/symfonic/agent/builder.py 
117
118
119
120
def fallback_telemetry(self, sink: Callable[[Any], None] | None) -> AgentBuilder:
    """Install a host-owned sink for metadata-only cutover fallbacks."""
    self._fallback_telemetry_sink = sink
    return self

kernel_route_attempts 

kernel_route_attempts(sink: Callable[[Any], None] | None) -> AgentBuilder

Observe actual Kernel route selection before admission, with a host sink.

Source code in src/symfonic/agent/builder.py 
137
138
139
140
def kernel_route_attempts(self, sink: Callable[[Any], None] | None) -> AgentBuilder:
    """Observe actual Kernel route selection before admission, with a host sink."""
    self._route_attempt_sink = sink
    return self

lazy_tooling 

lazy_tooling(on: bool = True) -> AgentBuilder

Toggle lazy tool routing (lazy_tooling).

Source code in src/symfonic/agent/builder.py 
107
108
109
110
def lazy_tooling(self, on: bool = True) -> AgentBuilder:
    """Toggle lazy tool routing (``lazy_tooling``)."""
    self._overrides["lazy_tooling"] = on
    return self

memory 

memory(orchestrator: MemoryOrchestrator | None = None, *, embeddings: EmbeddingProvider | None = None, auto_hydrate: bool = True, auto_consolidate: bool = True) -> AgentBuilder

Attach HMS memory.

Pass a pre-built orchestrator OR embeddings to build an in-memory HMS at :meth:build time (delegates to HMSFactory.build_in_memory). Enables auto_hydrate / auto_consolidate by default; override per call.

Source code in src/symfonic/agent/builder.py 
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
def memory(
    self,
    orchestrator: MemoryOrchestrator | None = None,
    *,
    embeddings: EmbeddingProvider | None = None,
    auto_hydrate: bool = True,
    auto_consolidate: bool = True,
) -> AgentBuilder:
    """Attach HMS memory.

    Pass a pre-built ``orchestrator`` OR ``embeddings`` to build an
    in-memory HMS at :meth:`build` time (delegates to
    ``HMSFactory.build_in_memory``). Enables ``auto_hydrate`` /
    ``auto_consolidate`` by default; override per call.
    """
    if orchestrator is not None:
        self._orchestrator = orchestrator
    elif embeddings is not None:
        self._embeddings = embeddings
        self._in_memory = True
    self._overrides.setdefault("auto_hydrate", auto_hydrate)
    self._overrides.setdefault("auto_consolidate", auto_consolidate)
    return self

model 

model(model_name: str | None = None, *, temperature: float | None = None, max_tokens: int | None = None, top_p: float | None = None, top_k: int | None = None) -> AgentBuilder

Override model knobs; unset ones inherit the base config's model.

Source code in src/symfonic/agent/builder.py 
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
def model(
    self,
    model_name: str | None = None,
    *,
    temperature: float | None = None,
    max_tokens: int | None = None,
    top_p: float | None = None,
    top_k: int | None = None,
) -> AgentBuilder:
    """Override model knobs; unset ones inherit the base config's model."""
    for key, val in (
        ("model_name", model_name),
        ("temperature", temperature),
        ("max_tokens", max_tokens),
        ("top_p", top_p),
        ("top_k", top_k),
    ):
        if val is not None:
            self._model_overrides[key] = val
    return self

observability 

observability(services: Any) -> AgentBuilder

Bind a host's observability bundle to cutover fallback telemetry.

The services own the metrics buffer; the agent borrows only its metadata-only fallback callback. A bundle without durable metrics supplies None and keeps the agent's local fallback counters.

Source code in src/symfonic/agent/builder.py 
127
128
129
130
131
132
133
134
135
def observability(self, services: Any) -> AgentBuilder:
    """Bind a host's observability bundle to cutover fallback telemetry.

    The services own the metrics buffer; the agent borrows only its
    metadata-only fallback callback. A bundle without durable metrics
    supplies ``None`` and keeps the agent's local fallback counters.
    """
    self._fallback_telemetry_sink = services.fallback_telemetry_sink
    return self

option 

option(**overrides: Any) -> AgentBuilder

Set any other FrameworkConfig field(s) verbatim.

Source code in src/symfonic/agent/builder.py 
112
113
114
115
def option(self, **overrides: Any) -> AgentBuilder:
    """Set any other ``FrameworkConfig`` field(s) verbatim."""
    self._overrides.update(overrides)
    return self

provider 

provider(provider: ModelProvider) -> AgentBuilder

Set the LLM provider (required).

Source code in src/symfonic/agent/builder.py 
53
54
55
56
def provider(self, provider: ModelProvider) -> AgentBuilder:
    """Set the LLM provider (required)."""
    self._provider = provider
    return self

sub_agent 

sub_agent(name: str, description: str, *, when_to_use: str | None = None, tools: Any = (), domain_description: str | None = None, model_name: str | None = None, temperature: float | None = None, max_tokens: int | None = None, provider: ModelProvider | None = None) -> AgentBuilder

Declare a child agent as a :class:SubAgentSpec (repeatable).

Source code in src/symfonic/agent/builder.py 
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
def sub_agent(
    self,
    name: str,
    description: str,
    *,
    when_to_use: str | None = None,
    tools: Any = (),
    domain_description: str | None = None,
    model_name: str | None = None,
    temperature: float | None = None,
    max_tokens: int | None = None,
    provider: ModelProvider | None = None,
) -> AgentBuilder:
    """Declare a child agent as a :class:`SubAgentSpec` (repeatable)."""
    self._sub_specs.append(
        SubAgentSpec(
            name=name,
            description=description,
            when_to_use=when_to_use,
            tools=tuple(tools),
            domain_description=domain_description,
            model_name=model_name,
            temperature=temperature,
            max_tokens=max_tokens,
            provider=provider,
        )
    )
    return self

sub_agent_spec 

sub_agent_spec(spec: SubAgentSpec) -> AgentBuilder

Add a pre-constructed :class:SubAgentSpec.

Source code in src/symfonic/agent/builder.py 
197
198
199
200
def sub_agent_spec(self, spec: SubAgentSpec) -> AgentBuilder:
    """Add a pre-constructed :class:`SubAgentSpec`."""
    self._sub_specs.append(spec)
    return self

tools 

tools(*tools: Any) -> AgentBuilder

Add tools (repeatable; accepts multiple per call).

Source code in src/symfonic/agent/builder.py 
96
97
98
99
def tools(self, *tools: Any) -> AgentBuilder:
    """Add tools (repeatable; accepts multiple per call)."""
    self._tools.extend(tools)
    return self