1# Invoke Foundry Agent
2 
3Invoke deployed agents in Azure AI Foundry. Manage sessions and file operations for hosted agents.
4 
5## Quick Reference
6 
7| Property | Value |
8|----------|-------|
9| Agent types | Prompt (LLM-based), Hosted |
10| MCP server | `azure` |
11| Key Foundry MCP tools | `agent_invoke`, `agent_get`, `session_create`, `session_get`, `session_delete`, `session_list` |
12| File operation tools | `session_file_upload`, `session_file_download`, `session_file_list`, `session_file_delete`, `session_file_stat`, `session_file_mkdir` |
13| Conversation support | Single-turn and multi-turn (via `conversationId` for responses protocol, via session state for invocations protocol) |
14| Session support | Managed sessions for hosted agents (via `session_create`) |
15| Protocols | `responses` (OpenAI-compatible), `invocations` (custom payloads) |
16 
17## When to Use This Skill
18 
19- Send messages to a deployed agent (single or multi-turn)
20- Create/manage sessions for hosted agents
21- Upload/download files to/from hosted agent sessions
22- Test agent behavior after creation or deployment
23 
24## MCP Tools
25 
26| Tool | Description | Parameters |
27|------|-------------|------------|
28| `agent_invoke` | Send a message to an agent and get a response | `projectEndpoint`, `agentName`, `inputText` (required); `agentVersion`, `conversationId`, `sessionId`, `protocol`, `stream` (optional) |
29| `agent_get` | Get agent details to verify existence and type | `projectEndpoint` (required), `agentName` (optional) |
30| `session_create` | Create a new session for a hosted agent | `projectEndpoint`, `agentName` (required); `sessionId` (optional) |
31| `session_get` | Get session status and details | `projectEndpoint`, `agentName`, `sessionId` (required) |
32| `session_delete` | Delete a session and release compute | `projectEndpoint`, `agentName`, `sessionId` (required) |
33| `session_list` | List sessions with pagination | `projectEndpoint`, `agentName` (required); `limit`, `order`, `after`, `before` (optional) |
34| `session_logstream` | Stream console logs (stdout/stderr) from a session | `projectEndpoint`, `agentName`, `sessionId` (required); `maxLines` (optional) |
35 
36For 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](references/file-operations.md).
37 
38## Protocols
39 
40Hosted agents support two invocation protocols declared at deployment time.
41 
42| Protocol | Recommended Version | Route | Best For |
43|----------|-------------------|-------|----------|
44| `responses` | `1.0.0` | `.../agents/{agentName}/endpoint/protocols/openai/responses` | Conversational agents, OpenAI-compatible |
45| `invocations` | `1.0.0` | `.../agents/{agentName}/endpoint/protocols/invocations` | Custom payloads, protocol bridges, webhook callers |
46 
47Key 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](references/invocations-protocol.md) for I/O details, schema discovery, and examples.
48 
49> ⚠️ **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.
50 
51> 💡 **Tip:** The `agent_invoke` MCP tool supports both protocols. Set `protocol: 'invocations'` when targeting an invocations-protocol agent.
52 
53## Workflow
54 
55### Step 1: Verify Agent Readiness
56 
57Use `agent_get` to verify the agent exists. For hosted agents, also verify the targeted version is `active`.
58 
59### Step 2: Create Session (Hosted Agents)
60 
61For 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.
62 
63> ⚠️ Skip this step for prompt agents — they do not use sessions.
64 
65For full session lifecycle details, see [Session Management](references/session-management.md).
66 
67### Step 3: Invoke Agent
68 
69Use the project endpoint and agent name from the project context. Use `agent_invoke` with:
70- `projectEndpoint`, `agentName`, `inputText` (required)
71- `agentVersion`, `conversationId`, `sessionId`, `protocol`, `stream` (optional)
72 
73**Responses protocol** (default): `inputText` is a natural language message string. Multi-turn via `conversationId`.
74 
75**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.
76 
77> ⚠️ **Do not guess the invocations request body.** To discover the expected schema:
78> 1. **Fetch the OpenAPI spec**: `GET {projectEndpoint}/agents/{agentName}/endpoint/protocols/invocations/docs/openapi.json` (if the developer registered one)
79> 2. Inspect the agent's **route handler code** or README for the expected payload shape
80> 3. If unknown, ask the user for the agent's API contract before invoking
81 
82Example invocations call (agent expects `{"message": "<text>"}`):
83 
84```text
85agent_invoke(projectEndpoint, agentName, inputText: "{\"message\":\"hello\"}", protocol: "invocations", sessionId: "<id>")
86```
87 
88See [Invocations Protocol Guide](references/invocations-protocol.md) for full details and examples.
89 
90### Step 4: Multi-Turn Conversations
91 
92**Responses protocol** → Pass `conversationId` from previous response to continue the thread. Platform manages history.
93 
94**Invocations protocol** → Reuse same `sessionId`; conversation state is agent-managed via `$HOME`. Do **not** pass `conversationId` — it has no effect for invocations.
95 
96### Step 5: File Operations (Hosted Agents)
97 
98Upload/download files to pass data to and retrieve results from agents. All file operations require an active session. See [File Operations](references/file-operations.md).
99 
100### Step 6: Clean Up
101 
102Use `session_delete` to release compute resources when done. Undeleted sessions expire per platform policies.
103 
104## Agent Type Differences
105 
106| Behavior | Prompt Agent | Hosted Agent |
107|----------|--------------|--------------|
108| Readiness | Immediate | After deployment, version must be `active` |
109| Session | Not applicable | Required via `session_create` |
110| Multi-turn | Via `conversationId` | Via `conversationId` (responses) or session state (invocations) |
111| File operations | ❌ | ✅ via session file tools |
112| Protocol | `responses` only | `responses` or `invocations` |
113 
114## Error Handling
115 
116| Error | Cause | Resolution |
117|-------|-------|------------|
118| Agent not found | Invalid name or endpoint | Use `agent_get` to list agents |
119| Hosted agent not active | Version still provisioning or failed | Check version status via `agent_get` |
120| Session not found | Invalid ID or expired | Create new session with `session_create` |
121| Invocation failed | Model error, timeout, or invalid input | Check agent logs, verify model deployment |
122| Invocations schema mismatch | Request body does not match what the agent expects | Inspect agent's route handler or API docs for the correct JSON schema; do not guess |
123| File operation failed | Session not active or invalid path | Verify session with `session_get` |
124| Permission error | Missing RBAC | Follow [troubleshoot skill](../troubleshoot/troubleshoot.md) |
125| Rate limit exceeded | Too many requests | Implement backoff and retry |
126 
127## Additional Resources
128 
129- [Session Management](references/session-management.md)
130- [File Operations](references/file-operations.md)
131- [Foundry Hosted Agents](https://learn.microsoft.com/en-us/azure/ai-foundry/agents/concepts/hosted-agents?view=foundry)
132- [Foundry Samples](https://github.com/azure-ai-foundry/foundry-samples)
133