Skip to content

antikythera_agents.reference_agent ¤

Reference agent: the worked example for the tool convention (ADR-0002, ADR-0003).

Copy from this file when authoring a new agent. Its three tools between them exercise every annotation kind the binder understands — a plain task input, an explicit Input[T], a required and a defaulted Param[T], a Context[T] value, an Optional[T] input, a TypedDict return with both a required and a NotRequired key, the Task escape hatch, and ExecutionContext cancellation. It has no dependency beyond this package, so it runs anywhere the launcher does, including CI. See examples/reference_agent_demo.json for a blueprint that drives it end to end, and ARCHITECTURE.md's "Reference Agent" section.

Classes¤

ReferenceAgent ¤

ReferenceAgent()

Worked example agent exercising every part of the tool convention.

Not a real fabrication tool: it exists so an agent author has a small, dependency-free file to copy from, and so the binder is exercised by combinations no first-party tool puts it through (ADR-0002, issue-td-10).

Methods:¤

assemble ¤
assemble(
    title: str,
    subtitle: Input[str],
    tag: Param[str],
    element_id: Context[str] = "unassigned",
    repeat: Param[int] = 1,
    note: str | None = None,
) -> AssembleResult

Combine a title, subtitle and tag into a message, repeated repeat times.

Parameters:

  • title (str) –

    A plain task input, bound by name exactly like subtitle.

  • subtitle (str) –

    A task input declared explicitly with Input[str] — binds identically to title, an unannotated parameter.

  • tag (str) –

    A required task parameter (Param[str], no default).

  • element_id (str, default: 'unassigned' ) –

    The expansion-context key this tool wants (Context[str]); falls back to its default outside a dynamic expansion, and binds per element inside one.

  • repeat (int, default: 1 ) –

    A task parameter with a default (Param[int] = 1).

  • note (str, default: None ) –

    An optional task input that legitimately accepts nothing.

Returns:

  • message ( str ) –

    The assembled, repeated message.

  • detail ( (str, optional) ) –

    Present only when note was given.

passthrough ¤
passthrough(task: Task) -> dict[str, Any]

The Task escape hatch: reads task.inputs directly, opaque to strict binding.

Returns:

  • dict –

    Every declared input's name mapped to its resolved value.

wait ¤
wait(seconds: Param[float], context: ExecutionContext) -> dict[str, Any]

Sleep in small increments, stopping early if the run is cancelled.

Parameters:

  • seconds (float) –

    Total time to sleep, in seconds, absent cancellation.

Returns:

  • dict –

    cancelled: whether the wait was interrupted by cancellation.