Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions docs/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,20 @@ they were written before the project cut tagged releases.
same Swagger and ReDoc assets, only the icon differs.

### Fixed
- **A team answered every follow-up turn with its first answer.** The supervisor checkpoints its
per-turn fields (`route`, `specialist_results`, `attempts`, `resolved`, `pending_write`,
`approved`) with the thread, and nothing cleared them, so on turn two dispatch saw a result for
every routed member, ran none, and the turn returned the previous answer again. `classify` now
resets them at the start of each turn.
- **A spec with `tools:` and no `template:` ran without its tools, silently.** The default graph
only calls the model, so the README's `calc.yaml` bound nothing and the model guessed at the
arithmetic. A spec that declares tools or MCP servers without a template now builds `single`.
- **A team's `params` reached its specialists but not its classifier or inline members.** A team
pointed at a local server (`api_base`) or told `reasoning_effort: none` routed and answered with
provider defaults. Classify now uses the team's engine-wired model, and inline members inherit
the team's params.
- **`reasoning_effort: none` was rejected.** It is the value that turns thinking off on GPT-5.1
and on OpenAI-compatible servers hosting Qwen3-style hybrid models.
- **The README contradicted itself about voice, and named a two-release-old version as current.**
One paragraph listed voice under "not built yet" while another listed it as shipped; voice has
been released since `0.0.3`. The Status section told readers to pin `agentship-sdk==0.0.2` as
Expand Down
6 changes: 5 additions & 1 deletion packages/agentship-core/src/agentship/spec.py
Original file line number Diff line number Diff line change
Expand Up @@ -216,7 +216,11 @@ class ModelParams(BaseModel):
#:
#: Typed rather than a free string so ``reasoning_effort: hgih`` fails when the spec
#: loads, not as a provider 400 in the middle of someone's turn.
reasoning_effort: Literal["minimal", "low", "medium", "high"] | None = None
#:
#: ``none`` asks a reasoning model not to think at all (OpenAI GPT-5.1, and the
#: OpenAI-compatible servers that host Qwen3-style hybrid models), which is distinct from
#: leaving the field unset and getting the provider's default.
reasoning_effort: Literal["none", "minimal", "low", "medium", "high"] | None = None


class ObservabilitySpec(BaseModel):
Expand Down
4 changes: 2 additions & 2 deletions packages/agentship-core/tests/test_reasoning.py
Original file line number Diff line number Diff line change
Expand Up @@ -28,9 +28,9 @@ def test_an_agent_can_ask_for_more_or_less_thinking():
assert ModelParams().reasoning_effort is None, "absent must keep the provider's default"


