google / google/adk-python-community

feat(models): add OpenAI Responses API adapters

Đang mở
#150 5 bình luận 0 reaction 0 người được giao Xem trên GitHub
Ngôn ngữ chính
Python
Star
182
Fork
75
Chỉ số merge pull request
Không có pull request nào được merge trong 30 ngày

Mô tả

## Feature Request: Add OpenAI Responses API model adapters

### Related issues
- adk-python [#3209](https://github.com/google/adk-python/issues/3209)

### Summary

Add community model adapters for the OpenAI Responses API, including Azure OpenAI Responses API support, under `google.adk_community.models.openai_responses`.

### Problem

`google-adk-community` does not currently provide a model adapter for the OpenAI Responses API. Users who want to use OpenAI or Azure OpenAI Responses API models with ADK need to implement their own request conversion, response parsing, streaming handling, tool-call mapping, and usage metadata handling.

This creates duplicated integration work for users who want to run ADK agents against OpenAI Responses API-compatible models, especially Azure OpenAI deployments exposed through the `/openai/v1/responses` endpoint.

### Proposed Solution

Add two model adapters:

- `OpenAIResponsesLlm` for OpenAI Responses API models.
- `AzureOpenAIResponsesLlm` for Azure OpenAI deployments that expose the OpenAI-compatible Responses API.

The adapters should support:

- Conversion from ADK `LlmRequest` into OpenAI Responses API `responses.create` parameters.
- Conversion of ADK contents, system instructions, tools, tool responses, and generation config into Responses API-compatible request shapes.
- Parsing OpenAI Responses API responses into ADK `LlmResponse` objects.
- Text output, function calls, reasoning parts, finish reasons, interaction IDs, model versions, and usage metadata.
- Streaming Responses API events, including partial text and reasoning deltas plus final response aggregation.
- Azure OpenAI-compatible client construction using the `/openai/v1/` base URL.
- Optional OpenAI response metadata on `LlmResponse.custom_metadata`.
- An optional `openai` dependency extra so users can install the OpenAI SDK only when needed.

### Example Usage

```python
from google.adk_community.models.openai_responses import OpenAIResponsesLlm

model = OpenAIResponsesLlm(model="gpt-5")
```

```python
from google.adk_community.models.openai_responses import AzureOpenAIResponsesLlm

model = AzureOpenAIResponsesLlm(
model="my-gpt-5-deployment",
azure_endpoint="https://my-resource.openai.azure.com/",
)
```

### Alternatives Considered

- Keep this in core ADK: this feature is better suited for `google-adk-community` because it is a third-party model integration and can evolve independently from the stable core ADK package.
- Require users to call the OpenAI SDK directly: this does not integrate with ADK runners, sessions, tool calls, streaming, or `LlmResponse` semantics.
- Provide only an OpenAI adapter: Azure OpenAI users need first-class support for deployment names, Azure endpoint configuration, and the `/openai/v1/` base URL.

### Testing Requirements

Unit tests should cover:

- Request shape conversion.
- System instructions and generation config mapping.
- Tool declaration and tool response mapping.
- Typed and mapping-based response parsing.
- Function calls and function call IDs.
- Reasoning metadata.
- Usage metadata.
- Streaming aggregation.
- Failed stream handling.
- Azure base URL construction.
- Optional disabling of response metadata in `custom_metadata`.

Manual E2E validation should be possible with a sample Azure OpenAI Responses agent under `contributing/samples/models/hello_world_azure_openai_responses`.

### Acceptance Criteria

- Users can import `OpenAIResponsesLlm` and `AzureOpenAIResponsesLlm` from `google.adk_community.models.openai_responses`.
- Users can install required dependencies with `pip install "google-adk-community[openai]"`.
- ADK agents can use the model adapters with the existing runner flow.
- Tool calling works through ADK function tools and OpenAI Responses API function calls.
- Streaming and non-streaming generation both return valid ADK `LlmResponse` objects.
- Azure OpenAI deployments use the expected `/openai/v1/` base URL.
- Unit tests pass locally and in CI.
- Documentation and a manual E2E sample are included.

Hướng dẫn đóng góp

Mở hướng dẫn đóng góp

Hướng nghiên cứu

Bắt đầu bằng cách xem xét module được đề xuất google.adk_community.models.openai_responses và các mẫu hiện có của ADK runner và model adapter. Sử dụng các yêu cầu được liệt kê về chuyển đổi request, phân tích response, streaming, Azure URL, metadata, kiểm thử, tài liệu và contributing/samples/models/hello_world_azure_openai_responses làm checklist hoàn thành.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Đánh giá

Công nghệ
python
Lĩnh vực
ai, api, backend-api-design
Loại issue
Tính năng
Độ khó
5/5
Thời gian dự kiến
Hơn một tuần
Mức độ hoạt động
Ít trao đổi
Độ rõ ràng
Khá rõ ràng
Mức phù hợp với người mới
35/100

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.