AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

microsoft-foundry

Build, deploy, evaluate, optimize, fine-tune, and manage Microsoft Foundry agents, models, and resources end to end. USE FOR: foundry, azd ai agent, azd provision/deploy, hosted agent scaffold/develop/run/deploy/troubleshoot, prompt agent, managed harness agent, Copilot harness, voice agent, create/update/invoke/evaluate agent, add tool to agent, agent insights, batch/continuous eval, continuous monitoring, agent CI/CD, optimize/improve prompt, optimize agent instructions, Agent Optimizer, dataset curation from traces, deploy model, model fine-tuning (SFT/DPO/RFT), Foundry project, RBAC, role assignment, permissions, quota, capacity, region, deployment failure, AI Services, create Foundry resource, knowledge index, customize deployment, onboard, availability, training-data, grader, distillation, large file upload. DO NOT USE FOR: Azure Functions, App Service, general Azure deploy (use azure-deploy), general Azure prep (use azure-prepare).

Original source
microsoft
License
MIT
Pinned revision
3f5b461b2314e01c400564051e92469114c5b68f

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read microsoft--microsoft-foundry at revision 3f5b461b2314e01c400564051e92469114c5b68f, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 151

foundry-agent/invoke/references/invocations-protocol.md

Invocations Protocol Guide

The invocations protocol is bytes in, bytes out. The platform is pure pass-through — the raw HTTP request body is forwarded to the container and the raw response is returned. The agent developer defines what the container accepts and returns. Unlike responses (OpenAI-compatible with platform-managed history), invocations gives full control to the container code.

Input/Output Contract

| Aspect | responses | invocations | |--------|------------|---------------| | Input | Natural language message | Raw HTTP request body from --input-file; format it as the container's invoke handler expects | | Output | Structured OpenAI response with output_text | Raw response bytes from the container — JSON, text, or SSE events. Format is defined by the agent developer | | Conversation history | Platform-managed; azd can persist the conversationId for reuse | Agent-managed via session filesystem | | Streaming | Platform-managed | Agent-controlled |

Discovering the Expected Input Schema

⚠️ Do not guess the invocations request body. The developer defines the schema in the container's invoke handler. The platform does not validate or transform the payload.

1. Fetch the OpenAPI Spec (Preferred)

Agents can register an OpenAPI spec that describes the expected request/response format. Fetch it from:

GET {projectEndpoint}/agents/{agentName}/endpoint/protocols/invocations/docs/openapi.json

If the developer registered an openapi_spec when creating the server, this returns the full API contract. If not registered, it returns 404.

2. Inspect Agent Source Code

Look at the agent's invoke handler — the function registered with @app.invoke_handler (Python) or equivalent. The handler reads the raw request (e.g., request.json() for JSON, request.body() for raw bytes) and returns a Response.

3. Ask the User

If neither the OpenAPI spec nor source code is available, ask the user for the expected request body format before invoking.

Examples

Responses protocol (default):

azd ai agent invoke "What is the weather in Seattle?"

Invocations protocol — agent expects {"message": "<text>"}:

azd ai agent invoke --protocol invocations --input-file request.json

Use --output raw when the unmodified status line, headers, and body are required. azd reuses the saved session automatically; use --new-session to reset agent-managed state.

Common Use Cases

| Scenario | Why Invocations | |----------|----------------| | Webhook receiver (GitHub, Stripe, Jira) | External system sends its own payload format | | Non-conversational processing (classification, extraction) | Input is structured data, not a chat message | | Custom streaming protocol (AG-UI) | Needs raw SSE control, not OpenAI-compatible streaming | | Protocol bridge (proprietary systems) | Caller has its own protocol that doesn't map to /responses |

Error Handling

| Error | Cause | Resolution | |-------|-------|------------| | 400/422 or invocation failed | Request body does not match what the container expects | Fetch OpenAPI spec or inspect handler code for the correct schema | | 404 on OpenAPI spec | Developer did not register an openapi_spec | Inspect handler source code or ask the user for the API contract | | Empty response | Agent returned no content | Check logs with azd ai agent monitor; verify the handler processes the request body correctly |