# Copyright 2026 Flower Labs GmbH. All Rights Reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
# ==============================================================================
"""AgentApp abstract base classes and callable type alias."""
from __future__ import annotations
from abc import ABC, abstractmethod
from collections.abc import Callable, Sequence
from flwr.app import Context
from flwr.proto.control_pb2 import Agent # pylint: disable=E0611
from flwr.proto.file_pb2 import File, FileMetadata # pylint: disable=E0611
from flwr.supercore.typing import JSONObject
# OpenResponses item types and streaming events used for run summaries.
# See https://www.openresponses.org/reference
# Schema: https://www.openresponses.org/openapi/openapi.json
RUN_SUMMARY_EVENT_TYPES: tuple[str, ...] = (
"message",
"response.completed",
"response.incomplete",
"function_call",
"function_call_output",
)
[docs]
class AgentConnectors(ABC):
"""Abstract base class for AgentApp connector execution."""
[docs]
def get_connections(self) -> list[JSONObject]:
"""List the current Space agent's connections without credentials.
Returns
-------
list[JSONObject]
Connection metadata with connector_id, connector_ref, display_name,
and description.
Raises
------
NotImplementedError
If the session does not support agent-owned connections.
"""
raise NotImplementedError("Agent-owned connections require a Space session.")
[docs]
@abstractmethod
def call(self, tool_call: JSONObject) -> JSONObject:
"""Execute one model function_call and return a function_call_output item."""
[docs]
class AgentEvents(ABC):
"""Abstract base class for AgentApp run events."""
[docs]
@abstractmethod
def get_trace(
self,
*,
event_types: Sequence[str] | None = None,
after_event_id: int | None = None,
before_event_id: int | None = None,
last_n: int | None = None,
) -> list[JSONObject]:
"""Get matching events from all runs in the current run series.
Parameters
----------
event_types : Optional[Sequence[str]] (default: None)
Filter by the given event types. If unset, include all event types.
Use `RUN_SUMMARY_EVENT_TYPES` for common summary inputs.
after_event_id : Optional[int] (default: None)
Return events with IDs greater than this value.
before_event_id : Optional[int] (default: None)
Return events with IDs less than this value.
last_n : Optional[int] (default: None)
Return the newest N matching events in ID order. If unset or zero,
return all matching events.
Returns
-------
list[JSONObject]
Matching event envelopes.
"""
[docs]
@abstractmethod
def emit(self, event: JSONObject) -> None:
"""Emit one structured run event."""
[docs]
@abstractmethod
def get_compacted_contexts(
self, *, limit: int = 1, before_context_id: int | None = None
) -> list[JSONObject]:
"""Return the newest summaries."""
[docs]
@abstractmethod
def put_compacted_context(
self, *, through_event_id: int, text: str, token_count: int
) -> None:
"""Store a summary."""
[docs]
class AgentGrid(ABC):
"""Model-facing access to the federation Grid."""
[docs]
@abstractmethod
def call(self, tool_call: JSONObject) -> JSONObject:
"""Execute one Grid function_call and return a function_call_output item."""
[docs]
class AgentSpace(ABC):
"""Read and publish messages in the authenticated agent's Space."""
[docs]
@abstractmethod
def get_messages(
self,
*,
limit: int = 100,
before_id: int | None = None,
after_id: int | None = None,
unread_only: bool = False,
) -> list[JSONObject]:
"""Read messages and advance this agent's read cursor.
Parameters
----------
limit : int (default: 100)
Maximum number of messages to return, between 1 and 100.
before_id : int | None (default: None)
Exclusive upper message ID bound.
after_id : int | None (default: None)
Exclusive lower ID bound; selects the oldest matching page.
unread_only : bool (default: False)
Select the oldest page after this agent's read cursor.
Returns
-------
list[JSONObject]
Messages in ascending ID order, with id, space_id, author, created_at,
content, and hidden. Author contains either flwr_aid or agent_id.
Notes
-----
Reads select the newest page by default. Every read advances the cursor
through the newest returned message, including history reads.
"""
[docs]
@abstractmethod
def call(self, tool_call: JSONObject) -> JSONObject:
"""Publish a message and return a function_call_output item."""
[docs]
class AgentFiles(ABC):
"""Persistent files owned by the authenticated agent."""
[docs]
@abstractmethod
def get(self, key: str) -> File | None:
"""Return the current file content and metadata.
Parameters
----------
key : str
File key within the agent's scope.
Returns
-------
File | None
Content and metadata, or None if absent or deleted.
"""
[docs]
@abstractmethod
def put(
self, key: str, data: bytes, *, expected_revision: int | None = None
) -> int:
"""Create or update a file, preserving its previous revisions.
Parameters
----------
key : str
Non-empty, non-whitespace file key, preserved unchanged.
data : bytes
File content to store.
expected_revision : int | None (default: None)
None means create-only and fails if a live file exists. Otherwise,
the current live revision must match for the update to succeed.
Returns
-------
int
The new revision ID.
"""
[docs]
@abstractmethod
def list(
self,
*,
prefix: str = "",
start_after: str = "",
limit: int | None = None,
) -> tuple[list[FileMetadata], str]:
"""List live file metadata in lexicographic key order.
Parameters
----------
prefix : str (default: "")
Include only keys starting with this prefix.
start_after : str (default: "")
Exclusive key cursor; empty starts from the beginning.
limit : int | None (default: None)
Maximum number of entries. None returns all matches; zero returns
an empty page.
Returns
-------
tuple[list[FileMetadata], str]
Metadata and the next cursor, which is empty when no more remain.
"""
[docs]
@abstractmethod
def delete(self, key: str, *, expected_revision: int) -> None:
"""Delete a file from the current view, retaining its history.
Parameters
----------
key : str
File key within the agent's scope.
expected_revision : int
Must match the current live revision; missing or deleted files
also cause a revision conflict.
"""
[docs]
class AgentSession(ABC):
"""Abstract base class for AgentApp runtime capabilities."""
@property
def identity(self) -> Agent | None:
"""Return this agent's stored identity, or None when unavailable."""
return None
@property
@abstractmethod
def prompt(self) -> str:
"""Return the initial prompt for this AgentApp run."""
@property
@abstractmethod
def connectors(self) -> AgentConnectors:
"""Connector tool schema and execution API."""
@property
@abstractmethod
def events(self) -> AgentEvents:
"""Frontend-visible structured run event API."""
@property
@abstractmethod
def grid(self) -> AgentGrid:
"""Model-facing federation Grid API."""
@property
@abstractmethod
def files(self) -> AgentFiles:
"""Persistent file API."""
@property
def space(self) -> AgentSpace | None:
"""Space messaging API, or None when unavailable for this session."""
return None
AgentAppCallable = Callable[[AgentSession, Context], None]