Vector stores no Agent Framework: guia prático em Python

Campos de chave, dados e vetor

Você marca cada atributo com VectorStoreField, indicando se ele é a chave, um campo de dados ou um campo vetorial. Em seguida, o decorador @vectorstoremodel deriva automaticamente a definição da coleção.

from dataclasses import dataclass
from typing import Annotated

from agent_framework import VectorStoreField, vectorstoremodel


@vectorstoremodel(collection_name="documents")
@dataclass
class Document:
    # Chave única do registro
    id: Annotated[str, VectorStoreField("key")]
    # Campo indexado, útil para filtros
    category: Annotated[str, VectorStoreField("data", is_indexed=True)]
    text: Annotated[str, VectorStoreField("data")]
    # Campo vetorial com dimensões e função de distância declaradas
    embedding: Annotated[
        list[float] | str | None,
        VectorStoreField(
            "vector",
            dimensions=1536,
            distance_function="cosine_similarity",
        ),
    ] = None

Repare que o campo embedding aceita list[float] ou str. Quando você entrega um texto, o framework chama o gerador de embeddings e converte esse texto em vetor durante a gravação.

As dimensões ficam declaradas no próprio modelo. Com isso, os vector stores no Agent Framework validam os vetores gerados ou fornecidos antes que eles cheguem ao banco.

Outros formatos de modelo suportados

Dataclasses representam apenas uma das opções disponíveis. A mesma camada de modelo também aceita modelos Pydantic, structs do msgspec, classes simples e dicionários.

Para dicionários, você usa diretamente VectorStoreCollectionDefinition. Já para tipos que pertencem a outro pacote, a função register_vectorstoremodel() recebe uma definição explícita e, opcionalmente, um encoder e um decoder personalizados.

Os modelos Pydantic oferecem validação, embora tragam um custo extra de conversão. Portanto, escolha o formato conforme o equilíbrio entre segurança de tipos e desempenho que o seu cenário exige.

Primeira busca com vector stores no Agent Framework

Antes de executar o código, defina a variável de ambiente OPENAI_API_KEY. O cliente de embeddings da OpenAI gera os vetores tanto na gravação quanto na consulta.

import asyncio

from agent_framework import Filter, InMemoryCollection
from agent_framework.openai import OpenAIEmbeddingClient


async def index_and_search() -> None:
    documents: InMemoryCollection[str, Document] = InMemoryCollection(
        Document,
        embedding_generator=OpenAIEmbeddingClient(model="text-embedding-3-small"),
    )
    await documents.ensure_collection_exists()

    # O texto em "embedding" vira vetor durante o upsert
    await documents.upsert([
        Document(
            id="release-checklist",
            category="operations",
            text="Verify rollback, monitoring, and owner sign-off.",
            embedding="Verify rollback, monitoring, and owner sign-off.",
        )
    ])

    results = await documents.search(
        "What should I check before a release?",
        filter=Filter("category", "eq", "operations"),
        top=3,
    )

    # Os resultados chegam de forma assíncrona
    async for result in results:
        print(result["record"].text, result["score"])


asyncio.run(index_and_search())

Os registros ficam apenas na memória do processo, então eles desaparecem quando a aplicação reinicia. Além disso, essa implementação faz uma varredura linear, o que a torna inadequada para cargas de produção.

O detalhe mais interessante aparece na troca de implementação. De fato, com vector stores no Agent Framework você substitui InMemoryCollection por outra coleção suportada sem alterar o restante do código.

Filtros portáveis com Filter e FilterGroup

Nos vector stores no Agent Framework, os filtros são estruturas de dados comuns, e nenhum código Python roda durante a busca. Por isso, eles funcionam de forma portável entre as diferentes integrações.

Quando você precisa combinar condições, o FilterGroup agrupa vários filtros com operadores lógicos. Nesse caso, também vale fornecer vetores pré-calculados e desligar a geração automática.

from agent_framework import Filter, FilterGroup, InMemoryCollection


async def search_hotels(collection: InMemoryCollection) -> None:
    # Combina cidade, faixa de avaliação e comodidade
    search_filter = FilterGroup(
        "and",
        (
            Filter("city", "eq", "Lisbon"),
            Filter("rating", "between", (4.5, 5.0)),
            Filter("amenities", "contains", "pool"),
        ),
    )

    results = await collection.search(
        vector=[1.0, 0.0],
        filter=search_filter,
        top=5,
    )

    async for result in results:
        print(f"{result['record'].name}: {result['score']:.3f}")

Para gravar registros que já possuem vetores, passe generate_vectors=False no upsert. Assim, o framework não chama o provedor de embeddings e respeita os valores que você entregou.

Parâmetros tipados com Param

O tipo Param simplifica a criação de ferramentas de busca personalizadas. Você coloca um Param dentro de um Filter ou FilterGroup, e o helper o expõe como um argumento tipado que o modelo pode preencher.

from typing import Literal

from agent_framework import Filter, Param, create_vector_search_tool

