responses Package

Public API surface for the Azure AI Agent Server Responses package.

Packages

hosting

HTTP hosting, routing, and request orchestration for the Responses server.
models

Canonical non-generated model types for the response server.
store
streaming

Event streaming, SSE encoding, and output item builders.

Classes

CreateResponse

Override generated CreateResponse to correct temperature/top_p types.
FoundryApiError

Raised for all other non-success HTTP responses.
FoundryBadRequestError

Raised for invalid-request or conflict errors (HTTP 400, 409).
FoundryResourceNotFoundError

Raised when the requested resource does not exist (HTTP 404).
FoundryStorageError

Base class for errors returned by the Foundry storage API.
FoundryStorageProvider

An HTTP-backed response storage provider that persists data via the Foundry storage API.

This class satisfies the <xref:azure.ai.agentserver.responses.store._base.ResponseProviderProtocol> structural protocol. Obtain an instance through the constructor and supply it when building a ResponsesServer.

Uses AsyncPipelineClient for HTTP transport, providing built-in retry, logging, distributed tracing, and bearer-token authentication.

Example:


   async with FoundryStorageProvider(credential=DefaultAzureCredential()) as provider:
       app = ResponsesServer(handler=my_handler, store=provider)
FoundryStorageSettings

Immutable runtime configuration for FoundryStorageProvider.
InMemoryResponseProvider

In-memory provider implementing both ResponseProviderProtocol and ResponseStreamProviderProtocol.

Initialize in-memory state and an async mutation lock.
IsolationContext

Platform-injected isolation keys for multi-tenant state partitioning.

The Foundry hosting platform injects x-agent-user-isolation-key and x-agent-chat-isolation-key headers on every protocol request (not on health probes). These opaque strings serve as partition keys:

  • user_key — unique per user across all sessions; use for user-private state.

  • chat_key — represents where conversation state lives; in 1:1 chats the two keys are equal.

When the headers are absent (e.g. local development), both keys are None. When the platform sends the header with an empty value, the key is an empty string. Use is None to detect whether the header was present at all.
ResponseContext

Runtime context exposed to response handlers and used by hosting orchestration.

  • response identifier

  • shutdown signal flag

  • async input/history resolution
ResponseEventStream

Response event stream with deterministic sequence numbers.

Initialize a new response event stream.
ResponseObject

Override generated ResponseObject to correct temperature/top_p types and fix Sphinx docstring warnings.
ResponseProviderProtocol

Protocol for response storage providers.

Implementations provide response envelope storage plus input/history item lookup.

Every operation accepts an optional isolation parameter (S-018). Implementations MUST use it to partition data in multi-tenant deployments. When None, the provider operates without tenant scoping (suitable for local development).
ResponseStreamProviderProtocol

Protocol for providers that can persist and replay SSE stream events.

Implement this protocol alongside ResponseProviderProtocol to enable SSE replay for responses that are no longer resident in the in-process runtime state (for example, after a process restart).
ResponsesAgentServerHost

Responses protocol host for Azure AI Hosted Agents.

A AgentServerHost subclass that adds the Responses API endpoints. Use the response_handler decorator to wire a handler function to the create endpoint.

For multi-protocol agents, compose via cooperative inheritance:


   class MyHost(InvocationAgentServerHost, ResponsesAgentServerHost):
       pass

Usage:


   from azure.ai.agentserver.responses import ResponsesAgentServerHost

   app = ResponsesAgentServerHost()

   @app.response_handler
   def my_handler(request, context, cancellation_signal):
       yield event

   app.run()
ResponsesServerOptions

Configuration values for hosting and runtime behavior.
TextResponse

A high-level convenience that produces a complete text-message response stream.

Implements <xref:AsyncIterable> so it can be returned directly from a response_handler.

Handles the full SSE lifecycle automatically:

  • response.created → response.in_progress

  • response.output_item.added (message)

  • response.content_part.added (text)

  • response.output_text.delta (one or more)

  • response.output_text.done

  • response.content_part.done

  • response.output_item.done

  • response.completed

Plain string:


   return TextResponse(context, request, text="Hello!")

Callable (sync or async):


   return TextResponse(context, request,
       text=lambda: "Hello!")

Async iterable (token streaming):


   async def tokens():
       for t in ["Hello", ", ", "world!"]:
           yield t

   return TextResponse(context, request, text=tokens())

Functions

get_conversation_id

Extract conversation ID from a request or response's conversation field.

If conversation is a plain string, returns it directly. If it is a <xref:azure.ai.agentserver.responses.ConversationParam_2> object, returns its id field.

get_conversation_id(request: CreateResponse | ResponseObject) -> str | None

Parameters

Name Description
request
Required
CreateResponse | ResponseObject

The create-response request or response object.

Returns

Type Description
str | None

The conversation ID, or None if no conversation is set.

get_input_expanded

Normalize CreateResponse.input into a list of <xref:azure.ai.agentserver.responses.Item>.

  • If input is None, returns [].

  • If input is a string, wraps it as a single <xref:azure.ai.agentserver.responses.ItemMessage> with role=user and <xref:azure.ai.agentserver.responses.MessageContentInputTextContent>.

  • If input is already a list, each element is deserialized into the appropriate <xref:azure.ai.agentserver.responses.Item> subclass (e.g., <xref:azure.ai.agentserver.responses.ItemMessage>, <xref:azure.ai.agentserver.responses.FunctionCallOutputItemParam>).

get_input_expanded(request: CreateResponse) -> list[azure.ai.agentserver.responses.models._generated.sdk.models.models._models.Item]

Parameters

Name Description
request
Required
CreateResponse

The create-response request.

Returns

Type Description
list[Item]

A list of typed input items.

to_output_item

Convert an <xref:azure.ai.agentserver.responses.Item> to the corresponding <xref:azure.ai.agentserver.responses.OutputItem>.

Generates a type-specific ID via <xref:IdGenerator.new_item_id> and applies status according to per-type rules:

  • Completed — explicitly listed types get status = "completed".

  • Preserve status — types whose original status must be kept (ItemOutputMessage, ApplyPatch*).

  • No status — all other types (including any future types) receive no status value. This opt-in design prevents newly-added item types from accidentally gaining a status field.

Returns None for <xref:azure.ai.agentserver.responses.ItemReferenceParam> or unrecognised types.

The conversion leverages _deserialize(OutputItem, data) which resolves the correct subtype via the type discriminator. All 24 input/output discriminator pairs share the same string values, so the dict representation produced by dict(item) is directly compatible with OutputItem deserialization.

to_output_item(item: Item, response_id: str | None = None) -> OutputItem | None

Parameters

Name Description
item
Required
Item

The input item to convert.
response_id
str | None

An existing ID (typically the response ID) used as a partition-key hint for the generated item ID.

Default value: None

Returns

Type Description
OutputItem | None

The converted output item, or None if non-convertible.