agent_contas/agent_framework_oci/docs/LLM_RICH_RESPONSE.md

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

answer = await llm.ainvoke(messages)
assert isinstance(answer, str)

Nenhum agente existente precisa ser alterado.

Nova API rica — opt-in

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:

answer = await llm.ainvoke(messages)
template = extract_response(answer)

pode passar a fazer:

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.