datawhalechina/hello-agents · error · HTTPException

Agent '{exc.args[0]}' not found

Error message

Agent '{exc.args[0]}' not found

What it means

POST /batch/run returns HTTP 404 when batch_runner.run() raises KeyError: at least one AgentRequest in the request batch referenced an agent_id that is not registered. The detail interpolates exc.args[0], which is the missing agent id from the registry lookup, identifying which entry failed.

Source

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


@app.post("/tasks/{task_id}/run", response_model=TaskRecord)
def run_task(task_id: str, background: bool = True) -> TaskRecord:
    try:
        task_manager.get(task_id)
    except KeyError:
        raise HTTPException(status_code=404, detail=f"Task '{task_id}' not found")
    if background:
        return task_runner.start_background(task_id)
    return task_runner.run(task_id)


@app.post("/batch/run")
def run_batch(request: BatchRunRequest) -> dict:
    try:
        return {"responses": batch_runner.run(request.requests)}
    except KeyError as exc:
        raise HTTPException(status_code=404, detail=f"Agent '{exc.args[0]}' not found")


@app.get("/events")
def list_events(task_id: str | None = None, limit: int = 100) -> dict:
    return {"events": event_logger.list_events(task_id=task_id, limit=limit)}

View on GitHub (pinned to 606a07d341)

Solutions

  1. Read the detail field — it names the exact missing agent id.
  2. Validate every request's agent_id against GET /agents before submitting the batch.
  3. Split the batch so one invalid id cannot fail valid requests, or have the backend return per-item results.

Example fix

# before
resp = requests.post(f"{BASE}/batch/run", json={"requests": batch})  # one bad id -> whole 404

# after
valid = {a["id"] for a in requests.get(f"{BASE}/agents").json()["agents"]}
batch = [r for r in batch if r["agent_id"] in valid]
resp = requests.post(f"{BASE}/batch/run", json={"requests": batch})
Defensive patterns

Strategy: validation

Validate before calling

valid = {a["id"] for a in requests.get(f"{BASE}/agents").json()["agents"]}
bad = [r["agent_id"] for r in batch if r["agent_id"] not in valid]
if bad:
    raise ValueError(f"unknown agent ids in batch: {bad}")
resp = requests.post(f"{BASE}/batch/run", json={"requests": batch})

Type guard

def batch_all_valid(batch: list[dict], valid_ids: set[str]) -> bool:
    return all(r.get("agent_id") in valid_ids for r in batch)

Try / catch

try:
    resp = requests.post(f"{BASE}/batch/run", json={"requests": batch})
    resp.raise_for_status()
except HTTPError as e:
    if e.response.status_code == 404:
        missing = e.response.json()["detail"]  # names the offending id
        batch = [r for r in batch if r["agent_id"] != missing.split("'")[1]]
        resp = requests.post(f"{BASE}/batch/run", json={"requests": batch})
    else:
        raise

Prevention

When it happens

Trigger: Sending {"requests": [...]} where any element's agent_id is unknown to the registry; a single bad id fails the whole batch with 404.

Common situations: Bulk orchestration scripts with one stale/typo'd agent id among many; heterogeneous batches where some agents are not deployed in the target environment.

Related errors

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