Open Source · MIT LicensePython 3.11+ · Azure AI Foundry

foundry-kit

A Python framework for building deployment-ready AI agents on Azure. Purpose-built for enterprise internal tooling and client-facing chat applications — with ETL helper, AI search, ToolBuilder utilities, and full Azure AI Foundry integration baked in.

View on GitHub Enterprise Platform

folder_openDocument ETL

manage_searchAI Search

smart_toyFoundry Agents

buildToolBuilder

terminal — quickstart

# Install the framework

$ pip install foundry-kit

Successfully installed foundry-kit

# Configure Azure endpoints

$ foundry-kit config init

→ wrote foundry-kit.yaml

# Ingest your documents

$ foundry-kit index ingest ./docs/ --index kb

✓ 42 files · 380 chunks · 0 errors

# Create and deploy agent

$ foundry-kit agent init my-bot --model gpt-4o

✓ Provisioned: asst_abc123

$ foundry-kit deploy --app-name my-app

✓ Deployed to Azure Functions

Use Cases

What you build with foundry-kit

foundry-kit is the framework you use to ship AI agents into production — not a development workflow tool. These are the production applications it targets.

build

Enterprise Internal Tooling

Build agents that query your internal knowledge bases, process documents, call internal APIs, and surface answers inside Teams or your intranet — all governed, all auditable.

forum

Client-Facing AI Chat

Deploy RAG-powered chat grounded in your proprietary data — policies, product docs, contracts. Answers are always cited, always accurate. Ship via Azure Functions in minutes.

folder_open

Document ETL Pipelines

Ingest PDF, DOCX, and XLSX documents into Azure AI Search with one CLI command. AI-enriched metadata, overlap-aware chunking, and idempotent re-ingestion built in.

manage_search

AI-Powered Search

Vector similarity search over your knowledge base using Azure AI Search HNSW indexes and Azure OpenAI embeddings. Plug SearchTool directly into any agent.

Core Capabilities

Everything you need to ship an agent.

smart_toy

Azure AI Foundry Integration

Provision, update, and manage Azure AI Foundry Hosted Agents from the CLI or Python SDK. Threads, runs, and streaming all handled.

travel_explore

AI Search Helper

Create HNSW vector indexes, embed documents with Azure OpenAI, and run semantic similarity queries — no raw Search SDK required.

folder_open

Document ETL Helper

Full ingestion pipeline: extract (PDF/DOCX/XLSX/ZIP) → chunk with overlap → AI-enrich metadata → embed → upsert to Azure AI Search.

build

ToolBuilder Utilities

Define function, API, and search tools with zero boilerplate. Auto-generates OpenAI function schemas from Python type hints and docstrings.

cloud_upload

One-Command Deploy

foundry-kit packages and deploys your agent as an Azure Function. No manual host.json or function.json authoring.

code

FastAPI Dev Server

Local development server with Swagger UI. POST /chat/{name} to test agents before deploying to Azure.

Document ETL Helper

Ingest any document into Azure AI Search.

The ETL pipeline extracts text from PDF, DOCX, XLSX, and ZIP files, splits it into overlap-aware chunks, optionally enriches each chunk with AI-detected metadata, then embeds and upserts to your Azure AI Search index in one command.

check_circle

PDF, DOCX, XLSX, ZIP

Extracts text from all common enterprise document formats

check_circle

Overlap-aware chunking

ParagraphChunker with configurable chunk size and overlap

check_circle

AI metadata enrichment

LLM extracts document type, dates, entities — improves retrieval

check_circle

Idempotent re-ingestion

SHA-256 chunk IDs — uploading the same file twice is safe

Install with extras: pip install "foundry-kit[documents]"for PDF, DOCX, and XLSX support.

CLI — document ingestion

# Ingest a directory of documents

$ foundry-kit index ingest ./documents/ \

--index policies

✓ 18 files · 204 chunks · 0 errors

# Custom chunk size, skip AI enrichment

$ foundry-kit index ingest ./docs/ \

--index kb --chunk-size 1200 \

--overlap 200 --no-ai

✓ Done (use --dry-run to preview)

Python SDK — ETL

from foundry_kit import SearchManager

search = SearchManager(

search_endpoint="https://mysearch.search.windows.net",

openai_endpoint="https://myoai.openai.azure.com",

)

result = search.ingest(

path="./documents/", index_name="policies",

chunk_size=1500, overlap=300, ai_enrich=True

)

print(f"{result.processed} files, {result.chunks} chunks")

AI Search Helper

Vector RAG without the SDK boilerplate.

SearchManager wraps Azure AI Search and Azure OpenAI embeddings into a clean API. Create indexes, embed documents, and run semantic similarity queries — all without touching the underlying Azure SDK.

