{"id":27572,"library":"agent-framework-azure-cosmos","title":"Azure Cosmos DB History Provider for Microsoft Agent Framework","description":"Azure Cosmos DB history provider integration for Microsoft Agent Framework. This package stores and retrieves agent conversation history using Azure Cosmos DB. Current version is 1.0.0b260507, a beta release. Release cadence is irregular, tied to the Agent Framework development cycle.","status":"active","version":"1.0.0b260507","language":"python","source_language":"en","source_url":"https://github.com/Azure/agent-framework-azure-cosmos","tags":["agent-framework","azure-cosmos","history-adapter","microsoft"],"install":[{"cmd":"pip install agent-framework-azure-cosmos","lang":"bash","label":"Install from PyPI"}],"dependencies":[{"reason":"Core SDK for Azure Cosmos DB operations","package":"azure-cosmos","optional":false},{"reason":"Required for authentication using DefaultAzureCredential","package":"azure-identity","optional":false},{"reason":"Peer dependency: the base Agent Framework package","package":"agent-framework","optional":false}],"imports":[{"note":"Legacy structure: this package is a separate distribution, not part of agent_framework namespace.","wrong":"from agent_framework.azure_cosmos import AzureCosmosDBHistoryAdapter","symbol":"AzureCosmosDBHistoryAdapter","correct":"from agent_framework_azure_cosmos import AzureCosmosDBHistoryAdapter"}],"quickstart":{"code":"import os\nfrom azure.identity import DefaultAzureCredential\nfrom agent_framework_azure_cosmos import AzureCosmosDBHistoryAdapter\n\n# Use environment variables for credentials (better to use managed identity in production)\ncredential = DefaultAzureCredential()\naccount_url = os.environ.get(\"COSMOS_ACCOUNT_URL\", \"https://your-account.documents.azure.com:443/\")\ndatabase_name = os.environ.get(\"COSMOS_DATABASE\", \"agent_history\")\ncontainer_name = os.environ.get(\"COSMOS_CONTAINER\", \"conversations\")\n\nadapter = AzureCosmosDBHistoryAdapter(\n    account_url=account_url,\n    credential=credential,\n    database_name=database_name,\n    container_name=container_name\n)\nprint(\"Adapter created successfully.\")\n# Use adapter with Agent Framework's Agent class","lang":"python","description":"Initialize the Azure Cosmos DB history adapter using DefaultAzureCredential for authentication."},"warnings":[{"fix":"Wrap all adapter operations in `async def` and `await` calls. Use `asyncio.run()` or an event loop.","message":"Must use async context to call adapter methods (e.g., store / retrieve). Synchronous calls will raise RuntimeError.","severity":"breaking","affected_versions":">=1.0.0b1"},{"fix":"Switch to `DefaultAzureCredential()` with appropriate RBAC roles on Cosmos DB.","message":"Default Azure credential fallback to managed identity; previously users relied on connection strings. Connection string support is deprecated and may be removed.","severity":"deprecated","affected_versions":">=1.0.0b260507"},{"fix":"`pip install agent-framework-azure-cosmos` -> `import agent_framework_azure_cosmos`","message":"The package name uses hyphens, but the Python module name uses underscores. Pip install with hyphens, import with underscores.","severity":"gotcha","affected_versions":"all"},{"fix":"Create container with partition key '/id' and ensure the container exists before running the adapter.","message":"Cosmos DB account must have a container with id field partition key set to '/id' for the adapter to work correctly.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-09T00:00:00.000Z","next_check":"2026-08-07T00:00:00.000Z","problems":[{"fix":"Ensure you call adapter methods inside an async function and await them. If running in a Jupyter notebook, use `await` directly; otherwise use `asyncio.run(your_async_function())`.","cause":"Calling an async adapter method (e.g., `adapter.store(...)`) from a synchronous context without an async runner.","error":"RuntimeError: This event loop is already running"},{"fix":"Set environment variables for service principal or enable managed identity. Alternatively, use `ClientSecretCredential` with explicit credentials.","cause":"No Azure credentials available in the environment (e.g., AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET not set, and no managed identity).","error":"azure.core.exceptions.ClientAuthenticationError: DefaultAzureCredential failed to retrieve a token"},{"fix":"Install the correct package: `pip install agent-framework-azure-cosmos` and import `from agent_framework_azure_cosmos import AzureCosmosDBHistoryAdapter`.","cause":"Installed the wrong package (e.g., `azure-cosmos` or `agent-framework`). Hyphen confusion in package name.","error":"AttributeError: module 'agent_framework_azure_cosmos' has no attribute 'AzureCosmosDBHistoryAdapter'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}