airbyte-agent-connectors

<div align="center">
  <a href="https://airbyte.ai/">
    <picture>
      <source media="(prefers-color-scheme: dark)" srcset=".github/images/logo-dark.svg">
      <source media="(prefers-color-scheme: light)" srcset=".github/images/logo-light.svg">
      <img alt="Airbyte Logo" src=".github/images/logo-dark.svg" width="80%">
    </picture>
  </a>
</div>

<p/>

[![Python](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
[![Publish Connectors](https://github.com/airbytehq/airbyte-agent-connectors/actions/workflows/publish.yml/badge.svg)](https://github.com/airbytehq/airbyte-agent-connectors/actions/workflows/publish.yml)
[![License](https://img.shields.io/badge/License-Elastic_2.0-blue.svg)](LICENSE)
[![Airbyte Stars](https://img.shields.io/github/stars/airbytehq/airbyte?style=social)](https://github.com/airbytehq/airbyte-agent-connectors)
[![Slack](https://img.shields.io/badge/Slack-Join_Community-4A154B?logo=slack&logoColor=white)](https://slack.airbyte.com/)
[![Twitter Follow](https://img.shields.io/twitter/follow/airbytehq?style=social)](https://twitter.com/airbytehq)

Airbyte Agent Connectors are packages that let AI agents call third‑party APIs through strongly typed, well‑documented tools. Each connector is a standalone Python package that you can use directly in your app or plug into an agent framework.

## What this repo contains
* Python SDKs for specific SaaS APIs (for example Gong, Stripe, GitHub). 
* A consistent connector layout so you can understand and extend any connector quickly. 
* Ready‑to-use clients that validate auth, handle schemas, and expose typed methods for each operation.

## Connector Structure
Each connector is a standalone Python package:

```
connectors/
├── gong/
│   ├── airbyte_agent_gong/
│   ├── pyproject.toml
│   ├── CHANGELOG.md
│   ├── README.md
│   └── REFERENCE.md
├── github/
│   └── ...
└── ...
```
Inside each connector folder, you’ll find:
* Generated Python client
* Connector-specific README with supported operations
* Typed methods generated from Airbyte’s connector definitions
* Validation + error handling

## When to use these connectors
Use Airbyte Agent Connectors when you want:
* Agent‑friendly data access: Let AI agents call real SaaS APIs (e.g., CRM, billing, analytics) with guardrails and typed responses. 
* Consistent auth and schemas: Reuse a uniform configuration and error‑handling pattern across many APIs. Use connectors inside frameworks like PydanticAI, LangChain, or any custom agent loop.
* Composable building blocks: Combine multiple connectors in a single agent to orchestrate multi‑system workflows. 
Compared to building ad‑hoc API wrappers, these connectors give you a shared structure, generated clients, and alignment with the rest of the Airbyte ecosystem.

## Roadmap
We are actively expanding AI Connectors. Coming soon:
* Writes!
* MCP support (Model Context Protocol)
* Hosted execution, authentication, and search
* Demo apps + starter templates
* More connectors added weekly

## Contributing / Feedback
We actively welcome feedback, ideas, and bug reports.
If you're building AI agents with Airbyte Agent Connectors and want to share ideas or get help, join our community on [slack](https://slack.airbyte.com/). We'd love to hear what you're building and what connectors or capabilities you'd like to see next.

## Agent Skill

This repo includes an agent skill for setup and usage guidance:

```bash
npx skills add airbytehq/airbyte-agent-connectors
```

Or in Claude Code:
```
/install airbytehq/airbyte-agent-connectors
```

See [`airbyte-agent-connectors`](skills/airbyte-agent-connectors/SKILL.md) for full usage details.

## Tutorial using the Python SDK

In this tutorial, you'll create a new Python project with `uv`, add a Pydantic AI agent, equip it to use one of Airbyte's agent connectors, and use natural language to explore your data. This tutorial uses GitHub, but if you don't have a GitHub account, you can use one of Airbyte's other agent connectors and perform different operations.

### Overview

This tutorial is for AI engineers and other technical users who work with data and AI tools. You can complete it in about 15 minutes.

The tutorial assumes you have basic knowledge of the following tools, but most software engineers shouldn't struggle with anything that follows.

- Python and package management with uv
- Pydantic AI
- GitHub, or a different third-party service you want to connect to

### Before you start

Before you begin this tutorial, ensure you have the following.

- [Python](https://www.python.org/downloads/) version 3.13 or later
- [uv](https://github.com/astral-sh/uv)
- A [GitHub personal access token](https://github.com/settings/tokens). For this tutorial, a classic token with `repo` scope is sufficient.
- An [OpenAI API key](https://platform.openai.com/api-keys). This tutorial uses OpenAI, but Pydantic AI supports other LLM providers if you prefer.

### Part 1: Create a new Python project

In this tutorial you initialize a basic Python project to work in. However, if you have an existing project you want to work with, feel free to use that instead.

1. Create a new project using uv:

   ```bash
   uv init my-ai-agent --app
   cd my-ai-agent
   ```

   This creates a project with the following structure:

   ```text
   my-ai-agent/
   ├── .gitignore
   ├── .python-version
   ├── README.md
   ├── main.py
   └── pyproject.toml
   ```

2. Create an `agent.py` file for your agent definition:

   ```bash
   touch agent.py
   ```

You create `.env` and `uv.lock` files in later steps, so don't worry about them yet.

### Part 2: Install dependencies

Install the GitHub connector and Pydantic AI. This tutorial uses OpenAI as the LLM provider, but Pydantic AI supports many other providers.

```bash
uv add airbyte-agent-github pydantic-ai
```

This command installs:

- `airbyte-agent-github`: The Airbyte agent connector for GitHub, which provides type-safe access to GitHub's API.
- `pydantic-ai`: The AI agent framework, which includes support for multiple LLM providers including OpenAI, Anthropic, and Google.

The GitHub connector also includes `python-dotenv`, which you can use to load environment variables from a `.env` file.

### Part 3: Import Pydantic AI and the GitHub agent connector

Add the following imports to `agent.py`:

```python title="agent.py"
import os

from dotenv import load_dotenv
from pydantic_ai import Agent
from airbyte_agent_github import GithubConnector
from airbyte_agent_github.models import GithubAuthConfig
```

These imports provide:

- `os`: Access environment variables for your GitHub token and LLM API key.
- `load_dotenv`: Load environment variables from your `.env` file.
- `Agent`: The Pydantic AI agent class that orchestrates LLM interactions and tool calls.
- `GithubConnector`: The Airbyte agent connector that provides type-safe access to GitHub's API.
- `GithubAuthConfig`: The authentication configuration for the GitHub connector.

### Part 4: Add a .env file with your secrets

1. Create a `.env` file in your project root and add your secrets to it. Replace the placeholder values with your actual credentials.

    ```text title=".env"
    GITHUB_ACCESS_TOKEN=your-github-personal-access-token
    OPENAI_API_KEY=your-openai-api-key
    ```

2. Add the following line to `agent.py` after your imports to load the environment variables:

    ```python title="agent.py"
    load_dotenv()
    ```

    This makes your secrets available via `os.environ`. Pydantic AI automatically reads `OPENAI_API_KEY` from the environment, and you'll use `os.environ["GITHUB_ACCESS_TOKEN"]` to configure the connector in the next section.

### Part 5: Configure your connector and agent

Now that your environment is set up, add the following code to `agent.py` to create the GitHub connector and Pydantic AI agent.

#### Define the connector

Define the agent connector for GitHub. It authenticates using your personal access token.

```pyt

[truncated…]