Anatomy of an Agent: Passive Agents
A Passive Agent is an AI worker that reacts to user inputs to solve problems. Its definition is written in a YAML file, which serves as its blueprint.
General Structure
The agent_definition.yaml file begins with the agents key, which contains one or more agents, each identified by a unique slug.
agents:
cep_agent: # <--- This is the agent slug
name: "CEP Agent"
description: "Weni's CEP agent"
instructions:
- "You are an expert in providing addresses to the user based on a postal code provided by the user"
- "The user will send a ZIP code (postal code) and you must provide the address corresponding to this code."
guardrails:
- "Don't talk about politics, religion or any other sensitive topic. Keep it neutral."
tools:
- get_address:
name: "Get Address"
source:
path: "tools/get_address"
entrypoint: "main.GetAddress"
path_test: "test_definition.yaml"
description: "Function to get the address from the postal code"
parameters:
- cep:
description: "postal code of a place"
type: "string"
required: true
contact_field: true
Agent
slug (cep_agent): This is the unique ID of your agent. It is used to update the agent in future deployments (push). If the slug does not exist, a new agent is created; if it already exists, it will be updated.Main Agent Properties
These keys define the agent’s characteristics and personality.
name(string) The name of your agent as it will appear in the Weni Platform interface. Limit: 55 characters.description(string) A brief description of the agent’s purpose, also visible in the interface.instructions(list of strings) Directives and guidelines that the agent must follow. Defines its role, personality, and operating behavior. Minimum length: 40 characters.guardrails(list of strings) Boundaries and topics the agent should avoid to keep conversations focused and safe. Minimum length: 40 characters.credentials(dict) Defines the credentials the agent’s tools may need to interact with external services.For a detailed explanation, refer to the Credential Management ####### guide.
Tool Definition
tools:
- get_address: # <--- This is the tool slug
name: "Get Address"
# ... rest of the tool configuration
Tool slug (
get_address): This is the unique ID of the tool within the agent.Tool Properties
name(string): The tool’s display name on the platform. Limit: 40 characters.description(string): An explanation of what the tool does.source(dict): Connects the definition to the Python code that implements the logic.path: The path to the directory containing the tool code (e.g.,tools/get_address).entrypoint: The entry point, in the formatfilename.ClassName(e.g.,main.GetAddress).path_test: The path to the YAML file containing the test cases forweni run.
Tool Parameters (parameters)
Defines the input data that the tool needs to operate.
description(string): Explains what the parameter is.type(string): Data type (string,number,integer,boolean,array).required(boolean): Iftrue, the agent will ensure this data is obtained from the user before executing the tool.contact_field(boolean): Iftrue, the parameter’s value will be stored in the contact’s profile in the Weni Platform.
For more details, read the Contact Fields ###### guide.
