Foundry Hosted Agents (Azure)

Foundry Hosted Agents are Fabric Harness's primary Azure direction. Fabric supports two related paths:

Build scaffold — fh build --target foundry-hosted-agent emits Docker/azd/Bicep/metadata scaffolding.
Agent Service client/tools — @fabric-harness/azure can invoke and manage Azure AI Foundry Agent Service agents from Fabric agents.

Status (preview). Build scaffold + Foundry Agent Service REST helpers ship today. The runtime adapter that lets Fabric agent code execute inside Foundry's hosted-agent runtime container is deferred — it depends on Foundry preview-SDK GA and the published hosted-agent contract spec (identity headers, lifecycle hooks). Track docs/ROADMAP.md. Exact hosted-agent deployment schemas may evolve with Azure preview APIs.

Build scaffold

fh build --target foundry-hosted-agent

Output:

.fabricharness/build/foundry-hosted-agent/
  Dockerfile
  azure.yaml
  foundry-agent.yaml
  infra/main.bicep
  dist/server.mjs
  manifest.json

Build runtime variants:

fh build --target foundry-hosted-agent --runtime node
fh build --target foundry-hosted-agent --runtime temporal-worker

Deploy the scaffold with Azure Developer CLI:

cd .fabricharness/build/foundry-hosted-agent
azd up

Foundry Agent Service client

import {
  createFoundryAgentServiceClient,
  foundryAgentTool,
} from '@fabric-harness/azure';

const foundry = createFoundryAgentServiceClient({
  projectEndpoint: process.env.AZURE_FOUNDRY_PROJECT_ENDPOINT!,
  agentId: process.env.AZURE_FOUNDRY_AGENT_ID!,
  token: process.env.AZURE_TOKEN!,
});

const fabric = await init({
  tools: [foundryAgentTool(foundry)],
});

This exposes a Fabric tool named foundry_agent with input:

{
  prompt: string;
  threadId?: string;
}

The client performs:

create or reuse a thread;
add a user message;
create a run for the configured agent;
optionally poll;
return thread/run status and messages.

Lifecycle tools

import { foundryAgentLifecycleTools } from '@fabric-harness/azure';

const tools = [
  ...foundryAgentLifecycleTools(foundry),
];

This exposes:

foundry_create_agent
foundry_update_agent
foundry_delete_agent

These are privileged write effects. Gate them with approvals:

const policy = {
  toolPolicy: {
    requireApproval: [
      'foundry_create_agent',
      'foundry_update_agent',
      'foundry_delete_agent',
    ],
  },
};

Identity and audit model

Fabric sessions can record actor identity:

await init({
  actor: {
    agentId: process.env.AZURE_ENTRA_AGENT_ID,
    onBehalfOf: userId,
  },
});

Approval entries should record:

the Foundry/Entra agent identity;
the on-behalf-of user;
the approver;
the tool or command being authorized.

Architecture guidance

Pattern	Use when
Fabric inside Foundry-hosted container	You want Azure-native hosting and per-session compute.
Fabric Temporal worker outside Foundry	You need durable replay, retries, and long approval waits.
Fabric agent invoking Foundry Agent Service	You already have Foundry agents and want Fabric governance/tools around them.

Model provider

Inside the Foundry Hosted Agent runtime, route inference through FoundryRuntimeModelProvider instead of configuring AZURE_OPENAI_API_KEY:

import { FoundryRuntimeModelProvider } from '@fabric-harness/azure/foundry-runtime';
import { init } from '@fabric-harness/sdk';

const fabric = await init({
  modelProvider: new FoundryRuntimeModelProvider({
    defaultModel: 'gpt-4o',
  }),
});

The runtime injects AZURE_OPENAI_ENDPOINT, AZURE_OPENAI_DEPLOYMENT, and FOUNDRY_AGENT_TOKEN at container startup, so no API keys land in your config. Outside the Foundry runtime (any Azure compute with a managed identity), install @azure/identity and the provider falls back to DefaultAzureCredential. See model providers → Foundry runtime.

The Hosted Agent runtime adapter that lets runAgent execute inside Foundry's container is still preview-blocked, but FoundryRuntimeModelProvider works today on any Azure compute (ACA Job, AKS pod, VM) with a managed identity.

Live test

FABRIC_AZURE_FOUNDRY_TEST=1 \
AZURE_FOUNDRY_PROJECT_ENDPOINT=... \
AZURE_FOUNDRY_AGENT_ID=... \
AZURE_TOKEN=... \
pnpm --filter @fabric-harness/azure test

The live test retrieves the configured agent and invokes it with a smoke prompt. Set FABRIC_AZURE_FOUNDRY_POLL=0 to create the run without polling for completion.

What is still left

Full hosted-agent create/update/deploy workflow wired to fh deploy or azd outputs.
Stable schema alignment once Azure Foundry Hosted Agent APIs settle.
Foundry Toolbox and Memory adapters beyond generic tool invocation.
Foundry Activity Protocol integration for durable Temporal activities.