@pytest.mark.parametrize("effort", ["minimal", "low", "medium", "high"])
@pytest.mark.parametrize("effort", ["none", "minimal", "low", "medium", "high"])
def test_every_supported_effort_is_accepted(effort: str):
"""The four levels LiteLLM maps onto each provider's own scale."""
"""The levels LiteLLM maps to each provider's scale, plus ``none`` to turn thinking off."""
assert ModelParams(reasoning_effort=effort).reasoning_effort == effort


Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@
from . import models
from .agent import LangGraphAgent
from .durability import open_checkpointer, open_turn_state
from .templates import resolve_template
from .templates import build_single, resolve_template
from .templates.graph_supervisor import INTERNAL_NODES as SUPERVISOR_INTERNAL_NODES
from .tools import ToolCallLogger
from .tracing import ObservabilityCallback
Expand Down Expand Up @@ -337,6 +337,13 @@ def build(self, spec: AgentSpec, authored: object = None) -> _CompiledAgent:
prompt_owned_by_graph = True
else:
template_body = resolve_template(spec)
if template_body is None and tools:
# The default graph only calls the model; it has no node that executes a tool. A
# spec that declares tools (or MCP servers) but no template means "an agent with
# these tools", which is the `single` template. Falling through instead bound
# nothing, and the model answered from its own knowledge with no error.
_engine_logger.debug("tools declared without a template: using template=single")
template_body = build_single(spec)
if template_body is not None:
_engine_logger.debug(
"build path=template template=%s model=%s tools=%d",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -76,6 +76,21 @@ class SupervisorState(TypedDict, total=False):
approved: bool | None


#: The per-turn working fields, cleared by ``classify`` (the first node of every turn). A thread's
#: state is checkpointed, so without this a follow-up turn inherits the previous turn's
#: ``specialist_results``: ``dispatch`` reads them as a retry pass with nothing left to retry, runs
#: no specialist, and ``resolve`` returns the previous turn's answer again. ``messages`` is the
#: only field meant to carry across turns.
_FRESH_TURN: dict[str, Any] = {
"route": None,
"specialist_results": [],
"attempts": {},
"resolved": None,
"pending_write": None,
"approved": None,
}


def _user_text(state: SupervisorState) -> str:
"""The user's request for this turn — the content of the latest inbound message."""
return state["messages"][-1].content
Expand Down Expand Up @@ -115,7 +130,7 @@ async def classify(state: SupervisorState) -> dict:
label = (reply.content or "").strip().lower()
intent = label if label in cfg.classify.intents else None
logger.info("classify: %r -> intent=%s", _preview(_user_text(state)), intent)
return {"intent": intent}
return {"intent": intent, **_FRESH_TURN}

return classify

Expand Down Expand Up @@ -277,13 +292,15 @@ def build_supervisor_graph(
return g


def _member_agent(member: Any, default_model: str | None) -> Any:
def _member_agent(member: Any, team: AgentSpec) -> Any:
"""Resolve one :class:`~agentship.spec.MemberSpec` into a built sub-agent.

A member declared by ``ref`` loads its own agent YAML (already resolved to an absolute path by
:func:`~agentship.spec.load_spec`); an inline member becomes a plain ``template: single`` agent
over its ``prompt`` (or a sensible default) and its ``model`` (falling back to the team model).
Either way the result is a full, independently-runnable agent the supervisor dispatches to.
An inline member inherits the team's ``params`` (``api_base``, ``reasoning_effort``, …), since
it has no way to declare its own; a ``ref`` member brings its own.
"""
from agentship.runtime import build_agent
from agentship.spec import AgentSpec
Expand All @@ -296,8 +313,9 @@ def _member_agent(member: Any, default_model: str | None) -> Any:
name=member.name,
engine="langgraph",
template="single",
model=member.model or default_model,
model=member.model or team.model,
prompt=prompt,
params=team.params,
)
)

Expand All @@ -317,7 +335,10 @@ def derive_graph_config(spec: AgentSpec) -> GraphConfig:
routing["_default"] = RouteEntry(specialists=[names[0]], strategy="single")
hints = {m.name: m.description for m in members if m.description}
return GraphConfig(
classify=ClassifyConfig(model=spec.model or "", intents=names, hints=hints),
# No model of its own: classify falls back to the team's engine-wired model, which carries
# the team's params. Naming spec.model here re-resolved it without them, so a team pointed
# at a local server (api_base) or told not to think (reasoning_effort) classified elsewhere.
classify=ClassifyConfig(model="", intents=names, hints=hints),
routing=routing,
conflict_resolver=ConflictPolicy(priority=names),
)
Expand All @@ -333,7 +354,7 @@ def build_declarative_supervisor(
attaching any checkpointer) and the coordinated member names (surfaced on the built artifact so
the ``multi_agent`` capability is inspectable).
"""
specialists = {m.name: _member_agent(m, spec.model) for m in (spec.members or [])}
specialists = {m.name: _member_agent(m, spec) for m in (spec.members or [])}
config = derive_graph_config(spec)
graph = build_supervisor_graph(model, config, specialists)
return graph, list(specialists)
Expand Down
11 changes: 10 additions & 1 deletion packages/agentship-langgraph/src/agentship_langgraph/testing.py
Original file line number Diff line number Diff line change
Expand Up @@ -36,13 +36,22 @@ def _langgraph_offline() -> Iterator[None]:
Replaces :func:`agentship_langgraph.models.resolve_model` with a factory that
returns a token-streaming ``FakeListChatModel``, so the engine compiles and
drives its graph with zero network calls. Restored on exit.

The fake accepts ``bind_tools`` (and ignores the tools): a spec that declares tools
builds a graph that binds them, and the stock fake raises ``NotImplementedError``
there, which would fail the ``tool_calling`` cell for the harness rather than the engine.
"""
from langchain_core.language_models.fake_chat_models import FakeListChatModel

import agentship_langgraph.models as models_module

class _ToolAcceptingFake(FakeListChatModel):
def bind_tools(self, tools, **kwargs):
"""Accept the bound tools and return itself: the scripted reply calls none."""
return self

