Use agents and federations¶

Flower uses a few related objects to describe AgentApp execution. This guide defines them, then shows how to select an agent and execution federation in the current browser and CLI interfaces.

Learn the mental model¶

AgentApp : Python control flow registered with AgentApp.main. It decides which model and connector calls to make and how to handle their results.

Agent : An AgentApp made available for selection. An app spec such as @flwrlabs/flwr-agent identifies a published app. SuperGrid may resolve the selection to a specific Flower App Bundle (FAB) hash.

Run : One execution of one app in one federation. Every message submitted through a chat interface starts a run.

Run series or conversation : A group of related runs with shared Flower Context. The browser presents a run series as a conversation. Sharing a series does not itself make history visible to a model; the AgentApp must replay stored messages.

Federation : A SuperGrid workspace that owns runs, run series, members, and execution resources. Your account has a personal workspace and can be a member of multiple collaborative federations.

Connector : A runtime-provided tool. Built-in tools need no external account. Account connectors use authorization granted by the signed-in user and are currently restricted to personal-workspace runs.

List your federations¶

Authenticate first, then ask SuperGrid for the federations visible to your account:

$ uvx --from flwr==1.35.0 flwr login supergrid
$ uvx --from flwr==1.35.0 flwr federation list supergrid

Use the full federation ID shown by this command, including its leading @, in later commands.

Choose a federation for `flwr run`¶

The following uv run examples use the Flower version installed in your local project environment. To stay consistent with the rest of this guide, ensure that environment has flwr==1.35.0 installed.

Flower selects the federation in this order:

The value passed with --federation.
The federation configured for the selected SuperLink connection.
The account’s default federation when neither is set.

With no command-line option, this command uses the configured federation or falls back to the account default:

$ uv run flwr run . supergrid

To choose explicitly:

$ uv run flwr run . supergrid \
    --federation @account/federation-name

The app can also be a published app spec:

$ uvx --from flwr==1.35.0 flwr run @publisher/agent supergrid \
    --federation @account/federation-name \
    --run-config 'agent.input="Summarize this federation task."'

The account must be a member of the federation and entitled to start the AgentApp there.

Choose the `flwr chat` federation¶

flwr chat starts in your @account/personal federation. Enter /federation to open the completion menu, then select a federation visible to your account. You can also type its full name:

/federation @account/federation-name

Switching federations clears the transcript, resets the selected agent to Flower Agent, and starts a new conversation. Use flwr run --federation when you want to select the federation in a non-interactive command.

Select an agent in Flower Chat¶

At an empty flwr chat prompt, type @. The completion menu lists agents returned for the active federation. Choose one and add your request:

@publisher/agent Compare the two proposed approaches.

The selected label above the prompt changes immediately. Flower keeps using that agent for later messages. Selecting a different agent clears the current series ID, so the request starts a new run series. Use /new to start a new series without changing agents.

Select an agent in SuperGrid¶

Open Flower Agent. The sidebar pins your personal federation and lists the other federations visible to your account. Select a federation, open New chat, and choose one of its assigned agents above the prompt.

The selected federation owns the run and its conversation. Recent AgentApp conversations appear below that federation in the sidebar, where you can open them again. Flower excludes non-AgentApp run series from this chat history.

Know when a new series starts¶

Action	Result
Send another message with the selected agent	Reuse the current run series
Enter `/new` in Flower Chat	The next message starts a new series
Select a different leading `@agent`	Start a new series with that agent
Enter `/history` in Flower Chat	Select and continue an older series
Switch federations in Flower Chat	Start a new series in that federation
Select New chat in SuperGrid	Start a new browser conversation
Select a browser conversation	Continue its existing run series
Run `flwr run` without a series ID	Start an independent run or series

Use connectors in the right workspace¶

Built-in tools such as web_search and web_fetch are chosen in AgentApp code. Slack, Notion, GitHub, and Attio are account connectors selected for a browser run. Flower 1.35.0 rejects account-connector references for a collaborative federation; run that task in your personal workspace instead.

See Connect accounts for setup and the exact read-only capability matrix.