Workspace and CLI API

The .tool-agents project folder and the command that runs it. See the CLI guide for the narrative version.

from ToolAgents.workspace import Workspace

Workspace

Workspace `dataclass`

Workspace(root: Path)

A loaded .tool-agents directory.

discover `classmethod`

discover(
    start: Path | str | None = None,
    dirname: str = DEFAULT_WORKSPACE_DIRNAME,
) -> "Workspace"

Find the nearest workspace at or above start.

Raises:

Type	Description
`WorkspaceNotFoundError`	if no such directory exists, naming every directory that was searched so the failure is diagnosable.

create `classmethod`

create(
    parent: Path | str | None = None,
    dirname: str = DEFAULT_WORKSPACE_DIRNAME,
) -> "Workspace"

Create an empty workspace under parent and return it.

workflow_files

workflow_files() -> list[Path]

Return every workflow document, sorted by name.

workflow_names

workflow_names() -> list[str]

Return the names workflows are referred to by.

workflow_path

workflow_path(name: str) -> Path

Return the path of one workflow, by name or filename.

tool_files

tool_files() -> list[Path]

Return every tool module.

prompt_files

prompt_files() -> list[Path]

Return every prompt file.

provider_files

provider_files() -> list[Path]

Return every provider declaration file.

adapter_files

adapter_files() -> list[Path]

Return every adapter module, inputs before outputs.

load_prompts

load_prompts() -> dict[str, str]

Return prompt text keyed by file stem.

load_adapters

load_adapters() -> list[str]

Import adapter modules so they register their types.

Returns the module names imported, for reporting.

build_tool_registry

build_tool_registry() -> PipelineToolRegistry

Register every tool module as a plugin named for its file.

load_agent_configs

load_agent_configs() -> (
    tuple[list[dict[str, Any]], str | None]
)

Return shared agent declarations and an optional default name.

A provider file may hold a list of agent declarations, or an object with agents and optionally default_agent.

load_env

load_env(env_file: str | Path | None = None) -> bool

Read a .env file so provider keys can come from one.

With no argument this reads .tool-agents/.env if it exists, which is where a project's keys naturally live: beside the workflows that need them, and easy to gitignore as one path. Values already exported in the environment are left alone.

Returns:

Name	Type	Description
`bool`	`bool`	Whether a file was read.

load_workflow_document

load_workflow_document(name: str) -> dict[str, Any]

Read one workflow document, merged with shared provider entries.

A workflow's own agents entries win over the shared ones, so a workflow can override a shared declaration by redeclaring the name.

load_pipeline

load_pipeline(
    name: str,
    allow_writes: bool = False,
    build_agents: bool = True,
    default_agent: Any = None,
    env_file: str | Path | None = None,
) -> Pipeline

Load one workflow with the workspace's tools, adapters and env.

run_workflow

run_workflow(
    name: str,
    arguments: Mapping[str, Any] | None = None,
    allow_writes: bool = False,
    build_agents: bool = True,
    default_agent: Any = None,
    env_file: str | Path | None = None,
) -> PipelineResults

Load and run one workflow, seeding the prompts section.

summary

summary() -> dict[str, list[str]]

Return what this workspace contains, for tool-agents list.

WorkspaceError

Bases: RuntimeError

Raised when a workspace is malformed or a member is missing.

WorkspaceNotFoundError

Bases: WorkspaceError

Raised when no workspace directory could be found.

Command line

main

main(argv: list[str] | None = None) -> int

Entry point for the tool-agents command.

build_parser

build_parser() -> ArgumentParser

Build the tool-agents argument parser.

parse_argument

parse_argument(pair: str) -> tuple[str, Any]

Parse one key=value argument.

The value is decoded as JSON when it can be, so --arg n=3 gives an integer, --arg tags=["a","b"] a list, and --arg name=Ada the plain string it looks like.

collect_arguments

collect_arguments(
    pairs: Sequence[str] | None,
    json_text: str | None,
    json_file: str | None,
) -> dict[str, Any]

Merge --arg, --json and --json-file into one mapping.