Welcome back, future AI architect! In Chapter 2, we got Kiro up and running on your system. Now, it’s time for the exciting part: bringing your very first Kiro agent to life! This chapter is your hands-on journey into Kiro’s agentic world, where you’ll learn to configure, deploy, and interact with an AI assistant that understands your development workflow.

By the end of this chapter, you’ll not only have a working Kiro agent but also a foundational understanding of how these agents operate, why their structure matters, and how to begin customizing them to your needs. We’ll break down complex ideas into simple, digestible steps, ensuring you build confidence with every line of code and every command you execute. Get ready to transform your development experience!

Before we dive in, please ensure you’ve completed the setup steps from Chapter 2, including installing the Kiro CLI and configuring your AWS credentials. If you haven’t, a quick refresh will ensure a smooth journey ahead.

What Exactly is a Kiro Agent?

Imagine a highly intelligent, proactive assistant residing right within your IDE, tailored to your specific project needs. That’s a Kiro agent! Unlike general-purpose AI assistants, Kiro agents are designed to be agentic, meaning they can:

  1. Understand Intent: Discern your goals and tasks from natural language or code context.
  2. Access Knowledge: Utilize project-specific documentation, codebases, and external resources.
  3. Execute Actions: Perform tasks like generating code, refactoring, writing tests, or interacting with AWS services.
  4. Oversee Progress: Monitor their own output, debug issues, and ensure adherence to best practices.

This “Intent, Knowledge, Execution, Oversight” (IKEO) framework, as described by AWS, is the beating heart of every Kiro agent. It allows agents to go beyond simple code completion, evolving into powerful, context-aware collaborators.

The Kiro Agent’s Inner Workings

Let’s visualize how a Kiro agent typically processes a request or task you give it.

flowchart TD A["Developer Input: \"Generate a function...\""] --> B{"Kiro Agent"} B -->|"1. Intent Recognition"| C["Intent Layer: What is the user trying to achieve?"] C -->|"2. Knowledge Retrieval"| D["Knowledge Layer: Relevant docs, code, context"] D -->|"3. Action Planning & Execution"| E["Execution Layer: Generate code, run tests, interact APIs"] E -->|"4. Output Review & Refinement"| F["Oversight Layer: Check errors, best practices, completeness"] F -->|"5. Present Output/Ask for Clarification"| B B --> G["Developer Output: Generated code, refactoring suggestion, test results"]

Breaking down the diagram:

  • Developer Input: This is you! You provide a task, a question, or a piece of code you want the agent to work on.
  • Intent Layer: The agent first tries to understand what you want. Are you asking for new code? A bug fix? A design review?
  • Knowledge Layer: Once the intent is clear, the agent pulls in all relevant information: your project’s code, specific documentation, AWS service details, or even internal best practice guides.
  • Execution Layer: This is where the magic happens. Based on its understanding and knowledge, the agent performs actions. This could involve calling a Large Language Model (LLM) to generate code, running a linter, or executing a predefined “hook” (we’ll get to those soon!).
  • Oversight Layer: Before presenting anything to you, the agent reviews its work. Does the code compile? Does it follow your project’s style guide? Is it secure? If not, it might try again or ask you for clarification.
  • Developer Output: Finally, the agent presents its solution, suggestion, or outcome to you.

Understanding this flow helps you craft better prompts and configure your agents more effectively.

Core Components of a Kiro Agent

When you create a Kiro agent, you’re essentially defining these key components:

  1. System Prompts: These are the core instructions that define your agent’s persona, its goals, and its constraints. Think of it as the agent’s “prime directive.” It tells the underlying AI model how to behave.
  2. Agent Hooks: These are specific, executable actions or scripts that your agent can trigger. Hooks allow agents to interact with your codebase, run tests, deploy resources, or integrate with other tools. They are the agent’s “hands” and “feet.”
  3. Model Context Protocol (MCP): This is the communication standard Kiro uses to exchange information between the agent, your IDE, and various AI models or external tools. It ensures a consistent way for agents to access context (like open files, selections, terminal output) and perform actions.

For our first agent, we’ll focus on setting up a basic system prompt and understanding how hooks come into play.

Step-by-Step Implementation: Building Your First Kiro Agent

Let’s roll up our sleeves and create a simple Kiro agent that helps us write Python docstrings. This agent will have a clear purpose and demonstrate the fundamental aspects of Kiro agent development.

Step 1: Initialize a New Kiro Agent Project

First, we need a dedicated directory for our agent. Open your terminal or command prompt.

# Create a new directory for our agent
mkdir my-first-kiro-agent
cd my-first-kiro-agent

# Initialize a new Kiro agent project
kiro agent init

When you run kiro agent init, Kiro will ask you a few questions. For this example, let’s provide the following:

  • Agent Name: DocstringHelper
  • Agent Description: An agent that assists in generating Python docstrings.
  • Programming Language (for default hooks): Python (if prompted, otherwise default is fine)

