{"id":49443148,"url":"https://github.com/airbytehq/airbyte-agent-sdk","last_synced_at":"2026-06-11T00:01:24.603Z","repository":{"id":327677521,"uuid":"1104847170","full_name":"airbytehq/airbyte-agent-sdk","owner":"airbytehq","description":"🐙 Drop-in tools that give AI agents reliable, permission-aware access to external systems.","archived":false,"fork":false,"pushed_at":"2026-06-08T21:44:32.000Z","size":100693,"stargazers_count":123,"open_issues_count":7,"forks_count":11,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-08T23:22:42.814Z","etag":null,"topics":["ai","ai-agents","airbyte","anthropic","connectors","data","enterprise","gemini","integrations","langchain","llm","mcp","open-source","openai","pydantic-ai","rag"],"latest_commit_sha":null,"homepage":"https://airbyte.com/agents","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/airbytehq.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-26T19:18:54.000Z","updated_at":"2026-06-08T21:44:35.000Z","dependencies_parsed_at":"2026-04-02T11:04:57.571Z","dependency_job_id":null,"html_url":"https://github.com/airbytehq/airbyte-agent-sdk","commit_stats":null,"previous_names":["airbytehq/airbyte-ai-connectors","airbytehq/airbyte-agent-sdk","airbytehq/airbyte-agent-connectors"],"tags_count":3103,"template":false,"template_full_name":null,"purl":"pkg:github/airbytehq/airbyte-agent-sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/airbytehq%2Fairbyte-agent-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/airbytehq%2Fairbyte-agent-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/airbytehq%2Fairbyte-agent-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/airbytehq%2Fairbyte-agent-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/airbytehq","download_url":"https://codeload.github.com/airbytehq/airbyte-agent-sdk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/airbytehq%2Fairbyte-agent-sdk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34175887,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-10T02:00:07.152Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-agents","airbyte","anthropic","connectors","data","enterprise","gemini","integrations","langchain","llm","mcp","open-source","openai","pydantic-ai","rag"],"created_at":"2026-04-29T21:04:10.624Z","updated_at":"2026-06-11T00:01:24.559Z","avatar_url":"https://github.com/airbytehq.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Airbyte Agent SDK\n\nType-safe connector execution framework with blessed connectors and full IDE autocomplete.\n\n## Overview\n\nThe Airbyte Agent SDK gives AI agents access to 50+ third-party APIs through strongly typed, well-documented tools. Connectors can run through the Airbyte platform (which manages credentials, rate limiting, and execution) or locally in OSS mode.\n\n## How to install\n\n```bash\nuv pip install airbyte-agent-sdk\n```\n\n## Documentation\n\nFull documentation is available at [docs.airbyte.com/ai-agents/about/](https://docs.airbyte.com/ai-agents/about/).\n\n## Tool integration\n\nThe SDK ships two decorators for turning a connector call into an LLM tool with retry-aware exception translation, output-size guards, and framework-specific error signalling.\n\n- **`@\u003cConnector\u003e.tool_utils`** — preferred for typed connectors. Auto-detects the installed framework (pydantic-ai, LangChain, OpenAI Agents, or FastMCP) and composes [`translate_exceptions`](https://airbytehq.github.io/airbyte-embedded/airbyte_agent_sdk/translation.html) under the hood. Pass `framework=\"...\"` to override auto-detection. Forwards `update_docstring`, `max_output_chars`, `framework`, `internal_retries`, `should_internal_retry`, and `exhausted_runtime_failure_message`.\n- **`@translate_exceptions`** — same translation behaviour for any callable that is not a generated `Connector` (custom helpers, eval harnesses, ad-hoc tools).\n\nBoth decorators preserve sync/async, `__name__`, and `__doc__`. Transient runtime failures (429/5xx, network, timeout) can be retried silently via `internal_retries=N` on **either** decorator. Output exceeding `max_output_chars` (default 100 KB) is converted to the framework's retry signal so the LLM can narrow the query.\n\n\u003e **Pick one decorator per tool.** Stacking `@translate_exceptions` over `@\u003cConnector\u003e.tool_utils` (or vice versa) is detected at decoration time: the inner layer is preserved and the outer layer logs a warning and short-circuits, so double-translation is impossible.\n\n### pydantic-ai\n\n```python\nfrom pydantic_ai import Agent\nfrom airbyte_agent_sdk.connectors.stripe import StripeConnector\n\nagent = Agent(\"openai:gpt-4o\")\n\n@agent.tool_plain\n@StripeConnector.tool_utils\nasync def list_customers(limit: int = 10) -\u003e list[dict]:\n    async with StripeConnector(connector_id=\"src_123\") as stripe:\n        result = await stripe.execute(\"customers\", \"list\", params={\"limit\": limit})\n        return result.data\n```\n\nFailures raise `pydantic_ai.ModelRetry` so the agent can retry with corrected arguments.\n\n### LangChain\n\n```python\nfrom langchain_core.tools import StructuredTool\nfrom airbyte_agent_sdk.connectors.stripe import StripeConnector\n\n@StripeConnector.tool_utils(framework=\"langchain\")\nasync def list_customers(limit: int = 10) -\u003e list[dict]:\n    async with StripeConnector(connector_id=\"src_123\") as stripe:\n        result = await stripe.execute(\"customers\", \"list\", params={\"limit\": limit})\n        return result.data\n\ntool = StructuredTool.from_function(\n    coroutine=list_customers,\n    name=\"list_customers\",\n    description=\"List Stripe customers.\",\n    handle_tool_error=True,  # surfaces ToolException as the tool's string result\n)\n```\n\nFailures raise `langchain_core.tools.ToolException`; `handle_tool_error=True` turns that into the tool's string result for the LLM.\n\n\u003e Alternative for non-typed callables: replace `@StripeConnector.tool_utils(framework=\"langchain\")` with `@translate_exceptions(framework=\"langchain\")` from `airbyte_agent_sdk`.\n\n### OpenAI Agents\n\n```python\nfrom agents import Agent, function_tool\nfrom airbyte_agent_sdk.connectors.stripe import StripeConnector\n\n@function_tool\n@StripeConnector.tool_utils(framework=\"openai_agents\")\nasync def list_customers(limit: int = 10) -\u003e list[dict]:\n    async with StripeConnector(connector_id=\"src_123\") as stripe:\n        result = await stripe.execute(\"customers\", \"list\", params={\"limit\": limit})\n        return result.data\n\nagent = Agent(name=\"stripe\", tools=[list_customers])\n```\n\nNote: the OpenAI Agents strategy uses **catch-and-return-string semantics** — `tool_utils` catches the failure and *returns* a string (e.g. `\"ConnectorValidationError: entity must be one of: ...\"`) instead of raising. The OpenAI runner serialises this string verbatim into the tool result the LLM sees.\n\n\u003e Alternative for non-typed callables: replace `@StripeConnector.tool_utils(framework=\"openai_agents\")` with `@translate_exceptions(framework=\"openai_agents\")` from `airbyte_agent_sdk`.\n\n### FastMCP\n\n```python\nfrom fastmcp import FastMCP\nfrom airbyte_agent_sdk.connectors.stripe import StripeConnector\n\nmcp = FastMCP(\"stripe-tools\")\n\n@mcp.tool()\n@StripeConnector.tool_utils(framework=\"mcp\")\nasync def list_customers(limit: int = 10) -\u003e list[dict]:\n    async with StripeConnector(connector_id=\"src_123\") as stripe:\n        result = await stripe.execute(\"customers\", \"list\", params={\"limit\": limit})\n        return result.data\n```\n\nFailures raise `fastmcp.exceptions.ToolError`, which FastMCP serialises as an MCP error response to the client.\n\nSee the [`translate_exceptions`](https://airbytehq.github.io/airbyte-embedded/airbyte_agent_sdk/translation.html) reference for advanced kwargs (`internal_retries`, `should_internal_retry`, `exhausted_runtime_failure_message`).\n\n## How to install the skills\n\nThe repo ships skills that walk agents through setting up and using the connectors. Three install paths:\n\n**skills.sh** (works for Claude Code, Codex, Cursor, OpenCode, and 40+ other agents):\n\n```bash\nnpx skills add airbytehq/airbyte-agent-sdk\n```\n\n**Claude Code** (native plugin):\n\n```\n/plugin marketplace add airbytehq/airbyte-agent-sdk\n/plugin install airbyte-agent-sdk@airbyte-agent-sdk\n```\n\n**Codex** (clone + symlink):\n\n```bash\ngit clone https://github.com/airbytehq/airbyte-agent-sdk ~/.codex/skills/airbyte-agent-sdk-src\nln -s ~/.codex/skills/airbyte-agent-sdk-src/connector-sdk/.claude/skills/* ~/.codex/skills/\n```\n\nSee [docs.airbyte.com/ai-agents/about/](https://docs.airbyte.com/ai-agents/about/) for full documentation.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fairbytehq%2Fairbyte-agent-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fairbytehq%2Fairbyte-agent-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fairbytehq%2Fairbyte-agent-sdk/lists"}