"""Teams and playbooks — the AgentTown collaboration capability set on the hub.""" from __future__ import annotations from tests.conftest import BASE, mock_agent, sse_payloads, wait_for def make_team(client, name: str, members: list[dict], **fields) -> dict: response = client.post(f"{BASE}/teams", json={"name": name, "members": members, **fields}) assert response.status_code == 201, response.text return response.json() def start_run(client, ref: str, objective: str, **fields) -> dict: response = client.post(f"{BASE}/teams/{ref}/runs", json={"objective": objective, **fields}) assert response.status_code == 201, response.text return response.json() def test_roster_labels_members(hub): scout = mock_agent(hub, "scout", reply="facts") writer = mock_agent(hub, "writer", reply="article") team = make_team( hub, "News Desk", [{"agent_id": scout["id"], "role": "researcher"}, {"agent_id": writer["name"], "role": "writer"}], description="two-agent newsroom", ) assert team["name"] == "news-desk" # names are slugged, so refs are URL-safe assert [member["agent_name"] for member in team["members"]] == ["scout", "writer"] assert team["member_count"] == 2 assert hub.get(f"{BASE}/teams/news-desk").json()["id"] == team["id"] def test_sequential_run_flows_output_to_the_next_agent(hub): mock_agent(hub, "scout", reply="facts") mock_agent(hub, "writer", reply="article") make_team( hub, "desk", [{"agent_id": "scout", "role": "researcher"}, {"agent_id": "writer", "role": "writer"}], playbook="sequential", ) run = start_run(hub, "desk", "cover the release", wait=True) assert run["status"] == "completed" assert [step["agent_name"] for step in run["steps"]] == ["scout", "writer"] assert run["output"] == "article" assert all(step["task_id"] for step in run["steps"]) detail = hub.get(f"{BASE}/runs/{run['id']}").json() assert "facts" in detail["steps"][1]["input"] keys = [entry["key"] for entry in detail["blackboard"]] assert "step:1:output" in keys and "step:2:input" in keys # the collaboration briefing taught the agent how to reach the shared board assert "/api/v1/collab/blackboard" in detail["steps"][1]["input"] def test_parallel_run_gathers_every_member(hub): mock_agent(hub, "alpha", reply="A-answer") mock_agent(hub, "beta", reply="B-answer") make_team(hub, "fan", [{"agent_id": "alpha"}, {"agent_id": "beta"}], playbook="parallel") run = start_run(hub, "fan", "answer this", wait=True) assert run["status"] == "completed" assert len(run["steps"]) == 2 assert "A-answer" in run["output"] and "B-answer" in run["output"] def test_parallel_run_can_synthesize(hub): mock_agent(hub, "alpha", reply="A") mock_agent(hub, "editor", reply="merged", config={}) make_team( hub, "merge", [{"agent_id": "alpha", "role": "member"}, {"agent_id": "editor", "role": "synthesizer"}], playbook="parallel", ) run = start_run(hub, "merge", "answer", spec={"synthesize": True}, wait=True) assert [step["agent_name"] for step in run["steps"]][-1] == "editor" assert "Merge the teammate outputs" in hub.get(f"{BASE}/runs/{run['id']}").json()["steps"][-1]["input"] def test_round_robin_runs_the_requested_rounds(hub): mock_agent(hub, "one", reply="r1") make_team(hub, "loop", [{"agent_id": "one"}], playbook="round_robin") run = start_run(hub, "loop", "converge", spec={"rounds": 3}, wait=True) assert [step["round"] for step in run["steps"]] == [1, 2, 3] def test_handoff_playbook_follows_agent_directives(hub): mock_agent( hub, "scout", reply="found the logs\n\n```agenthub\n" '{"action":"handoff","to":"writer","instruction":"write the postmortem"}\n```', ) mock_agent(hub, "writer", reply="postmortem written") make_team(hub, "relay", [{"agent_id": "scout"}, {"agent_id": "writer"}], playbook="handoff") run = start_run(hub, "relay", "explain the outage", wait=True) assert [step["agent_name"] for step in run["steps"]] == ["scout", "writer"] assert run["output"] == "postmortem written" detail = hub.get(f"{BASE}/runs/{run['id']}").json() handoffs = [message for message in detail["messages"] if message["kind"] == "handoff"] assert handoffs and "postmortem" in handoffs[0]["body"] assert "write the postmortem" in detail["steps"][1]["input"] def test_handoff_to_yourself_ends_the_run(hub): """Naming your own author as the next hop must not burn the remaining hops.""" mock_agent( hub, "solo", reply="still mine\n\n\n```agenthub\n" '{"action":"handoff","to":"solo","instruction":"more of the same"}' "\n```", ) mock_agent(hub, "other", reply="unused") make_team(hub, "loopback", [{"agent_id": "solo"}, {"agent_id": "other"}], playbook="handoff", spec={"max_hops": 4}) run = start_run(hub, "loopback", "go", wait=True) assert run["status"] == "completed", run assert [step["agent_name"] for step in run["steps"]] == ["solo"] def test_run_fails_loudly_when_a_member_fails(hub): mock_agent(hub, "solid", reply="fine") mock_agent(hub, "broken", fail=True) make_team(hub, "fragile", [{"agent_id": "solid"}, {"agent_id": "broken"}]) run = start_run(hub, "fragile", "go", wait=True) assert run["status"] == "failed" assert "broken" in run["error"] steps = hub.get(f"{BASE}/runs/{run['id']}").json()["steps"] assert [step["status"] for step in steps] == ["completed", "failed"] def test_runs_are_listable_and_cancel_is_idempotent(hub): mock_agent(hub, "solo", reply="done") make_team(hub, "solo-team", [{"agent_id": "solo"}]) run = start_run(hub, "solo-team", "go", wait=True) assert [item["id"] for item in hub.get(f"{BASE}/runs?team_id=solo-team").json()] == [run["id"]] assert [item["id"] for item in hub.get(f"{BASE}/teams/solo-team/runs").json()] == [run["id"]] assert len(hub.get(f"{BASE}/runs/{run['id']}/tasks").json()) == 1 assert hub.post(f"{BASE}/runs/{run['id']}/cancel").status_code == 409 assert hub.post(f"{BASE}/runs/run_missing/cancel").status_code == 404 def test_finished_run_stream_replays_then_stops(hub): mock_agent(hub, "solo", reply="done") make_team(hub, "solo-team", [{"agent_id": "solo"}]) run = start_run(hub, "solo-team", "go", wait=True) frames = sse_payloads(hub.get(f"{BASE}/runs/{run['id']}/stream").text) kinds = [frame["kind"] for frame in frames] assert kinds.count("step") == 1 and kinds[-1] == "eof" assert frames[-1]["payload"]["status"] == "completed" def test_unwaited_run_completes_in_the_background(hub): mock_agent(hub, "slowpoke", reply="eventually", delay_s=0.02) make_team(hub, "async-team", [{"agent_id": "slowpoke"}]) run = start_run(hub, "async-team", "go") assert run["status"] == "queued" assert wait_for(lambda: hub.get(f"{BASE}/runs/{run['id']}").json()["status"] == "completed") def test_team_validation(hub): mock_agent(hub, "solo") assert hub.post(f"{BASE}/teams", json={"name": "t1", "members": [{"agent_id": "ghost"}]}).status_code == 404 assert hub.post(f"{BASE}/teams", json={"name": "t2", "members": [], "playbook": "ping-pong"}).status_code == 400 make_team(hub, "dupe", [{"agent_id": "solo"}]) assert hub.post(f"{BASE}/teams", json={"name": "dupe", "members": []}).status_code == 409 empty = make_team(hub, "empty", []) assert hub.post(f"{BASE}/teams/empty/runs", json={"objective": "go"}).status_code == 400 assert hub.get(f"{BASE}/teams/nope").status_code == 404 def test_team_roster_and_playbook_can_be_updated(hub): mock_agent(hub, "one") mock_agent(hub, "two") team = make_team(hub, "evolving", [{"agent_id": "one"}]) updated = hub.patch( f"{BASE}/teams/evolving", json={"playbook": "parallel", "spec": {"rounds": 2}, "members": [{"agent_id": "one"}, {"agent_id": "two"}]}, ).json() assert updated["playbook"] == "parallel" and updated["member_count"] == 2 assert updated["spec"]["rounds"] == 2 assert hub.delete(f"{BASE}/teams/evolving").json()["ok"] is True assert hub.get(f"{BASE}/teams/evolving").status_code == 404 # the seed/demo data is not required for the console to render assert {item["name"] for item in hub.get(f"{BASE}/playbooks").json()} == { "sequential", "parallel", "round_robin", "handoff", } def test_cancelling_a_run_stops_the_step_in_flight(hub): """Cancel is not decorative: the running step and the rest of the plan stop.""" mock_agent(hub, "slowpoke", reply="detail " * 200, delay_s=0.05) mock_agent(hub, "after", reply="never runs") make_team(hub, "relay", [{"agent_id": "slowpoke"}, {"agent_id": "after"}]) run = start_run(hub, "relay", "ship it") detail = lambda: hub.get(f"{BASE}/runs/{run['id']}").json() # noqa: E731 assert wait_for(lambda: detail()["status"] == "running") # 等到「这一步真的在飞」再取消:run 状态先翻到 running,task_id 随后才写回 step。 # 不等这一下的话,取消可能落在那个窗口里,测的就不是"打断在跑的 step"了。 assert wait_for(lambda: detail()["steps"] and detail()["steps"][0]["task_id"]) assert hub.post(f"{BASE}/runs/{run['id']}/cancel").status_code == 200 assert wait_for(lambda: detail()["status"] == "cancelled") # the in-flight step lands on cancelled too -- no zombie "running" row assert wait_for(lambda: [step["status"] for step in detail()["steps"]] == ["cancelled"]) assert wait_for(lambda: [row["status"] for row in hub.get(f"{BASE}/runs/{run['id']}/tasks").json()] == ["cancelled"]) # ...and the playbook never reaches the next member assert len(detail()["steps"]) == 1 assert hub.get(f"{BASE}/agents/after").json()["last_task_at"] is None