Agent¶

The Agent is the orchestrator that combines connectors, an LLM, and the domain model into a working maintenance assistant. It receives messages from channels (CLI, Telegram, Slack, …), resolves referenced assets, gathers context from connectors, calls the LLM with domain-aware prompts, and executes tool calls.

This page is the auto-generated API reference. For tutorial-level usage see Quickstart and Architecture.

`Agent`¶

The central runtime class. Public attributes worth knowing:

sandbox — boolean property with a propagating setter. When mutated after construction (e.g. agent.sandbox = False to switch from sandbox to live), the change propagates to the internal workflow engine so write actions are no longer intercepted.
tracer — the ActionTracer instance recording every action.
plant — the Plant registered to this agent.

Agent ¶

Agent(*, name: str = 'Machina Agent', description: str = 'Maintenance AI assistant', plant: Plant | None = None, connectors: list[Any] | None = None, channels: list[Any] | None = None, llm: str | LLMProvider = 'openai:gpt-4o', temperature: float = 0.1, max_history: int = 20, workflows: list[Workflow] | None = None, sandbox: bool = False)

Maintenance AI agent that orchestrates reasoning and actions.

The agent receives user queries, resolves referenced assets, gathers context from configured connectors, and uses an LLM to produce grounded, domain-aware responses.

Parameters:

Name	Type	Description	Default
`name`	`str`	Human-readable agent name.	`'Machina Agent'`
`description`	`str`	What this agent specialises in.	`'Maintenance AI assistant'`
`plant`	`Plant \| None`	The plant with its asset registry.	`None`
`connectors`	`list[Any] \| None`	List of connector instances to register.	`None`
`channels`	`list[Any] \| None`	Communication channels (Telegram, CLI, etc.).	`None`
`llm`	`str \| LLMProvider`	LLM provider string (e.g. `"openai:gpt-4o"`) or an :class:`LLMProvider` instance.	`'openai:gpt-4o'`
`temperature`	`float`	LLM sampling temperature.	`0.1`
`max_history`	`int`	Maximum conversation turns to keep in memory.	`20`
`workflows`	`list[Workflow] \| None`	List of workflow definitions to register.	`None`
`sandbox`	`bool`	If `True`, write actions are logged but not executed.	`False`

Example

from machina import Agent, Plant
from machina.connectors.cmms import GenericCmmsConnector
from machina.connectors.comms.telegram import CliChannel

plant = Plant(name="Demo Plant")
cmms = GenericCmmsConnector(data_dir="sample_data/cmms")

agent = Agent(
    name="Maintenance Assistant",
    plant=plant,
    connectors=[cmms],
    channels=[CliChannel()],
    llm="openai:gpt-4o",
)
agent.run()

sandbox `property` `writable` ¶

sandbox: bool

Whether write actions are intercepted (True) or executed.

Read this attribute through normal access — no behaviour change for existing call sites that branch on if self.sandbox.

workflows `property` ¶

workflows: dict[str, Workflow]

Registered workflows (read-only copy).

from_config `classmethod` ¶

from_config(path: str | Path) -> Agent

Create an Agent from a machina.yaml configuration file.

Connectors and channels are instantiated from their type strings. Workflows cannot be defined in YAML (they may contain Python callables); register them after construction with :meth:register_workflow.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Path to the YAML configuration file.	required

Returns:

Type	Description
`Agent`	A fully configured `Agent` instance.

Example

from machina import Agent

agent = Agent.from_config("machina.yaml")
agent.run()

register_workflow ¶

register_workflow(workflow: Workflow) -> None

Register a workflow for later execution.

Parameters:

Name	Type	Description	Default
`workflow`	`Workflow`	The workflow definition to register.	required

trigger_workflow `async` ¶

trigger_workflow(workflow_name: str, event: dict[str, Any] | None = None) -> WorkflowResult

Trigger a registered workflow by name.

Parameters:

Name	Type	Description	Default
`workflow_name`	`str`	Name of a previously registered workflow.	required
`event`	`dict[str, Any] \| None`	Event data to pass to the workflow.	`None`

Returns:

Name	Type	Description
`A`	`WorkflowResult`	class:`WorkflowResult` with per-step outcomes.

Raises:

