Foundry Hosted Agents (Azure)

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

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

Use the build scaffold when packaging a Fabric Node or Temporal worker for Azure-managed compute. Use the Agent Service client when an existing Fabric agent needs to invoke or administer an Azure AI Foundry agent.

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:

1. create or reuse a thread;
2. add a user message;
3. create a run for the configured agent;
4. optionally poll;
5. 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

Model provider

On Azure compute with workload identity, 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',
  }),
});

Set AZURE_OPENAI_ENDPOINT and AZURE_OPENAI_DEPLOYMENT; supply FOUNDRY_AGENT_TOKEN when your host injects a token. On ACA, AKS, or a VM with managed identity, install @azure/identity and the provider falls back to DefaultAzureCredential. See model providers → Foundry runtime.

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.

See also

• Azure overview
• Live tests
• Capability matrix