Working with Agents

Learn how to create, configure, and deploy AI agents using Weni CLI.

Agent Definition File

Agents are defined using YAML files. Here's the basic structure:

agents:
   agent_id:
      name: "Agent Name"
      description: "Agent Description"
      instructions:
         - "Instruction 1"
         - "Instruction 2"
      guardrails:
         - "Guardrail 1"
      tools:
         - tool_name:
            name: "Tool Name"
            source:
               path: "tools/tool_name"
               entrypoint: "main.ToolClass"
            description: "Tool Description"
            parameters:
               - param_name:
                  description: "Parameter Description"
                  type: "string"
                  required: true
                  contact_field: true

Key Components

1. Agent ID
2. Unique identifier for your agent

3. Used internally by the system

4. Basic Information

5. name: Display name (max 55 characters)

6. description: Brief description of the agent's purpose

7. Instructions

8. Guide the agent's behavior
9. Minimum 40 characters each

10. Should be clear and specific

11. Guardrails

12. Define boundaries and limitations

13. Prevent unwanted behavior

14. Tools

15. Custom functionalities
16. Implemented as Python classes using the Weni SDK

Tool Source Configuration

The source field is critical for locating and executing your tool:

source:
  path: "tools/tool_name"
  entrypoint: "main.ToolClass"

• path: Points to the directory containing your tool implementation
• Example: tools/get_address refers to a folder named get_address inside a tools directory

• This folder should contain your Python modules and requirements.txt

• entrypoint: Specifies which class to use in which file

• Format: filename.ClassName
• Example: main.GetAddress means:
  • Look for a file named main.py in the path directory
  • Find a class named GetAddress inside that file
  • This class must inherit from the Tool class

Your directory structure should look like:

project/
├── agents.yaml
└── tools/
    └── get_address/
        ├── main.py             # Contains GetAddress class
        └── requirements.txt    # Dependencies

Creating Tools

Tool Implementation Structure

from weni import Tool
from weni.context import Context
from weni.responses import TextResponse

class ToolName(Tool):
    def execute(self, context: Context) -> TextResponse:
        # Extract parameters
        parameters = context.parameters
        param_value = parameters.get("param_name", "")

        # Process the request
        result = self.process_request(param_value)

        # Return response
        return TextResponse(data=result)

    def process_request(self, param_value):
        # Your business logic here
        return {"key": "value"}

Important Requirements

• The class must inherit from Tool
• The class must implement the execute method
• The class name must match the class name in your entrypoint

Deploying Agents

Push Command

Deploy your agent using:

weni project push agents.yaml

The command: 1. Validates your YAML 2. Uploads tools 3. Creates/updates the agent

Deployment Best Practices

1. Version Control
2. Keep agent definitions in version control

3. Document changes

4. Testing

5. Test locally when possible
6. Start with staging environment

7. Verify all tools work

8. Organization

9. Use clear file names
10. Keep related files together
11. Document dependencies

Advanced Topics

Parameter Types

Available parameter types: - string - number - integer - boolean - array

Response Formats

Tools can return: - Text responses via TextResponse - Structured data - Error messages

Error Handling

Your tools should: 1. Validate inputs 2. Handle exceptions gracefully 3. Return meaningful error messages

Troubleshooting

Common Issues

1. Deployment Failures
2. Check YAML syntax
3. Verify tool paths

4. Confirm project selection

5. Tool Errors

6. Verify tool entrypoint (class name)
7. Test tool class locally
8. Check parameter handling in context

9. Verify API endpoints

10. Agent Behavior

11. Review instructions
12. Check guardrails
13. Test with various inputs

Best Practices

1. Development Flow
2. Develop locally
3. Test in staging

4. Deploy to production

5. Monitoring

6. Keep deployment logs
7. Monitor tool performance

8. Track user interactions

9. Updates

10. Plan changes carefully
11. Test updates thoroughly
12. Document modifications