Agent Service Chat Task

task api name: invoke

Invokes an Agent worker with user instructions. The task is commonly used as an interactive chat surface, but the API task name is invoke.

Select the built-in NorFab agent or supply an nf:// or git:// YAML definition as name. See inventory and definitions. Each call starts a fresh conversation; there is no conversation thread setting.

Output

By default, returns the final agent response text. With verbose_result=True, returns the full agent invocation payload.

Examples

CLIPython

Ask the default agent a question:

nf# agent invoke instructions "Summarize the current NorFab inventory"

Invoke a custom agent:

nf# agent invoke name nf://agents/interface_check.yaml instructions "Check interfaces on r1"

Context manager:

from norfab.core.nfapi import NorFab

with NorFab(inventory="./inventory.yaml") as nf:
    client = nf.make_client()

    result = client.run_job(
        service="agent",
        task="invoke",
        workers="any",
        kwargs={
            "instructions": "Summarize the current NorFab inventory",
        },
    )
    print(result)

Direct lifecycle with a named agent:

from norfab.core.nfapi import NorFab

nf = NorFab(inventory="./inventory.yaml")
try:
    nf.start()
    client = nf.make_client()

    result = client.run_job(
        service="agent",
        task="invoke",
        workers="any",
        kwargs={
            "name": "NorFab",
            "instructions": "Check whether any workers are unhealthy",
            "verbose_result": True,
        },
    )
    print(result)
finally:
    nf.destroy()

NORFAB Agent Chat Command Shell Reference

NorFab shell supports these command options for Agent invoke task:

nf# man tree agent
root
└── agent:    AI Agent service
    ├── timeout:    Job timeout
    ├── workers:    Filter worker to target, default 'all'
    ├── show:    Show Agent service parameters
    │   ├── inventory:    show agent inventory data
    │   ├── version:    show agent service version report
    │   └── status:    show agent status
    ├── invoke:    Invoke an agent to chat or run a task
    │   ├── instructions:    Provide instructions
    │   ├── name:    Agent name to interact with
    │   └── progress:    Emit execution progress, default 'True'
    └── progress:    Emit execution progress, default 'True'
nf#

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 the built-in task-discovery agent, or an nf:// or git:// URL to a YAML agent definition. Custom definitions require name and system_prompt and may supply tools and llm. 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.

Raises:

Type	Description
RuntimeError	The built-in agent has no configured default_llm.
FileNotFoundError	The custom definition cannot be fetched.
KeyError	A required definition or fallback model setting is missing.

Source code in norfab\workers\agent_worker\agent_worker.py

@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 the built-in task-discovery agent, or an
            ``nf://`` or ``git://`` URL to a YAML agent definition. Custom
            definitions require ``name`` and ``system_prompt`` and may supply
            ``tools`` and ``llm``. 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.

    Raises:
        RuntimeError: The built-in agent has no configured ``default_llm``.
        FileNotFoundError: The custom definition cannot be fetched.
        KeyError: A required definition or fallback model setting is missing.
    """
    ret = Result()
    log.info(f"{self.name} - Invoke: Processing instructions with '{name}' agent")
    job.event(f"getting {name} agent ready")

    agent_data = self.get_agent(job, name)

    agent_instance = create_agent(
        name=agent_data["name"],
        model=self.get_llm(**agent_data["llm"]),
        system_prompt=agent_data["system_prompt"],
        tools=agent_data["tools"],
    )

    job.event(f"{name} agent thinking")

    ret.result = agent_instance.invoke(
        {"messages": [{"role": "user", "content": instructions}]}
    )

    if verbose_result is False:
        ret.result = ret.result["messages"][-1].content

    return ret