Native Activity protocol overview for Microsoft Foundry

With the native Activity adapter, your Microsoft Foundry hosted agent handles messages and events from Teams and other supported channels directly. Use it to build custom interactions, such as responding to a card action or welcoming someone who joins a conversation.

The adapter connects your agent code to the Microsoft 365 Agents SDK. You write the handlers that respond to each interaction and choose how your agent calls models and tools.

Native Activity support in hosted agents and the Python adapter package are generally available. The .NET adapter package remains in preview.

Prerequisites

  • Familiarity with hosted agents and their container protocols.
  • Familiarity with Activity Protocol, which defines messages, events, and interactions between an agent and a channel.

Choose native Activity or Responses

Both native Activity agents and Responses-based agents can receive messages from channels such as Teams. The difference is how your code handles those messages.

Path What the container handles When to choose it
Responses with channel translation Foundry converts channel messages to Responses requests and converts your agent's replies back to the channel format. You want to publish a conversational agent that already uses a Responses handler.
Native Activity The Activity adapter passes messages, events, and other activities to your Microsoft 365 Agents SDK handlers. You need custom handlers for interactions such as card actions or conversation events.

For example, a Responses-based assistant can answer a question sent from Teams without implementing Activity handlers. An agent that processes an interactive card action instead uses a native handler for that interaction.

Publishing to Teams doesn't switch a Responses-based agent to native Activity. To use native Activity, add the Activity adapter and declare the container's protocol. See Add a protocol adapter.

Your native Activity agent can still call models through the Responses API. The API you use for model calls is independent of how your agent receives channel messages.

Adapter and application responsibilities

Both Activity packages integrate the Microsoft 365 Agents SDK with the hosted agent runtime contract.

Language Package Entry point
Python azure-ai-agentserver-activity ActivityAgentServerHost
C# Azure.AI.AgentServer.Activity ActivityServer, with builder and self-hosted integration options

The adapter provides the HTTP endpoint, health checks, and integration with Foundry sessions and tracing. Its default host uses the Microsoft 365 Agents SDK to receive activities and send replies.

Your application handles each interaction, calls models and tools, and decides what to remember between messages. You also configure permissions and handle errors.

For endpoint details, see the runtime contract. For custom hosting options, see the Python Activity SDK reference and .NET Activity hosting guide.

Activity-specific interactions

An activity can contain a message, a file attachment, a card action, or a conversation event. Native handlers let your application respond to each type of interaction.

Interaction What your application does What to check
Messages and conversation events Answer messages or respond when someone joins a conversation. Which events the channel sends.
Interactive cards Send a card and respond to its actions. Which card versions and actions the channel supports.
Streaming replies Show an answer as the model generates it. Whether the channel and publishing method support streaming.
Multi-turn conversations Use earlier messages to provide context for later model calls. How you store, protect, and delete conversation history.
Files Process file attachments. File permissions, consent, and size limits.

The Adaptive Card routing helpers in the Adaptive Card guide aren't currently available in Python. Python card-action handling requires custom activity handlers.

The official Python Activity samples and C# Activity samples include simple echo agents and agents that call models. Review the samples' tool permissions and security guidance before adapting them for production.

Reply delivery

An agent can accept a message before it finishes preparing the reply. For example, the .NET adapter returns HTTP 202 Accepted for normal messages and sends the reply to the channel separately.

When testing, check that the reply appears in the channel, not just that the request succeeds. If the reply is missing, see native Activity troubleshooting.

Model streaming and channel streaming

When your channel and publishing method support streaming, use the Microsoft 365 Agents SDK streaming helpers to show an answer as it's generated. Enabling streaming on the model call alone doesn't send text to the channel.

For SDK examples that add citation and feedback information to a reply, see Teams citations and feedback.

Conversation state and history

Conversation state stores information your agent needs between messages. Model history contains the earlier messages that give a model context. Your application decides how to connect the two.

The Activity SDKs use different storage defaults:

Package version Default storage
Python 1.0.0 FoundryStorage in a Foundry-hosted container and MemoryStorage locally. Supplying storage= overrides the default.
.NET 1.0.0-beta.1 MemoryStorage, which is cleared when the process stops and isn't shared across instances. To keep state across restarts, configure persistent storage through ActivityServerOptions.Storage.

One way to maintain model context is to save a model conversation ID in your agent's conversation state and reuse it on later calls. The model service stores the messages separately.

Keep each conversation's state separate. In group chats, check that participants have permission to access earlier model messages, including when membership changes. When you reset or delete a conversation, handle both the saved ID and the model's message history.

Saving conversation state doesn't resume interrupted work. If your agent needs to continue a task after a restart, plan for recovery separately. See long-running hosted agent resilience.

Authentication, publishing, and identity

Configure permissions for both the people who use your agent and the resources your agent calls.

  • Use the supported agent identity and channel authentication configuration for replies.
  • Grant the agent only the model and downstream-resource access it needs.
  • Configure delegated access and consent separately when a tool acts on behalf of a person.
  • Keep bearer tokens out of conversation state and logs.

Direct publishing registers the agent without a separate Azure Bot Service resource. If your deployment tool creates a Bot resource, follow that tool's permission requirements. Making an agent visible in the store doesn't grant permission to use it. See authorization troubleshooting.

For private-network projects, channel messages still use a public messaging endpoint, not the project's Private Link connection. The REST publishing workflow secures that endpoint with authentication and source IP filtering.

An autopilot has its own identity, setup, licensing, and approval requirements. Using the Activity adapter doesn't change those requirements.

Use these guides to implement, deploy, and diagnose the native path: