Use function calling with Microsoft Foundry agents

Use function calling to extend Microsoft Foundry agents with custom functions. Define tools with Python, C#, TypeScript, or REST and return outputs to the agent.

Microsoft Foundry agents support function calling, which lets you extend agents with custom capabilities. Define a function with its name, parameters, and description, and the agent’s Foundry model can request your app to call it. Your app executes the function and returns the output. The agent then uses the result to continue the conversation with accurate, real-time data from your systems.

Runs expire 10 minutes after creation. Submit your tool outputs before they expire.

You can run agents with function tools in the Microsoft Foundry portal. However, the portal doesn’t support adding, removing, or updating function definitions on an agent. Use the SDK or REST API to configure function tools.

Usage support

The following table shows SDK and setup support.

Microsoft Foundry support	Python SDK	C# SDK	JavaScript SDK	Java SDK	REST API	Basic agent setup	Standard agent setup
✔️	✔️	✔️	✔️	✔️	✔️	✔️	✔️

Prerequisites

Before you start, make sure you have:

• A basic or standard agent environment.

• A Foundry project and a deployed model.

• The SDK package for your language:

  • Python: azure-ai-projects (latest)
  • .NET: Azure.AI.Extensions.OpenAI
  • TypeScript: @azure/ai-projects (latest)
  • Java: azure-ai-agents

  For installation and authentication steps, see the quickstart.

If you use DefaultAzureCredential, sign in by using az login before running the samples.

Create an agent with function tools

Function calling follows this pattern:

1. Define function tools — Describe each function’s name, parameters, and purpose.
2. Create an agent — Register the agent with your function definitions.
3. Send a prompt — The agent analyzes the prompt and requests function calls if needed.
4. Execute and return — Your app runs the function and submits the output back to the agent.
5. Get the final response — The agent uses your function output to complete its response.

Verify function calling works

Use these checks to confirm function calling is working:

1. Your first response contains an output item with type set to function_call.
2. Your app executes the requested function by using the returned arguments.
3. Your app submits a follow-up response that includes a function_call_output item and references the previous response, and the agent returns a natural-language answer.

If you use tracing in Microsoft Foundry, confirm the tool invocation occurred. For guidance on validating tool invocation and controlling tool usage, see Best practices for using tools in Microsoft Foundry Agent Service.

Security and data considerations

• Treat tool arguments and tool outputs as untrusted input. Validate and sanitize values before using them.
• Don’t pass secrets (API keys, tokens, connection strings) in tool output. Return only the data the model needs.
• Apply least privilege to the identity used by DefaultAzureCredential.
• Avoid side effects unless you explicitly intend them. For example, restrict function tools to safe operations, or require explicit user confirmation for actions that change data.
• For long-running operations, return a status immediately and implement polling. The 10-minute run expiration applies to total elapsed time, not individual function execution.

Troubleshooting

Issue	Likely cause	Resolution
Agent returns function call but no final answer.	Tool output not returned to model.	Execute the function, then call responses.create with the tool output and the conversation ID to continue.
No function call occurs.	Function not in agent definition or poor naming.	Confirm the function tool is added to the agent. Use clear, descriptive names and parameter descriptions.
Arguments aren’t valid JSON.	Schema mismatch or model generated incorrect information.	Verify JSON schema uses correct types and required properties. Handle parsing errors gracefully in your app.
Required fields are missing.	Schema doesn’t enforce required properties.	Add "required": [...] array to your parameter schema. Set strict: true for stricter validation.
Tool outputs fail due to expiration.	Run expired (10-minute limit).	Return tool outputs promptly. For slow operations, return a status and poll separately.
Function called with wrong parameters.	Ambiguous function description.	Improve the function description field. Add detailed parameter descriptions with examples.
Multiple function calls in one response.	Model determined multiple functions needed.	Handle each function call in the output array. Return all results in a single responses.create call.
Function not visible in Foundry portal.	Portal doesn’t execute function calls.	Test function calling via SDK or REST API. The portal shows agents but doesn’t invoke functions.

Clean up resources

When you finish testing, delete the resources you created to avoid ongoing costs.

Delete the agent:

curl -X DELETE "$FOUNDRY_PROJECT_ENDPOINT/agents/<AGENT_NAME>-function-calling?api-version=v1" \
  -H "Authorization: Bearer $AGENT_TOKEN"

Delete the conversation:

curl -X DELETE "$FOUNDRY_PROJECT_ENDPOINT/openai/v1/conversations/<CONVERSATION_ID>" \
  -H "Authorization: Bearer $AGENT_TOKEN"

Related content

• Best practices for using tools in Microsoft Foundry Agent Service
• Connect OpenAPI tools to Microsoft Foundry agents
• Microsoft Foundry Quickstart