Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.
Python agent-orchestrationaiai-agentschatopsdiscordlangchainmcpmicrosoft-teamsmulti-agentopen-sourceopenaiself-hostedslack
"""Management's side of the agent operations on machines and managed agents.
Implements Core's `AgentManagementPort` on top of `ManagementService`, so an
agent creating a managed agent goes through exactly the validation and
placement checks the owner's gateway route does. What is here is only what an
agent caller needs on top: finding a machine by name, shaping the answers for
an agent to read, and turning a refusal into a sentence it can relay.
Every method acts for the owner it is given, on that owner's machines alone;
another person's machine is never matched, so it reads as not existing.
"""
from __future__ import annotations
from typing import Any
from pydantic import ValidationError
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
from switch_core.bridges.agent.protocol.agent_core import AgentCore
from switch_core.bridges.agent.protocol.agent_management import (
AgentManagementRefused,
CheckedPlacement,
ManagedAgentChanges,
NewManagedAgent,
)
from switch_core.db.models import Agent, AgentController
from switch_core.db.models import AgentDefinition as AgentDefinitionRow
from switch_core.db.session_scope import tenant_session
from switch_core.management import reason_codes
from switch_core.management.advanced_config import provider_fields
from switch_core.management.errors import ManagementError
from switch_core.management.placement import is_revoked, provider_auth
from switch_core.management.schemas import (
CreateManagedAgentRequest,
DefinitionV1,
PatchManagedAgentRequest,
agent_status_from,
stored_definition,
wire_time_or_none,
workspaces_dir_of,
)
from switch_core.management.service import ManagementService
from switch_core.process_lease import ProcessLeases
NOTHING_CREATED = "Nothing was created"
NOTHING_CHANGED = "Nothing was changed"
CREATED_HINT = (
"The agent is created and its machine has been told. Check it with "
"list_managed_agents straight away; while its `actual` is still null, "
"pending or starting, check again every 2 seconds, for at most a minute."
)
def _validation_message(exc: ValidationError) -> str:
parts = []
for error in exc.errors():
location = ".".join(str(part) for part in error.get("loc", ()))
parts.append(f"{location}: {error.get('msg', 'invalid')}")
return "; ".join(parts) or "invalid request"
def _placement_sentence(
code: str, machine: str, provider: str, problem: str | None
) -> str | None:
"""Why the machine cannot take the agent, in a person's terms, for the
placement reason codes; None for any other code. `problem` is what the
machine said about the provider's login: a CLI that is signed in in a way
its agents cannot use is not fixed by logging in, and that says so."""
if code == reason_codes.PROVIDER_LOGIN_MISSING and problem:
return (
f"{provider} cannot be used on machine '{machine}'; your owner "
f"needs to fix this there: {problem}"
)
sentences = {
reason_codes.CONTROLLER_REVOKED: (
f"machine '{machine}' has been removed from Switch; pick another machine"
),
reason_codes.CONTROLLER_OFFLINE: (
f"machine '{machine}' is not connected to Switch or has not reported "
"recently (it may be asleep, off or disconnected); your owner needs "
"to bring it back online, or pick another machine"
),
reason_codes.PROVIDER_NOT_INSTALLED: (
f"{provider} is not installed on machine '{machine}'; your owner "
"needs to install it there, or pick another machine"
),
reason_codes.PROVIDER_LOGIN_MISSING: (
f"{provider} is not logged in on machine '{machine}'; your owner "
"needs to log in to it there"
),
reason_codes.PROVIDER_LOGIN_EXPIRED: (
f"the {provider} login on machine '{machine}' has expired; your "
"owner needs to log in to it again there"
),
}
return sentences.get(code)
def _machine_line(controller: AgentController, state: str) -> str:
described = f", {controller.description}" if controller.description else ""
return f"{controller.id} ({state}{described})"
def _agents_running(controller: AgentController) -> int | None:
if controller.status is None:
return None
agents = controller.status.get("agents")
return sum(
1
for entry in (agents if isinstance(agents, list) else [])
if isinstance(entry, dict) and entry.get("process") == "running"
)
def _provider_entries(controller: AgentController | None) -> list[dict[str, Any]]:
if controller is None or controller.status is None:
return []
providers = controller.status.get("providers")
return [
entry
for entry in (providers if isinstance(providers, list) else [])
if isinstance(entry, dict)
]
def _login_problem(entry: dict[str, Any]) -> str | None:
"""What the machine said about the provider's login, if anything."""
problem = entry.get("auth_problem")
return problem if isinstance(problem, str) and problem else None
def _provider_problem(controller: AgentController | None, provider: str) -> str | None:
return next(
(
_login_problem(entry)
for entry in _provider_entries(controller)
if entry.get("provider") == provider
),
None,
)
def _providers(controller: AgentController) -> list[dict[str, Any]]:
return [
{
"provider": entry.get("provider"),
"installed": entry.get("installed") is True,
"version": entry.get("version"),
"auth": provider_auth(entry),
# A login that works has nothing wrong with it, whatever else
# the machine said along the way.
"problem": (
_login_problem(entry) if provider_auth(entry) != "ok" else None
),
}
for entry in _provider_entries(controller)
]
class ManagementAgentOperations:
"""`AgentManagementPort`, served by the management service."""
def __init__(
self,
*,
service: ManagementService,
session_factory: async_sessionmaker[AsyncSession],
) -> None:
self._service = service
self._session_factory = session_factory
async def list_machines(
self, tenant_id: str, owner_id: str
) -> list[dict[str, Any]]:
async with tenant_session(self._session_factory, tenant_id) as session:
controllers = await self._service.controllers.list_for_owner(
session, tenant_id, owner_id
)
leases = await self._service.leases(session)
machines = []
for controller in controllers:
state = self._service.state_of(controller, leases)
if state == "revoked":
continue
machines.append(
{
"id": controller.id,
"name": controller.name,
"description": controller.description,
"kind": controller.kind,
"state": state,
"last_seen_at": wire_time_or_none(controller.last_seen_at),
"providers": _providers(controller),
"agents_running": _agents_running(controller),
}
)
return machines
def advanced_config_fields(self, provider: str) -> list[dict[str, Any]]:
try:
return provider_fields(provider)
except ValueError as exc:
raise AgentManagementRefused(
reason_codes.VALIDATION_ERROR, str(exc)
) from exc
async def _resolve_machine(
self,
session: AsyncSession,
tenant_id: str,
owner_id: str,
machine: str,
nothing_done: str,
) -> AgentController:
"""The owner's machine with this id, or else the one not revoked with
this exact name. `nothing_done` opens a refusal ("Nothing was
created")."""
controllers = await self._service.controllers.list_for_owner(
session, tenant_id, owner_id
)
by_id = next((c for c in controllers if c.id == machine), None)
if by_id is not None:
return by_id
named = [c for c in controllers if c.name == machine and not is_revoked(c)]
if len(named) == 1:
return named[0]
if not named:
raise AgentManagementRefused(
reason_codes.NOT_FOUND,
f"{nothing_done}: your owner has no machine with the id or "
f"name '{machine}'. list_machines shows the machines you can use.",
)
leases = await self._service.leases(session)
candidates = "; ".join(
_machine_line(c, self._service.state_of(c, leases)) for c in named
)
raise AgentManagementRefused(
reason_codes.VALIDATION_ERROR,
f"{nothing_done}: your owner has {len(named)} machines named "
f"'{machine}': {candidates}. Pass the id of the one you mean as "
"`machine`.",
)
@staticmethod
def _create_request(
spec: NewManagedAgent, controller: AgentController
) -> CreateManagedAgentRequest:
try:
return CreateManagedAgentRequest(
name=spec.name,
description=spec.description,
display_name=spec.display_name,
icon_url=spec.icon_url,
controller_id=controller.id,
desired_state="running" if spec.start else "stopped",
definition=DefinitionV1(
provider=spec.provider, # type: ignore[arg-type]
model=spec.model,
advanced_config=spec.advanced_config,
instructions=spec.instructions,
auto_mode=spec.auto_mode,
auto_approve=spec.auto_approve,
directory=spec.directory,
isolation=spec.isolation, # type: ignore[arg-type]
),
)
except ValidationError as exc:
raise AgentManagementRefused(
reason_codes.VALIDATION_ERROR,
f"{NOTHING_CREATED}: {_validation_message(exc)}.",
) from exc
@staticmethod
def _refusal(
exc: ManagementError, controller: AgentController, provider: str
) -> AgentManagementRefused:
sentence = _placement_sentence(
exc.code, controller.name, provider, _provider_problem(controller, provider)
)
return AgentManagementRefused(
exc.code,
f"{NOTHING_CREATED}: {sentence or exc.message} ({exc.code}).",
)
async def check_new_agent(
self, tenant_id: str, owner_id: str, spec: NewManagedAgent
) -> CheckedPlacement:
async with tenant_session(self._session_factory, tenant_id) as session:
controller = await self._resolve_machine(
session, tenant_id, owner_id, spec.machine, NOTHING_CREATED
)
request = self._create_request(spec, controller)
try:
await self._service.check_new_managed_agent(
session, tenant_id, owner_id, request
)
except ManagementError as exc:
raise self._refusal(exc, controller, spec.provider) from exc
await session.commit()
return CheckedPlacement(
machine_id=controller.id,
machine_name=controller.name,
workspaces_dir=workspaces_dir_of(controller),
)
async def create_agent(
self,
tenant_id: str,
owner_id: str,
spec: NewManagedAgent,
protocol: AgentCore,
) -> dict[str, Any]:
async with tenant_session(self._session_factory, tenant_id) as session:
controller = await self._resolve_machine(
session, tenant_id, owner_id, spec.machine, NOTHING_CREATED
)
request = self._create_request(spec, controller)
try:
view = await self._service.create_managed_agent(
session, tenant_id, owner_id, request, protocol
)
except ManagementError as exc:
raise self._refusal(exc, controller, spec.provider) from exc
return {
"agent_id": view["agent_id"],
"name": view["name"],
"machine": {"id": controller.id, "name": controller.name},
"desired_state": view["desired_state"],
"hint": CREATED_HINT,
}
def _managed_entry(
self,
row: AgentDefinitionRow,
agent: Agent,
controller: AgentController | None,
leases: ProcessLeases,
) -> dict[str, Any]:
status = agent_status_from(controller, agent.id)
return {
"agent_id": agent.id,
"name": agent.name,
"display_name": agent.display_name,
"description": agent.description,
"provider": row.definition.get("provider"),
"model": row.definition.get("model"),
"advanced_config": row.definition.get("advanced_config", {}),
"auto_mode": row.definition.get("auto_mode", False),
"auto_approve": row.definition.get("auto_approve", False),
"directory": row.definition.get("directory"),
"machine": None
if controller is None
else {
"id": controller.id,
"name": controller.name,
"state": self._service.state_of(controller, leases),
},
"desired_state": row.desired_state,
"actual": None
if status is None
else {
"process": status.get("process"),
"reason": status.get("reason"),
"detail": status.get("detail"),
"applied_revision": status.get("applied_revision"),
"since": status.get("since"),
"directory": status.get("directory"),
},
"revision": row.revision,
}
async def list_managed_agents(
self, tenant_id: str, owner_id: str
) -> list[dict[str, Any]]:
async with tenant_session(self._session_factory, tenant_id) as session:
controllers = {
c.id: c
for c in await self._service.controllers.list_for_owner(
session, tenant_id, owner_id
)
}
rows = await self._service.definitions.list_for_owner(
session, tenant_id, owner_id
)
leases = await self._service.leases(session)
return [
self._managed_entry(
row,
agent,
controllers.get(row.controller_id) if row.controller_id else None,
leases,
)
for row, agent in rows
]
async def managed_agent(
self, tenant_id: str, owner_id: str, agent_id: str
) -> dict[str, Any] | None:
async with tenant_session(self._session_factory, tenant_id) as session:
return await self._owned_entry(session, tenant_id, owner_id, agent_id)
async def _owned_entry(
self, session: AsyncSession, tenant_id: str, owner_id: str, agent_id: str
) -> dict[str, Any] | None:
agent = await self._service.agents.get(session, agent_id)
if agent is None or agent.owner_id != owner_id:
return None
row = await self._service.definitions.get_for_agent(
session, tenant_id, agent_id
)
if row is None:
return None
controller = (
await self._service.controllers.get(session, tenant_id, row.controller_id)
if row.controller_id is not None
else None
)
return self._managed_entry(
row, agent, controller, await self._service.leases(session)
)
async def update_managed_agent(
self,
tenant_id: str,
owner_id: str,
agent_id: str,
changes: ManagedAgentChanges,
protocol: AgentCore,
) -> dict[str, Any]:
async with tenant_session(self._session_factory, tenant_id) as session:
agent = await self._service.agents.get(session, agent_id)
row = await self._service.definitions.get_for_agent(
session, tenant_id, agent_id
)
if agent is None or agent.owner_id != owner_id or row is None:
raise AgentManagementRefused(
reason_codes.NOT_FOUND,
f"{NOTHING_CHANGED}: agent {agent_id} is not one of your "
"owner's managed agents, so it has no provider, model, "
"machine or run state Switch can set. Only its name-level "
"settings (description, display name, icon, addressing) "
"can be changed here.",
)
controller: AgentController | None = None
if changes.machine is not None:
controller = await self._resolve_machine(
session, tenant_id, owner_id, changes.machine, NOTHING_CHANGED
)
elif row.controller_id is not None:
controller = await self._service.controllers.get(
session, tenant_id, row.controller_id
)
definition_changes = changes.definition_changes()
body: dict[str, Any] = {}
if definition_changes:
body["definition"] = {
**stored_definition(row.definition),
**definition_changes,
}
if changes.desired_state is not None:
body["desired_state"] = changes.desired_state
if changes.machine is not None:
assert controller is not None
body["controller_id"] = controller.id
try:
request = PatchManagedAgentRequest.model_validate(body)
except ValidationError as exc:
raise AgentManagementRefused(
reason_codes.VALIDATION_ERROR,
f"{NOTHING_CHANGED}: {_validation_message(exc)}.",
) from exc
provider = (
request.definition.provider
if request.definition is not None
else str(row.definition.get("provider"))
)
try:
await self._service.patch_managed_agent(
session,
tenant_id,
owner_id,
agent_id,
definition=request.definition,
desired_state=request.desired_state,
controller_id=request.controller_id,
controller_id_given="controller_id" in request.model_fields_set,
protocol=protocol,
expected_revision=None,
)
except ManagementError as exc:
machine = controller.name if controller is not None else "(none)"
sentence = _placement_sentence(
exc.code, machine, provider, _provider_problem(controller, provider)
)
raise AgentManagementRefused(
exc.code,
f"{NOTHING_CHANGED}: {sentence or exc.message} ({exc.code}).",
) from exc
entry = await self._owned_entry(session, tenant_id, owner_id, agent_id)
if entry is None:
raise RuntimeError(f"managed agent {agent_id} vanished while updating it")
return entry