Skip to content

Role

A role is an agent your workflow runs: a model, a prompt, and what the agent may use. Define it with @role, and run it with Run.step().

@role(model=Claude.OPUS(effort=ClaudeEffort.HIGH), accepts=(Request,))
def builder_role() -> Role:
    return Role(name="builder", instructions=prompt_file("prompts/builder.md"))

builder = builder_role()

@role wraps a function that builds the Role. Call it to get the role you pass to Run.step(). The function can take arguments, to build a role for each task.

A Role built with Role(...) outside a @role function has no model, and Run.step() refuses it before the agent starts.

How it works

See also

Reference

agl.sdk.role(*, model, accepts=())

Declares a function that builds a Role.

Parameters:

  • model (ModelChoice) –

    The model the role runs on, bare or called with an effort. A bare model reasons at whatever its own tool does by default.

  • accepts (Sequence[type[object]], default: () ) –

    The classes the role takes as inputs, each named in its prompt as {{TypeName}}. If omitted, the role takes no inputs.

Returns:

  • _RoleDecorator –

    The decorator to write above the function, which turns it into a role factory.

Raises:

  • InputError –

    An accepts= entry that is not a class, one isinstance refuses, or two that share a name.

agl.sdk.RoleFactory

A @role function, which builds a Role when called.

__call__(*args, **kwargs)

Builds the Role, passing everything through to the function.

Parameters:

  • args (P.args, default: () ) –

    The positional arguments the decorated function takes.

  • kwargs (P.kwargs, default: {} ) –

    The keyword arguments the decorated function takes.

Returns:

  • Role[R] –

    The Role the function returned, carrying this factory's model and accepted types.

Raises:

  • InputError –

    A placeholder in the prompt has whitespace inside its braces, the prompt and accepts= don't name the same set of types, or the Role the function returned is refused.

agl.sdk.Role dataclass

An agent a step runs, with its instructions and tools.

name instance-attribute

The name this role's steps run under. Two roles' names should differ by more than case.

instructions instance-attribute

What the agent is asked to do. Each {{TypeName}} in it is filled with that input.

restrictions = frozenset() class-attribute instance-attribute

The Restriction members this role's agent works under.

tools = () class-attribute instance-attribute

The tools the agent is offered, with unique names and at most one reporting tool.

requires = frozenset() class-attribute instance-attribute

The Capability members the backend has to offer.

on_activity = None class-attribute instance-attribute

Called with each line of progress the agent reports as it works.

agl.sdk.Capability

Bases: StrEnum

Something a role needs its agent to be able to do.

FILE_EDIT class-attribute instance-attribute

Changing files in the checkout the step runs in.

SHELL class-attribute instance-attribute

Running shell commands.

TOOL_CALLING class-attribute instance-attribute

Calling the tools a role declares. A role with tools requires it without saying so.