agentscope-ai/agentscope · error · HTTPException

Agent {agent_id!r} not found.

Error message

Agent {agent_id!r} not found.

What it means

Raised inside ChatService._run_impl when access.resolve_agent raises (typically not-found or no access); the original HTTPException is wrapped into a clean 404 'Agent {id} not found'. This deliberately hides whether the agent doesn't exist or is invisible to the caller, to avoid leaking agent existence.

Source

Thrown at src/agentscope/app/_service/_chat.py:686

            # left saying "unknown error".
            try:
                # -------------------------------------------------------------
                # 1. Load records + resolve workspace ONCE here, reused below.
                # Reject missing records up front with a clear error so the
                # downstream assembly code can rely on non-None values.
                #
                # ``resolve_agent`` covers own agents (including team workers,
                # which the owner runs directly) and cross-owner shared agents
                # (viewer runs a shared user-source agent). It raises 404 when
                # the agent is not visible to the caller.
                # -------------------------------------------------------------
                try:
                    agent_record = await self._access.resolve_agent(
                        user_id,
                        agent_id,
                    )
                except HTTPException as exc:
                    raise HTTPException(
                        status_code=404,
                        detail=f"Agent {agent_id!r} not found.",
                    ) from exc
                session_record = await self._storage.get_session(
                    user_id,
                    agent_id,
                    session_id,
                )
                if session_record is None:
                    raise HTTPException(
                        status_code=404,
                        detail=(
                            f"Session {session_id!r} not found for "
                            f"agent {agent_id!r}."
                        ),
                    )
                worker_name = agent_record.data.name

View on GitHub (pinned to e90f1c7592)

Solutions

1. List the agents visible to the current user and use an id from that list
2. If the agent was deleted, recreate it or pick another agent id
3. Verify you are authenticated as a user that can resolve the agent
4. Handle the 404 in the run call and refresh the agent picker in the UI

Example fix

// before
await client.run(agent_id="agent-42", ...);  // 404
// after
agents = await client.list_agents();
match = next((a for a in agents if a.id == "agent-42"), None)
if match is None:
    raise SystemExit("Agent missing or not visible; pick from: " + ", ".join(a.id for a in agents))
await client.run(agent_id=match.id, ...);

agents = await client.list_agents()
if not any(a.id == agent_id for a in agents):
    agent_id = await prompt_agent_selection(agents)
await client.run(agent_id=agent_id, ...)

def agent_visible(agents: list[Agent], agent_id: str) -> bool:
    return any(a.id == agent_id for a in agents)

try:
    await client.run(agent_id=agent_id, ...)
except HTTPStatusError as e:
    if e.response.status_code == 404:
        await refresh_agent_picker()
    raise

When it happens

Trigger: Starting/continuing a chat run with an agent_id that was deleted, never existed, or is not visible to the calling user (resolve_agent denied). Also triggered by stale agent ids in persisted frontend state.

Common situations: Agent deleted between page load and message send; wrong environment's agent id in config; a collaborator runs an agent shared read-only in a context requiring resolution; typos in agent_id parameters.

Related errors

• Session {session_id!r} not found for agent {agent_id!r}.
• The 'reserve_ratio' of the context config must be smaller th
• The 'context_buffer_ratio' of the injection config must be s
• Agent did not produce a final message.
• The system prompt {suffix}exceed(s) the compression threshol

AI-assisted analysis of agentscope-ai/agentscope@e90f1c7592 (2026-08-28). Data as JSON: /api/errors/b93d8e3c3b2513c5. Report an issue: GitHub.