feat(agents): support invoke over the activity protocol

[glharper]

Closes #7493

What

Adds activity protocol support to azd ai agent invoke, alongside the existing responses and invocations protocols.

# Wrap a plain message as a message Activity
azd ai agent invoke --protocol activity_protocol "Hello!"

# Send a complete Activity object from a file
azd ai agent invoke --protocol activity_protocol -f activity.json

# Local agent (azd ai agent run) + raw passthrough also supported
azd ai agent invoke --local --protocol activity_protocol "Hello!"
azd ai agent invoke --protocol activity_protocol --output raw "Hello!"

Changes

• Make activity_protocol invocable — included in InvocableProtocols() / IsInvocable(). a2a remains deployment-only.
• Routing — --protocol activity_protocol and agent.yaml protocol auto-detection now route to new activityLocal / activityRemote handlers (new file invoke_activity.go). They are modeled on the invocations protocol: structured/opaque body + agent-session-based memory (agent_session_id), --new-session to reset, --new-conversation is a no-op (noted on stderr).
• Request body — a plain message is wrapped as a minimal message Activity ({"type":"message","text":...}); --input-file contents are forwarded verbatim as a complete Activity payload.
• Response — the agent's reply text is extracted from the response Activity (top-level text, InvokeResponse body.text, or an array of activities), with JSON pretty-print and raw-body fallbacks. An {"error":{...}} envelope surfaces as an agent error. --output raw dumps the response verbatim.
• Endpoint plumbing — added buildActivityURL and --agent-endpoint parsing for the .../endpoint/protocols/activity tail; updated --protocol help, the unsupported-protocol validation message, the multi-protocol guidance, and command examples.

Tests

• models_test.go: activity_protocol now IsInvocable() == true.
• agent_endpoint_test.go: parse + buildActivityURL (api-version/session-id escaping, default api-version).
• helpers_test.go: single activity_protocol auto-detects.
• invoke_activity_test.go: message wrapping, file passthrough, response text extraction across shapes, error-envelope detection, request-URL fallback.

Validation

go build ./..., full go test ./..., go vet, gofmt, golangci-lint run (0 issues), and cspell — all clean.

⚠️ Note for reviewers — Foundry wire format

There is no public spec for the Foundry hosted-agent activity invoke endpoint, and the repo had no prior reference (the activity/activity_protocol constants were previously deployment-only). This PR follows the codebase's established responses/invocations conventions:

• URL: {projectEndpoint}/agents/{name}/endpoint/protocols/activity?api-version=...[&agent_session_id=...] (remote) and http://localhost:{port}/activity (local).
• Request: an Activity JSON object; response: an Activity (or array / InvokeResponse) parsed for text.

These assumptions are centralized in buildActivityURL, buildActivityRequestBody, and handleActivityResponse, so if the Foundry contract differs they can be corrected in one place. --output raw is a format-independent escape hatch that works regardless. Please confirm the exact endpoint path and Activity request/response shape against the Foundry hosted-agent activity contract before merge.

[github-actions]

📋 Prioritization Note

Thanks for the contribution! The linked issue isn't in the current milestone yet.
Thank you for logging this issue; our team is reviewing it. If you need urgent prioritization, tag @RickWinter and @kristenwomack to let us know.

[Copilot]

Pull request overview

Adds activity protocol support to the azd ai agent invoke flow in the azure.ai.agents extension, making activity_protocol a first-class invocable protocol alongside responses and invocations.

Changes:

