# Common Pitfalls & FAQs (Agently Dev)

## 1) Stream hangs or no output
- Symptom: terminal appears stuck after input.
- Cause: using sync generators inside an async context, or consuming an execution runtime stream without closing the execution.
- Fix:
  - In async handlers, use `get_async_generator(...)` and `async for`.
  - Start with `await execution.async_start(...)`, consume `execution.get_async_runtime_stream(...)`, and finish with `execution.async_close()`.

## 1.1) Streaming output labels spam
- Symptom: every token prints its own label (e.g., repeated `[thinking]`).
- Cause: printing labels on every delta.
- Fix: print the label once, then append deltas on the same line; add a newline on completion.

## 1.2) Streaming inside async loop throws `asyncio.run` error
- Symptom: `asyncio.run() cannot be called from a running event loop`.
- Cause: using sync `get_result().get_generator(...)` inside an async handler.
- Fix: use `request.get_async_generator(...)` with `async for`.

## 2) TriggerFlow result shape is unexpected
- Symptom: close returns a full state snapshot instead of a single scalar.
- Cause: execution lifecycle now treats close as the reliable completion boundary.
- Fix:
  - Store user-facing output under a stable state key, such as `result` or `final`.
  - Use `set_result(...)` only as a compatibility override when integrating old callers.

## 3) when() branch output is missing
- Symptom: state does not contain the branch output you expected.
- Cause: `when()` branches are event-driven and only update state if a handler writes state.
- Fix: call `data.async_set_state(...)` in event handlers and close the execution after pending tasks drain.

## 4) Concurrency wrapper issues
- Symptom: wrong handler called in batch/for_each.
- Cause: closure binding in loops.
- Fix: bind handler per chunk (factory or default argument).

## 5) Flow data vs runtime data
- Symptom: data leaks across executions.
- Cause: `flow_data` is global.
- Fix: use execution state (`data.get_state`, `data.async_set_state`) for per-execution state.

## 6) Wrong entry point in loop flows
- Symptom: input never arrives or loop blocks.
- Cause: starting with `to(get_input)` and waiting on events that are never emitted.
- Fix: emit a loop event (e.g., `Loop`) at start, then `when("Loop") -> get_input`.

## 6) Instant stream is noisy
- Symptom: each token prints a label.
- Fix: print label once, then stream tokens on the same line; print newline on completion.

## 7) Tools not called or wrong tool
- Symptom: model ignores tools or calls invalid tool.
- Fix:
  - ensure tool names and schemas are clear in `.output()` or `.info()`
  - keep tool list concise

## 8) Knowledge base rebuild every turn
- Symptom: repeated slow initialization.
- Fix: build KB once and reuse (e.g., cached collection in outer scope).

## 9) httpx INFO spam
- Symptom: noisy httpx/httpcore logs.
- Fix: set `runtime.httpx_log_level` to `WARNING` or `ERROR`.

## 10) Settings not applied as expected
- Symptom: model config seems ignored.
- Fix:
  - call `Agently.set_settings(...)` before creating agents
  - check runtime mappings (`debug` toggles multiple flags)
