mirror of
https://github.com/hoshikawa2/agent_platform_oci.git
synced 2026-09-07 10:13:46 +00:00
75 lines
2.4 KiB
Markdown
75 lines
2.4 KiB
Markdown
# LLM Rich Response (`ainvoke_response`)
|
|
|
|
## Objetivo
|
|
|
|
O framework mantém `ainvoke()` como API retrocompatível, retornando apenas `str`, e adiciona `ainvoke_response()` para consumidores que precisam de metadados adicionais da inferência, incluindo `reasoning_content` quando o modelo/provider/API o disponibilizar.
|
|
|
|
## APIs
|
|
|
|
### API legada — sem alteração
|
|
|
|
```python
|
|
answer = await llm.ainvoke(messages)
|
|
assert isinstance(answer, str)
|
|
```
|
|
|
|
Nenhum agente existente precisa ser alterado.
|
|
|
|
### Nova API rica — opt-in
|
|
|
|
```python
|
|
response = await llm.ainvoke_response(messages)
|
|
|
|
answer = response.content
|
|
reasoning = response.reasoning_content
|
|
usage = response.usage
|
|
model = response.model
|
|
provider = response.provider
|
|
```
|
|
|
|
`reasoning_content` é `str | None`. `None` é o comportamento esperado quando o modelo, provider ou API não expõe reasoning textual.
|
|
|
|
## Backoffice
|
|
|
|
Um consumidor que antes fazia:
|
|
|
|
```python
|
|
answer = await llm.ainvoke(messages)
|
|
template = extract_response(answer)
|
|
```
|
|
|
|
pode passar a fazer:
|
|
|
|
```python
|
|
response = await llm.ainvoke_response(messages)
|
|
template = extract_response(response.content)
|
|
reasoning_content = response.reasoning_content
|
|
```
|
|
|
|
A lógica que espera texto continua recebendo `response.content`; o reasoning fica separado e não contamina resposta, cache, memória, judges ou guardrails.
|
|
|
|
## Compatibilidade de providers customizados
|
|
|
|
`LLMProvider.ainvoke_response()` possui fallback. Um provider externo que implemente apenas `ainvoke()` continua funcionando e recebe automaticamente um `LLMResponse(content=<texto>)`, com `reasoning_content=None`.
|
|
|
|
Providers nativos (`mock`, OpenAI-compatible/OCI OpenAI e OCI SDK) implementam a resposta rica e tentam preservar reasoning quando presente.
|
|
|
|
## Garantias de compatibilidade
|
|
|
|
- `ainvoke()` continua retornando `str`.
|
|
- Nenhum router, judge, RAG, memória, cache ou runtime existente foi migrado para a nova API.
|
|
- `reasoning_content` nunca é fabricado pelo framework.
|
|
- Ausência de reasoning não gera erro.
|
|
- O output existente de telemetria continua sendo o conteúdo final, sem anexar reasoning automaticamente.
|
|
|
|
## Testes
|
|
|
|
Os testes específicos estão em `tests/unit/test_llm_rich_response.py` e verificam:
|
|
|
|
1. provider legado que só implementa `ainvoke()`;
|
|
2. manutenção do retorno `str` em `ainvoke()`;
|
|
3. retorno de `LLMResponse` em `ainvoke_response()`;
|
|
4. reasoning via atributo direto;
|
|
5. reasoning via `model_extra`;
|
|
6. ausência de reasoning e extração no formato OCI SDK.
|