Skip to content

Commit 3699708

Browse files
ktro2828ktro2828
committed
TODO: add japanese version for unit1
Signed-off-by: ktro2828 <[email protected]>
1 parent 3889344 commit 3699708

17 files changed

+2326
-0
lines changed

‎units/ja/_toctree.yml‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,3 +10,35 @@
1010
sections:
1111
- local: communication/live1
1212
title: Live 1. How the course works and Q&A
13+
- title: Unit 1. Introduction to Agents
14+
sections:
15+
- local: unit1/introduction
16+
title: Introduction
17+
- local: unit1/what-are-agents
18+
title: What is an Agent?
19+
- local: unit1/quiz1
20+
title: Quick Quiz 1
21+
- local: unit1/what-are-llms
22+
title: What are LLMs?
23+
- local: unit1/messages-and-special-tokens
24+
title: Messages and Special Tokens
25+
- local: unit1/tools
26+
title: What are Tools?
27+
- local: unit1/quiz2
28+
title: Quick Quiz 2
29+
- local: unit1/agent-steps-and-structure
30+
title: Understanding AI Agents through the Thought-Action-Observation Cycle
31+
- local: unit1/thoughts
32+
title: Thought, Internal Reasoning and the Re-Act Approach
33+
- local: unit1/actions
34+
title: Actions, Enabling the Agent to Engage with Its Environment
35+
- local: unit1/observations
36+
title: Observe, Integrating Feedback to Reflect and Adapt
37+
- local: unit1/dummy-agent-library
38+
title: Dummy Agent Library
39+
- local: unit1/tutorial
40+
title: Let’s Create Our First Agent Using smolagents
41+
- local: unit1/final-quiz
42+
title: Unit 1 Final Quiz
43+
- local: unit1/conclusion
44+
title: Conclusion

‎units/ja/unit1/README.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Table of Contents
2+
3+
👉 <a href="https://hf.co/learn/agents-course/unit1/introduction">こちらから</a>Unit 1 にアクセスできます
4+
5+
<!--
6+
| Title | Description |
7+
|-------|-------------|
8+
| [Definition of an Agent](1_definition_of_an_agent.md) | General example of what agents can do without technical jargon. |
9+
| [Explain LLMs](2_explain_llms.md) | Explanation of Large Language Models, including the family tree of models and suitable models for agents. |
10+
| [Messages and Special Tokens](3_messages_and_special_tokens.md) | Explanation of messages, special tokens, and chat-template usage. |
11+
| [Dummy Agent Library](4_dummy_agent_library.md) | Introduction to using a dummy agent library and serverless API. |
12+
| [Tools](5_tools.md) | Overview of Pydantic for agent tools and other common tool formats. |
13+
| [Agent Steps and Structure](6_agent_steps_and_structure.md) | Steps involved in an agent, including thoughts, actions, observations, and a comparison between code agents and JSON agents. |
14+
| [Thoughts](7_thoughts.md) | Explanation of thoughts and the ReAct approach. |
15+
| [Actions](8_actions.md) | Overview of actions and stop and parse approach. |
16+
| [Observations](9_observations.md) | Explanation of observations and append result to reflect. |
17+
| [Quizz](10_quizz.md) | Contains quizzes to test understanding of the concepts. |
18+
| [Simple Use Case](11_simple_use_case.md) | Provides a simple use case exercise using datetime and a Python function as a tool. |
19+
-->

