Targets

AgentIdem Nebutex CLI commands operate on Python targets.

A target tells the CLI which Python function to import and execute.

Target format

Targets use this format:

module.path:function

For example:

examples.refund_agent:run

This target means:

module:
examples.refund_agent

function:
run

The CLI imports the module and resolves the named function from it.

Example module

Suppose your project contains:

examples/
└── refund_agent.py

and refund_agent.py contains:

from agentidem import read, write

@read
def get_payment(payment_id: str):
    return payments.get(payment_id)

@write(identity=lambda payment_id: payment_id)
def refund(payment_id: str):
    return payments.refund(payment_id)

def run():
    payment = get_payment("payment-123")

    if payment["status"] == "paid":
        return refund("payment-123")

    return "no_refund"

The corresponding CLI target is:

examples.refund_agent:run

Using the target with test

agentidem test examples.refund_agent:run

Using the target with record

agentidem record examples.refund_agent:run --trace trace.json

Using the target with replay

agentidem replay examples.refund_agent:run --trace trace.json

The same target format is used across these commands.

Module path

The portion before the colon is the Python module path.

For example:

examples.refund_agent

corresponds to an import such as:

import examples.refund_agent

Use dots between Python package and module names.

For example:

myapp.agents.billing.refund_agent:run

Function name

The portion after the colon is the function AgentIdem should execute.

For example:

:run

refers to:

def run():
    ...

The complete target becomes:

myapp.agents.billing.refund_agent:run

Importability

The module must be importable from the environment where the CLI is running.

If Python cannot import the module, AgentIdem cannot resolve the target.

For example, this target:

examples.refund_agent:run

requires Python to be able to import:

examples.refund_agent

Target resolution errors

A target can fail to resolve if:

the module cannot be imported
the function does not exist
the target syntax is invalid
the resolved object cannot be executed as the expected target

These are operational or setup errors rather than side effect safety findings.

CLI operational errors use exit code:

See Exit codes.

Keep CLI entry points simple

A small wrapper function can make a target easier to invoke from the CLI.

For example:

def run():
    return refund_agent("payment-123")

Then use:

agentidem test examples.refund_agent:run

This gives the CLI a direct callable target while your underlying agent can still accept arguments.