enterprise_ai.agent
Source: sdks/python/src/enterprise_ai/agent/__init__.py. Back to the Python SDK reference index.
This page is generated by tools/docs/gen_sdk_reference.py from the SDK sources and the OpenAPI text folders. Do not edit it by hand: change the source and regenerate.
Class Agent
An agent defined by its manifest, with local tools registered by decorator.
Attributes:
| Name | Type | Required | Description |
|---|---|---|---|
client | yes | Enterprise AI client given to the constructor (gateway, tools, runs), or None for a purely local agent. | |
last_loop | AgentLoop | None | yes | Last AgentLoop built by build_loop, or None before the first run. |
manifest | yes | Agent Manifest the agent was built from, as a dict. | |
metadata | yes | Free key-value pairs stored with the object and returned as they are; the platform never interprets them. | |
name | str | yes | Name of the agent, from metadata.name (default agent); used as agent_id towards the server. |
primary_model | dict[str, Any] | yes | Entry of spec.models whose role is primary, or else the first entry (empty dict when no model is declared). |
spec | yes | spec section of the manifest (models, tools, autonomy, budgets). | |
subagents | yes | Subagent manager built from the manifest, plugged into the runner of each turn. | |
system | yes | System prompt of the agent: the system argument, or else the spec.description of the manifest. | |
tools | dict[str, LocalTool] | yes | Local tools registered with tool, by name. |
Constructor Agent
Agent(manifest: dict[str, Any], client: Any = None, model_call: ModelCall | None = None, validate_manifest: bool = True, system: str | None = None) -> None
Create the agent from a manifest dict, validated against the agent-manifest schema unless validate_manifest is false.
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
manifest | dict[str, Any] | yes | Agent Manifest as a dict (metadata, spec). | |
client | Any | None | no | Parent client. |
model_call | ModelCall | None | None | no | Function (messages, tools) -> dict that calls the model; by default the agent calls the gateway with the manifest model (default_model_call). |
validate_manifest | bool | True | no | Validate the manifest against the agent-manifest schema and raise on errors (default True). |
system | str | None | None | no | System prompt of the agent; defaults to the spec.description of the manifest. |
Agent.apply
apply() -> Any
POST the manifest to /v1/manifests/apply.
This element takes no parameter.
Returns: Any. Response of client.manifests.apply for the manifest; raises ValueError when the agent has no client.
Raises: ValueError.
Agent.approval_patterns
approval_patterns() -> list[str]
Actions that need a human approval: the spec.autonomy.human_approval_for patterns plus tool:<name> for every manifest tool marked requires_approval.
This element takes no parameter.
Returns: list[str]. List of approval patterns, passed as approval_for to the loop.
Agent.build_loop
build_loop(run_id: str | None = None, **kwargs: Any) -> AgentLoop
The :class:AgentLoop configured from the manifest.
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
run_id | str | None | None | no | Run identifier given to the loop, to the gateway calls and to the remote tool invocations. |
**kwargs | Any | no | Extra AgentLoop options; budget defaults to the manifest budget, approval_for to approval_patterns() and remote_tool_specs to the specs of the Tool Gateway tools. |
Returns: AgentLoop. A AgentLoop: Run an agent with budgets and governance hooks.
Agent.default_model_call
default_model_call(run_id: str | None = None) -> ModelCall
Model call through the gateway with the manifest model, effort and output limit.
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
run_id | str | None | None | no | Run identifier added to the eai metadata of each gateway call. |
Returns: ModelCall. Function (messages, tools) -> dict that calls client.gateway.chat and returns the raw answer, with eai_cost when the cost is measured; raises ValueError without a client.
Raises: ValueError.
Agent.from_manifest
from_manifest(source: str | Path | dict[str, Any], **kwargs: Any) -> Agent
Build from a manifest dict, file or YAML string.
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
source | str | Path | dict[str, Any] | yes | Manifest as a dict, a path to a .yaml, .yml or .json file, or a YAML string. | |
**kwargs | Any | no | Keyword arguments of the constructor: client, model_call, validate_manifest, system. |
Returns: Agent. A Agent: An agent defined by its manifest, with local tools registered by decorator.
Agent.remote_tools
remote_tools() -> list[str]
Names of the manifest tools not implemented locally (served by the Tool Gateway).
This element takes no parameter.
Returns: list[str]. List of tool names taken from the spec.tools references, without the local ones.
Agent.run
run(task: Any = None, run_id: str | None = None, session_id: str | None = None, **kwargs: Any) -> TurnResult
Run one Navin turn in-process: :meth:AgentLoop.run_once over :class:AgentRunner.
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
task | Any | None | no | Input of the turn, added to the context as the user request. |
run_id | str | None | None | no | Identifier of the server run this turn belongs to, used for the gateway metadata and the remote tool calls; optional. |
session_id | str | None | None | no | Session whose history builds the context and where the answer is posted. |
**kwargs | Any | no | Options of the loop passed to build_loop; state (a saved turn state to resume) goes to run_once instead. |
Returns: TurnResult. A TurnResult: Outcome of :meth:AgentRunner.run_turn.
Agent.run_legacy
run_legacy(task: Any = None, run_id: str | None = None, **kwargs: Any) -> LoopResult
The former plan / act / verify loop (:meth:AgentLoop.run_legacy).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
task | Any | None | no | Task the loop plans, executes and verifies. |
run_id | str | None | None | no | Identifier of the server run, passed to build_loop; optional. |
**kwargs | Any | no | messages, state and raise_on_budget go to AgentLoop.run_legacy; the other options go to build_loop. |
Returns: LoopResult. A LoopResult: Outcome of :meth:AgentLoop.run.
Agent.run_remote
run_remote(task: Any = None, heartbeat_interval: float = 15.0, **kwargs: Any) -> TurnResult
Create a server run, then execute it locally with heartbeat, checkpoints and kill switch.
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
task | Any | None | no | Task sent to client.agents.run to create the server run, then given to the local turn. |
heartbeat_interval | float | 15.0 | no | Seconds between two heartbeats sent to the run (default 15.0). |
**kwargs | Any | no | Options of the loop passed to build_loop. |
Returns: TurnResult. A TurnResult: Outcome of :meth:AgentRunner.run_turn.
Raises: ValueError.
Agent.run_turn
run_turn(task: Any = None, session_id: str | None = None, run_id: str | None = None, **kwargs: Any) -> TurnResult
Alias of :meth:run (one Navin turn with continuation rules, heartbeat, checkpoints).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
task | Any | None | no | Input of the turn, added to the context as the user request. |
session_id | str | None | None | no | Session whose history builds the context and where the answer is posted. |
run_id | str | None | None | no | Identifier of the server run this turn belongs to; optional. |
**kwargs | Any | no | Options passed to run (loop options and state). |
Returns: TurnResult. A TurnResult: Outcome of :meth:AgentRunner.run_turn.
Agent.tool
tool(fn: Callable[..., Any] | None = None, **options: Any) -> Any
Decorator registering a local tool (@agent.tool or @agent.tool(requires_approval=True)).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
fn | Callable[..., Any] | None | None | no | Function to register as a tool; when omitted, the call returns a decorator that applies the given options. |
**options | Any | no | Per call options (idempotency key, traceparent, headers, abort signal). |
Returns: Any. The registered LocalTool when fn is given, otherwise the decorator.
Functions
ref_name
ref_name(ref: str) -> str
tool:erp-purchase-orders@1.0.0 -> erp-purchase-orders.
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
ref | str | yes | Reference such as tool:name@version. |
Returns: str. Name without the kind prefix and the version.
load_manifest
load_manifest(source: str | Path | dict[str, Any]) -> dict[str, Any]
Load an Agent Manifest from a dict, a YAML / JSON file path or a YAML string.
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
source | str | Path | dict[str, Any] | yes | Manifest as a dict (returned as is), a path to a .yaml, .yml or .json file, or a YAML string. |
Returns: dict[str, Any]. Manifest as a dict; raises ValueError when the YAML is not a mapping.
Raises: ValueError.