‎units/ja/unit1/actions.mdx‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
# Actions: Enabling the Agent to Engage with Its Environment
2+
3+
<tip>
4+
このセクションでは、エージェントが環境と相互作用するための具体的な方法ステップについて探索します。
5+
6+
アクションがどのように表現されるか(JSONやコードを使用)、ストップ&パース手法の重要性、そして様々な種類のエージェントを紹介します。
7+
</tip>
8+
9+
アクションとは**AIエージェントが環境と相互作用するための**具体的なステップです。
10+
11+
ウェブを閲覧して情報を得ようが、物理的なデバイスを操作しようが、それぞれのアクションはエージェントによって意図的に実行される操作です。
12+
13+
例えば、カスタマーサービスを支援するエージェントは顧客データを検索したり、サポート記事を提供したり、問題を人間の担当者に転送するかもしれません。
14+
15+
## エージェントアクションの種類
16+
17+
エージェントには複数の種類があり、それぞれ異なるアクションをとります:
18+
19+
| エージェントの種類 | 説明 |
20+
|------------------------|--------------------------------------------------------------------------------------------------|
21+
| JSON エージェント | 実行されるアクションはJSON形式で指定されます。 |
22+
| Code エージェント | エージェントは外部から解釈されるコードブロックを書きます。 |
23+
| 関数呼び出しエージェント | これはJSONエージェントのサブカテゴリで、アクションごとに新しいメッセージを生成するようにファインチューニングされます。 |
24+
25+
アクション自体は多くの目的を果たすことができます:
26+
27+
| アクションの種類 | 説明 |
28+
|--------------------------|------------------------------------------------------------------------------------------|
29+
| 情報収集 | ウェブ検索、データベースのクエリ化、またはドキュメントの取得。 |
30+
| ツールの使い方 | APIの呼び出し、計算の実行、コードの実行。 |
31+
| 環境との相互作用 | デジタルインターフェースの操作や物理デバイスの制御。
32+
| コミュニケーション | チャットや他のエージェントとの共同作業を通じてユーザーと関わる。 |
33+
34+
LLMはテキストのみを取り扱い実行したいアクションやツールに与えるパラメータを記述するためにテキストを使います。エージェントが適切に動作するためには、LLMは完全なアクションを定義するためにすべてのトークンを出力した後、新しいトークンの生成を停止しなければなりません。これにより、LLMからエージェントに制御が戻り、意図された形式がJSONであれ、コードであれ、関数呼び出しであれ、結果が解析可能であることが保証されます。
35+
36+
## ストップ&パース手法 (Stop and Parse Approach)
37+
38+
アクションを実装するための重要な手法が**ストップ&パース**です。この手法がエージェントの出力が構造化され予測可能であることを保証します:
39+
40+
1. **構造化された形式での生成**:
41+
42+
エージェントは意図されたアクションを明確な所定の形式(JSONまたはコード)で出力します。
43+
44+
2. **さらなる生成の停止**
45+
46+
アクションを定義するテキストが出力されると、**LLMは追加のトークン生成を停止します**。これにより、余分な出力や誤った出力を防ぐことができます。
47+
48+
3. **出力の解析**
49+
50+
外部のパーサーが形式されたアクションを読み込み、どのツールを呼び出すが決定し、必要なパラメータを抽出します。
51+
52+
例えば、天気を調べるエージェントは以下を出力するでしょう:
53+
54+
```json
55+
Thought: I need to check the current weather for New York.
56+
Action :
57+
{
58+
"action": "get_weather",
59+
"action_input": {"location": "New York"}
60+
}
61+
```
62+
63+
フレームワークは呼び出す関数名と適用する引数を簡単に解析できます。
64+
65+
この明確で機械が読める形式は、誤りを最小化し外部ツールが正確にエージェントのコマンドを実行することを可能にします。
66+
67+
注: 関数呼び出しエージェントは、指定された関数が正しい引数で呼び出されるようにアクションを構造化することで同様に動作します。
68+
69+
## コードエージェント
70+
71+
他のアプローチは*コードエージェント*を使用することです。
72+
The idea is: **instead of outputting a simple JSON object**, a Code Agent generates an **executable code block—typically in a high-level language like Python**.
73+
このアイデアは: **シンプルなJSON形式を出力する代わりに**、コードエージェントが**実行可能なコードブロック(通常はPythonのような高級言語による)**を生成します。
74+
75+
<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/code-vs-json-actions.png" alt="Code Agents" />
76+
77+
この方法にはいくつかの利点があります:
78+
79+
- **表現力:** コードはループ、条件分岐、ネスト関数などの複雑なロジックを自然に表現することができ、JSONよりも柔軟が高いです。
80+
- **モジュール性と再利用性:** 生成されたコードは異なるアクションやタスクをまたいで再利用できる関数やモジュールを含むことができます。
81+
- **デバッグ機能の強化:** プログラムの構文がきちんと定義されていれば、コードのエラーを発見しやすく、修正しやすくなります。
82+
- **直接統合:** コードエージェントは外部ライブラリやAPIと直接統合することができ、データ処理やリアルタイム意思決定などのより複雑な処理を可能にします。
83+
84+
LLMによって生成されたコードを実行すると、プロンプト・インジェクションから有害なコードの実行に至るまで、セキュリティリスクが生じる可能性があることに留意しなければなりません。
85+
そのため、デフォルトのセーフガードを統合した`smolagents`のようなAIエージェントフレームワークを使うことが推奨されています。
86+
リスクとその軽減方法について詳しく知りたい場合は、[こちらの専用セクションをご覧ください](https://huggingface.co/docs/smolagents/tutorials/secure_code_execution)。
87+
88+
例えば、現在の天気の取得をタスクとするコードエージェントは、次のようなPythonスニペットを生成するかもしれません:
89+
90+
```python
91+
# Code Agent Example: Retrieve Weather Information
92+
def get_weather(city):
93+
import requests
94+
api_url = f"https://api.weather.com/v1/location/{city}?apiKey=YOUR_API_KEY"
95+
response = requests.get(api_url)
96+
if response.status_code == 200:
97+
data = response.json()
98+
return data.get("weather", "No weather information available")
99+
else:
100+
return "Error: Unable to fetch weather data."
101+
102+
# Execute the function and prepare the final answer
103+
result = get_weather("New York")
104+
final_answer = f"The current weather in New York is: {result}"
105+
print(final_answer)
106+
```
107+
108+
この例では、コードエージェントは:
109+
110+
- 天気のデータを**API呼出しによって**取得する、
111+
- レスポンスを処理する、
112+
- 最終的な回答を出力するためにprint()関数を使用する。
113+
114+
This method **also follows the stop and parse approach** by clearly delimiting the code block and signaling when execution is complete (here, by printing the final_answer).
115+
この方法も、コードブロックを明確に区切り実行が完了したことを知らせる(ここでは、final_answerを表示する)ことで、**ストップ&パース手法**に従っています。
116+
117+
---
118+
119+
アクションは、JSON、コード、または関数呼び出しなどを通じて、明確で構造化されたタスクを実行することで、エージェントの内部推論と実世界の相互作用の橋渡しをすることを学びました。
120+
121+
この意図的な実行は、各アクションが正確で、停止と解析のアプローチを通じて外部処理の準備が整っていることを保証します。
122+
123+
次のセクションでは、エージェントがどのように環境からのフィードバックを取得し、統合するかを見るために、Observations(観察)を探求します。
124+
125+
その後、私達は**ついに最初のエージェントを作成する準備が整います!**
126+
127+
128+
129+
130+

‎units/ja/unit1/agent-steps-and-structure.mdx‎

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
# Understanding AI Agents through the Thought-Action-Observation Cycle
2+
3+
<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/whiteboard-check-3.jpg" alt="Unit 1 planning"/>
4+
5+
In the previous sections, we learned:
6+
7+
- **How tools are made available to the agent in the system prompt**.
8+
- **How AI agents are systems that can 'reason', plan, and interact with their environment**.
9+
10+
In this section, **we’ll explore the complete AI Agent Workflow**, a cycle we defined as Thought-Action-Observation.
11+
12+
And then, we’ll dive deeper on each of these steps.
13+
14+
15+
## The Core Components
16+
17+
Agents work in a continuous cycle of: **thinking (Thought) → acting (Act) and observing (Observe)**.
18+
19+
Let’s break down these actions together:
20+
21+
1. **Thought**: The LLM part of the Agent decides what the next step should be.
22+
2. **Action:** The agent takes an action, by calling the tools with the associated arguments.
23+
3. **Observation:** The model reflects on the response from the tool.
24+
25+
## The Thought-Action-Observation Cycle
26+
27+
The three components work together in a continuous loop. To use an analogy from programming, the agent uses a **while loop**: the loop continues until the objective of the agent has been fulfilled.
28+
29+
Visually, it looks like this:
30+
31+
<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/AgentCycle.gif" alt="Think, Act, Observe cycle"/>
32+
33+
In many Agent frameworks, **the rules and guidelines are embedded directly into the system prompt**, ensuring that every cycle adheres to a defined logic.
34+
35+
In a simplified version, our system prompt may look like this:
36+
37+
<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/system_prompt_cycle.png" alt="Think, Act, Observe cycle"/>
38+
39+
We see here that in the System Message we defined :
40+
41+
- The *Agent's behavior*.
42+
- The *Tools our Agent has access to*, as we described in the previous section.
43+
- The *Thought-Action-Observation Cycle*, that we bake into the LLM instructions.
44+
45+
Let’s take a small example to understand the process before going deeper into each step of the process.
46+
47+
## Alfred, the weather Agent
48+
49+
We created Alfred, the Weather Agent.
50+
51+
A user asks Alfred: “What’s the current weather in New York?”
52+
53+
<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/alfred-agent.jpg" alt="Alfred Agent"/>
54+
55+
Alfred’s job is to answer this query using a weather API tool.
56+
57+
Here’s how the cycle unfolds:
58+
59+
### Thought
60+
61+
**Internal Reasoning:**
62+
63+
Upon receiving the query, Alfred’s internal dialogue might be:
64+
65+
*"The user needs current weather information for New York. I have access to a tool that fetches weather data. First, I need to call the weather API to get up-to-date details."*
66+
67+
This step shows the agent breaking the problem into steps: first, gathering the necessary data.
68+
69+
<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/alfred-agent-1.jpg" alt="Alfred Agent"/>
70+
71+
### Action
72+
73+
**Tool Usage:**
74+
75+
Based on its reasoning and the fact that Alfred knows about a `get_weather` tool, Alfred prepares a JSON-formatted command that calls the weather API tool. For example, its first action could be:
76+
77+
Thought: I need to check the current weather for New York.
78+
79+
```
80+
{
81+
"action": "get_weather",
82+
"action_input": {
83+
"location": "New York"
84+
}
85+
}
86+
```
87+
88+
Here, the action clearly specifies which tool to call (e.g., get_weather) and what parameter to pass (the “location": “New York”).
89+
90+
<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/alfred-agent-2.jpg" alt="Alfred Agent"/>
91+
92+
### Observation
93+
94+
**Feedback from the Environment:**
95+
96+
After the tool call, Alfred receives an observation. This might be the raw weather data from the API such as:
97+
98+
*"Current weather in New York: partly cloudy, 15°C, 60% humidity."*
99+
100+
<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/alfred-agent-3.jpg" alt="Alfred Agent"/>
101+
102+
This observation is then added to the prompt as additional context. It functions as real-world feedback, confirming whether the action succeeded and providing the needed details.
103+
104+
105+
### Updated thought
106+
107+
**Reflecting:**
108+
109+
With the observation in hand, Alfred updates its internal reasoning:
110+
111+
*"Now that I have the weather data for New York, I can compile an answer for the user."*
112+
113+
<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/alfred-agent-4.jpg" alt="Alfred Agent"/>
114+
115+
116+
### Final Action
117+
118+
Alfred then generates a final response formatted as we told it to:
119+
120+
Thought: I have the weather data now. The current weather in New York is partly cloudy with a temperature of 15°C and 60% humidity."
121+
122+
Final answer : The current weather in New York is partly cloudy with a temperature of 15°C and 60% humidity.
123+
124+
This final action sends the answer back to the user, closing the loop.
125+
126+
127+
<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/alfred-agent-5.jpg" alt="Alfred Agent"/>
128+
129+
130+
What we see in this example:
131+
132+
- **Agents iterate through a loop until the objective is fulfilled:**
133+
134+
**Alfred’s process is cyclical**. It starts with a thought, then acts by calling a tool, and finally observes the outcome. If the observation had indicated an error or incomplete data, Alfred could have re-entered the cycle to correct its approach.
135+
136+
- **Tool Integration:**
137+
138+
The ability to call a tool (like a weather API) enables Alfred to go **beyond static knowledge and retrieve real-time data**, an essential aspect of many AI Agents.
139+
140+
- **Dynamic Adaptation:**
141+
142+
Each cycle allows the agent to incorporate fresh information (observations) into its reasoning (thought), ensuring that the final answer is well-informed and accurate.
143+
144+
This example showcases the core concept behind the *ReAct cycle* (a concept we're going to develop in the next section): **the interplay of Thought, Action, and Observation empowers AI agents to solve complex tasks iteratively**.
145+
146+
By understanding and applying these principles, you can design agents that not only reason about their tasks but also **effectively utilize external tools to complete them**, all while continuously refining their output based on environmental feedback.
147+
148+
---
149+
150+
Let’s now dive deeper into the Thought, Action, Observation as the individual steps of the process.

‎units/ja/unit1/conclusion.mdx‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Conclusion [[conclusion]]
2+
3+
Congratulations on finishing this first Unit 🥳
4+
5+
You've just **mastered the fundamentals of Agents** and you've created your first AI Agent!
6+
7+
It's **normal if you still feel confused by some of these elements**. Agents are a complex topic and it's common to take a while to grasp everything.
8+
9+
**Take time to really grasp the material** before continuing. It’s important to master these elements and have a solid foundation before entering the fun part.
10+
11+
And if you pass the Quiz test, don't forget to get your certificate 🎓 👉 [here](https://huggingface.co/spaces/agents-course/unit1-certification-app)
12+
13+
<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/certificate-example.jpg" alt="Certificate Example"/>
14+
15+
In the next (bonus) unit, you're going to learn **to fine-tune a Agent to do function calling (aka to be able to call tools based on user prompt)**.
16+
17+
Finally, we would love **to hear what you think of the course and how we can improve it**. If you have some feedback then, please 👉 [fill this form](https://docs.google.com/forms/d/e/1FAIpQLSe9VaONn0eglax0uTwi29rIn4tM7H2sYmmybmG5jJNlE5v0xA/viewform?usp=dialog)
18+
19+
### Keep Learning, stay awesome 🤗

0 commit comments

Comments
 (0)