Getting Started
===============

The Community DevOps Agent API provides native boto3 integration for AWS DevOps services. This guide will help you get up and running quickly.

Overview
--------

This library registers multiple custom boto3 services, enabling familiar AWS SDK patterns for DevOps operations. No special authentication or complex setup is required - just use your standard AWS credentials.

**Available Services:**

- **Community DevOps Agent** (``community-devops-agent``): AI-powered DevOps operations and automation
- **AWS DevOps Agent Control Plane** (``community-aidevops``): Agent space management and service associations

Prerequisites
-------------

- Python 3.8 or later
- AWS credentials configured (via AWS CLI, environment variables, or IAM roles)
- Access to AWS DevOps Agent services

Basic Usage
-----------

Import the library and use standard boto3 patterns:

**Community DevOps Agent (Task Management)**

.. code-block:: python

   import devopsagent_api  # Registers all services
   import boto3

   # Create a client for task management
   client = boto3.client('community-devops-agent', region_name='us-east-1')

   # List tasks with filtering
   response = client.list_tasks(
       agentSpaceId='your-agent-space-uuid',
       filter={'status': ['IN_PROGRESS', 'PENDING_START']}
   )

   for task in response['tasks']:
       print(f"Task: {task['title']} - Status: {task['status']}")

**AWS DevOps Agent Control Plane (Agent Spaces)**

.. code-block:: python

   import devopsagent_api  # Registers all services
   import boto3

   # Create a client for agent space management
   client = boto3.client('community-aidevops', region_name='us-east-1')

   # List agent spaces
   response = client.list_agent_spaces()

   for space in response['agentSpaces']:
       print(f"Agent Space: {space['name']} (ID: {space['agentSpaceId']})")

Using Configuration Module (Recommended)
-----------------------------------------

For more advanced usage with environment variable support and validation:

.. code-block:: python

   import devopsagent_api  # Registers all services
   from examples.config import get_config

   # Get configuration with environment variable support
   config = get_config()

   # Create configured clients for both services
   task_client = config.get_client('community-devops-agent')
   space_client = config.get_client('community-aidevops')

   # List tasks using configured settings
   response = task_client.list_tasks(
       agentSpaceId=config.agent_space_id,
       filter={'status': ['IN_PROGRESS', 'PENDING_START']}
   )

   for task in response['tasks']:
       print(f"Task: {task['title']} - Status: {task['status']}")

Core Features
-------------

**Native boto3 Integration**
   - Standard boto3 client creation: ``boto3.client('community-devops-agent')`` or ``boto3.client('community-aidevops')``
   - Automatic pagination with ``client.get_paginator()``
   - Waiters for long-running operations: ``client.get_waiter()``
   - Built-in retry logic and error handling

**Complete API Coverage**
   - **Task Management**: Create, list, get, and update tasks
   - **Goal Management**: Automated workflow management
   - **Recommendation Engine**: AI-generated improvement suggestions
   - **Journal API**: Execution history and investigation records
   - **Topology API**: GraphQL infrastructure discovery
   - **Support Integration**: AWS Support case management
   - **Agent Space Operations**: Create, list, get, update, and delete agent spaces
   - **Service Associations**: Associate and disassociate services with agent spaces
   - **Operator Applications**: Enable and disable operator applications

**Type Safety & Validation**
   - Full Pydantic model validation
   - Type hints throughout the codebase
   - IDE autocomplete support
   - Runtime data validation

Next Steps
----------

- :doc:`installation` - How to install the library
- :doc:`configuration` - Configuration options and environment variables
- :doc:`examples` - Complete usage examples
- :doc:`api_reference` - Detailed API documentation