> ## Documentation Index
> Fetch the complete documentation index at: https://grandcentral.backbase.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Create your first agent

> Step-by-step guide to creating and deploying your first agentic application

Create, configure, and deploy your first agentic application using the Backbase Agentic Platform.

## Prerequisites

Before you begin, ensure you have:

* Completed the [Onboarding](/agentic-ai/getting-started/onboarding) steps.
* Access to the **Self-Service** repository.
* Access to the **Applications Live** repository.

## Step 1: Create a new repository

Use the **Self-Service** GitOps workflow to provision a new repository based on the starter-agent template.

1. Clone the **Self-Service** repository.
2. Create a new branch (e.g., `feat/my-first-agent`).
3. Open `self-service.tfvars` and add your new repository definition under the `repositories` block:

```hcl theme={"system"}
repositories = {
  # ... existing repos ...
  
  my-first-agent = {
    description = "My first agentic application"
    enable_branch_protection = true
    protected_branches       = ["main", "develop"]
    
    repository_template = {
      owner      = "bb-ecos-agbs"
      repository = "starter-agent"
    }
  }
}
```

4. Commit your changes and push the branch.
5. Open a Pull Request (PR) and merge it after approval.
6. Once the PR is merged, a new repository named `my-first-agent` gets provisioned and the **Repository Provisioning Workflow** runs automatically to set up the repository with the template contents and CI/CD pipelines.

<Check>
  Repository successfully provisioned with starter-agent template!
</Check>

## Step 2: Build and publish Docker image

Now that your repository is provisioned, you need to build the application and publish a Docker image to Azure Container Registry (ACR).

1. Navigate to your newly provisioned repository on GitHub.
2. Go to **Actions** tab.
3. Select the **Build and Publish** workflow from the left sidebar.
4. Click **Run workflow** and select the branch (typically `main` or `develop`).
5. The workflow will:
   * Build the application
   * Create a Docker image
   * Push the image to ACR with a tag (e.g., `0.1.0.dev0-develop.2a7f4f6d`)

<Check>
  Your application's runnable image is now available on ACR!
</Check>

<Tip>
  Note the image tag generated by the workflow - you'll need it in the next step. The tag format is typically `VERSION-BRANCH.COMMIT_HASH`.
</Tip>

## Step 3: Deploy to Kubernetes runtime

Deploy your agent to the Kubernetes cluster using the **Applications Live** repository and ArgoCD.

### Create ArgoCD application

1. Clone the **Applications Live** repository:

```bash theme={"system"}
git clone https://github.com/bb-ecos-agbs/gc-devhub-agbs-applications-live.git
cd gc-devhub-agbs-applications-live
```

2. Create a new branch for your changes:

```bash theme={"system"}
git checkout -b feat/deploy-my-first-agent
```

3. Create an ArgoCD Application manifest in the appropriate environment folder (e.g., `runtimes/dev/applications/`):

```yaml runtimes/dev/applications/my-first-agent.yaml theme={"system"}
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-namespace
  namespace: argocd
spec:
  project: devhub-grandcentral
  destination:
    server: https://kubernetes.default.svc
    namespace: my-namespace
  sources:
    - repoURL: git@github.com:bb-ecos-agbs/gc-devhub-agbs-applications-live.git
      targetRevision: main
      ref: apps-live

    - repoURL: cragbs508.azurecr.io/charts
      chart: helm-chart-template
      targetRevision: 0.5.1
      helm:
        releaseName: my-first-agent-v0
        parameters:
          - name: "nameOverride"
            value: my-first-agent
        valueFiles:
          - $apps-live/runtimes/dev/values/my-namespace/my-first-agent-v0.values.yaml
```

### Create Helm values file

4. Create a values file at `runtimes/dev/values/my-namespace/my-first-agent-v0.values.yaml`:

```yaml runtimes/dev/values/my-namespace/my-first-agent-v0.values.yaml theme={"system"}
# Replica count for the deployment
replicaCount: 1

# Container image configuration
image:
  repository: cragbs508.azurecr.io/images/my-first-agent
  pullPolicy: IfNotPresent
  # Use the tag from Step 2 Build and Publish workflow
  tag: "0.1.0.dev0-develop.2a7f4f6d"

# Volume mounts for temporary storage
volumeMounts:
  - mountPath: /app/tmp
    name: temp

volumes:
  - name: temp
    emptyDir:
      sizeLimit: 500Mi

# Container port configuration
container:
  ports:
    - name: http
      containerPort: 8000
      protocol: TCP

# Kubernetes service configuration
service:
  type: ClusterIP
  ports:
    - port: &servicePort 80
      targetPort: http
      protocol: TCP
      name: http

# Istio virtualservice for external access
virtualService:
  enabled: true
  spec:
    gateways:
      - "knative-serving/knative-ingress-gateway"
    hosts:
      - '{{ include "helm-chart-template.fullname" . }}-{{ .Release.Namespace }}.dev.agbs.gcservices.io'
    http:
      - route:
          - destination:
              host: '{{ include "helm-chart-template.fullname" . }}.{{ .Release.Namespace }}.svc.cluster.local'
              port:
                number: *servicePort

# Resource limits and requests
resources:
  limits:
    cpu: "500m"
    memory: "512Mi"
  requests:
    cpu: "50m"
    memory: "150Mi"

# Health probes (optional)
livenessProbe: {}
readinessProbe: {}

# Environment variables
env:
  - name: APP_ENV
    value: "development"
  - name: AI_GATEWAY_ENDPOINT
    valueFrom:
      secretKeyRef:
        name: my-agent-secrets
        key: AI_GATEWAY_ENDPOINT
  - name: AI_GATEWAY_API_KEY
    valueFrom:
      secretKeyRef:
        name: my-agent-secrets
        key: AI_GATEWAY_API_KEY
  - name: LANGFUSE_SECRET_KEY
    valueFrom:
      secretKeyRef:
        name: my-agent-secrets
        key: LANGFUSE_SECRET_KEY
  - name: LANGFUSE_PUBLIC_KEY
    valueFrom:
      secretKeyRef:
        name: my-agent-secrets
        key: LANGFUSE_PUBLIC_KEY
  - name: LANGFUSE_BASE_URL
    valueFrom:
      secretKeyRef:
        name: my-agent-secrets
        key: LANGFUSE_BASE_URL
```

<Warning>
  The environment variables reference a Kubernetes secret named `my-agent-secrets`. You must create this secret in your namespace using **SOPS encryption** before deploying. The secret should contain the following keys: `AI_GATEWAY_ENDPOINT`, `AI_GATEWAY_API_KEY`, `LANGFUSE_SECRET_KEY`, `LANGFUSE_PUBLIC_KEY`, and `LANGFUSE_BASE_URL`.
</Warning>

