Skip to content

[agentserver] support invoke api#45481

Open
zhiyong-gayang wants to merge 10 commits intomainfrom
gayang/agentserver
Open

[agentserver] support invoke api#45481
zhiyong-gayang wants to merge 10 commits intomainfrom
gayang/agentserver

Conversation

@zhiyong-gayang
Copy link

@zhiyong-gayang zhiyong-gayang commented Mar 3, 2026 •
edited
Loading

Description

azure-ai-agentserver is the canonical agent-server package going forward. It supports
multiple protocol heads (/invoke, /responses, and future protocols) through a pluggable
handler architecture. Phase 1 ships with /invoke support; /responses and other
protocols will be added in subsequent phases.

It implements the invocation API from this spec:
Azure/azure-rest-api-specs#40709

All SDK Contribution checklist:

  • The pull request does not introduce [breaking changes]
  • CHANGELOG is updated for new features, bug fixes or other significant changes.
  • I have read the contribution guidelines.

General Guidelines and Best Practices

  • Title of the pull request is clear and informative.
  • There are a small number of commits, each of which have an informative message. This means that previously merged commits do not appear in the history of the PR. For more information on cleaning up the commits in your PR, see this page.

Testing Guidelines

  • Pull request includes test coverage for the included changes.

@github-actions github-actions bot added the Hosted Agents sdk/agentserver/* label Mar 3, 2026
@zhiyong-gayang zhiyong-gayang marked this pull request as ready for review March 3, 2026 01:09
Copilot AI review requested due to automatic review settings March 3, 2026 01:09
Copilot AI reviewed Mar 3, 2026
View reviewed changes
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds a new azure-ai-agentserver package under sdk/agentserver to provide an /invocations (“invoke”) protocol head with OpenAPI-based request/response validation, health endpoints, and a set of samples + tests, and wires the new package into the service CI artifacts.

Changes:

  • Add azure-ai-agentserver package implementation (Starlette/uvicorn server, types, logging, OpenAPI validator).
  • Add unit tests and multiple end-to-end samples for invoke, streaming, validation, and get/cancel flows.
  • Update sdk/agentserver/ci.yml to publish the new azure-ai-agentserver artifact.

Reviewed changes

Copilot reviewed 41 out of 42 changed files in this pull request and generated 20 comments.

Show a summary per file
File Description
sdk/agentserver/ci.yml Adds the azure-ai-agentserver artifact to CI.
sdk/agentserver/azure-ai-agentserver/azure/ai/agentserver/server/_base.py Implements the Starlette server and /invocations + health routes.
sdk/agentserver/azure-ai-agentserver/azure/ai/agentserver/validation/_openapi_validator.py Adds JSON-schema validation extracted from an OpenAPI spec.
sdk/agentserver/azure-ai-agentserver/azure/ai/agentserver/_types.py Introduces InvokeRequest dataclass passed to customer invoke().
sdk/agentserver/azure-ai-agentserver/azure/ai/agentserver/_logger.py Adds package-scoped logging configuration helper.
sdk/agentserver/azure-ai-agentserver/azure/ai/agentserver/_constants.py Adds env var/constants used by the server/logging behavior.
sdk/agentserver/azure-ai-agentserver/azure/ai/agentserver/init.py Exposes AgentServer and InvokeRequest as public API.
sdk/agentserver/azure-ai-agentserver/azure/ai/agentserver/_version.py Sets package version (1.0.0b1).
sdk/agentserver/azure-ai-agentserver/azure/ai/agentserver/py.typed Marks the package as typed.
sdk/agentserver/azure-ai-agentserver/azure/ai/agentserver/server/init.py Initializes server package.
sdk/agentserver/azure-ai-agentserver/azure/ai/agentserver/validation/init.py Initializes validation package.
sdk/agentserver/azure-ai-agentserver/azure/init.py Namespace package init for azure.
sdk/agentserver/azure-ai-agentserver/azure/ai/init.py Namespace package init for azure.ai.
sdk/agentserver/azure-ai-agentserver/README.md Documents package purpose, routes, validation, and samples.
sdk/agentserver/azure-ai-agentserver/CHANGELOG.md Adds initial unreleased changelog for 1.0.0b1.
sdk/agentserver/azure-ai-agentserver/LICENSE Adds MIT license file.
sdk/agentserver/azure-ai-agentserver/MANIFEST.in Ensures packaging includes metadata, tests/samples, and py.typed.
sdk/agentserver/azure-ai-agentserver/pyproject.toml Defines build/config (deps, ruff config, azure-sdk-build flags).
sdk/agentserver/azure-ai-agentserver/pyrightconfig.json Adds local pyright config (excluding samples).
sdk/agentserver/azure-ai-agentserver/dev_requirements.txt Adds dev/test requirements for the new package.
sdk/agentserver/azure-ai-agentserver/cspell.json Adds spell-check configuration for the package.
sdk/agentserver/azure-ai-agentserver/tests/conftest.py Adds test agents + httpx ASGI fixtures.
sdk/agentserver/azure-ai-agentserver/tests/test_types.py Tests the InvokeRequest type.
sdk/agentserver/azure-ai-agentserver/tests/test_server_routes.py Tests route registration and basic endpoint behavior.
sdk/agentserver/azure-ai-agentserver/tests/test_openapi_validation.py Tests OpenAPI request/response validation behavior.
sdk/agentserver/azure-ai-agentserver/tests/test_invoke.py Tests invoke dispatch (streaming and non-streaming).
sdk/agentserver/azure-ai-agentserver/tests/test_health.py Tests liveness/readiness endpoints.
sdk/agentserver/azure-ai-agentserver/tests/test_get_cancel.py Tests get_invocation and cancel_invocation paths.
sdk/agentserver/azure-ai-agentserver/samples/simple_invoke_agent/simple_invoke_agent.py Adds minimal invoke sample.
sdk/agentserver/azure-ai-agentserver/samples/simple_invoke_agent/requirements.txt Requirements for minimal invoke sample.
sdk/agentserver/azure-ai-agentserver/samples/openapi_validated_agent/openapi_validated_agent.py Adds OpenAPI-validated invoke sample.
sdk/agentserver/azure-ai-agentserver/samples/openapi_validated_agent/requirements.txt Requirements for OpenAPI-validated sample.
sdk/agentserver/azure-ai-agentserver/samples/langgraph_invoke_agent/langgraph_invoke_agent.py Adds LangGraph invoke adapter sample.
sdk/agentserver/azure-ai-agentserver/samples/langgraph_invoke_agent/requirements.txt Requirements for LangGraph sample.
sdk/agentserver/azure-ai-agentserver/samples/langgraph_invoke_agent/.env.sample Env template for LangGraph sample.
sdk/agentserver/azure-ai-agentserver/samples/human_in_the_loop_agent/human_in_the_loop_agent.py Adds human-in-the-loop invoke sample.
sdk/agentserver/azure-ai-agentserver/samples/human_in_the_loop_agent/requirements.txt Requirements for human-in-the-loop sample.
sdk/agentserver/azure-ai-agentserver/samples/async_invoke_agent/async_invoke_agent.py Adds async long-running invoke sample.
sdk/agentserver/azure-ai-agentserver/samples/async_invoke_agent/requirements.txt Requirements for async invoke sample.
sdk/agentserver/azure-ai-agentserver/samples/agentframework_invoke_agent/agentframework_invoke_agent.py Adds Agent Framework invoke adapter sample.
sdk/agentserver/azure-ai-agentserver/samples/agentframework_invoke_agent/requirements.txt Requirements for Agent Framework sample.
sdk/agentserver/azure-ai-agentserver/samples/agentframework_invoke_agent/.env.sample Env template for Agent Framework sample.

@github-actions
Copy link

github-actions bot commented Mar 3, 2026 •
edited
Loading

API Change Check

APIView identified API level changes in this PR and created the following API reviews

azure-ai-agentserver-server
azure-ai-agentserver-core

Copilot AI added a commit that referenced this pull request Mar 3, 2026
@zhiyong-gayang
Apply all review comment fixes for PR #45481
1d7c14f 
Co-authored-by: zhiyong-gayang <15938424+zhiyong-gayang@users.noreply.github.com>
Copilot AI mentioned this pull request Mar 3, 2026
Closed
splusq
splusq reviewed Mar 3, 2026
View reviewed changes
splusq
splusq reviewed Mar 3, 2026
View reviewed changes
Copy link

@splusq splusq left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code review — critical and significant issues below. (Please disregard the earlier draft reviews on this PR — they were test submissions with incorrect line positions.)

rama0120
rama0120 reviewed Mar 4, 2026
View reviewed changes
zhiyong-gayang added a commit that referenced this pull request Mar 4, 2026
@zhiyong-gayang
Add azure-ai-agentserver v1.0.0b1 (#45481)
b9804eb
@zhiyong-gayang @claude
[agentserver] Add azure-ai-agentserver v1.0.0b1 with invoke API support
1d649fe 
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@zhiyong-gayang @claude
Fix pylint/pyright CI failures and accept invocation ID from request …
bdb9d35 
…header

- Fix pylint: trailing newline, too-many-instance-attributes, missing
  docstrings, unused import, too-many-return-statements
- Fix pyright: guard error.context for reportOptionalIterable
- Accept x-agent-invocation-id from request header (generate UUID if absent)
- Server always controls the response header (handler cannot override)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
zhiyong-gayang and others added 8 commits March 11, 2026 09:11
@zhiyong-gayang
a few improvements
36a8826
@zhiyong-gayang @claude
Flatten package structure and fix several bugs
8051db7 
- Remove server/ and validation/ subdirectories, moving _base.py,
  _config.py, and _openapi_validator.py directly into azure/ai/agentserver/
- Fix _parse_int_env treating "0" as unset (if not raw → if raw is None)
- Return 501 Not Implemented when no invoke handler is registered instead
  of an unclear 500 Internal Server Error
- Add x-agent-invocation-id header to GET/cancel invocation responses
  (success and error paths)
- Fix pyright warnings by importing best_match from jsonschema.exceptions
- Update all internal and test imports for new flat layout

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@zhiyong-gayang @claude
Rename package to azure-ai-agentserver-server and fix CI issues
1b222e9 
- Rename azure-ai-agentserver → azure-ai-agentserver-server, move import
  path to azure.ai.agentserver.server to match sibling package conventions
- Fix pylint C0412: group collections imports in _openapi_validator.py
- Fix TimeoutError span not recorded as ERROR in _base.py
- Return 501 (not 404) for unregistered get/cancel handlers
- Update ci.yml artifact name, all tests, samples, and docs

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@zhiyong-gayang @claude
Refactor invocation protocol from mixin to composition and add OTel t…
58516ac 
…racing

Extract _InvocationProtocol into a standalone composed class that receives
shared server state via a frozen _ServerContext dataclass, enabling clean
addition of future protocol heads without inheritance conflicts.

Add OpenTelemetry tracing with GenAI semantic convention attributes,
W3C Trace Context propagation, baggage header parsing, and Azure Monitor
Application Insights export support.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@zhiyong-gayang @claude
Consolidate tracing into TracingHelper, make internal classes private
38403c0 
Move request-level header extraction and span creation into
_TracingHelper convenience methods so protocol heads get tracing
with a single call. Rename internal classes (TracingHelper →
_TracingHelper, OpenApiValidator → _OpenApiValidator) to reflect
private status. Extract span attribute keys into module constants,
refactor Azure Monitor setup into focused helpers, and rename the
confusing operation/operation_name params to span_operation/operation_name.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@zhiyong-gayang @claude
Fix pylint W0135 and CI test failures for span name matching
71dac32 
Replace nested @contextmanager + with pattern in request_span with
explicit start_span/end_span lifecycle to satisfy pylint
contextmanager-generator-missing-cleanup check. Use substring
matching for span names in tests to handle CI environments where
AGENT_NAME is set.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@zhiyong-gayang @claude
Replace x-agent-session-id header with agent_session_id query paramet…
5788b4d 
…er for session tracking

Session ID is now read from the agent_session_id query parameter instead of the
x-agent-session-id header. Removes SESSION_ID_HEADER constant and header fallback
in tracing. Adds activity_weather_agent sample demonstrating Activity protocol
bridging via the invoke handler.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@zhiyong-gayang
add no sdk spec and sample
a9fa33d
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@johanste johanste johanste left review comments

@RaviPidaparthi RaviPidaparthi RaviPidaparthi left review comments

Copilot code review Copilot Copilot left review comments

@ankitbko ankitbko ankitbko approved these changes

@lusu-msft lusu-msft lusu-msft approved these changes

@msyyc msyyc Awaiting requested review from msyyc msyyc is a code owner

@lmazuel lmazuel Awaiting requested review from lmazuel lmazuel is a code owner

@scbedd scbedd Awaiting requested review from scbedd scbedd is a code owner

@JC-386 JC-386 Awaiting requested review from JC-386 JC-386 is a code owner

@mccoyp mccoyp Awaiting requested review from mccoyp

@catalinaperalta catalinaperalta Awaiting requested review from catalinaperalta

@iscai-msft iscai-msft Awaiting requested review from iscai-msft

@l0lawrence l0lawrence Awaiting requested review from l0lawrence

@benbp benbp Awaiting requested review from benbp

@weshaggard weshaggard Awaiting requested review from weshaggard

@ChenxiJiang333 ChenxiJiang333 Awaiting requested review from ChenxiJiang333

@amber-yujueWang amber-yujueWang Awaiting requested review from amber-yujueWang

@emilyjiji emilyjiji Awaiting requested review from emilyjiji

@pankopon pankopon Awaiting requested review from pankopon

@rhurey rhurey Awaiting requested review from rhurey

@xitzhang xitzhang Awaiting requested review from xitzhang

@hectorhdzg hectorhdzg Awaiting requested review from hectorhdzg

@JacksonWeber JacksonWeber Awaiting requested review from JacksonWeber

@jeremydvoss jeremydvoss Awaiting requested review from jeremydvoss

@lzchen lzchen Awaiting requested review from lzchen

@MSNev MSNev Awaiting requested review from MSNev

@rads-1996 rads-1996 Awaiting requested review from rads-1996

@mitsha-microsoft mitsha-microsoft Awaiting requested review from mitsha-microsoft

@prativen prativen Awaiting requested review from prativen

@albertofori albertofori Awaiting requested review from albertofori

@avanigupta avanigupta Awaiting requested review from avanigupta

@jimmyca15 jimmyca15 Awaiting requested review from jimmyca15

@mrm9084 mrm9084 Awaiting requested review from mrm9084

@rossgrambo rossgrambo Awaiting requested review from rossgrambo

@xiangyan99 xiangyan99 Awaiting requested review from xiangyan99

@dargilco dargilco Awaiting requested review from dargilco

@glharper glharper Awaiting requested review from glharper

@howieleung howieleung Awaiting requested review from howieleung

@kingernupur kingernupur Awaiting requested review from kingernupur

@nick863 nick863 Awaiting requested review from nick863

@trangevi trangevi Awaiting requested review from trangevi

@trrwilson trrwilson Awaiting requested review from trrwilson

@annatisch annatisch Awaiting requested review from annatisch

@kashifkhan kashifkhan Awaiting requested review from kashifkhan

@pvaneck pvaneck Awaiting requested review from pvaneck

+2 more reviewers

@splusq splusq splusq left review comments

@rama0120 rama0120 rama0120 left review comments

Reviewers whose approvals may not affect merge requirements

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

Hosted Agents sdk/agentserver/*

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

8 participants

@zhiyong-gayang @splusq @ankitbko @rama0120 @johanste @RaviPidaparthi @lusu-msft