weiqingy commented on code in PR #705: URL: https://github.com/apache/flink-agents/pull/705#discussion_r3299717303
########## docs/content/docs/development/yaml.md: ########## @@ -0,0 +1,555 @@ +--- +title: YAML API +weight: 3 +type: docs +--- +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +## Overview + +Beyond the Python and Java programmatic APIs, Flink Agents offers a **declarative YAML API** for describing agents. Compared with the programmatic APIs, the YAML API has the following advantages: + +- **Human-friendly**: low entry barrier and easy to templatize across deployments. +- **Coding-agent-friendly**: a fixed schema reduces token cost, enables strict schema validation, and decouples configuration changes (declared parameters) from logic changes (action code). + +A Flink Agents application is composed of three concepts; the YAML API exposes all three as declarative sections: + +- **Events**: the messages flowing inside an agent. Every event has a type used for routing. +- **Actions**: code snippets triggered by events and emitting new events. They carry the agent's business logic. +- **Resources**: reusable components — Chat Models, Tools, Prompts, Vector Stores, MCP servers, etc. — referenced by actions at runtime. + +A YAML file describes **Resources** and **Actions** declaratively; the **Event** types are referenced by name (built-in event aliases like `input` / `chat_response`, or your own event-type strings). The implementation classes (action functions, tool functions, custom types) still live in your Python or Java code; the YAML file only describes *how* those pieces are wired together. + +If you'd rather declare agents directly in code, see [Workflow Agent]({{< ref "docs/development/workflow_agent" >}}) and [ReAct Agent]({{< ref "docs/development/react_agent" >}}). + +## Declaring an Agent + +This section walks through: + +1. Declaring a single agent in one YAML file. +2. Declaring multiple agents in one YAML file. +3. Declaring shared Resources and Actions that any agent in the file (or any later-loaded file) can reuse. + +### Declaring a single agent + +The example below declares one agent named `review_analysis_agent` with a chat-model connection, a chat-model setup, a function tool, and two actions. It demonstrates every field you typically use. + +```yaml +agents: + - name: review_analysis_agent + description: Analyze product reviews and emit a satisfaction score. + + # ---- Actions ---- + actions: + - name: process_input + function: my_pkg.actions:process_input + listen_to: [input] + type: python + - name: process_chat_response + function: my_pkg.actions:process_chat_response + listen_to: [chat_response] + type: python + + # ---- Resources ---- + chat_model_connections: + - name: ollama_server + clazz: ollama + type: python + base_url: http://localhost:11434 + + chat_model_setups: + - name: review_analysis_model + clazz: ollama + type: python + connection: ollama_server + model: qwen3:8b + prompt: review_analysis_prompt + tools: [notify_shipping_manager] + extract_reasoning: true + + prompts: + - name: review_analysis_prompt + messages: + - role: system + content: "Analyze the review and return JSON with score + reasons." + - role: user + content: "{input}" + + tools: + - name: notify_shipping_manager + function: my_pkg.actions:notify_shipping_manager + type: python +``` + +#### Agent properties + +| Field | Required | Description | +|-------|----------|-------------| +| `name` | yes | Agent name. Must be unique across the environment. Used to apply the agent by name later. | +| `description` | no | Free-form description of what the agent does. Not surfaced at runtime. | + +#### Resources + +All resource sections are declared as lists under the agent. Each entry has a `name` unique within its section. + +**Prompt** — declarative prompt template; pick exactly one of `text` or `messages`. + +| Field | Required | Description | +|-------|----------|-------------| +| `name` | yes | Prompt name (referenced by chat-model setups). | +| `text` | one-of | Single-string prompt template. Corresponds to `Prompt.from_text` / `Prompt.fromText`. | +| `messages` | one-of | Multi-turn message template. Corresponds to `Prompt.from_messages` / `Prompt.fromMessages`. Each entry has `role` (`system` / `user` / `assistant` / `tool`) and `content`. | + +```yaml +prompts: + - name: prompt1 + messages: + - {role: system, content: "..."} + - {role: user, content: "{input}"} + - name: prompt2 + text: "this is the {value}" +``` + +**Tool** — points at a callable that the chat model can invoke. + +| Field | Required | Description | +|-------|----------|-------------| +| `name` | yes | Tool name (referenced from `chat_model_setups[].tools`). | +| `function` | yes | Fully-qualified callable in the form `<module-or-class>:<qualname>`. See [Function references](#function-references). | +| `type` | no | Implementation language: `python` or `java`. Defaults to `python` (see [Selecting the implementation language](#selecting-the-implementation-language)). | +| `parameter_types` | java only | Required for Java tools — one Java type FQN per declared parameter, in order. Forbidden for Python tools (the signature is reflected from the callable). | + +```yaml +tools: + - name: my_tool + function: my_pkg.tools:my_tool + type: python +``` + +For **Java tools**, `parameter_types` is required because Java methods can be overloaded — list one FQN per declared parameter, in order. Generic type arguments are not part of the JVM method descriptor and must not be included (`java.util.List`, not `java.util.List<String>`). Boxed primitives (`java.lang.Integer`, etc.) and bare primitives (`int`, `boolean`, ...) are both accepted. + +```yaml +tools: + - name: add + type: java + function: com.example.MyTools:add + parameter_types: [java.lang.Integer, java.lang.Integer] +``` + +**Skills** — bundles of agent skill assets loaded from one or more sources. At least one of `paths` / `urls` / `classpath` / `package` must be non-empty; multiple sources can coexist. See [Agent Skills]({{< ref "docs/development/workflow_agent" >}}) for the skill loading model. Review Comment: The Agent Skills cross-link here — `[Agent Skills]({{< ref "docs/development/workflow_agent" >}})` — points at a doc that doesn't actually cover skills (`grep -i skills docs/content/docs/development/workflow_agent.md` returns nothing). For now the sentence sends readers somewhere that doesn't have the skill loading model. A couple of options: - Drop the link and leave just *"… for the skill loading model, see the Python/Java API docs"* (or a similar pointer) until a dedicated Skills doc lands. - Or, if a Skills doc is being authored (e.g. via #696), file a follow-up to swap the link once it's checked in. ########## python/flink_agents/examples/quickstart/yaml_review_analysis_agent.yaml: ########## @@ -0,0 +1,63 @@ +agents: + - name: review_analysis_agent + description: | + YAML-declared review analysis agent. Reuses the static methods of + ReviewAnalysisAgent from the workflow_agent quickstart as actions + and tool, but wires everything together through this YAML file + instead of class-level decorators. + + actions: + - name: process_input + function: flink_agents.examples.quickstart.agents.review_analysis_agent:ReviewAnalysisAgent.process_input + listen_to: [input] + - name: process_chat_response + function: flink_agents.examples.quickstart.agents.review_analysis_agent:ReviewAnalysisAgent.process_chat_response + listen_to: [chat_response] + + chat_model_connections: + - name: ollama_server + clazz: ollama + request_timeout: 120 + + prompts: + - name: review_analysis_prompt + messages: + - role: system + content: | + Analyze the user review and product information to determine a + satisfaction score (1-5) and potential reasons for dissatisfaction. + + Example input format: + { + "id": "12345", + "review": "The headphones broke after one week. Very poor quality." + } + + Ensure your response can be parsed by Python JSON, using this + format as an example: + { + "id": "12345", + "score": 1, + "reasons": ["poor quality"] + } + + If the review mentions shipping dissatisfaction, first call + notify_shipping_manager, then return the JSON above with no + mention of the tool call. + - role: user + content: | + "input": + {input} + + chat_model_setups: + - name: review_analysis_model Review Comment: The Java sibling YAML (`examples/src/main/resources/yaml/yaml_review_analysis_agent.yaml`) has an inline comment right above this line: ``` # Action ``processInput`` sends ``ChatRequestEvent("reviewAnalysisModel", ...)``, # so the chat-model setup MUST be named ``reviewAnalysisModel``. ``` The Python side has the same coupling — `ReviewAnalysisAgent.process_input` in `flink_agents.examples.quickstart.agents.review_analysis_agent` sends `ChatRequestEvent(model="review_analysis_model", ...)`, so this setup's `name:` has to stay as `review_analysis_model` — but the Python YAML (and the Python tab in `yaml_agent.md`) don't surface it. Adding the same comment here would save a reader who renames the setup from a hard-to-trace runtime mismatch. Suggested wording: ```yaml # Action `process_input` sends `ChatRequestEvent(model="review_analysis_model", ...)`, # so the chat-model setup MUST be named `review_analysis_model`. chat_model_setups: - name: review_analysis_model ``` ########## docs/content/docs/development/vector_stores.md: ########## @@ -1,6 +1,6 @@ --- title: Vector Stores -weight: 6 +weight: 7 Review Comment: `weight: 7` here collides with `docs/content/docs/development/memory/_index.md`, which is also pinned to `weight: 7`. At a tie, Hugo's ordering falls back to alphabetic path order, so the Memory section and Vector Stores can swap in the rendered sidebar depending on Hugo version. Would you also bump Memory to 8 in this PR? That keeps the development-tree weights collision-free (`workflow_agent=1, react=2, yaml=3, chat_models=4, prompts=5, embedding_models=6, vector_stores=7, memory=8, tool_use=…`) instead of relying on the tie-break. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
