datawhalechina/hello-agents · error · HTTPException

Agent '{agent_id}' not found

Error message

Agent '{agent_id}' not found

What it means

POST /agents/{agent_id}/run returns HTTP 404 when registry.get(agent_id) raises KeyError — i.e. the agent id in the URL path is not a registered agent. The registry only contains agents that were registered at startup (e.g. deep_research, rss_digest), so unknown or misspelled ids fail here.

Source

Thrown at Co-creation-projects/huailishang-AgentPlatformBase/backend/main.py:72

@app.get("/health")
def health() -> dict:
    return {"status": "healthy", "service": settings.app_name}


@app.get("/agents")
def list_agents() -> dict:
    profiles = registry.list_profiles()
    return {"agents": profiles, "total": len(profiles)}


@app.post("/agents/{agent_id}/run", response_model=AgentResponse)
def run_agent(agent_id: str, request: AgentRequest) -> AgentResponse:
    try:
        return registry.get(agent_id).run(request)
    except KeyError:
        raise HTTPException(status_code=404, detail=f"Agent '{agent_id}' not found")


@app.post("/tasks", response_model=TaskRecord)
def create_task(request: TaskCreateRequest) -> TaskRecord:
    if request.agent_id not in set(registry.ids()):
        raise HTTPException(status_code=404, detail=f"Agent '{request.agent_id}' not found")
    return task_manager.create(request)


@app.get("/tasks")
def list_tasks() -> dict:
    tasks = task_manager.list()
    return {"tasks": tasks, "total": len(tasks)}


@app.get("/tasks/{task_id}", response_model=TaskRecord)
def get_task(task_id: str) -> TaskRecord:
    try:

View on GitHub (pinned to 606a07d341)

Solutions

1. GET /agents first and use an exact id from the returned list.
2. If the agent should exist, check service startup logs for a failed registration/import of that agent module.
3. Fix the typo in the path (ids are exact-match).
4. Ensure the agent package is installed and registered in the registry configuration this backend boots with.

Example fix

# before
requests.post(f"{BASE}/agents/deep_reaserch/run", json=payload)  # 404

# after
agents = requests.get(f"{BASE}/agents").json()["agents"]
ids = [a["id"] for a in agents]
assert "deep_research" in ids, f"unknown id; available: {ids}"
requests.post(f"{BASE}/agents/deep_research/run", json=payload)

agents = requests.get(f"{BASE}/agents").json()["agents"]
valid_ids = {a["id"] for a in agents}
if agent_id not in valid_ids:
    raise SystemExit(f"unknown agent {agent_id!r}; available: {sorted(valid_ids)}")
resp = requests.post(f"{BASE}/agents/{agent_id}/run", json=payload)

def agent_exists(agent_id: str, valid_ids: set[str]) -> bool:
    return agent_id in valid_ids

try:
    resp = requests.post(f"{BASE}/agents/{agent_id}/run", json=payload)
except HTTPError as e:
    if e.response.status_code == 404:
        available = {a["id"] for a in requests.get(f"{BASE}/agents").json()["agents"]}
        raise SystemExit(f"{agent_id} not registered; available: {sorted(available)}") from e
    raise

When it happens

Trigger: POSTing to /agents/deep_reaserch/run (typo), an agent whose registration failed at boot, or an id that was never registered in this deployment.

Common situations: Typos in agent ids in client code or curl commands; agent module failed to import/register at startup (check boot logs); calling an environment that registers a different agent subset than the one the client was written against.

Related errors

• No report found for '{incident_id}'. Call POST /incidents/in
• 任务不存在
• 用户不存在
• 未找到相关论文
• diet_run_id 不存在

AI-assisted analysis of datawhalechina/hello-agents@606a07d341 (2026-08-14). Data as JSON: /api/errors/ba3a0b83a3634702. Report an issue: GitHub.