Type	Description
`WorkflowError`	If the workflow is not found.

start `async` ¶

start() -> None

Connect all connectors and load assets.

stop `async` ¶

stop() -> None

Disconnect all connectors and channels.

handle_message `async` ¶

handle_message(text: str, *, chat_id: str = 'default') -> str

Process a user message and return the agent's response text.

This is the main entry point for programmatic usage. The returned string is the rendered answer with inline [source:page] markers preserved but the trailing <citations> block stripped. Use :meth:handle_message_full to also access structured :class:Citation objects.

Parameters:

Name	Type	Description	Default
`text`	`str`	The user's message.	required
`chat_id`	`str`	Identifier for the conversation.	`'default'`

Returns:

Type	Description
`str`	The agent's response text.

Raises:

Type	Description
`LLMError`	If the underlying LLM call fails.

handle_message_full `async` ¶

handle_message_full(text: str, *, chat_id: str = 'default') -> AgentResponse

Process a user message and return the structured agent response.

Parameters:

Name	Type	Description	Default
`text`	`str`	The user's message.	required
`chat_id`	`str`	Identifier for the conversation.	`'default'`

Returns:

Name	Type	Description
`An`	`AgentResponse`	class:`AgentResponse` with the rendered text and any
	`AgentResponse`	citations the agent emitted.

Raises:

Type	Description
`LLMError`	If the underlying LLM call fails.

run ¶

run() -> None

Start the agent with all channels (blocking, sync wrapper).

Connects connectors, loads assets, and starts listening on all configured channels. Automatically detects Jupyter notebooks and other environments with an already-running event loop.

`EntityResolver`¶

Resolves free-text mentions in user messages (e.g. "the pump P-201", "compressore C-301") to concrete assets registered on the agent's Plant.

EntityResolver ¶

EntityResolver(plant: Plant)

Resolves natural language references to assets in a plant.

Uses a cascading strategy: 1. Exact ID match (e.g. "P-201") 2. Name match (e.g. "cooling water pump") 3. Location match (e.g. "building A") 4. Fuzzy keyword match across all asset fields

Parameters:

Name	Type	Description	Default
`plant`	`Plant`	The plant containing the asset registry.	required

Example

resolver = EntityResolver(plant)
matches = resolver.resolve("the pump in building A")
if matches:
    asset = matches[0].asset

resolve ¶

resolve(text: str) -> list[ResolvedEntity]

Resolve a natural language reference to zero or more assets.

Parameters:

Name	Type	Description	Default
`text`	`str`	User input that may reference an asset.	required

Returns:

Type	Description
`list[ResolvedEntity]`	List of :class:`ResolvedEntity` results, ordered by confidence
`list[ResolvedEntity]`	(highest first). Empty if no matches found.

resolve_best ¶

resolve_best(text: str) -> Asset | None

Resolve to the single best-matching asset, or None.

Parameters:

Name	Type	Description	Default
`text`	`str`	User input that may reference an asset.	required

Returns:

Type	Description
`Asset \| None`	The highest-confidence match, or `None`.

ResolvedEntity `dataclass` ¶

ResolvedEntity(asset: Asset, confidence: float = 1.0, match_reason: str = '')

Result of entity resolution.

Parameters:

Name	Type	Description	Default
`asset`	`Asset`	The matched asset.	required
`confidence`	`float`	Confidence score (0.0-1.0).	`1.0`
`match_reason`	`str`	How the match was determined.	`''`

`LLMProvider`¶

Thin wrapper around LiteLLM exposing complete() and complete_with_tools(). Constructed implicitly by Agent(llm="provider:model") but can also be passed in explicitly for custom providers.

LLMProvider ¶

LLMProvider(model: str = 'openai:gpt-4o', *, temperature: float = 0.1, max_tokens: int = 4096, request_timeout: float = 120.0, tracer: ActionTracer | None = None)

Provider-agnostic LLM interface.

Wraps LiteLLM to provide async complete() and complete_with_tools() methods. Machina's agent layer uses this instead of calling LLM libraries directly.

Parameters:

Name	Type	Description	Default
`model`	`str`	Provider and model identifier (e.g. `"openai:gpt-4o"`).	`'openai:gpt-4o'`
`temperature`	`float`	Sampling temperature.	`0.1`
`max_tokens`	`int`	Maximum tokens in the response.	`4096`
`tracer`	`ActionTracer \| None`	Optional ActionTracer for cost/token instrumentation.	`None`

