Skip to main content

castia

Idiomatic, FastAPI-style Python SDK for Microsoft Foundry hosted agents.

castia lets a hosted agent speak Foundry's three wire protocols — Activity (Teams/Bot Framework), OpenAI responses, and invocations — through protocol-named decorators, dependency injection (Depends), and typed builders for messages, Adaptive Cards, entities, and invoke envelopes. You decorate a handler, return a value, and the framework does the rest — the auth chains, hosting, Activity routing, and telemetry stay out of your file.

Install

uv add castia
# With baseline resolution, CLI YAML tooling, and offline tests:
uv add --prerelease=allow "castia[deploy,optimize,test]"

Requires Python 3.11+. For a standalone environment, use uv venv followed by uv pip install --prerelease=allow "castia[deploy,optimize,test]".

Local dev loop

From a Castia app root, python -m castia dev loads .env into a child environment, validates registration, azure.yaml, .agent_configs/baseline, eval.yaml, optional Prompty imports, and dry toolbox configuration, then starts main.py if the checks pass:

python -m castia dev --check-only --json
python -m castia dev

The command prints the local base URL plus /readiness and /responses paths for playground/canvas tooling. It is intentionally offline-safe by default: readiness checks do not invoke the model, mint credentials, list remote toolbox tools, submit optimizer/eval jobs, deploy, or read azd's persisted environment. If a toolbox is configured, the dev preflight only resolves and validates the MCP endpoint shape. Keep python -m castia optimize --check or the default dev optimizer drift check in CI so Agent-declared tools stay aligned with .agent_configs/baseline/tools.json.

The consumer agent guide has a complete Responses application, native MCP setup, credentials, and executable offline tests. Use LIFECYCLE.md for build, observation, evidence, and deployment workflows. These Markdown guides are maintained in this repository.

Package organization

Application imports stay short (from castia import Agent, Model, Message). Implementation code lives in capability packages under src/castia.

Package Implementation
protocols Activity wire models and accessors
runtime Agent/router composition, dependency injection, turn context, dispatch
hosting HTTP endpoints, local-run policy, credentials, agentic identity
messaging Activity routing, Teams surfaces, replies, cards, entities, invoke helpers, streaming, connector
inference Model calls and executable tool definitions
integrations Foundry toolbox adapters and Graph operations under integrations.graph
prompty Optional Prompty runtime/eval harness adapters (castia[prompty])
building Scaffolding, readiness checks, offline protocol testing
evaluation Evaluation-suite configuration, rubric validation, azd evaluation commands
observe Telemetry configuration and tracing, execution records, queries, drift checks
optimizing Candidate configuration, baseline generation, optimizer jobs
finetuning SFT/DPO/RFT preparation/submission and existing-job management
lifecycle Snapshots, datasets, evaluation evidence, acceptance and promotion records
delivery Manifest generation and guarded azd deployment

Each command family keeps its CLI handlers beside its implementation. __main__.py composes those commands.

The package root contains only __init__.py, __main__.py, and py.typed, alongside the capability folders. Implementation imports use their canonical paths, such as castia.inference.model and castia.optimizing.jobs. There are no compatibility modules or import redirects.

The former flat submodule paths have been removed. Change from castia.model import Model to from castia import Model or from castia.inference.model import Model. The root public API and CLI commands remain unchanged. Logger categories follow the canonical module names. The tracing guide lives with the package documentation.

Shared protocol definitions and behavioral fixtures belong in spec/. These Python modules are handwritten today. Typra now emits the experimental Rust contract layer from those TypeSpec files, but Python remains the shipped SDK. Generated types alone do not establish parity; each runtime must pass the same behavioral fixtures and still provide native host adapters.

Quickstart

from castia import Agent, Depends, Model, Teams

app = Agent(name="my-agent")

def gpt4o() -> Model:
    return Model("gpt-4o")

@app.activity(Teams.direct, Teams.group, Teams.channel_mention)
async def reply(text: str, model: Model = Depends(gpt4o)) -> str:
    return await model.respond(text)

if __name__ == "__main__":
    app.run()

Decorate a handler with the surfaces it answers on, return a str, and the framework sends it as the Teams reply. The model is built once for the process and injected via Depends — the model choice stays visible in your file instead of being buried in the framework. (Model() with no argument falls back to AZURE_AI_MODEL_DEPLOYMENT_NAME; get_model / use_model("gpt-4o") are zero-config conveniences.)

Register targeted Teams / Agent 365 commands with @app.command(...) when a turn should be handled before the model sees it:

from castia import Agent, Message, Teams

app = Agent(name="my-agent")

@app.command("version", description="Show deployed version", triggers=("slash",))
async def version(msg: Message) -> str:
    return "my-agent 1.2.3"

@app.activity(Teams.direct, Teams.group, Teams.channel_mention)
async def reply(text: str) -> str:
    return f"model handles: {text}"

Commands are still Activity messages on the wire, not a new protocol. A Teams targeted message such as /version is parsed and routed to the command handler before any broader @app.activity(...) route can call the model. Command metadata is available to Microsoft 365 dry-runs for Teams manifest discoverability.

app.run() binds to 0.0.0.0 and reads PORT when no explicit port is provided, falling back to 8088. Set a different PORT for each local agent when running multiple agents through the playground or canvas. Use app.run(host="127.0.0.1") for local-only development. GET /readiness returns low-disclosure JSON to non-local callers, for example {"status":"ok"}. Local loopback callers receive diagnostic readiness for development tooling: agent name, enabled protocols, route paths, and present/missing status for common configuration variables without exposing values.