manage_search

HNSW vector indexes

Create and manage Azure AI Search indexes with one CLI command

manage_search

Automatic embedding

Uses Azure OpenAI text-embedding-3-small (configurable)

manage_search

SearchTool integration

Plug directly into ToolBuilder — agents get RAG in three lines

manage_search

Responses API streaming

ResponsesEngine emits source citations as SSE events

search_agent.py

from foundry_kit import SearchManager, SearchTool,

ResponsesEngine, ToolRegistry

# Attach search index to agent as a tool

search = SearchManager(search_endpoint, oai_endpoint)

registry = ToolRegistry()

registry.register(SearchTool(

"search_kb", "Search knowledge base", "my-index", search))

# Stream reply with citations

engine = ResponsesEngine(oai_client, registry)

async for event in engine.stream(model, instructions, msg):

match event.type:

case "text_delta": print(event.data["delta"], end="")

case "sources": # citations from SearchTool

print(event.data["sources"])

Azure AI Foundry Integration

Full lifecycle management — from `init` to deploy.

foundry-kit wraps the Azure AI Foundry Agents API and Threads/Runs API into a simple SDK. Agents, configuration, and deployment all live in one foundry-kit.yaml.

foundry-kit.yaml

foundry_endpoint: "https://myhub.services.ai.azure.com/api/projects/myproject"

search_endpoint: "https://mysearch.search.windows.net"

openai_endpoint: "https://myoai.openai.azure.com"

agents:

- name: internal-ops-bot

model: gpt-4o

instructions: "You are an enterprise assistant."

search_index: company-kb

engine: responses # SSE streaming + tool loop

- name: client-chat-bot

model: gpt-4o

search_index: product-docs

engine: threads # Azure AI Foundry default

smart_toy

Hosted Agent Management

FoundryClient.create_agent(), update_agent(), delete_agent() — full CRUD from CLI or Python.

swap_horiz

Dual Engine Support

engine: threads uses Azure AI Foundry Threads/Runs API. engine: responses uses OpenAI Responses API with tool-calling loop (up to 10 iterations) and SSE streaming.

cloud_upload

Azure Functions Deploy

foundry-kit deploy packages your app as an Azure Functions HTTP trigger via ASGI middleware. One command, zero manual configuration.

vpn_key

DefaultAzureCredential

All Azure SDK clients use the credential chain — az login locally, Managed Identity or service principal in CI/CD. No secrets in source.

ToolBuilder Utilities

Define tools. Schema is automatic.

The ToolBuilder SDK lets you define OpenAI function-call tools from Python functions, HTTP endpoints, or Azure AI Search indexes — with zero schema boilerplate. Type hints and docstrings generate the OpenAI function schema automatically.

functions@tool / FunctionTool

Wrap any Python function. Schema auto-generated from type hints and docstrings. Supports str, int, float, bool, list[str] parameter types.

@tool
def get_policy(policy_number: str) -> str:
    """Retrieve policy by number."""
    return fetch_from_db(policy_number)

apiApiTool

Back a tool with an HTTP endpoint. URL templating for path parameters. Non-2xx responses are caught and returned as error strings to the model.

ApiTool("get_claim", "Look up a claim.",
  method="GET",
  url_template="https://api.internal/claims/{id}",
  parameters={...})

manage_searchSearchTool

Back a tool with an Azure AI Search index. The model calls search_kb(query) and gets cited sources back. Integrates directly with ResponsesEngine.

SearchTool("search_kb", "Search knowledge base",
  index_name="policies", search=search_manager)

tools.py — full example

from foundry_kit import tool, ApiTool, SearchTool, ToolRegistry

# Wrap a Python function as a tool

@tool

def get_ticket(ticket_id: str) -> str:

"""Get support ticket by ID."""

return fetch_ticket(ticket_id)

# HTTP tool for internal API

create_ticket = ApiTool(

"create_ticket", "Open a support ticket",

method="POST", url_template="https://internal.api/tickets",

parameters={"type": "object", ...}

)

# Assemble all tools into a registry

registry = ToolRegistry()

registry.register(get_ticket)

registry.register(create_ticket)

registry.register(SearchTool("search_kb", ..., search))

# Pass registry to ResponsesEngine

engine = ResponsesEngine(oai_client, registry)

info

ToolRegistry.dispatch() catches all tool errors and returns them as error strings to the model — the agent handles them gracefully. The tool-calling loop runs up to 10 iterations.

Python SDK

`FoundryClient` and `SearchManager`

Thin, typed wrappers around the Azure SDKs. Chat with a Foundry agent, query a vector index, and assemble a FastAPI app — all with three imports.

check_circle