<Tip>
  To create encrypted secrets with SOPS, follow the steps [here](https://github.com/bb-ecos-agbs/gc-devhub-agbs-applications-live/blob/main/runtimes/dev/secrets/README.md)
</Tip>

5. Commit and push your changes:

```bash theme={"system"}
git add .
git commit -m "feat: deploy my-first-agent to dev environment"
git push origin feat/deploy-my-first-agent
```

6. Open a Pull Request and merge it after approval.
7. Once merged, ArgoCD will automatically sync and deploy your application to the `my-namespace` namespace.

<Check>
  Your agentic application is now deployed on the Kubernetes cluster!
</Check>

### Test your deployed agent

Your agent is now accessible via the Istio VirtualService URL. Test it using the following curl command:

```bash theme={"system"}
curl --location 'https://my-first-agent-v0-my-namespace.dev.agbs.gcservices.io/run/instructions_agent' \
  --header 'Content-Type: application/json' \
  --data '{
    "query": "I'\''m my first agent"
}'
```

<Check>
  Your agentic application is deployed on the cluster and accessible via API!
</Check>

<Warning>
  This is **not a secured way** of accessing your agent. You should expose it via API Management (APIM) where you can set up authentication and different policies for production use.
</Warning>

## Step 4: Expose via APIM (secure access)

To securely access your agent's API with authentication and policies, expose it through API Management (APIM).

### Create API repository

1. Go back to the **Self-Service** repository and create a new branch.
2. Add an API repository definition in `self-service.tfvars`:

```hcl theme={"system"}
repositories = {
  # ... existing repos ...
  
  my-first-agent-api = {
    enable_branch_protection     = false
    enforce_admins               = true
    default_branch               = "develop"
    require_branch_up_to_date    = true
    protected_branches           = ["main", "develop", "release/*"]
    required_status_checks       = ["Validate pull request / Verify Maven project"]
    
    repository_init_from_zip = {
      name    = "grandcentral-generic-api"
      version = "2.0.3"
    }
    
    repository_visibility = "private"
  }
}
```

3. Commit, push, and merge the PR.
4. Once the `-api` repository is created, clone it and add the OpenAPI specification for your agent (e.g., `openapi.yaml`) that describes your agent's endpoints.

### Configure APIM in applications live

Now configure the API, backend, product, and subscription in the **Applications Live** repository.

<Steps>
  <Step title="Create API application">
    Create a file at `runtimes/dev/apim/apis/my-first-agent-api.yaml`:

    ```yaml runtimes/dev/apim/apis/my-first-agent-api.yaml theme={"system"}
    apiVersion: argoproj.io/v1alpha1
    kind: Application
    metadata:
      name: my-first-agent-api
      namespace: argocd
    spec:
      project: devhub-grandcentral
      destination:
        server: https://kubernetes.default.svc
        namespace: devhub-grandcentral
      sources:
        - repoURL: git@github.com:bb-ecos-agbs/gc-devhub-agbs-applications-live.git
          targetRevision: main
          ref: apps-live
        - repoURL: cragbs508.azurecr.io/charts
          chart: my-first-agent-api
          targetRevision: 0.1.0-20361246926
          helm:
            releaseName: my-first-agent-api-v0
            valueFiles:
              - $apps-live/runtimes/dev/apim/apis/common.apim.values.yaml
      syncPolicy:
        automated:
          prune: true
          allowEmpty: true
          selfHeal: true
        syncOptions:
          - CreateNamespace=false
    ```

    <Info>
      Update the `targetRevision` with the actual chart version from your API repository's build workflow.
    </Info>
  </Step>

  <Step title="Add API to version sets">
    Add your API to `runtimes/dev/apim/apiVersionsets.yaml`:

    ```yaml theme={"system"}
    # ... existing version sets ...
    - name: "my-first-agent-api"
    ```
  </Step>

  <Step title="Create backend">
    Add a backend entry in `runtimes/dev/apim/backends.yaml`:

    ```yaml theme={"system"}
    # ... existing backends ...
    - name: my-first-agent-backend
      url: 'https://my-first-agent-v0-my-namespace.dev.agbs.gcservices.io'
      title: "My First Agent Backend"
      description: "My First Agent Backend"
    ```

    <Info>
      The backend URL should match the VirtualService URL from Step 4 where you tested your agent.
    </Info>
  </Step>

  <Step title="Create product with policies">
    Add a product definition in `runtimes/dev/apim/products.yaml`:

    ```yaml theme={"system"}
    # ... existing products ...
    - name: my-first-agent-product
      description: My First Agent Product
      displayName: My First Agent Product
      approvalRequired: "false"
      policy:
        apiBackend:
          - api: my-first-agent-api-0
            backend: my-first-agent-backend
        value: |
          <policies>
              <inbound>
                  <base />
                  <set-header name="Accept" exists-action="override">
                     <value>application/json, text/event-stream</value>
                  </set-header>
                  <set-header name="Content-Type" exists-action="override">
                     <value>application/json</value>
                  </set-header>
                  <set-backend-service backend-id="my-first-agent-backend" />
              </inbound>
              <backend>
                  <base />
              </backend>
              <outbound>
                  <base />
              </outbound>
              <on-error>
                  <base />
              </on-error>
          </policies>
      productApis:
        - apiName: my-first-agent-api-0
    ```

    <Tip>
      The policy section defines how requests are processed. You can add authentication, rate limiting, and other policies here.
    </Tip>
  </Step>

  <Step title="Create subscription">
    Add a subscription in `runtimes/dev/apim/subscriptions.yaml`:

    ```yaml theme={"system"}
    # ... existing subscriptions ...
    - name: my-first-agent-subscription
      productScope: my-first-agent-product
    ```

    <Info>
      The subscription generates an API key that clients use to access your agent through APIM.
    </Info>
  </Step>
</Steps>

### Deploy APIM configuration

Commit and push all the APIM configuration changes, then open a Pull Request and merge it. ArgoCD will automatically sync and apply the APIM configurations.

### Access your agent via APIM

Once the APIM configuration is deployed, you can access your agent securely using the subscription key:

```bash theme={"system"}
curl --location 'https://apim.dev.agbs.gcservices.io/my-first-agent-api/v0/run/instructions_agent' \
  --header 'api-key: YOUR_SUBSCRIPTION_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "query": "I'\''m my first agent."
}'
```

<Warning>
  Replace `YOUR_SUBSCRIPTION_KEY` with the actual subscription key generated for `my-first-agent-subscription`. You can find this in the APIM portal or Kubernetes secrets.
</Warning>

<Check>
  You have successfully created, deployed, and exposed your first agentic application with secure API access through APIM!
</Check>

## Next steps

* **Local development**: Learn how to run and test your agent locally in the [Development Guide](/platform/developer-guides/overview)
* **CI/CD workflows**: Understand the automated workflows in [CI/CD Overview](/agentic-ai/ci-cd-workflows/overview)
* **BB AI SDK**: Explore SDK features in [BB AI SDK Documentation](/agentic-ai/bb-ai-sdk/overview)
* **Starter kits**: Check out other templates in [Starter kits](/agentic-ai/starter-kits/overview)