From bbce7b843c6e59981dc0a9f306f8744008189315 Mon Sep 17 00:00:00 2001 From: Dominik Kundel Date: Fri, 6 Jun 2025 15:34:10 -0700 Subject: [PATCH 1/3] wip --- docs/src/styles/global.css | 64 +++++++++++++++++++++++++++++--------- 1 file changed, 50 insertions(+), 14 deletions(-) diff --git a/docs/src/styles/global.css b/docs/src/styles/global.css index 7ea47ea9..1f088dd7 100644 --- a/docs/src/styles/global.css +++ b/docs/src/styles/global.css @@ -78,8 +78,11 @@ @layer my-overrides { :root { + --openai-text-primary: #ffffff; --openai-background: #202123; --openai-light-gray: #000; + --openai-primary: #4db8ff; + --openai-secondary: #6e6e80; --openai-gray-05: #f7f7f8; --openai-hover-gray: #565869; --openai-gray-1: #353741; @@ -94,9 +97,13 @@ --openai-code-highlight-color: rgba(255, 255, 255, 0.1); --openai-hero-background: var(--openai-code-background); --openai-hero-hover-color: var(--openai-gray-1); - --sl-color-bg-sidebar: var(--openai-light-gray) !important; - --sl-color-bg-nav: var(--openai-light-gray) !important; - --sl-color-bg: var(--openai-light-gray) !important; + --openai-search-text: var(--openai-text-primary); + --openai-search-field-background: var(--openai-light-gray); + --openai-search-button-color: var(--openai-gray-1); + --openai-search-button-hover-color: var(--openai-gray-2); + --sl-color-bg-sidebar: var(--openai-background) !important; + --sl-color-bg-nav: var(--openai-background) !important; + --sl-color-bg: var(--openai-background) !important; --sl-nav-pad-y: 1rem !important; --sl-text-h1: var(--sl-text-3xl) !important; --sl-text-h2: var(--sl-text-2xl) !important; @@ -114,8 +121,11 @@ } :root[data-theme='light'] { + --openai-text-primary: #202123; --openai-background: #ffffff; --openai-light-gray: #f5f5f5; + --openai-primary: #4db8ff; + --openai-secondary: #6e6e80; --openai-gray-05: #f7f7f8; --openai-hover-gray: hsla(240deg, 17%, 94%, 0.5); --openai-gray-1: #ececf1; @@ -129,9 +139,13 @@ --openai-title-color: #000000; --openai-code-highlight-color: var(--openai-gray-1); --openai-hero-background: var(--openai-gray-05); - --sl-color-bg-sidebar: var(--openai-light-gray) !important; - --sl-color-bg-nav: var(--openai-light-gray) !important; - --sl-color-bg: var(--openai-light-gray) !important; + --openai-search-text: var(--openai-text-primary); + --openai-search-field-background: var(--openai-light-gray); + --openai-search-button-color: var(--openai-gray-1); + --openai-search-button-hover-color: var(--openai-gray-2); + --sl-color-bg-sidebar: var(--openai-background) !important; + --sl-color-bg-nav: var(--openai-background) !important; + --sl-color-bg: var(--openai-background) !important; --sl-nav-pad-y: 1rem !important; --sl-text-h1: var(--sl-text-3xl) !important; --sl-text-h2: var(--sl-text-2xl) !important; @@ -218,10 +232,30 @@ site-search { button { - background-color: var(--openai-light-gray) !important; - kbd { - background-color: var(--openai-gray-1) !important; - color: var(--openai-gray-2) !important; + border: 0 !important; + color: var(--openai-search-text) !important; + background-color: var(--openai-search-field-background) !important; + > kbd { + display: inline-flex; + gap: 0.25rem; + padding: 0 !important; + background-color: transparent !important; + + kbd { + padding-inline-start: 0.4rem !important; + padding-inline-end: 0.4rem !important; + border-radius: 4px !important; + background-color: var(--openai-search-button-color) !important; + color: var(--openai-search-text) !important; + } + + &:hover { + kbd { + background-color: var( + --openai-search-button-hover-color + ) !important; + } + } } } } @@ -252,9 +286,9 @@ .sidebar { --sl-color-hairline-shade: rgba(0, 0, 0, 0) !important; a[aria-current='page'] { - color: initial !important; - font-weight: 700 !important; - background-color: var(--openai-gray-1) !important; + color: var(--openai-primary) !important; + font-weight: 500 !important; + background-color: transparent !important; } a { @@ -282,7 +316,9 @@ } ul.top-level > li > details > summary span { - text-transform: uppercase; + font-weight: 500 !important; + font-size: var(--sl-text-xs) !important; + color: var(--openai-secondary) !important; } details > summary span { From c667efda29cd44ecd856bc23f9d01fb91f4ad6a6 Mon Sep 17 00:00:00 2001 From: Dominik Kundel Date: Fri, 6 Jun 2025 18:07:31 -0700 Subject: [PATCH 2/3] finish first iteration --- docs/src/components/Hero.astro | 16 ++-- docs/src/content/docs/index.mdx | 13 +-- docs/src/styles/global.css | 135 ++++++++++++++++++++++++-------- 3 files changed, 111 insertions(+), 53 deletions(-) diff --git a/docs/src/components/Hero.astro b/docs/src/components/Hero.astro index 61323aa5..2e14fe63 100644 --- a/docs/src/components/Hero.astro +++ b/docs/src/components/Hero.astro @@ -3,24 +3,24 @@ import { Code, TabItem, Tabs } from '@astrojs/starlight/components'; import helloWorldExample from '../../../examples/docs/toppage/textAgent.ts?raw'; import helloWorldVoiceExample from '../../../examples/docs/toppage/voiceAgent.ts?raw'; const path = Astro.url.pathname; -const pathPrefix = path !== '/' ? !path.endsWith("/") ? path + "/" : path : ''; +const pathPrefix = + path !== '/' ? (!path.endsWith('/') ? path + '/' : path) : ''; ---
- +
- -
+
+
diff --git a/docs/src/content/docs/index.mdx b/docs/src/content/docs/index.mdx index 388d0430..964f38cb 100644 --- a/docs/src/content/docs/index.mdx +++ b/docs/src/content/docs/index.mdx @@ -11,11 +11,8 @@ import helloWorldExample from '../../../../examples/docs/hello-world.ts?raw'; Quickstart - - Build your first agent in minutes. Learn the basics of the OpenAI Agents - SDK. - - Get started + Build your first agent in minutes. + Let's build The [OpenAI Agents SDK for TypeScript](https://github.com/openai/openai-agents-js) @@ -36,12 +33,6 @@ real-world applications without a steep learning curve. In addition, the SDK comes with built-in **tracing** that lets you visualize and debug your agentic flows, as well as evaluate them and even fine-tune models for your application. - - ## Why use the Agents SDK The SDK has two driving design principles: diff --git a/docs/src/styles/global.css b/docs/src/styles/global.css index 1f088dd7..db364975 100644 --- a/docs/src/styles/global.css +++ b/docs/src/styles/global.css @@ -82,6 +82,7 @@ --openai-background: #202123; --openai-light-gray: #000; --openai-primary: #4db8ff; + --openai-primary-darker: #3e94ce; --openai-secondary: #6e6e80; --openai-gray-05: #f7f7f8; --openai-hover-gray: #565869; @@ -89,7 +90,8 @@ --openai-gray-2: #717182; --openai-green: #10a37f; --openai-green-darker: #1a7f64; - --openai-nav-text: #acacbe; + --openai-nav-category-text: #acacbe; + --openai-nav-text: #ffffff; --openai-toc-highlight: #ffffff; --openai-code-background: #161719; --openai-code-border-color: var(--openai-light-gray); @@ -101,6 +103,9 @@ --openai-search-field-background: var(--openai-light-gray); --openai-search-button-color: var(--openai-gray-1); --openai-search-button-hover-color: var(--openai-gray-2); + --openai-primary-button-background: var(--openai-text-primary); + --openai-primary-button-hover-background: var(--openai-gray-1); + --openai-primary-button-text: var(--openai-light-gray); --sl-color-bg-sidebar: var(--openai-background) !important; --sl-color-bg-nav: var(--openai-background) !important; --sl-color-bg: var(--openai-background) !important; @@ -125,14 +130,17 @@ --openai-background: #ffffff; --openai-light-gray: #f5f5f5; --openai-primary: #4db8ff; + --openai-primary-darker: #3e94ce; --openai-secondary: #6e6e80; --openai-gray-05: #f7f7f8; --openai-hover-gray: hsla(240deg, 17%, 94%, 0.5); --openai-gray-1: #ececf1; --openai-gray-2: #717182; + --openai-gray-3: #353740; --openai-green: #10a37f; --openai-green-darker: #1a7f64; --openai-nav-text: #202123; + --openai-nav-category-text: var(--openai-text-secondary); --openai-toc-highlight: #353740; --openai-code-background: var(--openai-gray-05); --openai-code-border-color: var(--openai-gray-1); @@ -143,6 +151,9 @@ --openai-search-field-background: var(--openai-light-gray); --openai-search-button-color: var(--openai-gray-1); --openai-search-button-hover-color: var(--openai-gray-2); + --openai-primary-button-background: #000000; + --openai-primary-button-hover-background: var(--openai-gray-3); + --openai-primary-button-text: var(--openai-light-gray); --sl-color-bg-sidebar: var(--openai-background) !important; --sl-color-bg-nav: var(--openai-background) !important; --sl-color-bg: var(--openai-background) !important; @@ -156,6 +167,15 @@ --sl-color-bg-inline-code: var(--openai-gray-05) !important; --sl-nav-gap: 1rem !important; --sl-content-width: 60rem !important; + --sl-content-pad-x: 1rem !important; + + @media (min-width: 48rem) { + --sl-content-pad-x: 2rem !important; + } + + @media (min-width: 72rem) { + --sl-content-pad-x: 3rem !important; + } } .openai-logo { @@ -199,12 +219,12 @@ } a:not(:where(.not-content *)) { - color: var(--openai-green) !important; + color: var(--openai-primary) !important; text-decoration: none !important; } a:hover:not(:where(.not-content *)) { - color: var(--openai-green-darker) !important; + color: var(--openai-primary-darker) !important; } table:not(:where(.not-content *)) { @@ -269,13 +289,28 @@ padding-top: var(--sl-content-pad-x) !important; } - starlight-toc ul > li { - padding-top: 0.3em; - padding-bottom: 0.3em; - border-left: calc(2px - var(--depth) * 2px) solid var(--openai-gray-1); + starlight-toc { + h2 { + font-size: var(--sl-text-2xs); + font-weight: 500; + color: var(--openai-nav-category-text); + } + ul > li { + padding-top: 0.3em; + padding-bottom: 0.3em; + border-inline-start: 0; + + a { + color: var(--openai-text-primary); + padding-inline-start: calc(var(--depth) * 1em); + } - &:has([aria-current='true']) { - border-left-color: var(--openai-toc-highlight); + &:has([aria-current='true']) { + a { + color: var(--openai-primary) !important; + } + border-left-color: var(--openai-toc-highlight); + } } } @@ -315,10 +350,16 @@ padding-inline-start: 0 !important; } - ul.top-level > li > details > summary span { - font-weight: 500 !important; - font-size: var(--sl-text-xs) !important; - color: var(--openai-secondary) !important; + ul.top-level > li > details > summary { + svg { + color: var(--openai-nav-category-text) !important; + } + + span { + font-weight: 500 !important; + font-size: var(--sl-text-xs) !important; + color: var(--openai-nav-category-text) !important; + } } details > summary span { @@ -367,7 +408,12 @@ .sl-markdown-content .openai-hero { background-color: var(--openai-hero-background); - border-radius: 8px; + border-radius: 24px; + --hero-padding: 2rem; + + @media (min-width: 72rem) { + --hero-padding: 3rem; + } .openai-hero-container { flex-direction: column; @@ -377,14 +423,30 @@ } } + ul[role='tablist'] { + border-bottom: 0; + } + + .openai-hero-code { + margin-bottom: var(--hero-padding); + margin-inline-start: calc(var(--hero-padding) - 1rem); + margin-inline-end: var(--hero-padding); + + @media (min-width: 72rem) { + margin-bottom: 0rem; + margin-inline-start: 0rem; + } + } + .tab a { - padding: 0.25rem 1rem; - margin-top: 0.5rem; + padding: 0; + padding-inline-start: 1rem; font-size: var(--sl-text-xs); border-radius: 0; &[aria-selected='true'] { + color: var(--openai-primary); font-weight: 500; - border-bottom: 2px solid var(--openai-green); + border-bottom: 0; } &:not([aria-selected='true']) { color: var(--openai-gray-2) !important; @@ -395,24 +457,15 @@ margin-top: 0; } - a.openai-quickstart { - border-radius: 8px; - padding: 1rem; + .openai-quickstart { + border-radius: 24px; + padding: var(--hero-padding); + min-width: 15rem; @media (min-width: 72rem) { max-width: 20rem; } - - &:hover, - &:focus { - background-color: var(--openai-hero-hover-color); - - .openai-hero-cta::after { - margin-inline-start: 0.5rem; - } - } - color: var(--openai-title-color) !important; span.title { @@ -421,17 +474,27 @@ } p { - margin-top: 0.5rem; + margin-top: 0.75rem; + margin-bottom: 0.75rem; font-size: var(--sl-text-sm); } .openai-hero-cta { font-size: var(--sl-text-sm); font-weight: 500; + color: var(--openai-primary-button-text) !important; + background-color: var(--openai-primary-button-background); + border-radius: 50px; + padding: 0.5rem 1rem; + + &:hover, + &:focus { + background-color: var(--openai-primary-button-hover-background); + } + &::after { - content: '→'; + content: '❯'; margin-inline-start: 0.25rem; - transition: margin-inline-start 0.2s ease-in-out; } } } @@ -447,6 +510,10 @@ background: none; } + .frame.has-title:not(.is-terminal) .title::after { + border: none; + } + .mark { background-color: var(--openai-code-highlight-color) !important; .code { @@ -467,7 +534,7 @@ figcaption span { /* title */ - font-family: var(--sl-font-mono); + font-family: var(--__sl-font-mono); font-size: var(--sl-text-2xs); padding: 0.75em 1rem; border-start-start-radius: var(--openai-code-border-radius); From c80f39a6a0009e2979a3f75bdae2e95b7a1f89ea Mon Sep 17 00:00:00 2001 From: Dominik Kundel Date: Fri, 6 Jun 2025 18:09:43 -0700 Subject: [PATCH 3/3] add japanese translation --- docs/src/content/docs/ja/index.mdx | 52 +++++++++++++----------------- 1 file changed, 22 insertions(+), 30 deletions(-) diff --git a/docs/src/content/docs/ja/index.mdx b/docs/src/content/docs/ja/index.mdx index 3f54dd2e..bb331275 100644 --- a/docs/src/content/docs/ja/index.mdx +++ b/docs/src/content/docs/ja/index.mdx @@ -11,43 +11,35 @@ import helloWorldExample from '../../../../../examples/docs/hello-world.ts?raw'; クイックスタート - - 数分で最初のエージェントを構築できます。OpenAI Agents SDK - の基本を学びましょう。 - - はじめる + 数分で最初のエージェントを構築します。 + 作ってみよう -[TypeScript 用 OpenAI Agents SDK](https://github.com/openai/openai-agents-js) は、最小限の抽象化で軽量かつ使いやすいパッケージとしてエージェント指向の AI アプリを構築できるようにします。これは、以前のエージェント向け実験プロジェクトである [Swarm](https://github.com/openai/swarm/tree/main) を本番環境向けにアップグレードしたもので、[Python でも利用可能です](https://github.com/openai/openai-agents-python)。Agents SDK が提供する基本コンポーネントはごく少数です。 +[OpenAI Agents SDK for TypeScript](https://github.com/openai/openai-agents-js) は、きわめて少ない抽象化でエージェント指向の AI アプリを簡単かつ軽量に構築できるパッケージです。これは以前のエージェント向け実験 +[Swarm](https://github.com/openai/swarm/tree/main) を本番利用向けにアップグレードしたもので、[Python 版](https://github.com/openai/openai-agents-python) も提供されています。Agents SDK にはごく少数の基本コンポーネントがあります。 -- **エージェント**: `instructions` と `tools` を備えた LLM -- **ハンドオフ**: 特定のタスクを別のエージェントに委任する仕組み -- **ガードレール**: エージェントへの入力を検証する仕組み +- ** エージェント **: instructions と tools を備えた LLM +- ** ハンドオフ **: 特定タスクを別のエージェントに委任 +- ** ガードレール **: エージェントへの入力を検証 -TypeScript と組み合わせることで、これらの基本コンポーネントだけでツールとエージェント間の複雑な関係を表現でき、学習コストを抑えつつ実用的なアプリケーションを構築できます。さらに、SDK には **トレーシング** が組み込まれており、エージェントフローの可視化やデバッグ、評価、さらにはアプリ向けモデルのファインチューニングまで行えます。 +TypeScript と組み合わせることで、これらの基本コンポーネントはツールとエージェント間の複雑な関係を表現でき、学習コストを抑えつつ実運用アプリを構築できます。さらに SDK には ** トレーシング ** が組み込まれており、エージェントフローの可視化とデバッグ、評価、さらにはモデルのファインチューニングまで行えます。 - +## Agents SDK を使用する理由 -## Agents SDK を利用する理由 +SDK の設計原則は次の 2 つです。 -SDK の設計原則は次の二つです。 +1. 使う価値のある十分な機能を備えつつ、学習が容易な最小限の基本コンポーネント +2. デフォルトで優れた動作を提供しつつ、細部を自由にカスタマイズ可能 -1. 使う価値のある機能を十分に備えつつ、習得が早いようコンポーネントを絞る -2. デフォルトでもすぐに使えるが、動作を細かくカスタマイズできる +主な機能は以下のとおりです。 -主な特徴は以下のとおりです。 - -- **エージェントループ**: ツール呼び出し、結果の LLM への送信、LLM が完了するまでのループ処理を内蔵 -- **TypeScript ファースト**: 新しい抽象概念を学ばなくても、言語機能でエージェントをオーケストレーション -- **ハンドオフ**: 複数エージェント間での協調や委任を実現する強力な機能 -- **ガードレール**: 入力のバリデーションやチェックをエージェントと並行実行し、不合格なら早期終了 -- **関数ツール**: 任意の TypeScript 関数をツール化し、自動スキーマ生成と Zod による検証を提供 -- **トレーシング**: ワークフローの可視化・デバッグ・モニタリングに加え、OpenAI の評価・ファインチューニング・蒸留ツールを活用可能 -- **Realtime Agents**: 自動割り込み検知、コンテキスト管理、ガードレールなどを備えた高機能な音声エージェントを構築 +- ** エージェントループ **: tool を呼び出し、その結果を LLM に送り、LLM が完了するまでループ処理 +- ** TypeScript ファースト **: 新しい抽象化を覚えることなく、言語機能でエージェントを編成・連鎖 +- ** ハンドオフ **: 複数エージェント間の調整と委任を実現する強力な機能 +- ** ガードレール **: 入力検証やチェックをエージェントと並行して実行し、不合格なら早期終了 +- ** 関数ツール **: 任意の TypeScript 関数を自動スキーマ生成と Zod 検証付きで tool 化 +- ** トレーシング **: ワークフローを可視化・デバッグ・監視し、OpenAI の評価、ファインチューニング、蒸留ツールを活用 +- ** Realtime Agents **: 自動割り込み検知、コンテキスト管理、ガードレールなどを備えた高機能音声エージェントを構築 ## インストール @@ -55,11 +47,11 @@ SDK の設計原則は次の二つです。 npm install @openai/agents ``` -## Hello World の例 +## Hello World コード例 -(_実行する場合は `OPENAI_API_KEY` 環境変数を設定してください_) +(_実行する場合は、環境変数 `OPENAI_API_KEY` を設定してください_) ```bash export OPENAI_API_KEY=sk-...