Async-first

Built on asyncio — no blocking calls in your event loop

check_circle

Config-driven

Endpoints and deployment names read from foundry-kit.yaml

check_circle

DefaultAzureCredential

Works with az login locally, service principals in CI

agent.py

from foundry_kit import FoundryClient, SearchManager, create_app, load_config

config = load_config("foundry-kit.yaml")

client = FoundryClient(config.foundry_endpoint)

# Async chat with a Foundry agent

import asyncio

reply = asyncio.run(

client.run_chat("asst_abc123", "What can you do?")

)

# Vector similarity search

search = SearchManager(config.search_endpoint, config.openai_endpoint)

results = search.query("my-index", "leave policy")

# FastAPI app factory — POST /chat/internal-ops-bot

app = create_app("foundry-kit.yaml")

Quickstart

From pip install to deployed agent in five steps.

download

1. Install

# Requires Python 3.11+

$ pip install foundry-kit

# With document ETL extras (PDF, DOCX, XLSX)

$ pip install "foundry-kit[documents]"

settings

2. Configure

# Scaffolds foundry-kit.yaml

$ foundry-kit config init

→ wrote foundry-kit.yaml

smart_toy

3. Create agent

$ foundry-kit agent init my-bot \

--prompt "You are a helpful assistant." \

--model gpt-4o

✓ Provisioned: asst_abc123

folder_open

4. Ingest documents

# Load your knowledge base

$ foundry-kit index ingest ./docs/ --index kb

✓ 42 files · 380 chunks · 0 errors

cloud_upload

5. Serve & Deploy

$ foundry-kit serve

→ http://127.0.0.1:8000

# When ready for production:

$ foundry-kit deploy --app-name my-function-app

✓ Deployed to Azure Functions

CLI Reference

All commands at a glance.

foundry-kit config init

Scaffold foundry-kit.yaml interactively

foundry-kit agent init <name>

Provision a Foundry Hosted Agent

foundry-kit agent update <name>

Update agent prompt or model

foundry-kit agent list

List all registered agents

foundry-kit agent show <name>

Show agent details and status

foundry-kit agent delete <name>

Delete agent from Foundry and config

foundry-kit index create <name>

Create an Azure AI Search HNSW index

foundry-kit index ingest <path>

Full ETL: extract, chunk, embed, upsert

foundry-kit index upsert

Embed and upload raw text to an index

foundry-kit index query

Run a vector similarity query

foundry-kit serve

Start local FastAPI dev server at :8000

foundry-kit deploy

Deploy agents to Azure Functions

REST API

Built-in FastAPI server — Swagger included.

foundry-kit serve starts a FastAPI dev server on port 8000 with Swagger UI at /docs. The same app deploys as an Azure Function.

GET

/health

Health check — returns {"status": "ok"}

GET

/agents

List all agents from foundry-kit.yaml

GET

/agents/{name}

Get details and status for a single agent

POST

/chat/{name}

Send a message — JSON response or SSE stream (?stream=true)

Authentication

DefaultAzureCredential — zero secrets in code.

foundry-kit uses Azure's credential chain. Run az login locally or set environment variables for CI/CD — no secrets ever touch your source.

vpn_key

Service Principal

CI/CD and production deployments

AZURE_CLIENT_IDAZURE_CLIENT_SECRETAZURE_TENANT_ID

laptop_mac

Developer Workstation

Local development — no secrets needed

az login

checklist

Prerequisites

deployed_code

Python 3.11+

cloud

Azure AI Foundry project (pre-provisioned)

travel_explore

Azure AI Search resource (for RAG)

functions

Azure Functions Core Tools (for deploy)

Ready to build production agents with foundry-kit?

Star the repo, open an issue, or explore the enterprise platform for multi-tenant isolation, MCP integrations, audit trails, and production SLA support.

View on GitHub Explore Enterprise Platform

foundry-kit

What you build with foundry-kit

Enterprise Internal Tooling

Client-Facing AI Chat

Document ETL Pipelines

AI-Powered Search

Everything you need to ship an agent.

Azure AI Foundry Integration

AI Search Helper

Document ETL Helper

ToolBuilder Utilities

One-Command Deploy

FastAPI Dev Server

Ingest any document into Azure AI Search.

Vector RAG without the SDK boilerplate.

Full lifecycle management — from init to deploy.

Define tools. Schema is automatic.

FoundryClient and SearchManager

From pip install to deployed agent in five steps.

All commands at a glance.

Built-in FastAPI server — Swagger included.

DefaultAzureCredential — zero secrets in code.

Ready to build production agents with foundry-kit?

Full lifecycle management — from `init` to deploy.

`FoundryClient` and `SearchManager`