模块4: 第一次API调用

让我们从最基本的API调用开始。OpenAI Chat Completions API接收一个消息列表（每条消息包含角色和内容），并返回模型生成的响应。这是你将构建的每个智能体的基础。

最小示例

from openai import OpenAI

# Client automatically reads OPENAI_API_KEY from environment
client = OpenAI()

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What is an AI agent?"}
    ]
)

# Extract the response text
print(response.choices[0].message.content)

messages 数组是核心概念。它代表一段对话历史，包含三种可能的角色：

理解响应对象

OpenAI的响应包含的不仅仅是文本。以下是如何检查它：

# Full response inspection
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Explain AI agents in one sentence."}
    ]
)

# The response text
print(response.choices[0].message.content)

# Why the model stopped generating
print(response.choices[0].finish_reason)  # "stop", "length", or "tool_calls"

# Token usage (important for cost tracking!)
print(f"Prompt tokens:     {response.usage.prompt_tokens}")
print(f"Completion tokens: {response.usage.completion_tokens}")
print(f"Total tokens:      {response.usage.total_tokens}")

# Model used
print(f"Model: {response.model}")

使用Temperature和Max Tokens控制输出

Temperature控制随机性。对于智能体，你几乎总是希望低temperature（确定性、可靠的输出）。Max tokens限制响应长度。

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "You are a precise data analyst."},
        {"role": "user", "content": "What is 15% of 847?"}
    ],
    temperature=0.0,    # Deterministic output (best for agents)
    max_tokens=100,     # Limit response length
)
print(response.choices[0].message.content)
# Output: "15% of 847 is 127.05."

多轮对话

要进行来回对话，你需要将助手的响应和用户的后续跟进都追加到messages数组中：

messages = [
    {"role": "system", "content": "You are a helpful maths tutor."},
    {"role": "user", "content": "What is a derivative?"},
]

# First turn
response = client.chat.completions.create(model="gpt-4o", messages=messages)
assistant_reply = response.choices[0].message.content
print(f"Assistant: {assistant_reply}")

# Append assistant reply and user follow-up
messages.append({"role": "assistant", "content": assistant_reply})
messages.append({"role": "user", "content": "Can you give me a simple example?"})

# Second turn - model has full context of the conversation
response = client.chat.completions.create(model="gpt-4o", messages=messages)
print(f"Assistant: {response.choices[0].message.content}")

Anthropic的Messages API遵循类似的概念，但语法不同。最大的区别是系统提示是一个独立参数，而不是messages数组的一部分。

最小示例

import anthropic

# Client automatically reads ANTHROPIC_API_KEY from environment
client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,                              # Required (not optional!)
    system="You are a helpful assistant.",         # Separate from messages
    messages=[
        {"role": "user", "content": "What is an AI agent?"}
    ]
)

# Extract the response text
print(message.content[0].text)

理解Anthropic响应

message = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    system="You are a helpful assistant.",
    messages=[{"role": "user", "content": "Explain AI agents in one sentence."}]
)

# The response text (Anthropic returns a list of content blocks)
print(message.content[0].text)

# Stop reason
print(message.stop_reason)  # "end_turn", "max_tokens", or "tool_use"

# Token usage
print(f"Input tokens:  {message.usage.input_tokens}")
print(f"Output tokens: {message.usage.output_tokens}")

# Model used
print(f"Model: {message.model}")

Anthropic的多轮对话

messages = [
    {"role": "user", "content": "What is a derivative in calculus?"},
]

# First turn
response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    system="You are a helpful maths tutor.",
    messages=messages
)
assistant_reply = response.content[0].text

# Append and continue
messages.append({"role": "assistant", "content": assistant_reply})
messages.append({"role": "user", "content": "Can you give me a simple example?"})

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    system="You are a helpful maths tutor.",
    messages=messages
)
print(response.content[0].text)

Anthropic的结构化输出

对于智能体用例，你经常需要模型返回结构化数据（JSON）而不是自由格式文本。以下是如何请求和解析结构化输出：

import json

message = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    system="""You are a data extraction assistant.
Always respond with valid JSON. No other text.""",
    messages=[{
        "role": "user",
        "content": "Extract the key details: 'Meeting with Sarah on Tuesday at 3pm to discuss Q4 budget. Location: Room 204.'"
    }]
)

# Parse the JSON response
data = json.loads(message.content[0].text)
print(json.dumps(data, indent=2))
# {
#   "event": "Meeting",
#   "attendee": "Sarah",
#   "day": "Tuesday",
#   "time": "3:00 PM",
#   "topic": "Q4 budget",
#   "location": "Room 204"
# }

构建智能体时，你通常会希望支持多个LLM供应商（用于成本优化、故障转移或能力差异）。以下是两个API的详细对比：

编写供应商无关的包装器

由于概念相同但语法不同，常见的模式是编写一个薄包装器来统一两个API：

from openai import OpenAI
import anthropic

class LLMClient:
    """Unified wrapper for OpenAI and Anthropic APIs."""

    def __init__(self, provider: str = "openai"):
        self.provider = provider
        if provider == "openai":
            self.client = OpenAI()
            self.model = "gpt-4o"
        elif provider == "anthropic":
            self.client = anthropic.Anthropic()
            self.model = "claude-sonnet-4-20250514"

    def chat(self, system: str, user_message: str,
             temperature: float = 0.0, max_tokens: int = 1024) -> str:
        """Send a message and return the response text."""
        if self.provider == "openai":
            response = self.client.chat.completions.create(
                model=self.model,
                temperature=temperature,
                max_tokens=max_tokens,
                messages=[
                    {"role": "system", "content": system},
                    {"role": "user", "content": user_message},
                ],
            )
            return response.choices[0].message.content

        elif self.provider == "anthropic":
            message = self.client.messages.create(
                model=self.model,
                max_tokens=max_tokens,
                system=system,
                messages=[{"role": "user", "content": user_message}],
            )
            return message.content[0].text

# Usage - switch providers with one parameter
llm = LLMClient(provider="anthropic")
answer = llm.chat(
    system="You are a helpful assistant.",
    user_message="What is an AI agent?"
)
print(answer)

成本意识

API调用需要花钱。理解token定价对于构建不会让你破产的智能体至关重要：