akeyless-foundry-runtime

Fetch Akeyless secrets at runtime on Microsoft Foundry Hosted Agents. Authenticate with cloud identity (Azure AD / Entra) — no long-lived API keys in your agent deployment. Application secrets stay in Akeyless, not Azure Key Vault.

Built on the Akeyless Python SDK with Foundry-specific auth defaults, path conventions, caching, and optional MCP tools.

Repository: github.com/akeyless-community/foundry-akeyless-runtime

Documentation

Why this integration?

Foundry Hosted Agents assign a dedicated Microsoft Entra identity at deploy time. This library uses that identity to generate an Akeyless cloud ID and authenticate — the same Azure AD pattern used by AKS, Functions, and other Akeyless integrations.

Install

No git clone needed. Add to your agent project and install with pip.

From PyPI (recommended once published)

pip install akeyless-foundry-runtime

See docs/PYPI_PUBLISHING.md for maintainer setup. The package is not on PyPI yet — use GitHub install below until the first release is published.

From GitHub (available once the repo is public)

pip install "akeyless-foundry-runtime @ git+https://github.com/akeyless-community/foundry-akeyless-runtime.git@v0.1.0"

Add to your Foundry agent requirements.txt:

akeyless-foundry-runtime @ git+https://github.com/akeyless-community/foundry-akeyless-runtime.git@v0.1.0

Full install guide: docs/INSTALL.md

Requires Python 3.10+.

Quick start

1. Configure Akeyless

Follow docs/AKEYLESS_SETUP.md — create an Azure AD Auth Method, RBAC, and store secrets under /foundry-agents/<agent>/<env>/.

2. Test locally

cp .env.example .env   # edit with access_key auth for local test
python3 -c "from akeyless_foundry import get_secret; print('OK' if get_secret('APP_SECRET') else 'empty')"

Do not print secret values.

3. Deploy to Foundry

Follow docs/FOUNDRY_DEPLOY.md — set bootstrap env vars on the hosted agent, bind the agent Entra object ID in Akeyless, deploy, then invoke.

4. Set bootstrap env vars on the hosted agent

Configure only auth + path prefix — not application secrets:

5. Fetch a secret in your agent

from akeyless_foundry import get_secret

app_secret = get_secret("APP_SECRET")

6. Deploy

Package and deploy as a Foundry Hosted Agent (container or source zip). See examples/hosted-agent/.

Two ways to retrieve secrets

Both use the same Akeyless SDK under the hood (auth + get-secret-value / get-dynamic-secret-value / get-rotated-secret-value). The tool adds a JSON response layer.

from akeyless_foundry import get_secret, AkeylessRuntimeClient

app_secret = get_secret("APP_SECRET")
client = AkeylessRuntimeClient()
client.get_dynamic_secret("azure-creds")
client.get_rotated_secret("api-key")

API reference

get_secret(name) — fetch a secret from your code

from akeyless_foundry import get_secret

value = get_secret("APP_SECRET")

AkeylessRuntimeClient — full client

from akeyless_foundry import AkeylessRuntimeClient

client = AkeylessRuntimeClient(
    gateway_url="https://api.akeyless.io",
    secret_prefix="/foundry-agents/my-agent/production",
    access_id="p-xxxxx",
    access_type="azure_ad",
)

client.get_secret("APP_SECRET")
client.get_secret_json("APP_CONFIG")
client.get_dynamic_secret("azure-creds")
client.get_rotated_secret("api-key")
client.list_secrets()

Agent tools — get_akeyless_secret / list_akeyless_secrets

# pip install 'akeyless-foundry-runtime[mcp]'
from akeyless_foundry.tools.mcp import run_mcp_server

Authentication

Architecture

sequenceDiagram
    participant Agent as Foundry Hosted Agent
    participant Lib as akeyless-foundry-runtime
    participant Entra as Entra / IMDS
    participant AKL as Akeyless Gateway

    Agent->>Lib: get_secret("APP_SECRET")
    Lib->>Entra: Generate cloud ID (Azure AD token)
    Entra-->>Lib: Identity token
    Lib->>AKL: POST /auth (access_id, azure_ad, cloud_id)
    AKL-->>Lib: Session token
    Lib->>AKL: GET /get-secret-value
    AKL-->>Lib: Secret value
    Lib-->>Agent: APP_SECRET

Local development

export AKEYLESS_ACCESS_ID=p-xxxxx
export AKEYLESS_ACCESS_TYPE=access_key
export AKEYLESS_ACCESS_KEY=your-readonly-key
export AKEYLESS_SECRET_PREFIX=/foundry-agents/my-agent/dev

python3 -c "from akeyless_foundry import get_secret; print('fetched' if get_secret('APP_SECRET') else 'empty')"

Related community projects

• bedrock-agentcore-akeyless-runtime — AWS Bedrock AgentCore
• netlify-akeyless-runtime — Netlify Functions
• fly-akeyless-runtime — Fly.io Machines

License

Apache-2.0