Declare runtime-required settings with app.require_env(...) so readiness can distinguish optional discovery from configuration that blocks answers:

app.require_env(
    "FOUNDRY_PROJECT_ENDPOINT",
    "AZURE_AI_MODEL_DEPLOYMENT_NAME",
    "TOOLBOX_ENDPOINT",
)

Missing required settings fail before app.run() serves traffic and make local readiness report {"status":"configuration_missing"} with the missing names.

For local debugging of a single turn, set CASTIA_DEV_DIAGNOSTICS=1 and call GET /diagnostics/last-turn from loopback. It reports the last local wire turn's input, selected local/Prompty tool calls, arguments, success/error summaries, and final output. The endpoint is disabled by default and returns 404 to non-loopback callers.

Responses lifecycle support

Castia serves the OpenAI Responses wire protocol at POST /responses. A non-streaming request returns a completed response object immediately. stream: true returns Responses SSE lifecycle events followed by [DONE] on success. When streaming, if the handler raises mid-turn, Castia emits a terminal response.failed event with a generic server_error, then [DONE]; the exception is logged server-side and the public event does not include exception details. During idle gaps, the stream also carries : keep-alive SSE comments, every SSE_KEEPALIVE_INTERVAL seconds (default 15, 0 disables; same contract as azure-ai-agentserver-core), so proxies don't drop slow turns. Unless the request sets store: false, Castia also keeps the terminal completed or failed response and normalized input items in a bounded in-memory store for the current process. The completed record is available through:

  • GET /responses/{response_id}
  • DELETE /responses/{response_id}
  • POST /responses/{response_id}/cancel
  • GET /responses/{response_id}/input_items

This default lifecycle store is intentionally lightweight. It is process-local, in-memory, and capped at the most recent 512 responses per process; older records are evicted, so a later GET can return 404 even before restart. It is not durable and does not survive process restart, scale-out, or container replacement. Pass a response_store (below) to keep records in your own storage instead. Stored and returned response objects are wire-shaped but minimal: completed usage token counts are reported as zeros and are not real model accounting; failed responses currently report usage: null.

POST /responses/{response_id}/cancel cancels only a queued or in_progress background response; for a terminal response it returns 400 unsupported_parameter (Cannot cancel a completed response.), and 404 if the response is unknown. previous_response_id and conversation replay prior turns through a store you provide; see Conversation history.

Multi-turn through the Foundry gateway. Foundry's reference SDK hydrates history from conversation.id automatically (hosted agent runtime contract). In Castia, history is replayed only when your store implements castia.ResponseHistoryStore. Without it, clients that rely on conversation (the playground, simulated-user evaluation) see a stateless agent.

Gateway facts that affect hosted Castia agents:

  • Only allowlisted caller headers reach the container: x-client-*, content headers, tracing headers, and user-agent. Authorization is never forwarded, so pass custom caller data as x-client-*.
  • Castia forwards x-agent-foundry-call-id unchanged on model and toolbox calls. It never forwards x-agent-user-id. Do the same in your own calls to Foundry services.
  • For Python containers, set PYTHONNOUSERSITE=1.

Background responses

Foundry tooling, including native evaluations, can call a hosted agent with background: true. The client then expects a queued response right away and polls GET /responses/{response_id} until the status is terminal. A hosted agent may run on several replicas, so a poll can reach a replica other than the one running the turn. For that reason, you own the response store. Castia ships no production backend. Without a store, background: true returns 400 unsupported_parameter and the message says how to configure one.

Implement the async castia.ResponseStore protocol over storage that every replica can reach (Cosmos DB, Redis, SQL, and so on), then pass it to the agent:

from castia import Agent, ResponseStore, StoredResponse


class InMemoryResponseStore:
    """EXAMPLE ONLY, not for production: single-process and unbounded."""

    def __init__(self) -> None:
        self._records: dict[str, StoredResponse] = {}

    async def create(self, record: StoredResponse) -> None:
        self._records[record["response"]["id"]] = record

    async def get(self, response_id: str) -> StoredResponse | None:
        return self._records.get(response_id)

    async def update(self, record: StoredResponse, *, expected_status: str) -> bool:
        current = self._records.get(record["response"]["id"])
        if current is None or current["response"]["status"] != expected_status:
            return False  # compare-and-set; never upsert a deleted record
        self._records[record["response"]["id"]] = record
        return True

    async def delete(self, response_id: str) -> bool:
        return self._records.pop(response_id, None) is not None


store: ResponseStore = InMemoryResponseStore()
app = Agent(name="my-agent", response_store=store)
Contract Behavior
Lifecycle queued → in_progress → completed, failed, or cancelled. Non-terminal snapshots have output: [] and usage: null.
update An atomic compare-and-set on response.status. It returns False on a mismatch or a missing record, and it never upserts. This is how a cancel or delete wins over a late completion.
Per-user isolation Each record stores the caller's Foundry x-agent-user-id as user_id (None without one). GET, input_items, cancel, and DELETE return 404 when the caller's user id differs. It is ownership metadata, not a lookup key; records stay keyed by response id.
Store errors Raise from the store; don't return None. Castia answers 503 store_unavailable: when create fails no work starts, and when a cancel write fails the cancel is not reported as done.
Foreground turns Stored through the same store (unless store: false). A failed write is logged and never fails the turn.
Not supported background with store: false returns 400. background with stream: true returns 400. GET ...?stream=true returns 400.
Execution Bound to a process. The store makes state visible on every replica, but a restart abandons in-flight work, and on shutdown Castia marks local work failed on a best-effort basis. A cancel from another replica records cancelled, but the worker keeps running until it finishes and its result is discarded. Expiring stale queued/in_progress records is the store owner's job.