After initialization, Kiro creates a basic project structure. Take a moment to explore the generated files:

my-first-kiro-agent/
├── .kiro/
│   └── agent.yaml  # Agent configuration
│   └── prompts/    # Directory for system prompts
│       └── main.prompt
└── hooks/          # Directory for agent hooks (e.g., Python scripts)
    └── default_hook.py
└── README.md

Explanation:

  • .kiro/agent.yaml: This YAML file contains metadata about your agent and references to its prompts and hooks.
  • .kiro/prompts/main.prompt: This is where your agent’s primary system prompt resides. It’s a plain text file.
  • hooks/: This directory will contain executable scripts (our “hooks”) that the agent can invoke. Kiro might generate a default_hook.py or similar based on your language choice.

Step 2: Define Your Agent’s System Prompt

Now, let’s give our DocstringHelper agent its personality and instructions.

Open the file .kiro/prompts/main.prompt in your code editor. You’ll likely see a default prompt. Let’s replace its content with instructions specific to our docstring task.

# .kiro/prompts/main.prompt
You are DocstringHelper, an expert Python developer assistant specializing in generating accurate, concise, and PEP 257 compliant docstrings. Your primary goal is to help users write high-quality documentation for their Python functions and classes.

When a user provides a Python code snippet, your task is to:
1. Identify the function or class definition.
2. Generate a suitable docstring following PEP 257 (e.g., using reStructuredText or Google style, if specified by the user, otherwise default to reStructuredText).
3. Ensure the docstring explains parameters, return values, and what the function/class does.
4. Present only the generated docstring or the code with the docstring inserted, clearly indicating the changes.

Do not write any code other than the docstring itself or the full code with the docstring inserted. Do not engage in general conversation unless explicitly asked. Focus strictly on docstring generation.

Explanation:

  • You are DocstringHelper...: This establishes the agent’s persona and expertise. It’s crucial for guiding the underlying AI model’s behavior.
  • Your primary goal is...: Clearly states the agent’s objective.
  • When a user provides...: Defines the expected input and the steps the agent should follow.
  • PEP 257 compliant: Specifies a technical standard, ensuring the output is useful for Python developers.
  • Do not write any code other than...: Sets constraints, preventing the agent from “hallucinating” or generating irrelevant code.

This prompt is now the guiding principle for our DocstringHelper.

Step 3: Testing Your Agent Locally

With the prompt defined, let’s test our agent! Kiro provides a powerful CLI for interacting with your agents.

You can interact with your agent using the kiro agent chat command, which allows you to send messages and receive responses directly in your terminal.

# From your 'my-first-kiro-agent' directory
kiro agent chat

The kiro agent chat command will launch an interactive session. You’ll see a prompt like DocstringHelper >.

Now, paste a simple Python function without a docstring and ask your agent to help:

DocstringHelper > Here's a Python function. Please add a docstring:

def calculate_area(length, width):
    return length * width

What to observe:

The DocstringHelper should process your input and return a docstring similar to this:

"""
Calculates the area of a rectangle.

:param length: The length of the rectangle.
:type length: float or int
:param width: The width of the rectangle.
:type width: float or int
:return: The area of the rectangle.
:rtype: float or int
"""

Or, it might return the full function with the docstring inserted:

def calculate_area(length, width):
    """
    Calculates the area of a rectangle.

    :param length: The length of the rectangle.
    :type length: float or int
    :param width: The width of the rectangle.
    :type width: float or int
    :return: The area of the rectangle.
    :rtype: float or int
    """
    return length * width

Congratulations! You’ve just interacted with your first custom Kiro agent. It understood your intent, applied its knowledge (from the prompt), and executed the task.

To exit the chat session, type /exit or press Ctrl+D.

While our DocstringHelper currently relies solely on its system prompt, real-world Kiro agents heavily utilize hooks to perform actions beyond simple text generation. Hooks are essentially scripts that the agent can execute.

Let’s look at the hooks/default_hook.py that Kiro might have generated. Its content will vary, but it’s often a placeholder.

For instance, a simple hook might look like this:

# hooks/default_hook.py
import sys
import json

def main():
    # Kiro provides context via stdin
    context = json.load(sys.stdin)

    # Example: Print the user's selected text
    selected_text = context.get("selection", {}).get("text", "No text selected.")
    print(f"Hook received selection: {selected_text}", file=sys.stderr)

    # Example of returning a result to Kiro
    result = {
        "output_type": "text",
        "content": "Default hook executed successfully!",
        "actions": [] # Can specify actions like 'insert_text', 'open_file'
    }
    json.dump(result, sys.stdout)

if __name__ == "__main__":
    main()

