BAML 原理与实战：AI 工作流与代理的声明式提示语言全解析

function ChatAgent(message: Message[], tone: "happy" | "sad") -> string

function ChatAgent(message: Message[], tone: "happy" | "sad") -> StopTool | ReplyTool {
    client "openai/gpt-4o-mini"

    prompt #"
        Be a {{ tone }} bot.

        {{ ctx.output_format }}

        {% for m in message %}
        {{ _.role(m.role) }}
        {{ m.content }}
        {% endfor %}
    "#
}

class Message {
    role string
    content string
}

class ReplyTool {
  response string
}

class StopTool {
  action "stop" @description(#"
    when it might be a good time to end the conversation
  "#)
}

from baml_client import b
from baml_client.types import Message, StopTool

messages = [Message(role="assistant", content="How can I help?")]

while True:
  print(messages[-1].content)
  user_reply = input()
  messages.append(Message(role="user", content=user_reply))
  tool = b.ChatAgent(messages, "happy")
  if isinstance(tool, StopTool):
    print("Goodbye!")
    break
  else:
    messages.append(Message(role="assistant", content=tool.response))

stream = b.stream.ChatAgent(messages, "happy")
# partial 是所有字段可选的 Partial 类型
for tool in stream:
    if isinstance(tool, StopTool):
      ...
    
final = stream.get_final_response()

class Resume {
  name string
  education Education[] @description("Extract in the same order listed")
  skills string[] @description("Only include programming languages")
}

class Education {
  school string
  degree string
  year int
}

function ExtractResume(resume_text: string) -> Resume {
  // see clients.baml
  client GPT4o

  // The prompt uses Jinja syntax. Change the models or this text and watch the prompt preview change!
  prompt #"
    Parse the following resume and return a structured representation of the data in the schema below.

    Resume:
    ---
    {{ resume_text }}
    ---

    {# special macro to print the output instructions. #}
    {{ ctx.output_format }}

    JSON:
  "#
}

system:
Parse the following resume and return a structured representation of the data in the schema below.

Resume:
---
John Doe

Education
- University of California, Berkeley
  - B.S. in Computer Science
  - 2020

Skills
- Python
- Java
- C++
---

Answer in JSON using this schema:
{
  name: string,
  // Extract in the same order listed
  education: [
    {
      school: string,
      degree: string,
      year: int,
    }
  ],
  // Only include programming languages
  skills: string[],
}

JSON:

uv init baml-samples
cd baml-samples
uv run main.py
source .venv/bin/activate

uv add baml-py

uv run baml-cli init

uv run baml-cli generate

from baml_client.sync_client import b
from baml_client.types import Resume

def example(raw_resume: str) -> Resume: 
  # BAML's internal parser guarantees ExtractResume
  # to be always return a Resume type
  response = b.ExtractResume(raw_resume)
  return response

def example_stream(raw_resume: str) -> Resume:
  stream = b.stream.ExtractResume(raw_resume)
  for msg in stream:
    print(msg) # This will be a PartialResume type
  
  # This will be a Resume type
  final = stream.get_final_response()

  return final

def main():
    print("Hello from baml-samples!")
    example("""
        John Doe

        Education
        - University of California, Berkeley
            - B.S. in Computer Science
            - 2020

        Skills
        - Python
        - Java
        - C++
    """)

if __name__ == "__main__":
    main()

$ tree -L 1
.
├── README.md
├── baml_client
├── baml_src
├── main.py
├── pyproject.toml
└── uv.lock

3 directories, 4 files

2025-07-13T20:28:47.266 [BAML INFO] Function ExtractResume:
    Client: openai/gpt-4o-mini (gpt-4o-mini-2024-07-18) - 2429ms. StopReason: stop. Tokens(in/out): 87/44

system: Extract from this content:

        John Doe

        Education
        - University of California, Berkeley
            - B.S. in Computer Science
            - 2020

        Skills
        - Python
        - Java
        - C++

Answer in JSON using this schema:
{
  name: string,
  email: string,
  experience: string[],
  skills: string[],
}

{
  "name": "John Doe",
  "email": "",
  "experience": [],
  "skills": [
    "Python",
    "Java",
    "C++"
  ]
}

{
  "name": "John Doe",
  "email": "",
  "experience": [],
  "skills": [
    "Python",
    "Java",
    "C++"
  ]
}

model ExtractResume(raw_resume: string): Resume

type Resume = {
  name: string,
  email: string,
  phone: string,
  experience: list<string>,
  education: list<Education>,
  skills: list<string>
}

type Education = {
  institution: string,
  location: string,
  degree: string,
  major: list<string>,
  graduation_date?: string
}

baml compile baml_src/clients.baml --output python/baml_client/

# types.py（自动生成）
from pydantic import BaseModel
import typing

class Education(BaseModel):
    institution: str
    location: str
    degree: str
    major: typing.List[str]
    graduation_date: typing.Optional[str] = None

class Resume(BaseModel):
    name: str
    email: str
    phone: str
    experience: typing.List[str]
    education: typing.List[Education]
    skills: typing.List[str]

# sync_client.py（自动生成，部分节选）
class BamlSyncClient:
    # ... 初始化和内部属性省略 ...

    def ExtractResume(self, resume: str, img: typing.Optional[baml_py.Image] = None, baml_options: BamlCallOptions = {}) -> Resume:
        result = self.__options.merge_options(baml_options).call_function_sync(
            function_name="ExtractResume",
            args={"resume": resume, "img": img}
        )
        return typing.cast(Resume, result.cast_to(types, types, stream_types, False, __runtime__))

from baml_client.sync_client import b

resume_obj = b.ExtractResume("raw resume text")
print(resume_obj.name)

# sync_client.py（自动生成，部分节选）
class BamlStreamClient:
    def ExtractResume(self, resume: str, img: typing.Optional[baml_py.Image] = None, baml_options: BamlCallOptions = {}) -> baml_py.BamlSyncStream[stream_types.Resume, Resume]:
        ctx, result = self.__options.merge_options(baml_options).create_sync_stream(
            function_name="ExtractResume",
            args={"resume": resume, "img": img}
        )
        return baml_py.BamlSyncStream[stream_types.Resume, Resume](
            result,
            lambda x: typing.cast(stream_types.Resume, x.cast_to(types, types, stream_types, True, __runtime__)),
            lambda x: typing.cast(Resume, x.cast_to(types, types, stream_types, False, __runtime__)),
            ctx,
        )

stream = b.stream.ExtractResume("raw resume text")
for partial in stream:
    print(partial)  # Partial Resume 类型
final_resume = stream.get_final_response()

# This file was generated by BAML: please do not edit it. Instead, edit the
# BAML files and re-generate this code using: baml-cli generate
# baml-cli is available with the baml package.

__version__ = "0.201.0"

try:
  from baml_py.safe_import import EnsureBamlPyImport
except ImportError:
  raise ImportError(f"""Update to baml-py required.
Version of baml_client generator (see generators.baml): {__version__}

Please upgrade baml-py to version \"{__version__}\".

$ pip install baml-py=={__version__}
$ uv add baml-py=={__version__}

If nothing else works, please ask for help:

https://github.com/boundaryml/baml/issues
https://boundaryml.com/discord
""") from None

with EnsureBamlPyImport(__version__) as e:
  e.raise_if_incompatible_version(__version__)

  from . import types
  from . import tracing
  from . import stream_types
  from . import config
  from .config import reset_baml_env_vars
  
  from .sync_client import b
  

# FOR LEGACY COMPATIBILITY, expose "partial_types" as an alias for "stream_types"
# WE RECOMMEND USERS TO USE "stream_types" INSTEAD
partial_types = stream_types

__all__ = [
  "b",
  "stream_types",
  "partial_types",
  "tracing",
  "types",
  "reset_baml_env_vars",
  "config",
]

from .globals import DO_NOT_USE_DIRECTLY_UNLESS_YOU_KNOW_WHAT_YOURE_DOING_RUNTIME as __runtime__

from baml_client.sync_client import b
resume = b.ExtractResume("raw resume text")