original = models_module.resolve_model
fake = FakeListChatModel(responses=["conformance ok, streamed in pieces."])
fake = _ToolAcceptingFake(responses=["conformance ok, streamed in pieces."])
models_module.resolve_model = lambda *args, **kwargs: fake # type: ignore[assignment]
try:
yield
Expand Down
58 changes: 58 additions & 0 deletions packages/agentship-langgraph/tests/test_declarative_supervisor.py
Original file line number Diff line number Diff line change
Expand Up @@ -59,3 +59,61 @@ async def test_declarative_supervisor_exposes_members(tmp_path, monkeypatch):
agent = build_agent(_team(tmp_path))
assert agent.compiled.members # non-empty coordinated team
assert set(agent.compiled.members) == {"billing", "faq"}


async def test_each_turn_in_a_thread_is_routed_afresh(tmp_path, monkeypatch):
"""A follow-up turn in the same thread is classified, dispatched and answered on its own.

The supervisor's per-turn fields are checkpointed with the thread. Before they were reset at
the start of a turn, turn two inherited turn one's ``specialist_results``: dispatch saw a retry
pass with nothing to retry, ran no member, and the team returned turn one's answer again.
"""
monkeypatch.setattr(
models_module,
"resolve_model",
lambda *a, **k: FakeListChatModel(responses=["billing", "faq"]),
)
agent = build_agent(_team(tmp_path))

first = await agent.run("I was double charged", user_id="alice", session_id="thread-1")
second = await agent.run("How do I reset my password?", user_id="alice", session_id="thread-1")

assert "echo: I was double charged" in first.output
assert "echo: How do I reset my password?" in second.output


async def test_team_params_reach_the_classifier_and_inline_members(tmp_path, monkeypatch):
"""A team's ``params`` apply to every model it builds: the classifier and inline members too.

The classifier used to re-resolve the team's model id without its params, and inline members
were built without them. A team pointed at a local server with ``api_base``, or told
``reasoning_effort: none``, then classified and answered with the provider defaults.
"""
calls = []

def fake_resolve(model, **params):
calls.append(params)
return FakeListChatModel(responses=["writer", "Hello there."])

monkeypatch.setattr(models_module, "resolve_model", fake_resolve)
team = tmp_path / "team.yaml"
team.write_text(
textwrap.dedent(
"""
name: team
engine: langgraph
model: x
params:
api_base: http://localhost:9999/v1
members:
- name: writer
description: greetings and small talk
prompt: Answer in one sentence.
"""
)
)
agent = build_agent(str(team))
await agent.run("Hi!", user_id="alice")

assert calls, "no model was resolved"
assert all(c.get("api_base") == "http://localhost:9999/v1" for c in calls), calls
25 changes: 25 additions & 0 deletions packages/agentship-langgraph/tests/test_tool_execution.py
Original file line number Diff line number Diff line change
Expand Up @@ -300,3 +300,28 @@ async def test_a_raising_tool_reports_the_failure_when_invoked_directly():
lc = to_langchain_tool(boom)
out = await lc.ainvoke({"label": "x"})
assert "boom" in str(out) and "upstream service refused" in str(out)


async def test_tools_without_a_template_still_run(monkeypatch):
"""``tools:`` with no ``template:`` builds an agent that calls them, as the quickstart promises.

The README's ``calc.yaml`` declares ``tools: [calculator]`` and no template. That used to take
the engine's default graph, which only calls the model: nothing was bound, the model answered
from its own arithmetic, and no error said the tool was ignored.
"""
asks = AIMessage(
content="",
tool_calls=[{"name": "calculator", "args": {"expression": "17 * 23"}, "id": "c1"}],
)
model = ScriptedModel(script=[asks, AIMessage(content="391")])
monkeypatch.setattr(models_module, "resolve_model", lambda *a, **k: model)

spec = AgentSpec(name="calc", engine="langgraph", model="x", tools=["calculator"])
engine = LangGraphEngine()
result = await engine.run(
engine.build(spec), "What is 17 times 23?", _ctx("no-template-thread")
)

assert result.output == "391"
tool_messages = [m for m in model.seen[1] if m.type == "tool"]
assert tool_messages and '"result": 391' in str(tool_messages[-1].content)
Loading