Skip to content

Commit 845ef4c

Browse files
octavia-bot[bot]ian-at-airbyte
octavia-bot[bot]
and
ian-at-airbyte
authored
docs: sync agent connector docs from airbyte-agent-connectors repo (#74315)
Co-authored-by: ian-at-airbyte <187576150+ian-at-airbyte@users.noreply.github.com>
1 parent 5c47ddb commit 845ef4c

3 files changed

Lines changed: 1393 additions & 0 deletions

File tree

‎docs/ai-agents/connectors/amazon-seller-partner/AUTH.md‎

Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
# Amazon-Seller-Partner authentication
2+
3+
This page documents the authentication and configuration options for the Amazon-Seller-Partner agent connector.
4+
5+
## Authentication
6+
7+
### Open source execution
8+
9+
In open source mode, you provide API credentials directly to the connector.
10+
11+
#### OAuth
12+
13+
`credentials` fields you need:
14+
15+
16+
| Field Name | Type | Required | Description |
17+
|------------|------|----------|-------------|
18+
| `lwa_app_id` | `str` | Yes | Your Login with Amazon Client ID. |
19+
| `lwa_client_secret` | `str` | Yes | Your Login with Amazon Client Secret. |
20+
| `refresh_token` | `str` | Yes | The Refresh Token obtained via the OAuth authorization flow. |
21+
| `access_token` | `str` | No | Access token (optional if refresh_token is provided). |
22+
23+
Example request:
24+
25+
```python
26+
from airbyte_agent_amazon_seller_partner import AmazonSellerPartnerConnector
27+
from airbyte_agent_amazon_seller_partner.models import AmazonSellerPartnerAuthConfig
28+
29+
connector = AmazonSellerPartnerConnector(
30+
auth_config=AmazonSellerPartnerAuthConfig(
31+
lwa_app_id="<Your Login with Amazon Client ID.>",
32+
lwa_client_secret="<Your Login with Amazon Client Secret.>",
33+
refresh_token="<The Refresh Token obtained via the OAuth authorization flow.>",
34+
access_token="<Access token (optional if refresh_token is provided).>"
35+
)
36+
)
37+
```
38+
39+
#### Token
40+
This authentication method isn't available for this connector.
41+
42+
### Hosted execution
43+
44+
In hosted mode, you first create a connector via the Airbyte API (providing your OAuth or Token credentials), then execute operations using either the Python SDK or API. If you need a step-by-step guide, see the [hosted execution tutorial](https://docs.airbyte.com/ai-agents/quickstarts/tutorial-hosted).
45+
46+
#### OAuth
47+
Create a connector with OAuth credentials.
48+
49+
`credentials` fields you need:
50+
51+
52+
| Field Name | Type | Required | Description |
53+
|------------|------|----------|-------------|
54+
| `lwa_app_id` | `str` | Yes | Your Login with Amazon Client ID. |
55+
| `lwa_client_secret` | `str` | Yes | Your Login with Amazon Client Secret. |
56+
| `refresh_token` | `str` | Yes | The Refresh Token obtained via the OAuth authorization flow. |
57+
| `access_token` | `str` | No | Access token (optional if refresh_token is provided). |
58+
59+
`replication_config` fields you need:
60+
61+
| Field Name | Type | Required | Description |
62+
|------------|------|----------|-------------|
63+
| `replication_start_date` | `str (date-time)` | Yes | UTC date and time in the format 2017-01-25T00:00:00Z. Any data before this date will not be replicated. |
64+
65+
Example request:
66+
67+
```bash
68+
curl -X POST "https://api.airbyte.ai/api/v1/integrations/connectors" \
69+
-H "Authorization: Bearer <YOUR_BEARER_TOKEN>" \
70+
-H "Content-Type: application/json" \
71+
-d '{
72+
"customer_name": "<CUSTOMER_NAME>",
73+
"connector_type": "Amazon-Seller-Partner",
74+
"name": "My Amazon-Seller-Partner Connector",
75+
"credentials": {
76+
"lwa_app_id": "<Your Login with Amazon Client ID.>",
77+
"lwa_client_secret": "<Your Login with Amazon Client Secret.>",
78+
"refresh_token": "<The Refresh Token obtained via the OAuth authorization flow.>",
79+
"access_token": "<Access token (optional if refresh_token is provided).>"
80+
},
81+
"replication_config": {
82+
"replication_start_date": "<UTC date and time in the format 2017-01-25T00:00:00Z. Any data before this date will not be replicated.>"
83+
}
84+
}'
85+
```
86+
87+
88+
89+
#### Bring your own OAuth flow
90+
To implement your own OAuth flow, use Airbyte's server-side OAuth API endpoints. For a complete guide, see [Build your own OAuth flow](https://docs.airbyte.com/ai-agents/platform/authenticate/build-auth/build-your-own).
91+
92+
##### Step 1: Initiate the OAuth flow
93+
94+
Request a consent URL for your user.
95+
96+
| Field Name | Type | Required | Description |
97+
|------------|------|----------|-------------|
98+
| `customer_name` | `string` | Yes | Your unique identifier for the customer |
99+
| `connector_type` | `string` | Yes | The connector type (e.g., "Amazon-Seller-Partner") |
100+
| `redirect_url` | `string` | Yes | URL to redirect to after OAuth authorization |
101+
102+
Example request:
103+
104+
```bash
105+
curl -X POST "https://api.airbyte.ai/api/v1/integrations/connectors/oauth/initiate" \
106+
-H "Authorization: Bearer <YOUR_BEARER_TOKEN>" \
107+
-H "Content-Type: application/json" \
108+
-d '{
109+
"customer_name": "<CUSTOMER_NAME>",
110+
"connector_type": "Amazon-Seller-Partner",
111+
"redirect_url": "https://yourapp.com/oauth/callback"
112+
}'
113+
```
114+
115+
Redirect your user to the `consent_url` from the response.
116+
117+
##### Step 2: Handle the callback
118+
119+
After the user authorizes access, Airbyte automatically creates the connector and redirects them to your `redirect_url` with a `connector_id` query parameter. You don't need to make a separate API call to create the connector.
120+
121+
```text
122+
https://yourapp.com/oauth/callback?connector_id=<connector_id>
123+
```
124+
125+
Extract the `connector_id` from the callback URL and store it for future operations. For error handling and a complete implementation example, see [Build your own OAuth flow](https://docs.airbyte.com/ai-agents/platform/authenticate/build-auth/build-your-own#part-3-handle-the-callback).
126+
127+
#### Token
128+
This authentication method isn't available for this connector.
129+
130+
#### Execution
131+
132+
After creating the connector, execute operations using either the Python SDK or API.
133+
If your Airbyte client can access multiple organizations, include `organization_id` in `AirbyteAuthConfig` and `X-Organization-Id` in raw API calls.
134+
135+
**Python SDK**
136+
137+
```python
138+
from airbyte_agent_amazon_seller_partner import AmazonSellerPartnerConnector, AirbyteAuthConfig
139+
140+
connector = AmazonSellerPartnerConnector(
141+
auth_config=AirbyteAuthConfig(
142+
customer_name="<your_customer_name>",
143+
organization_id="<your_organization_id>", # Optional for multi-org clients
144+
airbyte_client_id="<your-client-id>",
145+
airbyte_client_secret="<your-client-secret>"
146+
)
147+
)
148+
149+
@agent.tool_plain # assumes you're using Pydantic AI
150+
@AmazonSellerPartnerConnector.tool_utils
151+
async def amazon_seller_partner_execute(entity: str, action: str, params: dict | None = None):
152+
return await connector.execute(entity, action, params or {})
153+
```
154+
155+
**API**
156+
157+
```bash
158+
curl -X POST 'https://api.airbyte.ai/api/v1/integrations/connectors/<connector_id>/execute' \
159+
-H 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \
160+
-H 'X-Organization-Id: <YOUR_ORGANIZATION_ID>' \
161+
-H 'Content-Type: application/json' \
162+
-d '{"entity": "<entity>", "action": "<action>", "params": {}}'
163+
```
164+
165+
166+
## Configuration
167+
168+
The Amazon-Seller-Partner connector requires the following configuration variables. These variables are used to construct the base API URL. Pass them via the `config` parameter when initializing the connector.
169+
170+
| Variable | Type | Required | Default | Description |
171+
|----------|------|----------|---------|-------------|
172+
| `region` | `string` | Yes | https://sellingpartnerapi-na.amazon.com | The SP-API endpoint URL based on seller region:
173+
- NA (North America: US, CA, MX, BR): https://sellingpartnerapi-na.amazon.com
174+
- EU (Europe/Middle East/Africa/India): https://sellingpartnerapi-eu.amazon.com
175+
- FE (Far East: JP, AU, SG): https://sellingpartnerapi-fe.amazon.com
176+
|

‎docs/ai-agents/connectors/amazon-seller-partner/README.md‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
# Amazon-Seller-Partner
2+
3+
The Amazon-Seller-Partner agent connector is a Python package that equips AI agents to interact with Amazon-Seller-Partner through strongly typed, well-documented tools. It's ready to use directly in your Python app, in an agent framework, or exposed through an MCP.
4+
5+
Connector for the Amazon Selling Partner API (SP-API). Provides access to seller orders and order items, financial events and event groups, catalog item search and details, and report metadata. Supports OAuth 2.0 authentication via Login with Amazon (LWA) with automatic token refresh.
6+
7+
8+
## Example questions
9+
10+
The Amazon-Seller-Partner connector is optimized to handle prompts like these.
11+
12+
- List all recent orders
13+
- Show me order items for a specific order
14+
- List financial event groups
15+
- Show recent financial events
16+
- Search catalog items by keyword
17+
- List recent reports
18+
- What are my top-selling products by order volume?
19+
- Show orders from the last 30 days with status Shipped
20+
- Find financial events related to refunds
21+
- Which orders have the highest total value?
22+
23+
## Unsupported questions
24+
25+
The Amazon-Seller-Partner connector isn't currently able to handle prompts like these.
26+
27+
- Create a new order
28+
- Cancel an order
29+
- Submit a new report request
30+
- Update product listings
31+
32+
## Installation
33+
34+
```bash
35+
uv pip install airbyte-agent-amazon-seller-partner
36+
```
37+
38+
## Usage
39+
40+
Connectors can run in open source or hosted mode.
41+
42+
### Open source
43+
44+
In open source mode, you provide API credentials directly to the connector.
45+
46+
```python
47+
from airbyte_agent_amazon_seller_partner import AmazonSellerPartnerConnector
48+
from airbyte_agent_amazon_seller_partner.models import AmazonSellerPartnerAuthConfig
49+
50+
connector = AmazonSellerPartnerConnector(
51+
auth_config=AmazonSellerPartnerAuthConfig(
52+
lwa_app_id="<Your Login with Amazon Client ID.>",
53+
lwa_client_secret="<Your Login with Amazon Client Secret.>",
54+
refresh_token="<The Refresh Token obtained via the OAuth authorization flow.>",
55+
access_token="<Access token (optional if refresh_token is provided).>"
56+
)
57+
)
58+
59+
@agent.tool_plain # assumes you're using Pydantic AI
60+
@AmazonSellerPartnerConnector.tool_utils
61+
async def amazon_seller_partner_execute(entity: str, action: str, params: dict | None = None):
62+
return await connector.execute(entity, action, params or {})
63+
```
64+
65+
### Hosted
66+
67+
In hosted mode, API credentials are stored securely in Airbyte Cloud. You provide your Airbyte credentials instead.
68+
If your Airbyte client can access multiple organizations, also set `organization_id`.
69+
70+
This example assumes you've already authenticated your connector with Airbyte. See [Authentication](AUTH.md) to learn more about authenticating. If you need a step-by-step guide, see the [hosted execution tutorial](https://docs.airbyte.com/ai-agents/quickstarts/tutorial-hosted).
71+
72+
```python
73+
from airbyte_agent_amazon_seller_partner import AmazonSellerPartnerConnector, AirbyteAuthConfig
74+
75+
connector = AmazonSellerPartnerConnector(
76+
auth_config=AirbyteAuthConfig(
77+
customer_name="<your_customer_name>",
78+
organization_id="<your_organization_id>", # Optional for multi-org clients
79+
airbyte_client_id="<your-client-id>",
80+
airbyte_client_secret="<your-client-secret>"
81+
)
82+
)
83+
84+
@agent.tool_plain # assumes you're using Pydantic AI
85+
@AmazonSellerPartnerConnector.tool_utils
86+
async def amazon_seller_partner_execute(entity: str, action: str, params: dict | None = None):
87+
return await connector.execute(entity, action, params or {})
88+
```
89+
90+
## Full documentation
91+
92+
### Entities and actions
93+
94+
This connector supports the following entities and actions. For more details, see this connector's [full reference documentation](REFERENCE.md).
95+
96+
| Entity | Actions |
97+
|--------|---------|
98+
| Orders | [List](./REFERENCE.md#orders-list), [Get](./REFERENCE.md#orders-get), [Search](./REFERENCE.md#orders-search) |
99+
| Order Items | [List](./REFERENCE.md#order-items-list), [Search](./REFERENCE.md#order-items-search) |
100+
| List Financial Event Groups | [List](./REFERENCE.md#list-financial-event-groups-list), [Search](./REFERENCE.md#list-financial-event-groups-search) |
101+
| List Financial Events | [List](./REFERENCE.md#list-financial-events-list), [Search](./REFERENCE.md#list-financial-events-search) |
102+
| Catalog Items | [List](./REFERENCE.md#catalog-items-list), [Get](./REFERENCE.md#catalog-items-get) |
103+
| Reports | [List](./REFERENCE.md#reports-list), [Get](./REFERENCE.md#reports-get) |
104+
105+
106+
### Authentication
107+
108+
For all authentication options, see the connector's [authentication documentation](AUTH.md).
109+
110+
### Amazon-Seller-Partner API docs
111+
112+
See the official [Amazon-Seller-Partner API reference](https://developer-docs.amazon.com/sp-api/).
113+
114+
## Version information
115+
116+
- **Package version:** 0.1.0
117+
- **Connector version:** 1.0.1
118+
- **Generated with Connector SDK commit SHA:** f84710e40f853d4aba27e1b9952576cae7598d1a
119+
- **Changelog:** [View changelog](https://github.com/airbytehq/airbyte-agent-connectors/blob/main/connectors/amazon-seller-partner/CHANGELOG.md)

0 commit comments

Comments
 (0)