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.

Inputs

Parameter	Required	Description
instructions	Yes	User instructions to send to the agent
name	No	Agent name to invoke, default NorFab
verbose_result	No	Return the full message payload instead of only the final response

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 named agent:

nf#agent invoke name NorFab instructions "Check whether any workers are unhealthy"

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

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:
    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