Invoke Foundry Agent

Invoke deployed agents in Azure AI Foundry. Manage sessions and file operations for hosted agents.

Quick Reference

When to Use This Skill

• Send messages to a deployed agent (single or multi-turn)
• Create/manage sessions for hosted agents
• Upload/download files to/from hosted agent sessions
• Test agent behavior after creation or deployment

MCP Tools

For session file operation tools (session_file_upload, session_file_download, session_file_list, session_file_delete, session_file_stat, session_file_mkdir), see File Operations.

Protocols

Hosted agents support two invocation protocols declared at deployment time.

Key difference: responses takes a natural language inputText message with platform-managed history. invocations is bytes in, bytes out — the request body is forwarded as-is to the container and the raw response is returned. The developer defines the schema; the platform is pure pass-through. See Invocations Protocol Guide for I/O details, schema discovery, and examples.

⚠️ Critical for invocations: inputText is forwarded as the raw HTTP request body. The agent developer defines what the container accepts. Do not guess — fetch the agent's OpenAPI spec or inspect its source code first.

💡 Tip: The agent_invoke MCP tool supports both protocols. Set protocol: 'invocations' when targeting an invocations-protocol agent.

Workflow

Step 1: Verify Agent Readiness

Use agent_get to verify the agent exists. For hosted agents, also verify the targeted version is active.

Step 2: Create Session (Hosted Agents)

For hosted agents, create a session before invoking using session_create with projectEndpoint and agentName. Optionally provide a sessionId (must match ^[A-Za-z0-9_-]{8,128}$). Store the returned sessionId for subsequent calls.

⚠️ Skip this step for prompt agents — they do not use sessions.

For full session lifecycle details, see Session Management.

Step 3: Invoke Agent

Use the project endpoint and agent name from the project context. Use agent_invoke with:

• projectEndpoint, agentName, inputText (required)
• agentVersion, conversationId, sessionId, protocol, stream (optional)

Responses protocol (default): inputText is a natural language message string. Multi-turn via conversationId.

Invocations protocol: Set protocol: 'invocations'. This is bytes in, bytes out — inputText is forwarded as the raw HTTP request body to the container. The developer defines the expected schema.

⚠️ Do not guess the invocations request body. To discover the expected schema:

1. Fetch the OpenAPI spec: GET {projectEndpoint}/agents/{agentName}/endpoint/protocols/invocations/docs/openapi.json (if the developer registered one)
2. Inspect the agent's route handler code or README for the expected payload shape
3. If unknown, ask the user for the agent's API contract before invoking

Example invocations call (agent expects {"message": "<text>"}):

agent_invoke(projectEndpoint, agentName, inputText: "{\"message\":\"hello\"}", protocol: "invocations", sessionId: "<id>")

See Invocations Protocol Guide for full details and examples.

Step 4: Multi-Turn Conversations

Responses protocol → Pass conversationId from previous response to continue the thread. Platform manages history.

Invocations protocol → Reuse same sessionId; conversation state is agent-managed via $HOME. Do not pass conversationId — it has no effect for invocations.

Step 5: File Operations (Hosted Agents)

Upload/download files to pass data to and retrieve results from agents. All file operations require an active session. See File Operations.

Step 6: Clean Up

Use session_delete to release compute resources when done. Undeleted sessions expire per platform policies.

Agent Type Differences

Error Handling

Additional Resources

• Session Management
• File Operations
• Foundry Hosted Agents
• Foundry Samples