# O Literal vira um enum no schema da ferramenta
category = Param(
    "category",
    Literal["engineering", "operations", "product"],
    required=False,
    description="Only return documents from this category.",
)

search_documents = create_vector_search_tool(
    documents,
    name="search_documents",
    description="Search the document collection.",
    filter=Filter("category", "eq", category),
    result_mapper=lambda result: result["record"].text,
)

A ferramenta resultante sempre aceita uma consulta em linguagem natural e, opcionalmente, a categoria. Como os valores do Literal viram um enum no schema, o agente recebe um conjunto claro de escolhas válidas.

Se o modelo omitir o parâmetro opcional, o filtro correspondente simplesmente deixa de existir na consulta. Por outro lado, ferramentas mais complexas podem combinar vários parâmetros por meio do FilterGroup, inclusive com limites como avaliação mínima e máxima.

VectorCollectionContextProvider na prática

Quando o agente precisa de mais do que uma busca isolada, o VectorCollectionContextProvider oferece uma experiência de nível mais alto. Ele adiciona ferramentas de upsert, get, delete e search, junto com instruções sobre como usá-las.

Com esse provider, os vector stores no Agent Framework ganham diversas possibilidades de uso. Por exemplo, você pode expor uma base de conhecimento somente leitura, permitir que o agente gerencie registros com aprovação ou substituir a busca padrão por ferramentas especializadas.

from agent_framework import Agent, InMemoryCollection, VectorCollectionContextProvider
from agent_framework.openai import OpenAIChatClient, OpenAIEmbeddingClient


async def run_notes_assistant() -> None:
    collection: InMemoryCollection[str, ProjectNote] = InMemoryCollection(
        ProjectNote,
        embedding_generator=OpenAIEmbeddingClient(model="text-embedding-3-small"),
    )
    await collection.ensure_collection_exists()

    # Upsert sem aprovação; delete continua exigindo aprovação
    collection_context = VectorCollectionContextProvider(
        collection,
        scope_filter=None,
        approval_mode={"upsert": "never_require"},
    )

    async with Agent(
        client=OpenAIChatClient(model="gpt-5.4-nano"),
        name="ProjectNotesAssistant",
        instructions="Use the collection tools to manage project notes. Do not invent stored notes.",
        context_providers=[collection_context],
    ) as agent:
        response = await agent.run("Save a note: the release is planned for Friday.")
        print(response.text)

Por padrão, upsert e delete exigem aprovação, enquanto get e search funcionam sem ela. Esse comportamento seguro evita que o agente altere dados sem supervisão.

O parâmetro scope_filter agrupa registros para as ferramentas geradas. Contudo, a documentação oficial alerta que esse filtro não funciona como fronteira de autorização nem como garantia atômica do banco.

A configuração de embeddings também respeita cada operação. Enquanto a ingestão usa opções voltadas a documentos, a busca usa opções voltadas a consultas, e as ferramentas geradas repassam essas configurações para a mesma coleção.

Histórico de conversa pesquisável

Além de servir como base de conhecimento, os vector stores no Agent Framework também resolvem o crescimento do histórico, que aumenta o contexto a cada turno. Para resolver isso, o VectorStoreHistoryProvider persiste a conversa completa em uma coleção vetorial e carrega no contexto apenas um conjunto compactado.

from agent_framework import (
    Agent,
    InMemoryStore,
    SlidingWindowStrategy,
    VectorStoreHistoryProvider,
)
from agent_framework.openai import OpenAIChatClient, OpenAIEmbeddingClient


async def run_release_assistant() -> None:
    history = VectorStoreHistoryProvider(
        InMemoryStore(),
        application_id="release-planning",
        tenant_id="contoso",
        agent_id="release-assistant",
        collection_name="release_planning_history_text_embedding_3_small",
        contents_format="json",
        embedding_generator=OpenAIEmbeddingClient(model="text-embedding-3-small"),
        embedding_options={"dimensions": 1536, "encoding_format": "float"},
        # Mantém apenas os grupos mais recentes no contexto
        compaction_strategy=SlidingWindowStrategy(keep_last_groups=2, preserve_system=True),
        # Permite pesquisar o histórico completo
        include_search_tool=True,
    )

    async with Agent(
        client=OpenAIChatClient(model="gpt-5.4-nano"),
        name="ReleaseAssistant",
        instructions="Use the history search tool when an older detail is missing.",
        context_providers=[history],
    ) as agent:
        response = await agent.run("Which deadline did we agree on earlier?")
        print(response.text)

Quando include_search_tool=True, o agente recebe uma ferramenta para pesquisar toda a transcrição dentro do escopo. Assim, o contexto ativo permanece limitado, mas o agente ainda recupera uma decisão antiga, um requisito ou uma preferência do usuário quando precisa.

Os identificadores de aplicação, tenant, agente e sessão evitam sobreposições acidentais entre conversas. Mesmo assim, a sua aplicação continua responsável por autorizar o acesso e usar credenciais com escopo adequado.

Os nomes de importação podem variar entre versões prévias. Portanto, confira sempre os samples oficiais do repositório antes de copiar os exemplos para o seu projeto.