Conversation history

A Responses handler receives only the latest user text. Ask for the earlier turns with response_history and pass them to the model:

from castia import Depends, Model, response_history


@app.responses()
async def reply(
    text: str,
    model: Model = Depends(model_provider),
    history: list[dict] = Depends(response_history),
) -> str:
    return await model.respond(text, history=history)

Model.respond, stream, and respond_with_tools accept history=. Items are replayable Responses input items, oldest first: text message items and function_call/function_call_output pairs (output after its call, even across responses). Ids, statuses, non-text parts, and unpaired or out-of-order tool items are dropped. History comes from three sources:

Source Needs Behavior
Earlier items in input Nothing Items before the current user message (the one the handler receives as text) become history. Items after it are ignored.
previous_response_id Agent(response_store=...) Castia walks the chain with get: each response's input_items, then its output. Without a store it returns 400 unsupported_parameter.
conversation ("id" or {"id": ...}) A store that also implements castia.ResponseHistoryStore Castia calls get_history(conversation_id=...). Without that method, conversation is echoed but ignored, with the span attribute castia.responses.conversation_ignored.

Implement get_history to serve previous_response_id from an index too:

class MyStore:  # also implements ResponseStore
    async def get_history(
        self, *, previous_response_id, conversation_id, user_id, limit
    ) -> list[list[dict]]:
        ...  # one item list per prior response, oldest first; only matching user_id

Castia never writes a conversation itself. Each stored response carries response["conversation"]["id"] and response["previous_response_id"], so your store can index them on create. For conversation lookups, Castia can't check record owners, so get_history must filter by user_id.

Rule Behavior
Ownership A previous_response_id owned by another x-agent-user-id returns 404, including for background: true. Anonymous records are visible only to anonymous callers. A chain stops at a foreign or deleted link.
Limits At most 100 chained responses and 1,000 items. The oldest whole responses are dropped first, and the span attribute castia.responses.history.truncated is set.
Errors Both previous_response_id and conversation → 400. An unfinished previous response → 400. A store failure → 503 store_unavailable.
store: false History is read, but the new turn is not written.
Echo Every response shape (JSON, SSE, background snapshots) echoes previous_response_id and conversation.

Depends(..., use_cache=False) resolves a dependency on every turn. Castia marks response_history per-turn, so it is never cached across requests.

Snapshot lifecycle

Foundry can snapshot an idle hosted-agent process and later restore it for a session. Castia serves the platform hooks from azure-ai-agentserver-core 2.3.0, so agents need no extra code:

Endpoint Behavior
POST /_agent/before-snapshot (alias /_before_snapshot) Takes a JSON object body and returns {"status":"ok"}. It's idempotent. Castia holds no state to release.
POST /_agent/after-restore (alias /_after_restore) Takes session_context with session_id, restore_id, and optional session_env_overrides. It applies the overrides and FOUNDRY_AGENT_SESSION_ID to os.environ, and returns {"status":"ok"}.
Errors A malformed body → 400 invalid_before_snapshot_request / invalid_after_restore_request. A different session after the first restore → 409 session_mismatch. A failed env write → 500 after_restore_failed, rolled back.

Replaying a restore_id returns ok without reapplying it. Restored values only reach code that reads the environment after the restore. Settings captured at startup keep their snapshot-time values.

Composing protocols with routers

Like FastAPI's include_router, an Agent composes Routers so each protocol can live in its own module:

from castia import Agent
from handlers import activity, responses, invocations

app = Agent(name="my-agent")
app.include(activity.router, responses.router, invocations.router)

Richer replies

Handlers can take a Message and reach for typed builders — Adaptive Cards, suggested actions, citations, mentions, sensitivity labels, live-typing streamers, and reactions:

from castia import Depends, Message, Model, Reaction, Router, Teams, get_model

router = Router()

@router.activity(Teams.direct)
async def reply(text: str, msg: Message, model: Model = Depends(get_model)) -> None:
    await msg.react(Reaction.eyes)
    answer = await model.respond(text)
    await msg.say(answer)

Consume a toolbox

A Foundry toolbox is a curated set of tools the platform exposes behind one MCP-compatible endpoint, with centralized auth, governance, and versioning. castia turns it into a single Responses-API mcp tool spec the model service resolves server-side — no local impl, no function loop. Build the spec and hand it to the model as an extra_specs entry:

from castia import Depends, Model, Teams, get_model, toolbox_mcp_tool, toolbox_token

@app.activity(Teams.direct)
async def reply(text: str, model: Model = Depends(get_model)) -> str:
    tool = toolbox_mcp_tool(token=await toolbox_token())   # reads TOOLBOX_* env
    return await model.respond_with_tools(
        text, tools=[], activity=None, extra_specs=[tool] if tool else []
    )

toolbox_mcp_tool() (called with no endpoint) reads the environment via resolve_toolbox_endpoint, whose precedence is:

  1. an explicit full URL in TOOLBOX_ENDPOINT / TOOLBOX_MCP_ENDPOINT;
  2. the platform-native TOOLBOX_<NAME>_MCP_ENDPOINT that the azd ai toolbox extension writes, keyed off TOOLBOX_NAME (see platform_endpoint_env);
  3. composed from FOUNDRY_PROJECT_ENDPOINT + TOOLBOX_NAME (+ optional TOOLBOX_VERSION). The unversioned URL resolves the promoted default version, so a version bump needs no redeploy.

