Runtime Migration

This release keeps old APIs working and adds structured runtime APIs for new work. Use this page to migrate incrementally.

Agent.chat() to Agent.generate()

Old:

answer = agent.chat("Summarize this")

New:

response = agent.generate("Summarize this")
answer = response.content

Use generate() when you need provider/model metadata, usage, structured outputs, reasoning, multimodal input, or consistent per-call options.

Provider Strings to Provider and Model

Old compact strings still work:

Agent("assistant", model="openai:gpt-5.4-mini")

Preferred explicit form:

Agent("assistant", provider="openai", model="gpt-5.4-mini")

Tool Behavior

Legacy provider tool-call handling remains compatible. New calls use provider-neutral runtime orchestration for OpenAI, Anthropic, Cohere, and Gemini. Provider-hosted tools and provider-hosted MCP descriptors are not inferred from client tools; they require the experimental opt-in documented in Providers. Direct stdio and Streamable HTTP MCP connections use the first-class tools-only client documented in MCP Tool Clients.

Spore.knowledge to V2 Payload Fields

Spore.knowledge remains the compatibility field. New code can also populate content_parts, knowledge_references, and data_references. Rich Spores use the V2 JSON envelope; knowledge-only Spores retain the legacy wire body. Do not place bytes directly in a Spore. Use base64 content parts or storage references.

Embedding Configuration

Chat model settings no longer select the memory embedding model. Configure the embedding space in memory_config:

agent = Agent(
    "researcher",
    provider="openai",
    model="gpt-5.4-mini",
    memory_enabled=True,
    memory_config={
        "embedding_provider": "openai",
        "embedding_model": "text-embedding-3-small",
        "embedding_dimensions": 1536,
    },
)

Changing provider, model, or dimensions changes vector space. Existing Chroma or Qdrant collections must be re-embedded, or a new collection name must be used. Praval records the embedding identity and raises EmbeddingConfigurationError when it can prove a collection is incompatible.

Local LLMs

Old provider strings such as openai with custom base_url continue to work, but new local code should use provider="ollama", provider="vllm", provider="lmstudio", provider="llama-cpp", or provider="openai-compatible" so capability resolution uses the right profile.