Explanation:

  • Kiro passes contextual information (like selected code, file paths, etc.) to hooks via stdin as a JSON object.
  • Hooks can perform any operation a script can (e.g., read/write files, call external APIs).
  • Hooks return their results back to Kiro via stdout, also as a JSON object, which Kiro then interprets.

How to integrate a hook:

To make our DocstringHelper use a hook, we would modify our main.prompt to instruct it to call a specific hook when certain conditions are met. For example:

# Modified .kiro/prompts/main.prompt excerpt
...
If the user explicitly asks to "insert the docstring into the code", you should invoke the 'insert_docstring' hook with the generated docstring and the original code.
...

Then, you would need to define an insert_docstring.py hook that takes the docstring and code, inserts it, and returns the modified code. This is a more advanced topic we’ll cover in future chapters, but it’s important to understand why hooks exist: to give your agents actionable capabilities within your development environment.

Mini-Challenge: Refine Your Agent’s Persona

Let’s make our DocstringHelper even more specific!

Challenge: Modify your main.prompt so that the DocstringHelper always generates docstrings using the Google style format, and never uses reStructuredText, regardless of user specification. Also, instruct it to be very concise and only include parameters and return values if they are explicitly present in the function signature.

Hint: Focus on the “Generate a suitable docstring…” and “Ensure the docstring explains…” sections of your prompt. Be explicit about the desired style and verbosity.

What to observe/learn:

After updating the prompt, use kiro agent chat again with your calculate_area function (or a new one). Observe if the generated docstring adheres to the Google style and is more concise. This exercise will reinforce how precisely defining the prompt directly influences the agent’s behavior and output.

Common Pitfalls & Troubleshooting

Even with a simple agent, you might encounter issues. Here are a few common pitfalls and how to troubleshoot them:

  1. Agent Not Following Instructions:

    • Pitfall: Your agent is generating code or responses that don’t match your prompt.
    • Troubleshooting:
      • Review main.prompt: Is your prompt clear, concise, and unambiguous? Ambiguous language can lead to unexpected behavior.
      • Add Constraints: Explicitly tell the agent what not to do (e.g., “Do not generate boilerplate code,” “Only output JSON”).
      • Iterate: Prompt engineering is an iterative process. Small tweaks can have significant impacts.
      • Context Window Limits: While less likely for simple tasks, very long prompts or input might exceed the underlying LLM’s context window, leading to truncated understanding.

  2. kiro agent chat Errors (e.g., “Agent can’t access AWS resources”):

    • Pitfall: Kiro CLI is failing to communicate with AWS or the underlying AI models.
    • Troubleshooting:
      • AWS CLI Configuration: Verify your AWS CLI is correctly configured by running aws sts get-caller-identity. Ensure the region is set and credentials have the necessary permissions to invoke AI services (like Amazon Bedrock or other relevant LLM endpoints Kiro uses).
      • Internet Connectivity: Kiro agents rely on cloud services, so ensure you have a stable internet connection.
      • Kiro CLI Version: While unlikely with our setup, ensure your Kiro CLI is up to date (kiro --version).

  3. No Output or Unexpected Blank Output:

    • Pitfall: The agent processes your request but returns nothing or an empty response.
    • Troubleshooting:
      • Prompt Clarity: Is the agent’s output instruction clear? For example, if you tell it to “summarize,” but the input is empty, it might return nothing.
      • Underlying Model Issues: Occasionally, the AI model itself might fail to generate a response. Try re-running the command.
      • Kiro Logs: Kiro usually provides more detailed error messages in the terminal if something goes wrong internally. Pay close attention to any red text.

Summary

Phew! You’ve just taken your first significant steps into the world of AWS Kiro agents. Here’s a quick recap of what we covered:

  • Kiro Agents are Agentic: They follow an Intent, Knowledge, Execution, Oversight (IKEO) framework to understand and act on your behalf.
  • Core Components: You learned about System Prompts (the agent’s brain), Agent Hooks (the agent’s actions), and the Model Context Protocol (MCP) for communication.
  • Hands-on Creation: You initialized a new Kiro agent project using kiro agent init.
  • Prompt Engineering: You defined and modified your agent’s persona and instructions in .kiro/prompts/main.prompt.
  • Local Testing: You interacted with your agent using kiro agent chat to see its responses in action.
  • Troubleshooting: We discussed common issues like prompt ambiguity and AWS CLI configuration.

You now have a functional Kiro agent, albeit a simple one, and a solid understanding of the fundamental concepts. This foundation is crucial for building more complex and powerful agents in the future.

In the next chapter, we’ll dive deeper into Agent Hooks, exploring how to create custom scripts that allow your Kiro agent to perform actions directly within your codebase, truly extending its capabilities beyond just text generation. Get ready to give your agent some real “hands-on” power!

References

This page is AI-assisted and reviewed. It references official documentation and recognized resources where relevant.