Provedores de contexto

Os provedores de contexto são executados em torno de cada invocação para adicionar contexto antes da execução e processar dados após a execução.

Padrão embutido

O padrão regular é configurar provedores context_providers=[...] ao criar um agente.

ChatHistoryProvider e AIContextProvider são os pontos de extensão internos para histórico de curto prazo e enriquecimento de longo prazo/contexto.

Para Python, InMemoryHistoryProvider é o provedor de histórico interno usado para memória conversacional local.

from agent_framework import InMemoryHistoryProvider
from agent_framework.openai import OpenAIChatClient

agent = OpenAIChatClient().as_agent(
    name="MemoryBot",
    instructions="You are a helpful assistant.",
    context_providers=[InMemoryHistoryProvider("memory", load_messages=True)],
)

session = agent.create_session()
await agent.run("Remember that I prefer vegetarian food.", session=session)

RawAgent pode adicionar InMemoryHistoryProvider("memory") automaticamente em casos específicos, mas adicioná-lo explicitamente quando desejar um comportamento determinístico de memória local.

Provedor de contexto personalizado

Use provedores de contexto personalizados quando precisar injetar instruções/mensagens dinâmicas ou extrair o estado após a execução.

from typing import Any

from agent_framework import AgentSession, BaseContextProvider, SessionContext


class UserPreferenceProvider(BaseContextProvider):
    def __init__(self) -> None:
        super().__init__("user-preferences")

    async def before_run(
        self,
        *,
        agent: Any,
        session: AgentSession,
        context: SessionContext,
        state: dict[str, Any],
    ) -> None:
        if favorite := state.get("favorite_food"):
            context.extend_instructions(self.source_id, f"User's favorite food is {favorite}.")

    async def after_run(
        self,
        *,
        agent: Any,
        session: AgentSession,
        context: SessionContext,
        state: dict[str, Any],
    ) -> None:
        for message in context.input_messages:
            text = (message.text or "") if hasattr(message, "text") else ""
            if isinstance(text, str) and "favorite food is" in text.lower():
                state["favorite_food"] = text.split("favorite food is", 1)[1].strip().rstrip(".")

Provedor de histórico personalizado

Os provedores de histórico são provedores de contexto especializados para carregar/armazenar mensagens.

from collections.abc import Sequence
from typing import Any

from agent_framework import BaseHistoryProvider, Message


class DatabaseHistoryProvider(BaseHistoryProvider):
    def __init__(self, db: Any) -> None:
        super().__init__("db-history", load_messages=True)
        self._db = db

    async def get_messages(
        self,
        session_id: str | None,
        *,
        state: dict[str, Any] | None = None,
        **kwargs: Any,
    ) -> list[Message]:
        key = (state or {}).get(self.source_id, {}).get("history_key", session_id or "default")
        rows = await self._db.load_messages(key)
        return [Message.from_dict(row) for row in rows]

    async def save_messages(
        self,
        session_id: str | None,
        messages: Sequence[Message],
        *,
        state: dict[str, Any] | None = None,
        **kwargs: Any,
    ) -> None:
        if not messages:
            return
        if state is not None:
            key = state.setdefault(self.source_id, {}).setdefault("history_key", session_id or "default")
        else:
            key = session_id or "default"
        await self._db.save_messages(key, [m.to_dict() for m in messages])

Importante

No Python, você pode configurar vários provedores de histórico, mas apenas um deve usar load_messages=True. Use provedores adicionais para diagnósticos/avaliações com load_messages=False e store_context_messages=True para que capturem o contexto de outros provedores junto com a entrada/saída.

Padrão de exemplo:

primary = DatabaseHistoryProvider(db)
audit = InMemoryHistoryProvider("audit", load_messages=False, store_context_messages=True)
agent = OpenAIChatClient().as_agent(context_providers=[primary, audit])

Próximas etapas

Armazenamento