• Make activity_protocol invocable (InvocableProtocols() / IsInvocable()), and route invoke to new activity local/remote handlers.
• Add Activity-protocol endpoint parsing/building (.../endpoint/protocols/activity) and update protocol validation/help text.
• Add targeted unit tests for request wrapping / passthrough, response text extraction, and endpoint URL building.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
cli/azd/extensions/azure.ai.agents/internal/pkg/agents/agent_api/models.go	Marks activity_protocol as invocable.
cli/azd/extensions/azure.ai.agents/internal/pkg/agents/agent_api/models_test.go	Updates protocol invocability tests for activity_protocol.
cli/azd/extensions/azure.ai.agents/internal/cmd/invoke.go	Routes --protocol activity_protocol and updates help/validation strings.
cli/azd/extensions/azure.ai.agents/internal/cmd/invoke_activity.go	Implements activity-protocol invoke (local + Foundry) including request/response shaping.
cli/azd/extensions/azure.ai.agents/internal/cmd/invoke_activity_test.go	Adds unit tests for activity request wrapping/passthrough and response parsing helpers.
cli/azd/extensions/azure.ai.agents/internal/cmd/helpers.go	Updates protocol auto-detection guidance text for activity protocol.
cli/azd/extensions/azure.ai.agents/internal/cmd/helpers_test.go	Adds agent.yaml auto-detect coverage for activity_protocol.
cli/azd/extensions/azure.ai.agents/internal/cmd/agent_endpoint.go	Extends --agent-endpoint parsing and URL builder to support activity.
cli/azd/extensions/azure.ai.agents/internal/cmd/agent_endpoint_test.go	Adds tests for parsing/building activity-protocol URLs (escaping + default api-version).
cli/azd/extensions/azure.ai.agents/CHANGELOG.md	Adds unreleased changelog entry for activity-protocol invoke support.

[jongio]

This PR adds activity protocol support following the established invocations protocol patterns closely. The implementation is well-organized: request body building, local/remote handlers, response text extraction, and error handling are all centralized and testable.

A few observations:

• buildActivityURL correctly applies DefaultAgentAPIVersion as a fallback (matching buildResponsesURL). buildInvocationsURL actually lacks this default, so the activity handler is slightly more robust than its sibling.
• The response text extraction (extractActivityText) handles three response shapes gracefully. The fallback chain (single Activity -> InvokeResponse envelope -> array of Activities -> JSON pretty-print -> raw bytes) is solid.
• The DefaultPort usage in buildLocalAgentKey is consistent with invocationsLocal (invoke.go:1084). This is intentional: the session storage key uses a stable port so sessions persist regardless of which port the user happens to pass on any given invocation.
• The PR clearly documents the unspecced Foundry wire format assumptions and centralizes them for easy correction.

Two minor inline observations below.

[jongio]

This PR adds activity protocol support following the established invocations protocol patterns closely. The implementation is well-organized: request body building, local/remote handlers, response text extraction, and error handling are all centralized and testable.

A few observations:

• buildActivityURL correctly applies DefaultAgentAPIVersion as a fallback (matching buildResponsesURL). buildInvocationsURL actually lacks this default, so the activity handler is slightly more robust than its sibling.
• The response text extraction (extractActivityText) handles three response shapes gracefully. The fallback chain (single Activity -> InvokeResponse envelope -> array of Activities -> JSON pretty-print -> raw bytes) is solid.
• The DefaultPort usage in buildLocalAgentKey is consistent with invocationsLocal (invoke.go:1084). This is intentional: the session storage key uses a stable port so sessions persist regardless of which port the user happens to pass on any given invocation.
• The PR clearly documents the unspecced Foundry wire format assumptions and centralizes them for easy correction.

Two minor inline observations below.

[glharper]

Thanks for the review! Pushed 277cf49 addressing the feedback:

• helpers.go "protocol protocols" stutter — applied @jongio's suggested wording: "...responses, invocations, or activity protocols".
• DefaultPort in the local session key (flagged by azd-code-reviewer) — kept intentionally, as @jongio noted this matches \invocationsLocal\ so local sessions persist across invokes regardless of --port. Added a comment documenting the rationale to prevent future confusion.
• Skipped OpenAPI fetch (@jongio) — left as-is since the activity protocol has no defined OpenAPI discovery endpoint; added a clarifying comment.

All builds/tests/lint/cspell remain green.

[jongio]

Incremental review: my two prior inline comments (the "protocol protocols" stutter in helpers.go and the DefaultPort/OpenAPI-skip observations in invoke_activity.go) are both addressed in 277cf49.

No new issues found in the incremental diff or the full changeset. The implementation follows the invocations protocol patterns closely, has solid test coverage across the key functions (URL building, request body construction, response text extraction, error envelope detection), and the routing/validation updates are consistent with siblings.

One open item for other reviewers: the PR explicitly asks for confirmation of the Foundry hosted-agent activity endpoint contract (path tail, request body shape, response shape) before merge. The assumptions are centralized in buildActivityURL, buildActivityRequestBody, and handleActivityResponse, so corrections would be localized if the contract differs.