Skip to content

Invoke an Agent¤

task api name: invoke

Give an agent a network question or a check to perform. The default NorFab agent can call tasks from running services. A custom definition supplies a repeatable prompt and selected tools; see worker configuration and definitions.

Each call starts a fresh conversation. Include the device scope, expected state and evidence you want in every request. Use the client agent for ongoing chat.

Output¤

The default result is the agent's final answer. Python calls return it under result for each agent worker, alongside failed and errors.

For example, these are the relevant fields of a successful response; the wording of the answer varies with the model and task results:

{
  "agent-worker-1": {
    "result": "r1: one interface is down. Review Ethernet2 and its peer.",
    "failed": false,
    "errors": []
  }
}

Request verbose_result=True to include the conversation and tool results when you need to inspect the evidence behind an answer.

Check network state¤

nf# agent invoke workers agent-worker-1 instructions "Check interfaces on r1. List down interfaces and error counters. Include the commands used and any checks that could not be completed."
from norfab.core.nfapi import NorFab

with NorFab(inventory="./inventory.yaml") as nf:
    client = nf.make_client()
    results = client.run_job(
        service="agent",
        task="invoke",
        workers="agent-worker-1",
        kwargs={
            "instructions": (
                "Check interfaces on r1. List down interfaces and error "
                "counters. Include the commands used and any checks that "
                "could not be completed."
            ),
        },
    )
    for worker, response in results.items():
        if response["failed"]:
            print(worker, response["errors"])
        else:
            print(worker, response["result"])

Interface examples require a running Nornir service with r1 in its inventory. A completed agent request does not mean every network check passed: read the findings and any reported task failures in the answer.

Follow progress¤

Workers send progress events while the model responds and tools run. These show activity and tool names, without exposing model reasoning or full tool data.

Progress is displayed by default:

nf# agent invoke workers agent-worker-1 instructions "Check interfaces on r1" progress true

Use the client from the previous example to read events as they arrive:

future = client.submit_job(
    service="agent",
    task="invoke",
    workers="agent-worker-1",
    kwargs={"instructions": "Check interfaces on r1", "progress": True},
)
for event in future.events():
    print(event["message"])
print(future.result())

Run a focused agent¤

This uses the interface-check definition.

nf# agent invoke workers agent-worker-1 name nf://agents/interface_check.yaml instructions "Check interfaces on r1 and r2. Report only problems and their evidence."
from norfab.core.nfapi import NorFab

nf = NorFab(inventory="./inventory.yaml")
try:
    nf.start()
    client = nf.make_client()
    results = client.run_job(
        service="agent",
        task="invoke",
        workers="agent-worker-1",
        kwargs={
            "name": "nf://agents/interface_check.yaml",
            "instructions": (
                "Check interfaces on r1 and r2. Report only problems "
                "and their evidence."
            ),
        },
    )
    for worker, response in results.items():
        print(worker, response["result"])
finally:
    nf.destroy()

Inspect tool results¤

nf# agent invoke workers agent-worker-1 verbose-result instructions "Check interfaces on r1 and include the evidence."
results = client.run_job(
    service="agent",
    task="invoke",
    workers="agent-worker-1",
    kwargs={
        "instructions": "Check interfaces on r1 and include the evidence.",
        "verbose_result": True,
    },
)
for response in results.values():
    print(response["result"])

Use the client created in the examples above. workers selects the agent host; network devices are selected through your instructions and the tools it calls.

Task Command Shell Reference¤

nf# man tree agent invoke

Python API Reference¤

Run instructions with the built-in agent or a custom YAML definition.

Parameters:

Name Type Description Default
job Job

Job context used to report execution progress.

required
instructions str

Request sent to the agent.

required
name str

NorFab for native access to discovered NorFab tasks, or an nf:// or git:// URL to a YAML agent definition. Custom definitions may supply name, system_prompt, tools and llm using the shared core agent format. Defaults to NorFab.

'NorFab'
verbose_result bool

Return the full agent invocation payload when true; otherwise return the final response content. Defaults to false.

False

Returns:

Name Type Description
Result Result

Final response content or the full invocation payload. Each invocation starts a fresh conversation without stored history. Failed result if core agent dependencies are missing.

Raises:

Type Description
FileNotFoundError

The custom definition cannot be fetched.

KeyError

Neither the definition nor inventory supplies an LLM.

ValueError

The definition has duplicate tools or an unsupported provider.

ImportError

A configured provider or optional feature is not installed.

Source code in norfab\workers\agent_worker\agent_worker.py
155
156
157
158
159
160
161
162
163
164
165
166
167
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
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
@Task(
    input=InvokeInput,
    output=InvokeResult,
    fastapi={"methods": ["POST"]},
    mcp={
        "annotations": {
            "title": "Invoke Agent",
            "readOnlyHint": False,
            "destructiveHint": True,
            "idempotentHint": False,
            "openWorldHint": True,
        }
    },
)
def invoke(
    self,
    job: Job,
    instructions: str,
    name: str = "NorFab",
    verbose_result: bool = False,
) -> Result:
    """Run instructions with the built-in agent or a custom YAML definition.

    Args:
        job (Job): Job context used to report execution progress.
        instructions (str): Request sent to the agent.
        name (str): ``NorFab`` for native access to discovered NorFab tasks, or an
            ``nf://`` or ``git://`` URL to a YAML agent definition. Custom
            definitions may supply ``name``, ``system_prompt``, ``tools``
            and ``llm`` using the shared core agent format. Defaults to ``NorFab``.
        verbose_result (bool): Return the full agent invocation payload when
            true; otherwise return the final response content. Defaults to false.

    Returns:
        Result: Final response content or the full invocation payload.
            Each invocation starts a fresh conversation without stored history.
            Failed result if core agent dependencies are missing.

    Raises:
        FileNotFoundError: The custom definition cannot be fetched.
        KeyError: Neither the definition nor inventory supplies an LLM.
        ValueError: The definition has duplicate tools or an unsupported provider.
        ImportError: A configured provider or optional feature is not installed.
    """
    if not core_agent.HAS_LIBS:
        return Result(failed=True, errors=[core_agent.DEPENDENCY_ERROR])
    job.event(f"getting {name} agent ready")
    if name == "NorFab":
        config = {"llm": self.agent_inventory["default_llm"]}
    else:
        config = yaml.safe_load(
            self.fetch_file(name, raise_on_fail=True, read=True)
        )
        if not config.get("llm"):
            config["llm"] = self.agent_inventory["default_llm"]

    agent = NFAgent(self.client, config)
    try:
        return Result(
            result=agent.invoke(
                instructions,
                verbose_result=verbose_result,
                callbacks=[AgentProgress(job.event)],
            )
        )
    finally:
        agent.close()