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 three protocols declared at deployment time. They are distinct contracts — pick per use case (an agent may declare more than one and serve them from the same container):
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| `invocations_ws` | `1.0.0` | `wss://.../agents/endpoint/protocols/invocations_ws` | Duplex WebSocket — voice, WebRTC signaling, custom real-time streams. See the dedicated [invocations-ws skill](../invocations-ws/invocations-ws.md); `agent_invoke` does **not** speak WebSocket. |
47 
48Key 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.
49 
50> ⚠️ **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.
51 
52> 💡 **Tip:** The `agent_invoke` MCP tool supports both `responses` and `invocations` protocols. Set `protocol: 'invocations'` when targeting an invocations-protocol agent.
53 
54## Workflow
55 
56### Step 1: Verify Agent Readiness
57 
58Use `agent_get` to verify the agent exists. For hosted agents, also verify the targeted version is `active`.
59 
60### Step 2: Fast smoke test for azd-deployed agents
61 
62When the current folder is an azd agent project and deployment just completed, prefer the azd CLI first:
63 
64```bash
65azd ai agent invoke "hello, are you up?"
66```
67 
68Use `azd ai agent show --output json` only when you need structured status, version, endpoints, or troubleshooting details; a successful remote invocation is the fast smoke test.
69 
70If `azd ai agent invoke` returns a `confirmation_required` envelope, summarize the change and proceed only when the user already requested remote invocation or explicitly consents. Prefer the returned `confirmCommand` over inventing flags. If azd cannot resolve the service or agent name, fall back to the MCP workflow below with the resolved `projectEndpoint` and `agentName`.
71 
72For a post-deploy smoke test, invoke once unless the user explicitly asked to validate multi-turn/session behavior. If that single invoke returns a successful response, the smoke test passes;
73 
74### Step 3: Create Session (Hosted Agents)
75 
76For 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.
77 
78> ⚠️ Skip this step for prompt agents — they do not use sessions.
79 
80For full session lifecycle details, see [Session Management](references/session-management.md).
81 
82### Step 4: Invoke Agent
83 
84Use the project endpoint and agent name from the project context. Use `agent_invoke` with:
85- `projectEndpoint`, `agentName`, `inputText` (required)
86- `agentVersion`, `conversationId`, `sessionId`, `protocol`, `stream` (optional)
87 
88**Responses protocol** (default): `inputText` is a natural language message string. Multi-turn via `conversationId`.
89 
90**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.
91 
92> ⚠️ **Do not guess the invocations request body.** To discover the expected schema:
93> 1. **Fetch the OpenAPI spec**: `GET {projectEndpoint}/agents/{agentName}/endpoint/protocols/invocations/docs/openapi.json` (if the developer registered one)
94> 2. Inspect the agent's **route handler code** or README for the expected payload shape
95> 3. If unknown, ask the user for the agent's API contract before invoking
96 
97Example invocations call (agent expects `{"message": "<text>"}`):
98 
99```text
100agent_invoke(projectEndpoint, agentName, inputText: "{\"message\":\"hello\"}", protocol: "invocations", sessionId: "<id>")
101```
102 
103See [Invocations Protocol Guide](references/invocations-protocol.md) for full details and examples.
104 
105### Step 5: Multi-Turn Conversations
106 
107**Responses protocol** → Pass `conversationId` from previous response to continue the thread. Platform manages history.
108 
109**Invocations protocol** → Reuse same `sessionId`; conversation state is agent-managed via `$HOME`. Do **not** pass `conversationId` — it has no effect for invocations.
110 
111### Step 6: File Operations (Hosted Agents)
112 
113Upload/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).
114 
115### Step 7: Clean Up
116 
117Use `session_delete` to release compute resources when done. Undeleted sessions expire per platform policies.
118 
119## Agent Type Differences
120 
121| Behavior | Prompt Agent | Hosted Agent |
122|----------|--------------|--------------|
123| Readiness | Immediate | After deployment, version must be `active` |
124| Session | Not applicable | Required via `session_create` |
125| Multi-turn | Via `conversationId` | Via `conversationId` (responses) or session state (invocations) |
126| File operations | ❌ | ✅ via session file tools |
127| Protocol | `responses` only | `responses` or `invocations` |
128 
129## Error Handling
130 
131| Error | Cause | Resolution |
132|-------|-------|------------|
133| Agent not found | Invalid name or endpoint | Use `agent_get` to list agents |
134| Hosted agent not active | Version still provisioning or failed | Check version status via `agent_get` |
135| Session not found | Invalid ID or expired | Create new session with `session_create` |
136| `424 FailedDependency` or `session_not_ready` | Hosted agent session is still warming up or readiness has not completed | Wait 15-30 seconds, check `session_logstream` if needed, then retry `agent_invoke` with the same `sessionId` if one was returned; if no `sessionId` was returned, retry `session_create`. If this persists across 3+ retries (with exponential backoff: 15s, 30s, 60s), the container likely cannot start within the readiness probe deadline — redeploy with higher CPU/memory (recommended minimum: `1` CPU / `2Gi` for direct-code deployments). Also verify the model deployment name is correct via `model_deployment_get`. |
137| `could not resolve agent service in azd project: no azure.ai.agent service named '<agentName>' found in azure.yaml` from `azd ai agent invoke` | Name mismatch. | Update the agent name to the deployed agent name. |
138| `invalid value "json" for --output` from `azd ai agent invoke` | Invoke supports only `default` and `raw` currently. | Retry without `--output json`. |
139| Invocation failed | Model error, timeout, or invalid input | Check agent logs, verify model deployment |
140| 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 |
141| File operation failed | Session not active or invalid path | Verify session with `session_get` |
142| Permission error | Missing RBAC | Follow [troubleshoot skill](../troubleshoot/troubleshoot.md) |
143| Rate limit exceeded | Too many requests | Implement backoff and retry |
144 
145## Additional Resources
146 
147- [Session Management](references/session-management.md)
148- [File Operations](references/file-operations.md)
149- [Foundry Hosted Agents](https://learn.microsoft.com/en-us/azure/ai-foundry/agents/concepts/hosted-agents?view=foundry)
150- [Foundry Samples](https://github.com/azure-ai-foundry/foundry-samples)
151