complete `async` ¶

complete(messages: list[dict[str, str]], *, conversation_id: str = '', **kwargs: Any) -> str

Send a chat completion request and return the response text.

Parameters:

Name	Type	Description	Default
`messages`	`list[dict[str, str]]`	Chat messages in OpenAI format.	required
`conversation_id`	`str`	Conversation identifier for tracing.	`''`
`**kwargs`	`Any`	Extra parameters forwarded to LiteLLM.	`{}`

Returns:

Type	Description
`str`	The assistant's response text.

complete_with_tools `async` ¶

complete_with_tools(messages: list[dict[str, str]], tools: list[dict[str, Any]], *, conversation_id: str = '', **kwargs: Any) -> dict[str, Any]

Send a chat completion with tool/function definitions.

Parameters:

Name	Type	Description	Default
`messages`	`list[dict[str, str]]`	Chat messages in OpenAI format.	required
`tools`	`list[dict[str, Any]]`	Tool definitions (OpenAI function calling schema).	required
`conversation_id`	`str`	Conversation identifier for tracing.	`''`
`**kwargs`	`Any`	Extra parameters forwarded to LiteLLM.	`{}`

Returns:

Type	Description
`dict[str, Any]`	The full response dict including any tool calls.

`Capability`¶

Enum identifying what a connector can do. Used by ConnectorRegistry.find_by_capability(...) for capability-based dispatch (the agent and workflow engine both rely on this to discover available actions at runtime).

Capability ¶

Bases: StrEnum

Actions a connector can perform, declared at registration.

Membership in a connector's capabilities frozenset grants permission for the agent/MCP layer to invoke the corresponding method. String values are stable wire identifiers — do not change them without a deprecation cycle.

Citations¶

When the agent answers a question from retrieved documents it returns a structured AgentResponse carrying inline citations alongside the prose answer. Each Citation references a chunk_id produced by DocumentStoreConnector.search() so callers can audit which exact passage drove the answer.

AgentResponse ¶

Bases: BaseModel

Structured agent output carrying text and grounded citations.

Attributes:

Name	Type	Description
`text`	`str`	The rendered answer (with inline citation markers preserved but the trailing `<citations>` block stripped).
`citations`	`list[Citation]`	List of source citations, one per chunk the agent relied on. May be empty when the answer is not grounded in documents.

Citation ¶

Bases: BaseModel

A pointer from an answer back to its source chunk.

Attributes:

Name	Type	Description
`chunk_id`	`str`	Deterministic identifier of the source chunk (matches :attr:`DocumentChunk.chunk_id`).
`source`	`str`	Source file path or document name.
`page`	`int`	Page number, when known. `0` means "no page".
`quote`	`str`	Optional short verbatim excerpt the claim is grounded in.
`confidence`	`float`	Optional confidence score in `[0.0, 1.0]`.

Example

Citation(chunk_id="abc123", source="manuals/pump.pdf", page=42)

inline_marker ¶

inline_marker() -> str

Render a compact inline marker like [source:page].

Agent¶

Agent¶

Agent ¶

sandbox property writable ¶

workflows property ¶

from_config classmethod ¶

register_workflow ¶

trigger_workflow async ¶

start async ¶

stop async ¶

handle_message async ¶

handle_message_full async ¶

run ¶

EntityResolver¶

EntityResolver ¶

resolve ¶

resolve_best ¶

ResolvedEntity dataclass ¶

LLMProvider¶

LLMProvider ¶

complete async ¶

complete_with_tools async ¶

Capability¶

Capability ¶

Citations¶

AgentResponse ¶

Citation ¶

inline_marker ¶

`Agent`¶

sandbox `property` `writable` ¶

workflows `property` ¶

from_config `classmethod` ¶

trigger_workflow `async` ¶

start `async` ¶

stop `async` ¶

handle_message `async` ¶

handle_message_full `async` ¶

`EntityResolver`¶

ResolvedEntity `dataclass` ¶

`LLMProvider`¶

complete `async` ¶

complete_with_tools `async` ¶

`Capability`¶