Skip to content

trading_agent.subagents.subagent_library

The subagents every desk can delegate to.

Definitions are Markdown files in workspace/shared/agents/, which belongs to the user, and in the agents/ folder of each installed package. When two files define the same name, the user's own folder wins. The folders are read afresh every time, so a new definition is available on the desk's next turn.

Typical usage example:

library = SubagentLibrary(Path('workspace/shared/agents'), packages.agent_roots) definition = library.find('news_reader')

BrokenDefinition dataclass 

BrokenDefinition(path, error)

A subagent file that could not be read, and why.

Attributes:

Name Type Description
path Path

The file.
error str

The reason.

SubagentLibrary 

SubagentLibrary(agents_directory, package_agent_roots=None)

Finds subagent definitions.

Describes the folders without reading them.

Parameters:

Name Type Description Default
agents_directory Path

workspace/shared/agents.

 required
package_agent_roots Callable[[], Sequence[Path]] | None

Returns the agents/ folders of installed packages, or None for no packages.

 None
Source code in src/trading_agent/subagents/subagent_library.py 
37
38
39
40
41
42
43
44
45
46
47
48
49
50
def __init__(
    self,
    agents_directory: Path,
    package_agent_roots: Callable[[], Sequence[Path]] | None = None,
):
    """Describes the folders without reading them.

    Args:
        agents_directory (Path): workspace/shared/agents.
        package_agent_roots (Callable[[], Sequence[Path]] | None): Returns the agents/ folders of installed packages, or None for no packages.
    """
    self.agents_directory = agents_directory
    self._package_agent_roots = package_agent_roots
    self._parser = definition_module.SubagentParser()

definitions 

definitions()

Every readable definition, the user's first, without repeated names.

Returns:

Type Description
list[SubagentDefinition]

The subagents.
Source code in src/trading_agent/subagents/subagent_library.py 
52
53
54
55
56
57
58
59
def definitions(self) -> list[definition_module.SubagentDefinition]:
    """Every readable definition, the user's first, without repeated names.

    Returns:
        list[definition_module.SubagentDefinition]: The subagents.
    """
    definitions, _ = self._read_all()
    return definitions

broken 

broken()

The files that could not be read.

Returns:

Type Description
list[BrokenDefinition]

Each broken file and why.
Source code in src/trading_agent/subagents/subagent_library.py 
61
62
63
64
65
66
67
68
def broken(self) -> list[BrokenDefinition]:
    """The files that could not be read.

    Returns:
        list[BrokenDefinition]: Each broken file and why.
    """
    _, broken = self._read_all()
    return broken

find 

find(name)

Finds one subagent by name.

Parameters:

Name Type Description Default
name str

The name.

 required

Returns:

Type Description
SubagentDefinition | None

The subagent, or None when there is none of that name.
Source code in src/trading_agent/subagents/subagent_library.py 
70
71
72
73
74
75
76
77
78
79
80
81
82
def find(self, name: str) -> definition_module.SubagentDefinition | None:
    """Finds one subagent by name.

    Args:
        name (str): The name.

    Returns:
        definition_module.SubagentDefinition | None: The subagent, or None when there is none of that name.
    """
    for definition in self.definitions():
        if definition.name == name:
            return definition
    return None

index_text 

index_text()

The section of the desk's prompt listing its subagents.

Returns:

Type Description
str

The section, or an empty string when there are no subagents.
Source code in src/trading_agent/subagents/subagent_library.py 
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
def index_text(self) -> str:
    """The section of the desk's prompt listing its subagents.

    Returns:
        str: The section, or an empty string when there are no subagents.
    """
    definitions = self.definitions()
    if not definitions:
        return ''
    lines = [
        '===== Subagents =====',
        'Subagents are helpers you can hand a self-contained task to with delegate_task. Up to four tasks run at the same time, each with its own fresh conversation, so give each one everything it needs in the task text. They report back to you; they cannot talk to the user or start subagents of their own.',
    ]
    for definition in definitions:
        lines.append(f'- {definition.name}: {definition.description}')
    return '\n'.join(lines)