It returns None when no toolbox is configured, so "no toolbox" just attaches no tool. Auth is either a bearer token (minted from the container's managed identity by toolbox_token()) or a stored-connection project_connection_id. A Foundry IQ knowledge base is the same shape via knowledge_base_mcp_tool. Use toolbox_mcp_tool(required=True) when the app cannot answer without its toolbox; Castia then raises a specific configuration error instead of silently omitting the tool. Foundry toolbox URLs must include api-version, and toolbox_token() wraps credential failures with toolbox-specific context.

For optimizer-ready toolbox guidance, pass an override map for the selected tools and declare the same pure spec provider with app.tools(...) so python -m castia optimize can emit the federated tools to tools.json:

def web_tools():
    tool = toolbox_mcp_tool(
        allowed_tools=("web",),
        descriptions={
            "web": "Search current public web information."
        },
        param_guidance={
            "web": {
                "search_query": "A concise public web search query."
            }
        },
    )
    return [tool] if tool else []

app.tools(web_tools)

Use names from your server's tools/list result. For the verified web toolbox, the tool is web and its parameter is search_query, not query. Castia emits the selected tool name to tools.json; it accepts toolbox___web only as an older override-key spelling. Unknown or ambiguous tool names raise immediately. If two allowed tools share the same bare name after a ___ federated prefix, use the fully qualified toolbox tool name in descriptions and param_guidance, for example contracts-kb-mcp___knowledge_base_retrieve. Guidance is folded into server_description and an optimizer sidecar. It does not replace the upstream tool schema or turn MCP into local function execution. Private sidecars are stripped before the Responses API call.

app.tools(...) declares tools for baseline generation; it does not attach them to a model request. The handler must pass the same specs, with current authentication, to respond_with_tools. Keep token acquisition out of the registered provider so baseline checks remain offline. The complete application shows both paths.

Deploying: the azd ai toolbox extension writes TOOLBOX_<NAME>_MCP_ENDPOINT into the azd environment, but does not auto-inject it into a hosted container — declare that env passthrough on your container yourself (there is no azure.yaml/manifest step in castia for it).

Gotcha: do not copy rai_config.rai_policy_name: Microsoft.Default from the azd ai toolbox create --help example — it is invalid on the project and 500s at tool enumeration (tools/list). Omit the policies block.

Validation status. Validated live (Foundry Responses path, App Insights-traced): the end-to-end pipe (env → compose URL → attach one mcp tool → tools/list + tools/call), a raw https://ai.azure.com bearer minted in-container (no project_connection_id required), both env forms, and unversioned→default-version resolution. Doc-derived / not yet live: knowledge_base_mcp_tool (Foundry IQ), connection-backed tools (Azure AI Search / remote-MCP / A2A), the Activity path with a toolbox, and approval-gated tools (require_approval other than "never").

Experimental Prompty runtime harness

The default Castia runtime path remains Model.respond(...) and Model.respond_with_tools(...). Prompty support is optional and does not load from import castia; install it explicitly when you want Prompty's runtime/eval harness:

uv pip install "castia[prompty]"

.agent_configs remains the Foundry Agent Optimizer contract. The Prompty helper projects the resolved Castia config into an in-memory Prompty agent instead of replacing optimizer files. For hosted agents, prompty_runner_provider does the whole setup once (Foundry connection, config load, optional toolbox preflight, runner build) and caches the result; failures are not cached, so the next turn retries:

from pathlib import Path

from castia import Agent, Teams
from castia.inference.tools import graph_tools
from castia.prompty import ToolboxRuntimeConfigError, prompty_runner_provider
from castia.protocols.activity import Activity

app = Agent(name="contracts-agent")
runner = prompty_runner_provider(
    Path(__file__).parent / ".agent_configs",
    tools=[*graph_tools()],  # Castia Tool objects and Prompty tool defs mix
)


@app.activity(Teams.direct)
async def reply(text: str, activity: Activity) -> str:
    try:
        return await (await runner()).turn(text, activity=activity)
    except ToolboxRuntimeConfigError as error:
        return f"Toolbox is not configured: {error}"
Argument Behavior
config AgentConfig, a .agent_configs path, or None for the default.
prompty_path Sidecar .prompty file; extra tools are appended unless the file already defines that name.
tools Castia Tool objects (run host-side with the turn's activity) and Prompty tool definitions. Duplicate names raise PromptyIntegrationError.
toolbox None uses the toolbox when TOOLBOX_* env resolves, True requires it, False disables it, a list requires exactly those names. A failed preflight raises ToolboxRuntimeConfigError.
toolbox_descriptions Description overrides; optimizer tool_definitions in the config win.

PromptyRunner.turn(text, *, activity=None, loop=None, **inputs) passes activity to Castia tools that accept it (for example agentic-user Graph tools); without it, the ambient Activity turn is used. activity is reserved and is not a template input. @app.responses() handlers cannot take an Activity; there, call turn(text) and tools see no activity. Use prompty_tools_from_castia(tools) to get the Prompty definitions and callables yourself, or configured_prompty_runner(config, tools=...) for the lower-level, uncached builder.

Prompty's agent-loop options are available too. Set runner-wide defaults with loop=PromptyLoopOptions(...) on prompty_runner_provider or configured_prompty_runner. To change them for one turn, pass a replacement: runner.turn(text, loop=dataclasses.replace(runner.loop, cancel=token)). An explicit None in the replacement clears that option for the turn.

PromptyLoopOptions field Behavior
guardrails prompty.Guardrails(input=, output=, tool=). Denied input/output raises prompty.GuardrailError.
on_event Prompty loop event callback (turn, LLM, tool, steering events).
cancel, steering prompty.CancellationToken / prompty.Steering; usually set per turn.
context_budget, compaction Trim or summarize the conversation when it exceeds the budget.
parallel_tool_calls, max_llm_retries Forwarded as-is; unset keeps Prompty's default.

Agents built from AgentConfig also accept history on turn(): prior messages ([{"role": ..., "content": ...}], oldest first) rendered between the system prompt and the new turn. activity and loop are reserved turn() keywords and are never sent as Prompty template inputs.

Telemetry matches the Model path:

  • Each Castia or toolbox tool call emits an execute_tool span; Tool.kind becomes gen_ai.tool.type (default function; set kind, such as graph_iq, on your own tools to classify them).
  • Token usage is summed across the tool loop and returned in the Responses usage object (both Model and Prompty paths).
  • Hosting-layer invoke_agent, execute_tool, and model spans go to Agent 365 like the Model path. Prompty's own pipeline spans (turn_async, run_async) are not A365 GenAI spans; they appear only in App Insights and local sinks.
  • turn() called outside a hosted request has no Foundry agent identity on its spans.

register_prompty_otel_tracing() registers Prompty's OTel backend. Prompty's inputs and result attributes are dropped unless AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED=true (or enable_content_recording=True), because they can carry prompts and tool results. When Castia observability is configured, the agent-identity span processor stamps Prompty spans with Foundry agent/project metadata.

For local development, register a Castia sink (for example register_trace_sink("jsonl", jsonl_trace_sink(".castia/traces/live.jsonl"))) and call register_prompty_trace_sinks(). Prompty turn_async / run_async spans then flow into the same local trace records as Castia runtime/model/tool steps. Inputs and results are still omitted unless AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED=true or register_prompty_trace_sinks(enable_content_recording=True) is used; set CASTIA_PROMPTY_TRACE_INTERNAL=true only when debugging Prompty lifecycle internals such as prepare_async or render_async.

The local JSONL stream can be summarized without cloud access:

python -m castia observe local-traces --path .castia/traces/live.jsonl --limit 20
python -m castia observe local-traces --path .castia/traces/live.jsonl --kind prompty

For a Prompty-owned tool loop, Castia provides a local toolbox MCP executor. This is different from the default server-side Responses mcp spec above: Prompty receives a model function-tool call, Castia calls the toolbox MCP endpoint host-side, then Prompty feeds the result back into the loop.

from castia.prompty import (
    ToolboxMcpClient,
    configured_prompty_runner,
    register_toolbox_function,
    toolbox_preflight,
    toolbox_prompty_tools_from_mcp,
)

preflight = await toolbox_preflight(
    ("contracts-kb-mcp___knowledge_base_retrieve",),
)
if not preflight.ok:
    raise RuntimeError("\n".join(preflight.diagnostics))

client = ToolboxMcpClient()  # resolves TOOLBOX_* env and mints ai.azure.com tokens
tools = await toolbox_prompty_tools_from_mcp(
    ("contracts-kb-mcp___knowledge_base_retrieve",),
    client=client,
    descriptions={
        "contracts-kb-mcp___knowledge_base_retrieve":
            "Retrieve cited grounding passages from contracts and policies.",
    },
)
register_toolbox_function("contracts-kb-mcp___knowledge_base_retrieve", client=client)
runner = configured_prompty_runner(config, tools=tools)

toolbox_prompty_tools_from_mcp(...) reads the authoritative tools/list inputSchema and projects it into Prompty function tools, preserving required fields, arrays, nested objects, descriptions, and additionalProperties where Prompty exposes those fields. Use this instead of hand-writing toolbox_prompty_tools(...) whenever the toolbox endpoint is available; the older helper remains for offline/static compatibility but can drift from the real MCP schema. toolbox_preflight(...) resolves the endpoint, mints the same https://ai.azure.com/.default bearer Castia uses at runtime, calls tools/list, and reports missing allowed tool names with diagnostics.

prompty_runner_provider does the preflight and schema projection above and wires toolbox callbacks into the runner directly (no global register_toolbox_function); use these pieces only for custom wiring.

This Prompty path is experimental. It does not replace Model.respond_with_tools, and server-side Foundry MCP execution remains the validated default path.

The newer issue #13 consumer proof verified direct and applied-candidate web guidance from a local process against live Foundry services. Its 16/16 calls preserve native MCP execution and the upstream schema. Those controlled fixtures were not a new optimizer run or a new hosted deployment.

Protocols

castia publishes handlers for the protocols in PUBLISHABLE_PROTOCOLS:

  • Activity — Teams / Bot Framework message and invoke turns.
  • responses — the OpenAI responses wire shape.
  • invocations — Foundry invoke envelopes (tool execution, agent-to-agent).

Microsoft 365 publish dry-run

For hosted agents with an Activity handler, Castia can prepare a Microsoft 365 publish payload without submitting anything to Foundry:

python -m castia publish microsoft365 --mode autopilot --dry-run \
  --project-endpoint https://<account>.services.ai.azure.com/api/projects/<project> \
  --agent-name contracts \
  --agent-display-name "Contracts" \
  --short-description "Reviews contracts." \
  --full-description "Reviews contracts and prepares evidence-backed reports." \
  --developer-name "Caldova" \
  --developer-website-url https://caldova.com \
  --privacy-url https://caldova.com/privacy \
  --terms-of-use-url https://caldova.com/terms \
  --color-icon color.png \
  --outline-icon outline.png \
  --blueprint-client-id <agent.blueprint.client_id>

Autopilot mode targets the preview publish API, forces tenant scope, uses the digital-worker agentic user template, and requires the blueprint client id from azd ai agent show. Teams mode targets the stable v1 publish API, supports Shared or Tenant scope, and requires --bot-service-arm-id.

The command validates that the app registers Activity protocol, metadata URLs are HTTPS, the color icon is a PNG exactly 192x192, and the outline icon is a PNG exactly 32x32. Dry-run output writes a redacted JSON artifact containing payload fields plus icon hashes and dimensions; it does not write bearer tokens or full icon base64 blobs. If the app registers targeted commands, the artifact also includes a teamsManifestPatch with bots[].supportsTargetedMessages and bots[].commandLists[] metadata for Teams discoverability. Castia records that patch for review but does not include it in the live publish payload yet because publish-endpoint support for commandLists has not been verified in this SDK slice. Live --submit and package download are reserved for a later explicit publishing slice.

Observability & evaluation

castia configures Foundry/Agent 365 telemetry for you when the agent starts. Castia emits client-side GenAI spans by default so the SDK owns an app-level trace for every protocol. Hosted Foundry agents can also receive server-side Responses spans from the platform (cloud_RoleName == "responsesapi"). Treat Castia spans as authoritative for SDK behavior; they carry castia.telemetry.source = "castia" and cover activity, responses, chat, invocations, and streaming handlers.

Recording content is what makes client-side traces evaluable — trace-based evaluators read the input/output text from GenAI spans when it is present. When enabled, the standard Foundry GenAI instrumentor records content on the client-side chat {model} span as gen_ai.input.messages and gen_ai.output.messages. Turn it on deliberately via configure_observability:

from castia.observe.configuration import configure_observability

# Records prompt/response text onto GenAI spans so traces can be evaluated.
configure_observability(enable_content_recording=True)

In hosted Foundry agents, the platform can also emit server-side responsesapi GenAI spans. Those spans are outside the Castia process, and their content recording policy is controlled by Foundry, not by Castia's enable_content_recording flag.

Resolution order for each flag is explicit argument > environment variable > default:

Flag Argument Environment variable Default
Content recording enable_content_recording AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED off
GenAI tracing enable_genai_tracing AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING on
ASGI internal event span tracing — CASTIA_OTEL_TRACE_ASGI_INTERNAL off
Azure metadata span tracing — CASTIA_OTEL_TRACE_MSI_TOKEN off
Infrastructure span tracing — CASTIA_OTEL_TRACE_INFRASTRUCTURE off

Passing nothing preserves the default behavior. Telemetry setup is best-effort: a failure is logged, never raised, so it can't break startup or a turn.

Castia suppresses OpenTelemetry ASGI internal event child spans (send and receive) by default. Streaming Responses can otherwise emit one near-zero- duration POST /responses http send span per chunk, and receive spans describe framework event handling rather than agent work. Server/request spans plus semantic GenAI/tool spans are still recorded. Castia also records aggregate stream transport attributes (stream.chunk_count, stream.first_chunk_ms, stream.last_chunk_ms, stream.bytes_sent) on the request span when available, without recording streamed text. Set CASTIA_OTEL_TRACE_ASGI_INTERNAL=true only when debugging the ASGI transport itself. CASTIA_OTEL_TRACE_ASGI_SEND=true remains accepted as a compatibility alias.

Castia suppresses fast Azure metadata/IMDS dependency probes by default, while keeping slow calls and spans with exception evidence. If a new platform probe adds noise before Castia has a built-in rule, register a bounded escape hatch:

from castia import suppress_telemetry_spans

suppress_telemetry_spans("future-probe", name_contains="/metadata/new-token")

The same behavior can be configured operationally with CASTIA_OTEL_SUPPRESS_SPAN_NAME_CONTAINS, CASTIA_OTEL_SUPPRESS_SPAN_TARGET_CONTAINS, and CASTIA_OTEL_SUPPRESS_SPAN_MAX_DURATION_MS. Set CASTIA_OTEL_TRACE_INFRASTRUCTURE=true to disable Castia infrastructure suppression while debugging.

Agent 365 export

Hosted Foundry agents export GenAI spans to Agent 365 with the S2S flow; no client secret or extra configuration is needed. Castia mints the token in two steps: first a blueprint managed-identity assertion, then an app-only client-credentials grant as the agent instance for api://9b975845-388f-4429-889e-eab1ef63949c/.default. Tokens are cached until five minutes before expiry. On the Agent 365 export path only, Castia rewrites gen_ai.agent.id to the instance client id and microsoft.tenant.id to the agent tenant. Azure Monitor and the Foundry Traces UI keep <name>:<version>. Token failures back off from 30 s to 15 min. Permanent failures (token endpoint 4xx, managed identity unavailable) drop the batch; transient ones queue it for the distro's durable replay.

Environment variable Purpose
FOUNDRY_AGENT_TENANT_ID, FOUNDRY_AGENT_BLUEPRINT_CLIENT_ID Platform-injected; required for S2S export
FOUNDRY_AGENT_DEFAULT_INSTANCE_CLIENT_ID Platform-injected agent instance id (falls back to FOUNDRY_AGENT_INSTANCE_CLIENT_ID)
CASTIA_A365_AGENT_INSTANCE_ID Optional override for the instance id
CASTIA_A365_EXPORT false turns export off (overriding ENABLE_A365_OBSERVABILITY_EXPORTER); true without hosted identity uses the distro default resolver

Without the hosted identity (local runs), Agent 365 export is off, so local runs log no token warnings.

Local Castia trace records can also be redirected into the active OpenTelemetry pipeline. Register otel_trace_sink() after configuring observability when you want the same runtime/model/tool/Prompty local records to appear in App Insights with castia.trace.* correlation attributes:

from castia import otel_trace_sink, register_trace_sink

register_trace_sink("otel", otel_trace_sink())

Security caveat: enabling content recording writes prompt and response text to Application Insights. Only enable it where storing that content is acceptable for your data-handling and privacy requirements.

Building a scored eval suite

Once your traces are evaluable, python -m castia eval wraps the azd ai agent eval extension to synthesize and run a scored eval suite — a generated JSONL dataset plus an auto-generated, weighted rubric (a custom multi-dimension evaluator):

# Offline gate — validate eval.yaml + rubric files, no Azure, free in CI:
python -m castia eval check

# Synthesize a rubric + dataset from the agent instruction (billable):
python -m castia eval generate --agent my-agent --max-samples 25

# Re-upload locally edited rubric/dataset files as a new version:
python -m castia eval update --evaluator-only

# Submit a scored run against the deployed agent (billable):
python -m castia eval run

check is a pure, offline referential-integrity gate: it resolves every evaluator/dataset local_uri and validates each rubric dimensions file. generate and run submit billable Foundry jobs, so both accept --dry-run to print the resolved azd command line without submitting anything. The YAML checks need uv pip install "castia[deploy]". The live wrappers also require a separately installed and authenticated azd with azd ai agent eval.

The rubric dimensions file is a bare JSON list where each entry is keyed by id (a stable slug like correct_outcome), with an optional always_applicable: true on the catch-all dimension. That cross-SDK shape is pinned in the monorepo at spec/conformance/rubric/.

Optimizer-readiness

The Foundry Agent Optimizer searches for a better system prompt (and, when you declare tools, better tool descriptions) by running candidates against your eval suite. Making a castia agent optimizer-ready is three things: install the runtime resolver, ship a baseline config, and source your model + instructions from that config instead of hardcoding them — so the optimizer can swap in a candidate with zero handler changes.

Bind your model dependency with configured_model() and thread its resolved instructions through:

from castia import Depends, Model, Router, configured_model

router = Router()
gpt = configured_model()  # resolves baseline (or the injected candidate) once

@router.responses()
async def reply(text: str, model: Model = Depends(gpt)) -> str:
    return await model.respond(text)   # instructions flow into responses.create

configured_model() calls load_agent_config(), which is best-effort: if the optimizer package isn't installed, resolution fails, or no config is found, it degrades to environment defaults (AZURE_AI_MODEL_DEPLOYMENT_NAME, no instructions). The agent can still start, but that fallback does not preserve the candidate's behavior. Inspect AgentConfig.source before reporting that a candidate loaded.

Ship a baseline under .agent_configs/baseline/:

.agent_configs/baseline/
  metadata.yaml       # model, instruction_file, (optional) tool_file pointers
  instructions.md     # the system prompt the optimizer tunes
  tools.json          # optional: tool specs the optimizer may reword

If your agent declares tools with app.tools(...), keep the baseline tools.json in sync with the code using the build-time reconciler:

python -m castia optimize          # write/refresh .agent_configs/baseline/tools.json
python -m castia optimize --check   # CI drift gate (exits non-zero, writes nothing)

Then submit optimizer jobs directly through castia. This path reads the same eval.yaml and baseline files, inlines local JSONL datasets for the request, and preserves tools.json so toolbox/federated tool descriptions are visible to the optimizer:

python -m castia optimize run --dry-run   # FREE: print the exact payload
python -m castia optimize run             # billable: submit to Foundry
python -m castia optimize status --watch  # poll the latest castia-submitted job
python -m castia optimize apply           # write the best candidate locally
python -m castia optimize cancel          # cancel the latest job

optimize run uses FOUNDRY_PROJECT_ENDPOINT (or --project-endpoint) and the model/evaluator/dataset declarations in eval.yaml. optimize apply materializes the candidate under .agent_configs/<candidate-id>/ with metadata.yaml, instructions.md, tools.json, and skills/ as returned by Foundry. Deployment is still an azd handoff: set OPTIMIZATION_LOCAL_DIR=.agent_configs and OPTIMIZATION_CANDIDATE_ID=<candidate-id>, then deploy the hosted agent with your existing azd workflow.

For local functional checks, use python -m castia observe drift with an explicit project configuration and your local Azure credentials. See the lifecycle guide for coverage, limits, and report handling. The CLI does not install a schedule or submit fine-tuning jobs.

The optional .github/workflows/foundry-optimizer-live.yml workflow runs on manual dispatch only. It submits one billable optimizer candidate against a pre-deployed Foundry smoke agent, waits for completion, and applies the best candidate into a throwaway runner directory. To use this optional workflow, configure the foundry-live GitHub environment with OIDC Azure login secrets (AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_SUBSCRIPTION_ID) and these variables:

Variable Purpose
FOUNDRY_PROJECT_ENDPOINT Target Foundry project endpoint for local/process checks; do not put this under hosted azure.yaml env.
FOUNDRY_OPTIMIZER_AGENT_NAME Pre-deployed smoke agent name.
FOUNDRY_OPTIMIZER_AGENT_VERSION Optional pinned hosted-agent version.
FOUNDRY_EVAL_MODEL Optional evaluator model, defaults to gpt-4o.
FOUNDRY_OPTIMIZE_MODEL Optional optimizer model, defaults to gpt-5.

Config resolution order is first-wins: OPTIMIZATION_CONFIG (inline JSON) → resolver API (OPTIMIZATION_CANDIDATE_ID + OPTIMIZATION_RESOLVE_ENDPOINT) → local .agent_configs/ → environment defaults. An explicit config_dir argument (or OPTIMIZATION_LOCAL_DIR) affects only the local source — pass it anchored to your app root so the baseline resolves the same under python app.py and python -m castia. That contract is pinned for every SDK in spec/conformance/optimization/.

Switching to a fine-tuned model

The optimizer's model search can land on a reasoning model — an o-series or GPT-5 deployment, or one you mint yourself with fine-tuning. Reasoning models take a reasoning.effort control that plain chat models don't. Model exposes it as reasoning_effort (minimal|low|medium|high):

from castia import use_model

o4 = use_model("o4-mini-rft-2025", reasoning_effort="high")

An unset effort omits the field entirely, so chat models are called exactly as before; a bad level raises at construction rather than as a 400 mid-turn. An operator can also switch a deployed agent onto a reasoning model with zero code by setting MODEL_REASONING_EFFORT — an explicit argument still wins. Because configured_model() builds its Model through the same path, that env override flows through to the resolved candidate automatically.

Responses-only constraint: the optimizer accepts only single-protocol responses agents — submitting a multi-protocol agent (one that also speaks activity/invocations) is rejected with a 400 at submission. Project a responses-only sibling from the same handler code with app.responses_only(), deploy that as its own service, optimize it, then apply the winning .agent_configs candidate back to your live agent.

The runtime resolver and reconciler need the optimizer extra, uv pip install --prerelease=allow "castia[optimize]". Fine-tuning remains a separate build-time operation: train, deploy the resulting model, evaluate the deployment, then include that deployment in optimizer model search if desired.

Fine-tuning: SFT, DPO, and RFT

Fine-tuning is an optional, separately authorized training operation. A resulting model still needs a separate deployment before an application or optimizer search can use it. Castia supplies builders, offline validators, and an explicit billable submit command. Passing an offline check does not authorize training or checkpoint deployment.

# Offline gates — validate datasets, no Azure, free in CI:
python -m castia finetune check --type sft --dataset train.jsonl --validation val.jsonl
python -m castia finetune check --type dpo --dataset train.jsonl
python -m castia finetune check --type rft --dataset train.jsonl --validation val.jsonl --grader grader.json

# Bridge an eval rubric into a score_model grader (offline):
python -m castia finetune grader --rubric rubric.json --model gpt-4o --out grader.json

# Preview payloads without uploads or submission:
# Removing --dry-run starts billable training and needs separate approval.
python -m castia finetune submit --type sft --model gpt-4.1-mini \
  --dataset train.jsonl --validation val.jsonl --n-epochs 2 --dry-run
python -m castia finetune submit --type dpo --model gpt-4.1 \
  --dataset train.jsonl --beta 0.1 --dry-run
python -m castia finetune submit --model o4-mini --dataset train.jsonl \
  --validation val.jsonl --grader grader.json --reasoning-effort high --dry-run

SFT datasets are JSONL chat messages[] rows with at least one user and one assistant turn, and the final message role must be assistant. SFT accepts optional n_epochs, batch_size, and learning_rate_multiplier hyperparameters.

DPO datasets are JSONL preference rows with input.messages, preferred_output, and non_preferred_output. The output arrays may contain assistant or tool messages and must include at least one assistant message. DPO accepts the SFT hyperparameters plus beta and l2_multiplier.

RFT trains a reasoning model against a grader. Its datasets are JSONL chat messages[] rows whose final message role must be user, with extra top-level keys as the item.* ground truth; both train and validation splits are required. A grader is one of string_check, text_similarity, score_model, python, multi, or endpoint (preview); templates reference two namespaces only — {{ sample.output_text }} and {{ item.<field> }}. rubric_to_score_model() bridges an eval rubric straight into a score_model grader — the natural tie between the evaluate and switch-models steps.

⚠️ Provisional / doc-derived. The grader JSON schema, the RFT hyperparameter names, and the SFT/DPO/RFT fine_tuning.jobs.create payload shapes are doc-derived and have not been confirmed against live Castia training jobs. The builders and validators are fully offline-tested; treat submitted wire shapes as provisional until real submissions validate them. The RFT language-neutral contract is pinned in spec/conformance/graders/.

Design

castia is deliberately import-cheap: import castia never pulls in the instrumented Azure/OpenAI/httpx stacks, so telemetry can be configured before those libraries load. The heavy imports are deferred into the methods that need them.

License

MIT © 2026 Seth Juarez

Metadata

Release files for castia 0.18.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for castia 0.18.0
File Size Uploaded Provenance Actions
castia-0.18.0.tar.gz 399.4 kB With provenance Details for castia-0.18.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for castia 0.18.0
File Interpreter ABI Platform Actions
castia-0.18.0-py3-none-any.whl Python 3 none any Details for castia-0.18.0-py3-none-any.whl

Total release size: 682.9 kB

Release files / castia-0.18.0.tar.gz

Download URL castia-0.18.0.tar.gz
Size 399.4 kB
Tags Source
SHA-256 checksum
How to use checksums
6aaecb7691a2d3f569de0957a187ff05ad094794a68e6dd52e62889d24f8b297
BLAKE2b-256 checksum
How to use checksums
cb78605d104d79e59086a81d30cb00fe0870b2b03512078a496a17c58f2b01a4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 3, 2026.

Transparency log

Release files / castia-0.18.0-py3-none-any.whl

Download URL castia-0.18.0-py3-none-any.whl
Size 283.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c76055b2f7c2f73a57ecf144307d9352f6a72a99f420427557712698aef840cf
BLAKE2b-256 checksum
How to use checksums
506181611a26a06945824991b2295b689323701dfba22dcae84fc77756565abd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 3, 2026.

Transparency log

Security for castia 0.18.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for castia-0.18.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 3, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.18.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page