Skip to main content

Recipe: Create & Ingest Embeddings

The Problem​

"We have a folder of product documentation (Markdown, PDFs, Word docs) that we need turned into searchable embeddings in our vector store — without hand-rolling text extraction, chunking, and batching against the embeddings API ourselves."

Ingredients​

  • A vector store (see Add a Vector Store)
  • client.build_and_push_embeddings() for files, or client.batch_text_to_embeddings() / client.text_to_embedding() for raw text
  • The underlying CAIP LLM API /v1/embeddings endpoint (used automatically by the SDK)
LLM API Integration

The Agents SDK uses the LLM API's /v1/embeddings endpoint under the hood — it just handles authentication, batching, and retries for you.

The Recipe​

1. Easiest: ingest a whole directory of files​

result = await client.build_and_push_embeddings(
    document_path="your_document_path",
    vector_store_id=vector_store_id,
    metadata={"category": "documentation"},
)

print(f"✓ Processed {len(result['processed_files'])} files")
print(f"✓ Created {result['total_chunks']} chunks")

Supported formats: .txt, .md, .pdf, .docx, .doc, .html, .htm, .rtf, .odt. This extracts text, chunks it, generates embeddings in batches, and uploads them — in one call.

For production, run ingestion as a repeatable job (CI/CD or scheduler), not manually from a laptop.

2. Convert raw text to embeddings​

# Many texts at once (10-100x faster than one-by-one)
texts = ["Authentication requires an API key", "Rate limits are 1000 req/hour"]
embeddings = await client.batch_text_to_embeddings(
    texts=texts,
    vector_store_id=vector_store_id,
)

# A single text (e.g. to embed a search query — see the next recipe)
embedding = await client.text_to_embedding(
    text="How do I authenticate?",
    vector_store_id=vector_store_id,
)

3. Advanced: store pre-computed embeddings directly​

If you already have embeddings from another source:

await client.create_embeddings(
    vector_store_id=vector_store_id,
    embedding_data={
        "embeddings": pre_computed_embeddings,       # e.g. 1536-dim vectors
        "chunks": texts,
        "documentIds": ["api/authentication", "api/rate-limits"],
        "sequences": [0, 0],   # chunk order within each document; [0]*len(texts) if one chunk per doc
        "metadata": [
            {"category": "api", "topic": "auth"},
            {"category": "api", "topic": "limits"},
        ],
    },
)

Use hierarchical documentIds (e.g. "api/authentication" rather than "doc_1") — this makes later filtering by document/section fast and precise.

4. Manage stored embeddings​

# List
embeddings = await client.list_embeddings(vector_store_id=vector_store_id)

# Delete specific documents
await client.delete_embeddings(
    vector_store_id=vector_store_id,
    delete_request={"documentIds": ["doc-1", "doc-2"]},
)

# Delete everything
await client.delete_embeddings(
    vector_store_id=vector_store_id,
    delete_request={"deleteAll": True},
)

Use metadata to identify source/version and replace only what changed.

source_id = "docs/api"
source_version = "2026-08-09"

# Optional cleanup for previous version of same source.
await client.delete_embeddings(
    vector_store_id=vector_store_id,
    delete_request={"documentIds": [source_id]},
)

await client.build_and_push_embeddings(
    document_path="./docs/api",
    vector_store_id=vector_store_id,
    metadata={"source": source_id, "version": source_version},
)

Best Practices​

  • ✅ Always batch (build_and_push_embeddings() / batch_text_to_embeddings()) — individual calls are 10–100x slower
  • ✅ Use rich, structured metadata (category, version, topic) rather than {"type": "doc"}
  • ✅ Use hierarchical document IDs ("guides/quickstart") for precise filtering later
  • ✅ Keep chunkSize at 800–1200 characters with ~15–20% overlap (set on the vector store, see previous recipe)

Enterprise Hardening Checklist​

  • Define metadata schema upfront (source, version, classification, owner).
  • Run ingestion in non-production first; validate chunk count and sample retrieval.
  • Track ingestion metrics (files processed, chunks created, failures, duration).
  • Re-ingest on document updates via automation, not manual one-off uploads.
  • Enforce content governance for sensitive documents before embedding.